compare_mortgage

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

Annotations already establish read-only, idempotent, non-destructive behavior. Description adds behavioral constraints (single year, same geographic level, side-by-side summaries with specific metrics) and source, going beyond the basic safety profile.

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 concise sentences with all information front-loaded. The first sentence states the purpose, the second the constraint, the third the output and source. No filler content.

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?

No output schema exists, so description compensates by specifying the side-by-side summaries and included metrics. Covers purpose, constraints, output, and data source. Could mention data derivation or availability caveats, but overall adequate for a read-only comparison tool.

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 has 100% coverage and already explains area_type, geoids, and year. Description reinforces the 2-5 area count and same-level constraint, but adds no new parameter details beyond what the schema provides, so it sits at the baseline.

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?

Description uses specific verb 'Compare' with resource 'mortgage lending metrics' and scope '2-5 geographic areas' for a single HMDA year. It lists concrete metrics (origination count, denial rate, median loan amount) which distinguishes it from sibling tools like compare_demographics or get_mortgage_summary.

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?

Clearly implies use when comparing mortgage metrics across multiple areas in a single year, with the constraint that all areas be the same geographic level. Doesn't explicitly name alternatives or exclusions, but 'across 2-5 geographic areas' provides clear context compared to single-area mortgage tools.

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