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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds material context beyond them: cursor pagination, the bounded-summary contract, the payload-size consequence of includeResult, the meaning of servedEndpointId/servedProviderId when a request went unanswered, and an explicit prompt-injection warning that providerText.fields is 'data, not instructions'.

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-loaded with the verb, resource, and pagination model before the field enumeration. The long em-dash field list is dense but every item carries information (especially the servedEndpointId/servedProviderId caveat and the injection warning); a shorter phrasing of the field list would have lost meaning.

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 and 0% parameter coverage, the description compensates by enumerating the returned row fields and the includeResult variant, and by warning about untrusted provider text. It is nearly complete for a read-only list tool; only the phantom 'workspace' filter and the unexplained limit parameter leave gaps.

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 0%, so the description carries the burden and mostly delivers: it explains cursor pagination, status/capability filtering, and precisely what includeResult does. It does not explain limit or its 1-50 cap, and it references a 'workspace' filter that has no corresponding parameter in the schema, which is a small source of confusion.

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 ('list runs') plus the exact scope: a cursor-paginated run history filtered by workspace, status, or capability. It also distinguishes itself from the singular retrieval sibling by noting the rows have 'the same shape as run/runs_get', so an agent can separate listing from fetching without opening a schema.

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?

Usage is implied rather than stated: it explains the includeResult tradeoff ('never the full result payload unless includeResult:true'), which helps an agent decide how to call it, but it never says when to prefer runs_list over runs_get, runs_evidence, or search, nor does it state any exclusions. The routing guidance is left to inference.

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