Get homes.com property + tax history (combined)

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

Annotations already cover readOnly/idempotent/openWorld, but the description adds substantial semantics beyond them: sections return `[]` when absent, `events_normalized` carries a cross-MCP-stable enum, and `price_change_pct` appears only on PriceChange rows while every other row uses `list_to_sale_pct`. That field-level contract is not inferable from annotations.

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?

Front-loaded with the combined purpose, then return shape, parameter, empty-series behavior, and enum semantics — each sentence earns its place given there is no output schema. It is dense, but the density is functional rather than redundant.

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 carries the full burden of explaining returns, and it does so: top-level keys, per-event row shape, and the meaning of each numeric field. An agent has everything needed to call and interpret the result.

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?

Only one parameter and schema coverage is 100%, so the baseline is 3. The description restates it ('Pass `url` — the full property detail URL'), adding mild emphasis over the schema's 'homes.com property detail URL or path' but no new syntax or format guidance.

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?

States a specific combined verb+resource ('Combined history endpoint') and explicitly names the two sibling tools it replaces, so an agent can distinguish it from homes_get_property_history and homes_get_tax_history without opening either schema. It also enumerates the exact return keys.

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?

Explicitly routes the agent: it 'replaces `homes_get_property_history` + `homes_get_tax_history` with a single fetch', which tells the caller when to prefer this tool over those two alternatives. The invocation requirement ('Pass `url`') is stated directly.

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