ask_claude

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

With no annotations, description fully discloses safety and execution traits: default denial of Edit/Write/NotebookEdit, inclusion of inspection tools, `write=True` bypassing permissions and requiring HARDLINE_ALLOW_WRITE, advisory-mode neutralization/fail-closed auth checks, and the hang-to-timeout risk. This goes far beyond annotations (none provided) and clearly informs the agent of side effects and safeguards.

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 opening sentence delivers purpose; remaining paragraphs are dense, information-rich parameter explanations. The long run-on style with em-dashes and parentheticals makes it slightly harder to scan, but no sentence is superfluous.

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 6-parameter tool with no output schema, the description covers what responses include (ok/reply plus metadata for optioned calls), when the tool hangs, env-var gating, mode-specific behaviors, and compatibility defaults. It is sufficiently complete for an agent to invoke safely, though exact return structure is left unspecified.

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 0%, but the description compensates by explaining every non-obvious parameter: `model` pinning/default, `effort` values and default omission, `workdir` targeting and rejection, `write` opt-in semantics and prerequisites, and `mode` distinctions. Even `prompt` is inferable from the tool's purpose.

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?

Clearly states 'Ask Claude Code a question and wait for its reply'—a specific verb, target resource, and synchronous behavior. The phrase 'wait for its reply' and underlying `claude -p` reference distinguish it from async siblings like ask_claude_async.

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?

Provides detailed conditions: default/no-options behavior, when `write=True` is allowed/refused, and advisory-mode constraints. However, it never explicitly names alternative sibling tools or says 'use this when X vs async,' leaving comparison mostly implicit.

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