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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds context the agent couldn't otherwise get: an explicit price of $0.002 USDC per successful call via x402 on Base, Solana or Arc, with failed calls free, and a stated data-freshness marker (Bankrate's "rates as of" time) plus the ~60-day history window. It stops short of describing update cadence, rate limits, or caching.

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?

It opens with the core payload description, then the history detail, then the alternative tool, then pricing, so the most important information comes first. The product enumeration is long but useful for gauging coverage; the pricing sentence could be slightly tighter, but nothing is truly filler.

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?

Given an output schema exists, the description need not explain return values, and the annotations cover read-only behavior. The remaining agent-critical facts, the data and its source, the freshness timestamp, the history window, tool choice against the overlapping sibling, and the per-call cost, are all stated, so nothing needed to call this 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 coverage is 100%, so the baseline would be 3. The description adds meaning beyond the schema by enumerating exactly which loan products and purchase/refinance scenarios the request covers, and by quantifying the history parameter as "about 60 days" of daily 30-year fixed purchase rate and APR, which the schema's boolean "include the daily history" does not.

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 a specific verb and resource: the national average mortgage interest rate and APR from Bankrate, broken out by product (30/20/15/10-year fixed, FHA, VA, jumbo, ARM) for purchase and refinance, plus a ~60-day 30-year fixed history. It also names the sibling realestate_hmda_mortgage_loan_data and the different data it returns, so an agent can tell the two apart without reading schemas.

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 explicitly routes to a sibling ("realestate_hmda_mortgage_loan_data when you need official US mortgage application totals from the CFPB HMDA") and so covers the closest overlap case. It does not give broader when-not-to-use guidance against the many other real-estate siblings, nor does it describe prerequisites, but the one relevant exclusion is clear.

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