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

The annotations already declare readOnlyHint=true, so the description does not need to rehash safety. It adds valuable behavioral context beyond the annotations: the data source (FRED HOUST since 1962), the calculation methodology (percent deviation from trailing mean), and the update frequency (monthly). This enriches the agent's understanding of data vintage and semantics without contradicting the read-only hint.

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 two sentences: the first delivers the core output and methodology, the second lists usage triggers. 'Updates: monthly.' is a concise, informative fragment. Every sentence earns its place with no redundancy or 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?

With one optional parameter, no output schema, and read-only annotations, the description covers the essential context: what the score represents, the data source and calculation, the three returned fields, and the specific scenarios where the tool is relevant. The optional 'days' parameter is fully explained in the schema, so its absence from the description does not create a completeness gap.

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?

The schema covers 100% of the single parameter 'days' with a detailed description of its optional history-series behavior, Gold tier requirement, and value range. The description does not add meaning beyond the schema for this parameter, so the baseline of 3 is appropriate. It does not compensate with additional param detail, but none is needed given full schema coverage.

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 returns a 0-100 US housing-starts momentum score, specifies the data source (monthly FRED HOUST) and calculation method (recent value vs trailing-mean percent deviation), and lists the exact output fields. This specific verb+resource combination distinguishes it from generic sibling tools and leaves no ambiguity about what the tool does.

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 provides explicit when-to-use triggers: 'Call when the user asks about housing starts, homebuilding, whether US housing construction is accelerating or stalling, or the residential real-estate cycle, or when timing homebuilder and building-materials equity overweights or tactical sector rebalancing.' It gives clear context but does not mention when-not-to-use or name alternative tools, so it falls short of a 5.

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