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

Despite annotations covering only readOnlyHint, the description discloses rich behavior beyond structured fields: flagged_pct is a percentage over the determinate-flag denominator (never total_debt_fv), is deliberately NULL when determinate coverage is under 90% or a parse misread is suspected, trend ordering is oldest-first, quarters is capped at 24, and caveats ride tool_notes. This is exactly the withheld-vs-zero distinction an agent needs.

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?

Dense but front-loaded: the purpose leads, then return shape, then the critical null semantics, then defaults, pairings, and source. Nearly every clause earns its place, though the single long sentence carrying the null/denominator logic is somewhat hard to parse at speed.

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 carries the full burden and does so: it names the return keys ({summary, ticker, latest, trend}), explains the trend ordering, defines the null-vs-zero behavior of flagged_pct, and points to where caveats live. Nothing an agent needs to interpret the response correctly is missing.

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 100%, so the two parameters (ticker, quarters) are already documented with examples and default/cap. The description restates the quarters default and cap but adds no new parameter-level syntax or format detail, so baseline 3 applies.

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 resource and measurement ('share of debt fair value on non-accrual in the latest filing, plus the trailing-quarter trend'), and explicitly names the sibling tools it pairs with. An agent can distinguish this credit-deterioration signal from ol_bdc_top_borrowers or ol_bdc_mark_changes without opening the 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?

Provides clear usage context: it names the paired tools (ol_bdc_borrower_dispersion, ol_bdc_top_borrowers) and instructs the agent to 'read coverage_state before reading flagged_pct'. It stops short of an explicit when-to-use/when-not statement versus alternatives, so it is clear context without hard exclusions.

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