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

Annotations already establish the safe-read, idempotent, closed-world profile, so the description's job is to add interpretive context—and it excels. It discloses the fact-class taxonomy (filed vs derived vs carried vs inferred) with the lower-bound caveat for summed pieces, and it pre-empts misreading with explicit guardrails: a mark below cost is not an impairment, a moved maturity is not an amendment, and non-accrual/default are never present. This directly prevents an agent from drawing false conclusions from result rows.

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?

Three dense sentences, each earning its place: scope and provenance first, then query-vs-filter mechanics, then fact-class semantics and interpretive guardrails. The density is justified given 13 parameters, no output schema, and high misinterpretation risk; nothing is fluff and the most critical caveats are saved for the end where they reinforce rather than distract.

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 tool this complex—13 params, no output schema, ambiguous query resolution—the description covers the data provenance, mode selection, fact classes, and interpretive guardrails well. What is missing is the result shape (row fields, pagination/next_cursor behavior beyond the schema's one-liner) and the semantics of `sort` and `held_only`. Since there is no output schema, the description carries more of the return-value burden than it fully discharges.

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 62%, so the schema handles roughly half the parameters. The description compensates where it matters most: `query` has no schema description but gets rich semantics here (trigram matching across names/aliases, distinct rows for adviser/BDC/ticker). It also explains how the filter parameters divide into provider-listing vs borrower-listing modes. Gaps remain for `sort`, `held_only`, and `limit`, which are neither described in the schema nor the 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?

The description names the resource (the private-market capital structure graph) and the data source (every BDC's schedule of investments since 2022), and states the tool searches lenders, BDCs, borrowers, sponsors, and credit funds. It distinguishes itself from siblings through its provenance and its query-vs-filter mechanics, though it never names a sibling it is not, so differentiation is implicit rather than explicit.

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 clear within-tool usage context: `query` is for name resolution (with trigram/alias semantics), and without a query, filters list either providers (class, state, BDC advisers only) or borrowers (sponsor, industry, minimum BDC lenders, maturity before, sort). It does not, however, name alternative sibling tools or state when to prefer them over this one, so cross-tool routing is left to the agent.

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