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

Annotations already declare readOnly=true and idempotent=true, but the description goes far beyond them by disclosing non-obvious behavioral semantics: a gap is non-reporting, never zero assets; GAV is filing-date assets, never fund size, commitments, or dry powder; quarantined readings add no sum; nothing reflects 2025 facts; and holdings appear only when a binding passed blind labels. These are exactly the kind of traps an agent would otherwise fall into.

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?

Although the description is longer than average, every sentence earns its place: the first sentence front-loads the return contents, then each subsequent sentence clarifies a distinct interpretation risk (gaps, GAV, tape range, holdings visibility). There is no filler or repetition of annotation data.

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 is responsible for explaining return values, and it does so thoroughly: reporting history, family sequence, commitment disclosures, holdings, events, accepted id types, data coverage period, and caveats. An agent has enough information to call the tool and correctly interpret the response for a read-only lookup.

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%: the schema already documents dfx_id as accepting a dfx:ref:<uuid> vehicle id, an 805-ADV fund id, or an 021-Form D file number. The description merely repeats these accepted id forms without adding syntax details, constraints, or examples beyond what the schema provides, 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?

The description opens with 'The vehicle card with its reporting history year by year' and then enumerates the exact contents: GAV, owners, minimum investment, fund type/name, family sequence, public plan commitments, validated holdings, and events. This clearly distinguishes get_re_fund_vehicle from siblings like search_re_fund_vehicles and get_re_fund_manager by naming a specific resource and its scope.

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 provides useful context—accepted identifier formats, the 2011–2024 tape range, and the meaning of gaps—but it never explicitly tells an agent when to choose this tool over alternatives such as search_re_fund_vehicles or get_re_fund_trends. There is no when-to-use / when-not-to-use guidance, leaving the routing decision partly to inference.

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