Ask Claude

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, openWorldHint=true, and readOnlyHint=false, and the description adds meaningful context: 'There is no enforced read-only sandbox,' which reinforces the permission risk. It stops short of explaining what could be destroyed or the implications of permission_mode/bypassPermissions, which would be valuable for a destructive tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences, no filler, and the core capability plus the return-value hint are front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter, non-idempotent, destructive, open-world tool with no output schema, the description omits key behavioral context such as permission-mode risk, timeout behavior, and tool-preservation on follow-ups. Adequate but with clear gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 57%, and the description adds no parameter-level detail beyond what the schema provides. It mentions session_id as a return value but doesn't illuminate the model, effort, timeout_sec, or permission_mode semantics that remain only lightly documented in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific action (start an independent Claude Code session in a project), names what it enables (Claude can inspect the project and perform the task), and the output (session_id). The mention of session_id for follow-ups implicitly distinguishes it from the claude_followup sibling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The 'session_id for follow-ups' note implies when to use claude_followup next, but the description never explicitly states when-not to use this tool or the condition that selects the sibling. Usage is left to inference rather than spelled out.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.