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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds value beyond them by disclosing the return shape ('summaries with links') and the topical breadth, though it says nothing about result limits or empty-result behavior (limit is capped at 5 in the schema).

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, front-loaded with purpose and domain, second sentence covering return shape and the sibling handoff. No filler or repetition of the title.

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 usefully states that results are summaries with links, and the get_guide handoff defines the depth boundary. Minor gaps: the undocumented limit parameter and no note on how many results to expect by default, but nothing that would cause a mis-call.

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 67%: query and language are already documented in the schema, while limit (default 5, max 5) is undocumented anywhere. The topic examples in the description implicitly clarify what a good query looks like, but the description adds nothing about limit or the effect of language beyond what the schema states. 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?

States a specific verb (search) and a clearly scoped resource: Huisly's own editorial guides, not listings or place data. The parenthetical topic list (rental contracts, deposits, transfer tax, mortgages, city moving guides) makes the content domain unmistakable and separates it from search_listings.

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 to the sibling get_guide when it needs the outline, FAQs and official sources of a single guide, which is exactly the right next-step guidance. It stops short of stating when to prefer search_listings or get_place_insights over this tool, so the exclusion set is only partially drawn.

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