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

Annotations already cover readOnly, idempotent, non-destructive and open-world, so the safety bar is low; the description still adds real context by disclosing the upstream source (Freddie Mac PMMS), the return shapes, the derived high/low/change over the range, and the default window. It does not state units (rate in percent), whether weeks with no survey are omitted, or how the frequency default escalates past 3 years (that detail sits only in the schema).

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?

Two sentences, no filler, with the core resource and output capability front-loaded and the default behavior placed last where it belongs. Every clause carries new information.

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 must carry return-value burden, and it does: it names the row shapes and the aggregate fields. Minor gaps remain around units and handling of gaps or empty ranges for a 4-parameter, all-optional tool, but nothing an agent needs to invoke it 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 baseline would be 3; the description earns the bump by tying start/end dates to the computed high, low and change over the range and by clarifying that the 30/15 term selects a fixed-rate product family and that frequency controls row size. It adds framing rather than syntax detail, which is appropriate given the schema documents formats and enums.

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?

Names a specific resource (Freddie Mac PMMS 30-year / 15-year fixed averages) and a specific operation (history between two dates), and immediately states the output shapes: weekly rows or monthly/annual averages with high, low and change. This scope cleanly separates it from the point-in-time siblings get_mortgage_rate_on_date and get_mortgage_rates_today without needing to name them.

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 range-based framing plus the stated default ('last 52 weeks of the 30-year rate') makes it clear this is the tool for trends and aggregates rather than a single quote, which implicitly routes the agent away from the on-date and today siblings. It stops short of explicitly naming those alternatives or stating when *not* to use it.

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