Skip to content

tool-description-agent-usage-notes.md

Latest commit

 

History

History
37 lines (35 loc) · 3.85 KB

tool-description-agent-usage-notes.md

File metadata and controls

37 lines (35 loc) · 3.85 KB
Raw

${TOOL_BASE_DESCRIPTION} ${TOOL_PARAMETERS_DESCRIPTION}

Usage notes

  • Always include a short description summarizing what the agent will do
  • When the agent is done, it will return a single message back to you. The result returned by the agent is not visible to the user. To show the user the result, you should send a text message back to the user with a concise summary of the result.
  • Trust but verify: an agent's summary describes what it intended to do, not necessarily what it did. When an agent writes or edits code, check the actual changes before reporting the work as done.${!ENVIRONMENT_CONFIG.CLAUDE_CODE_DISABLE_BACKGROUND_TASKS&&!IS_SUBAGENT_CONTEXT_FN()&&!HAS_SUBAGENT_TYPES?"\n- Agents run in the background by default. When an agent runs in the background, you will be automatically notified when it completes — do NOT sleep, poll, or proactively check on its progress. Continue with other work or respond to the user instead.\n- Foreground vs background: Pass run_in_background: false to run an agent in the foreground when you need its results before you can proceed — e.g., research agents whose findings inform your next steps. Otherwise let it run in the background (the default) so you can keep working in parallel.":""}
  • To continue a previously spawned agent, use ${SEND_MESSAGE_TOOL_NAME} with the agent's ID or name as the to field — that resumes it with full context. A new ${AGENT_TOOL_NAME} call starts a fresh agent with no memory of prior runs${CAN_FORK_CONTEXT?' (except subagent_type: "fork")':""}, so the prompt must be self-contained.
  • Each agent type's model, reasoning effort, and tool access are set in its definition (.claude/agents/*.md frontmatter, or the SDK agents option); the model parameter here overrides the definition for this one call.
  • Clearly tell the agent whether you expect it to write code or just to do research (search, file reads, web fetches, etc.), since a fresh agent is not aware of the user's intent
  • If the agent description mentions that it should be used proactively, then you should try your best to use it without the user having to ask for it first.
  • If the user specifies that they want you to run agents "in parallel", you MUST send a single message with multiple ${AGENT_TOOL_NAME} tool use content blocks. For example, if you need to launch both a build-validator agent and a test-runner agent in parallel, send a single message with both tool calls.
  • With isolation: "worktree", the worktree is automatically cleaned up if the agent makes no changes; otherwise the path and branch are returned in the result.${IS_REMOTE_ISOLATION_AVAILABLE_FN()?'\n- You can set isolation: "remote" to run the agent in a remote CCR environment. This is always a background task; you'll be notified when it completes. Use for long-running tasks that need a fresh sandbox.':""}${IS_SUBAGENT_CONTEXT_FN()?`
  • The run_in_background, name, and mode parameters are not available in this context. Only synchronous subagents are supported.:IS_TEAMMATE_CONTEXT_FN()?
  • The name and mode parameters are not available in this context — teammates cannot spawn other teammates. Omit them to spawn a subagent.`:""}${ADDITIONAL_USAGE_NOTES}${EXTRA_USAGE_NOTES}

${CAN_FORK_CONTEXT?SUBAGENT_TYPE_DEFINITIONS:DEFAULT_AGENT_DESCRIPTION}