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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered by structured data. The description adds genuinely useful behavior beyond that: results are ids, titles and canonical URLs pointing at live portfolio data, and the intended follow-up is a fetch by id. It does not cover result volume, ranking, or what an empty match looks like, and since an output schema exists the return-shape detail is partly redundant.

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 purpose, then the search-to-fetch workflow, then a worked example, in four short units with no filler. The example argument is slightly duplicative of the schema example but serves as a quick usage cue rather than padding.

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?

For a one-parameter read-only search with an output schema and full annotation coverage, the description supplies everything essential: scope, return type, and the follow-up call. Minor gaps remain around result limits and how it relates to the structured property-search sibling, but nothing blocks a correct invocation.

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?

With one parameter at 100% schema coverage, the baseline is 3, but the description earns extra credit by showing that the single query field spans two domains (properties and guides such as "IMT costs") and by supplying a concrete natural-language example argument. This tells an agent how to phrase queries across both corpora, which the schema's single example does not fully convey.

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 and resource with scope: "Free-text search over Metastate's live property portfolio in Portugal and its guides", and even enumerates guide topics (INE prices, purchase costs, foreigners). It clearly separates itself from the fetch sibling by explaining that fetch with an id returns full content. It stops short of 5 because the sibling pesquisar_imoveis (structured property search) is not addressed, leaving ambiguity about which search path to pick for property queries.

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 prescribes the two-step workflow: search here, then "use fetch with an id for the full content", which is the key alternative an agent needs. It also frames itself as the standard search/fetch interface for deep research, implying when the pattern applies. No exclusions are given relative to structured property search or the guide-specific tools in the sibling list.

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