public_contracts_summary

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

No annotations are provided, so the description carries the full burden; it implies a read-only aggregation and discloses the shape of the summary (counts, totals, procedure breakdown, top counterparties). It does not state the underlying data source or coverage, whether entity names are fuzzy-matched, or how the ranking in 'top partners' is computed (by value or by count).

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 summary sentence is front-loaded and wastes no words, followed by a tight per-argument block. Slightly telegraphic phrasing ('by procedure, top partners') but nothing extraneous.

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 four parameters at 0% schema coverage and an output schema present, the description does cover the calling surface adequately. What it leaves out is the routing question an agent actually faces: how this differs from `public_contracts`, and how ambiguous entity names are handled.

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 0%, so the description must carry all parameter meaning — and it largely does: `entity` accepts a name or 9-digit NIF, `role` takes buyer/supplier/any (values the schema does not enumerate), `year` defaults to the current year, `top` is the count of counterparties to list. The only gap is a small inconsistency: the schema default for `year` is null while the description says 'this year', without confirming null means current year.

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 states a concrete resource (public contracts) and an aggregate operation (totals for one entity in a year), and enumerates the output dimensions: count, total value, breakdown by procedure, top partners. That is enough to distinguish it from a raw listing tool. It stops short of naming the sibling `public_contracts` explicitly, so the differentiation is inferred rather than stated.

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?

Usage is implied by the word 'totals' versus the sibling `public_contracts`, which presumably returns individual contract records, but the description never says when to prefer one over the other. There is no guidance on prerequisites, entity-name resolution, or what happens when a name matches multiple bodies.

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