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

Annotations already declare readOnly, idempotent, non-destructive, open-world, so the safety profile is covered. The description adds real value beyond them: it discloses the data source and operator, the default limit (20) and cap (100), newest-first ordering, and the default date windows. It omits auth/rate-limit context, which is the only remaining gap.

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 scope and data source are front-loaded, followed by filters, then return shape, then the routing sentence. Dense but each sentence carries information; only the explicit field list of return values is slightly redundant given the tool shapes output itself.

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 compensates by enumerating the returned fields (idcontrato, title, buyer, supplier, amount, CPV, dates) and explaining the compact-vs-full distinction. Combined with 100% schema coverage and safety annotations, an agent has nearly everything needed; only pagination behavior beyond 'newest-first' is unaddressed.

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 description coverage is 100%, so the schema already documents all 8 parameters in detail (partial match, Portuguese spelling, EUR amounts, YYYY-MM-DD). The description restates the same filter semantics without adding syntax or edge-case detail beyond what the schema provides, so the baseline 3 applies.

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 names a specific verb+resource (search Portuguese public-procurement awarded contracts), the exact data source (Portal BASE, base.gov.pt, run by IMPIC), and enumerates the five filter dimensions. It explicitly distinguishes itself from the sibling pt_contract_detail by routing the agent there for full records.

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?

It clearly states the search context (awarded contracts from Portal BASE) and names the alternative tool for detail lookups with the exact key to pass (idcontrato). There is no explicit 'when-not-to-use' guidance relative to other search siblings (e.g. pt_announcement_search), but the domain scoping is strong enough that an agent can pick correctly.

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