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

Annotations already establish the safe read-only, idempotent profile, so the description correctly spends its budget elsewhere. It discloses genuinely useful behavior: results are paginated, 'concise' caps the per-prompt array to a readable head while 'detailed' returns the whole page, and both stay under a response ceiling.

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?

Front-loads the purpose, then details return fields, then paging, then Args. Well-organized and every section is functional, though the long enumeration of returned fields is slightly heavier than needed since there is no output schema to lean on.

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?

With no output schema, the description fully compensates by enumerating the returned fields and per-result shape. Combined with pagination guidance, the response_format tradeoff, and annotations covering the safety profile, an agent has everything needed to call it correctly.

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 only 20%, so the description must carry the load, and it does: it documents run_id, the 1-500 range and default 100 for results_limit, the offset default for results_offset, and the semantic difference between the concise and detailed enum values. Only user_intent is left to the schema's own description.

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 verb and resource ('Get a single prompt research run') and immediately scopes the payload as 'the full analytics payload'. The singular 'a single run' and the pointer to get_research_runs for IDs clearly distinguish it from the plural list 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?

Gives clear usage context: retrieve one run by ID, fetch IDs from get_research_runs, and use results_limit/results_offset to page because runs routinely hold 500+ entries. It does not compare against adjacent siblings like get_latest_research, so it stops short of full when/when-not guidance.

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