Analyze Case

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

Even with no annotations, the description fully discloses key behaviors: it consumes AI credits, is asynchronous, returns immediately with processing status, may return existing analysis with alreadyExists=true, force re-analyzes and re-consumes credits, and fails if no usable content exists. This exceeds transparency expectations.

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?

The description is compact yet comprehensive, with each sentence serving a distinct purpose: primary action, credit consumption, async/polling behavior, existing-analysis behavior, force behavior, and failure condition. 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 the tool's complexity (async, credit consumption, subtle id matching, conditional re-analysis) and the absence of an output schema, the description covers all necessary operational details. It provides a complete mental model for correct invocation and follow-up.

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?

The schema already documents both parameters with 100% coverage, providing a baseline of 3. The description adds meaningful semantics beyond the schema: the id lookup order (ObjectId parse attempt followed by case number fallback), including the 404 edge case, and that force consumes credits again. This enriches parameter understanding.

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?

The description clearly states the tool's function: 'Triggers AI analysis of a single case.' It distinguishes from siblings, notably 'analyze_consolidated_case' (consolidated cases) and 'get_case_analysis' (retrieval), by focusing on the triggering action and mentioning polling for results.

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 description provides clear usage context: it explains the asynchronous flow, says to poll 'get_case_analysis' after 30-60 seconds, and describes when to set 'force' for re-analysis. It does not explicitly name alternative tools for excluding, but the implicit guidance is strong.

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