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

Annotations include readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds clarity by stating it is 'not a forecast, appraisal, or investment recommendation', which is a useful disclaimer. However, it does not disclose potential edge cases (e.g., what happens if geography is not found, or how recent the data is). With annotations covering safety, the description meets the baseline.

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?

The description is concise (three sentences) and front-loads the primary purpose and output. It efficiently packs use casesheb and a disclaimer without fluff. Every sentence earns its place, making it easy for an agent to scan and understand quickly.

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 the tool's moderate complexity (6 parameters, 100% schema coverage, no output schema), the description adequately covers what the agent needs: purpose, example outputs, and usage context. It doesn't explain the return format in detail, but with readOnly and idempotent annotations, it is reasonably complete. A minor gap is not describing the 'stable geography identifiers' field, but it is not critical.

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 schema already documents all parameters. The description adds some context by mentioning the type of data (e.g., 'self-hosted official series') and includes a 'stable geography identifiers' hint, but it doesn't add meaningful semantics beyond the schema. It doesn't clarify the format of 'place' beyond schema, but the schema has examples, so a baseline 3 is appropriate.

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 clearly states the tool summarizes FHFA HPI trend for a geography, listing the exact output metrics (latest index, changes, CAGR, direction). It provides concrete example questions that specify the resource (Texas, Miami). It does not explicitly distinguish from the sibling fhfa_hpi_compare or fhfa_hpi_series, but the purpose is clear and the examples are specific.

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 gives concrete use cases ('how fast are home prices rising in Texas?', 'is the Miami HPI falling?') and explicitly mentions using it as a public-data corroboration leg for 'realestate_market_screen'. It does not explicitly say when not to use it or mention alternatives like fhfa_hpi_compare, but the context provided is actionable and sufficient for common selection.

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