Ask Claude

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

With no annotations, the description fully bears the burden. It clearly states Claude is advisory only (read-only, never modifies files), and that results include a session_id for continuation. This gives a complete behavioral picture.

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?

Single paragraph of 6 sentences, front-loaded with purpose and usage, then behavioral disclosure, then sibling references. Every sentence adds value; no wasted words.

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?

Given 5 parameters and no output schema, the description covers all essential aspects: purpose, usage, behavior, parameter hints, and continuation mechanism. It adequately references siblings for alternative scenarios.

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 coverage is 100% with descriptions for all 5 parameters. The description adds value by explaining the purpose of parameters in context (e.g., session_id continues conversation, workspace_dir should be reused). Slightly above baseline due to contextual hints.

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?

Description clearly states the verb ('ask') and resource ('Claude') with specific purposes: co-analysis, second perspective, or knowledge. It distinguishes from siblings by mentioning alternatives like claude_review_files for file-specific questions and claude_panel for structured multi-perspective reviews.

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?

Explicitly describes when to use: architecture trade-offs, tricky bugs, unfamiliar APIs, or independent expert view. Provides clear exclusions: prefer claude_review_files for file-specific questions and claude_panel for structured multi-perspective reviews.

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