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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds valuable behavior: the 'first sight' ordering semantics, the exclusion of seeded rows unless include_seeded=true, and the use of next_since for polling. This goes beyond the annotations and clarifies the pagination model, which is essential for correct usage.

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 verbose with a long list of example change types ('Commitments and re-ups...', 'facilities marked down...') which adds color but is not essential for calling the tool. The core concept is front-loaded in the first sentence, but the subsequent examples and caveats could be trimmed. It's structured but not tightly concise.

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?

There is no output schema, so the description should explain the return value. It mentions 'next_since' and lists change types, but does not describe the response structure (e.g., fields per row, pagination format). It also doesn't clarify the event_type parameter's allowed values or the limit's effect. For a tool with 6 parameters and no output schema, the description is moderately complete but leaves some operational details uncovered.

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 descriptions cover 4 of 6 parameters (graph, since, dfx_id, include_seeded), but limit and event_type lack descriptions. The tool description does not explain these parameters either, so the gap remains. The description mentions next_since but doesn't map it to the since parameter. Since the schema covers the main parameters and the description adds no new parameter semantics, a baseline score 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 identifies the tool as a change tape for three specific capital graphs (allocators, private credit, real estate funds) and explains it returns rows by first-seen date. This clearly distinguishes it from general search tools, though the purpose is implied rather than stated as a direct verb like 'retrieves changes'. The resource and scope are explicit, but it doesn't explicitly say 'returns a list of changes'.

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 context for polling ('Poll with the next_since the answer returns') and notes that seeded rows are excluded by default. However, it does not compare this tool to sibling alternatives like search_private_credit_changes or changes_since, nor does it state when NOT to use it. The usage is implied for polling changes on these graphs, but lacks explicit routing guidance.

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