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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so safety and idempotency are covered. The description adds real behavioral context by explaining that compact mode drops photo and tour links while expand true keeps them, and that cost is the same either way. No annotation contradiction.

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 carry a large amount of useful information without fluff: the full output hierarchy and the compact/expand trade-off. The core resource is front-loaded and every clause earns its place.

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 does a good job enumerating the returned fields and the compact/expand distinction. The schema handles parameter semantics, though the description never explicitly states that callers must provide either buildingId or a lat/lng pair, since all parameters are optional in the schema.

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 parameters with descriptions, so the baseline is 3. The description mostly restates the expand behavior already documented in the schema and adds no new format, mutual-exclusivity, or source-guidance details for lat/lng or buildingId.

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 identifies the resource as floor plans of a rental building and enumerates the exact fields returned, including units and their availability. It is unambiguous and distinct from sibling tools, though it lacks an explicit imperative verb like 'retrieves' or 'lists.'

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 implies usage through the phrase 'Every floor plan of a rental building' and the focus on units, but it never explicitly says when to choose this tool over siblings such as zillow_building or zillow_search_listings. There is no when-not-to-use guidance or alternative routing.

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