get_analysis

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description goes far beyond by detailing the live progress fields, the full result object with all possible indeterminate_reason values, and the immutable usage snapshot. This adds significant behavioral context about what to expect in various states.

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 long but every sentence provides essential information about the response format and edge cases. It is front-loaded with the core action and then systematically enumerates fields and their meanings, with no filler or redundancy.

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 single-parameter fetch tool with complex response semantics, the description is exceptionally complete. It covers the running state, completed result fields, the usage snapshot, and explains each indeterminate_reason, leaving no major gaps for an agent to invoke or interpret the result.

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 a clear parameter description ('The analysis id (an_…).'). The tool description does not add extra meaning about the parameter itself, so the baseline of 3 is appropriate.

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 starts with 'Fetch an analysis by id (GET /v1/analyses/{id})', a specific verb+resource that exactly matches the tool name and clearly distinguishes it from siblings like wait_for_analysis or create_analysis. It also provides a detailed preview of the response, reinforcing what the tool does.

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 implies usage by explaining the behavior during running and completed states, but it does not explicitly state when to use get_analysis instead of sibling tools like wait_for_analysis. There are no exclusions or alternative recommendations, so it stops at implied context.

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