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

Goes well beyond the readOnlyHint annotation: it warns that construction-age values are estimates, not registry dates, that permit records only begin in 2016, and that 'not established' is stated explicitly rather than omitted. It also discloses the 4-token cost and the empty result for transactions with no buildings.

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 longer than average but every sentence adds necessary operational detail: what the tool returns, when to use it, data-quality caveats, and empty-result behavior. The key identifiers and usage are front-loaded, with caveats and cost after.

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 present, the description covers return fields (footprint area, number of storeys, estimated total floor area, construction-age estimate), the no-buildings edge case, cost, input origin, and usage context. An agent has enough to invoke it correctly and interpret results.

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 coverage is complete: the input schema already says transaction_id is a UUID from search_transactions/search_by_area/search_by_polygon that carries building data. The description mostly restates this, adding at most a pointer to 'the id shown on a search result'. It provides no substantial meaning beyond the schema.

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 opens with a specific verb and outcome ('Get the building-by-building breakdown for one transaction') and enumerates the exact fields returned (footprint area, storeys, estimated total floor area). It also explicitly distinguishes this tool from the search tools that return per-transaction building sums inline, so an agent can immediately tell what it does and what it is not.

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 clear when-to-use guidance: call it after a search when a result has building data and you need per-building detail, e.g. for a developed-land deed. It also contrasts it with search_transactions / search_by_area / search_by_polygon, which return sums, making the choice between sibling tools explicit.

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