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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, but the description adds substantial non-obvious behavior: no auth/PII, public endpoint rate limits (60 req/min, 250 calls/day), the result shape {data, meta}, meta field semantics (available, as_of, source_scope, weighting, units, cache_status, caveats, truncated), and critical guidance on handling meta.available=false (retry, never report as zero). This goes well beyond the annotations and is essential for correct invocation.

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?

Despite its length, the description is tightly structured: a one-line purpose, a bulleted list of nine topics each with its data payload, a compact use/do-not-use section, and a concise behavior paragraph. Every sentence adds unique value—rate limits, meta handling, and cache-warming are all critical and not stated elsewhere. There is no fluff or repetition; it earns its length.

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?

The tool is complex (nine topics, six parameters, one required) and the description fully equips an agent to call it correctly. It covers all topics and their data shapes, parameter scoping, behavioral constraints (read-only, rate limits, retry logic), result meta semantics, and how to handle unavailable data. An output schema exists (indicated by 'Has output schema: true'), so return-value details are already structured; the description complements rather than duplicates it. Nothing essential 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 coverage is 100% with each parameter individually described (e.g., gse enum with defaults, from_date/to_date ISO dates, top_n and max_points with ranges). The description adds cross-cutting meaning: which parameters apply to which topics (from_date applies to credit/prepayment/delinquency/loss/transitions history; top_n applies to transitions/modification/lock_in; max_points applies to time-series/vintage/transitions). It also clarifies topic-specific output shapes (data.series, data.latest, data.flows, etc.), which the schema does not cover. This enriches beyond the structured fields.

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 a precise statement: 'Fannie Mae and Freddie Mac single-family loan-performance analytics for exactly one topic.' It then enumerates nine distinct topics, each with its own data shape, and explicitly names sibling tools (search_lenders, get_lender_profile, get_market_snapshot, get_servicer_analytics) to say what it is not. An agent can immediately understand the resource, scope, and how it differs from alternatives.

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?

It provides an explicit 'Use for' list (agency credit quality, prepayment speeds, delinquency, roll and cure rates, modification outcomes, losses, lock-in effect) and a 'Do not use for' list that names the exact sibling tools to route to instead (originator volume -> search_lenders/get_lender_profile, today's rates -> get_market_snapshot, per-servicer -> get_servicer_analytics). This leaves no ambiguity about when to select this tool.

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