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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds genuine behavioral context beyond annotations: upstream-default ordering, lack of sorting support, and the instruction to follow llmContext guidance in results. This meaningfully shapes agent expectations about response ordering and downstream action.

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?

Four short sentences, each earning its place: purpose, filter strategy, ordering limitation, and a result-consumption note. The core purpose is front-loaded and there is zero redundancy with the schema or annotations.

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 7-param read-only list tool with 100% schema coverage, rich annotations, and an output schema, the description covers the non-obvious aspects: ordering, sorting limitation, and llmContext handling. The only minor gap is that 'parse group' is referenced but never defined, leaving the agent to infer its meaning from context.

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%, so the baseline is 3. The description adds value above that by grouping status, batchId, and fileNameContains as filters and recommending them over pagination — semantic guidance the schema alone does not convey. It does not duplicate the enum or format details already present in the schema.

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 uses a specific verb-resource pair ('List recent parse runs') and adds ordering scope ('newest first'). The parenthetical '(parse group)' distinguishes it from sibling list_*_runs tools (classify, extract, split, workflow) without ambiguity.

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 gives actionable usage guidance: 'Filter rather than paginate' names the preferred strategy and calls out status, batchId, fileNameContains as the filter dimensions. It also warns that sorting is unsupported. However, it never explicitly names alternative tools or states when NOT to use it, leaving sibling differentiation to inference.

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