MCP Compras.gov.br

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description additionally discloses important runtime behavior: count mode reads only totalRegistros, value modes scan pages, the 25-page/12,500-record cap, truncado=true signaling, internal concurrency of 4 calls, and a 30-minute cache. This is excellent transparency beyond the annotations.

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 compact and well-structured with bolded mode headings. Every sentence carries useful information: mode semantics, performance characteristics, limits, truncation behavior, concurrency, and cache. There is no filler or repetition of schema content.

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?

The output schema and annotations already cover return values and safety semantics, so the description only needs to cover behavior and limits, which it does thoroughly. The main gap is the lack of explicit routing guidance against similar aggregation/indicator siblings, but this is minor for a tool with this much structured support.

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 each parameter, establishing a baseline of 3. The description adds value by explaining what the 'metrica' modes actually do mechanically and by documenting the truncation ceiling and page-scan behavior, which is not fully captured in 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 opening line clearly states the tool produces a time series of PNCP contracting data grouped into buckets, which is a specific verb+resource pairing. It is clearly an aggregation tool and distinct from the many single-record/list lookup siblings, though it never names a sibling explicitly.

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 strong within-tool guidance: use 'count' for trends, only enable value modes when necessary, and notes that the 'esfera' filter only matters in value mode. It does not explicitly compare against siblings like compras_comparar_periodos_contratacoes, but the context is clear enough for an agent to decide when this aggregation is appropriate.

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

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

Annotations already cover read-only, idempotent, non-destructive, and open-world traits. The description adds value beyond those by disclosing the underlying endpoint path, the 15-minute cache behavior, and the semantic content of the response in terms of demand and legal limits.

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 compact and front-loaded: the core purpose appears in the first sentence, followed by endpoint traceability, use-case interpretation, and cache behavior. Every sentence earns its place without redundancy.

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?

The tool has full schema documentation, a clear output schema, and annotations covering safety profile. The description adds the remaining context an agent needs: what the tool returns, why that matters, and a cache freshness caveat. Nothing essential is missing.

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 description does not need to repeat parameter meanings. It correctly leaves parameter details to the schema and only adds domain-level context about ARP adhesions, which is useful but not required for parameter understanding.

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 specific verb and resource: 'Lista adesões (caronas) já realizadas a uma ARP'. It clarifies the output ('quem aderiu e com que quantidade') and distinguishes its focus from sibling tools like saldo_item or unidades_item by emphasizing demand and remaining legal adhesion limits.

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 makes the use context clear: use when you need to see which entities adhered to an ARP and in what quantities, and to assess demand level or remaining adhesion capacity. It does not explicitly mention alternatives or exclusions, but the intended scenario is well implied.

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

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

Annotations already declare read-only, idempotent, and open-world; the description adds substantial behavior beyond them: internal pagination up to max_paginas_varridas, client-side filtering, short-circuit at max_resultados, accent-normalized case-insensitive matching, and a 15-minute cache keyed by (palavra_chave + janela + caps). The bounded pagination honestly signals that the search is capped and not exhaustive, consistent with openWorldHint. No contradiction with annotations.

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?

Purpose is front-loaded in the first sentence, followed by mechanism, rationale, known limitation, and output shape in a clearly partitioned structure. The internal provenance note ('Achado da bateria A v0.3.5') adds no value for an agent, and the 169k/339-page anecdote, while illustrative of latency motivations, is slightly longer than strictly necessary.

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?

Complete for the tool's complexity level: it defines the output object inline, discloses the bounded-search behavior, the caching semantics, and the missing-UF limitation with a concrete remediation path. Nothing an agent needs to invoke it correctly or interpret results properly is absent.

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 100% with well-documented individual parameters, so the baseline is 3. The description adds meaning by explaining how the parameters interact — page scanning up to max_paginas_varridas, short-circuiting when max_resultados is reached, and the cache key spanning keyword+window+caps — which the schema does not convey. Not a 5 because the schema already carries most per-parameter semantics.

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+resource+scope: searches current ARPs whose `objeto` contains a keyword, with case-insensitive and accent-normalized matching. It references the exact upstream endpoint it builds upon and explicitly calls out the scenario it was created for (oportunidades_carona_arp), clearly distinguishing it from siblings like compras_arp_por_fim_vigencia and compras_arp_consultar.

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?

Explains why the tool exists — the upstream endpoint /modulo-arp/1.2_consultarARP_FimVigencia does not accept text filters — and when it applies (keyword search in `objeto`). It also gives an explicit when-not: for UF filtering it instructs crossing matches with compras_uasg_consultar via codigoUnidadeGerenciadora, naming the exact alternative and the reason.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds valuable behavioral context: it detects compra-format IDs and returns an explicit diagnostic, and it mentions a 15-minute cache. These are beyond what annotations provide, enhancing transparency about the tool's behavior in edge cases.

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 concise and well-structured. It front-loads the main purpose, then provides the endpoint, return content, a special behavior note, and cache info. Every sentence adds value without redundancy. It's appropriately sized for a single-parameter tool.

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?

The description covers the essential aspects: what it does, what it returns (header fields), and a specific edge case. Given the tool has an output schema (not shown but referenced), the description doesn't need to detail return structure. It lacks explicit error handling beyond the format issue, but that's minor. Overall, it's complete enough for an agent to call it correctly.

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 100%, and the schema already provides a detailed description of the parameter, including format, example, and a warning about confusion with compra ID. The description adds a bit about the diagnostic behavior, but that is more behavioral than parameter semantics. Since the schema does the heavy lifting, a baseline of 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?

The description clearly states the tool's purpose: 'Consulta uma ARP específica pelo identificador PNCP.' It specifies the exact resource (a specific ARP) and the identifier format, and it mentions the endpoint and return content. This distinguishes it from sibling tools like compras_arp_listar (which lists many) and compras_arp_por_fim_vigencia (which filters by date).

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 implies when to use this tool: when you have a specific ARP identifier. It also provides a clear usage warning: if the identifier is in compra format (without the '-NNNNNN' suffix), the tool returns a diagnostic instead of a silent false. This is a practical guideline. However, it does not explicitly mention alternatives or when not to use it, though the specificity is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds valuable behavioral context: the upstream endpoint, the ≤365-day window constraint, and a 15-minute cache, none of which appear in annotations. It does not over-promise or contradict annotations.

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?

Three short, dense sentences front-load the core purpose and then provide endpoint, constraint, filter tip, and cache details without repetition. Each sentence adds distinct useful information.

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?

Given the existing output schema and annotations, the description covers the essential operational facts: required window, max 365 days, optional filters, and cache behavior. It does not discuss pagination limits or authentication, but these are visible in the schema/annotations and are not critical gaps.

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 covers 100% of parameters, but the description goes beyond it by warning that the upstream requires the date-range pair and that the window cannot exceed 365 days—a constraint absent from the schema. It also gives the optional filters a purpose ('localizar atas com um item específico').

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 specific action and resource: listing ARP items within a supplied validity window, and identifies the exact upstream endpoint. It does not, however, explicitly differentiate itself from sibling tools such as compras_arp_listar or compras_arp_consultar, relying on the tool name to imply the item-level scope.

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 provides clear context for when the tool applies—list ARP items in a date window—and even offers a filter tip for finding atas with a specific item. But it never names alternative tools or conditions under which another sibling should be preferred, so usage guidance remains implicit.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds meaningful context beyond those: the upstream open-data endpoint, the 365-day window constraint, and the 15-minute cache. This is useful supplementary behavioral information without contradicting annotations.

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 compact and front-loaded: purpose, endpoint, constraint, alternative, and cache are each communicated in tight, purposeful sentences. There is no filler or redundant restatement of schema details.

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?

Given that there is a rich output schema and annotations already cover safety and idempotency, the description provides all essential context for correct invocation: what it lists, the upstream constraint, the sibling alternative, and caching behavior. Nothing critical is missing.

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%, and each parameter is already well-documented in the input schema. The description reinforces the 365-day window rule but does not add substantial new parameter-level meaning, so the baseline score of 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?

The description starts with a specific verb and resource: 'Lista Atas de Registro de Preço (ARPs) por janela de início de vigência.' It clearly defines what the tool does and explicitly distinguishes it from the sibling compras_arp_por_fim_vigencia.

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 gives explicit guidance: the upstream requires a date window of at most 365 days, and it names the exact alternative to use for ARPs near expiration ('Para listar atas próximas do vencimento, use compras_arp_por_fim_vigencia'). This is clear when-to-use and when-not-to-use direction.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds meaningful behavioral context beyond annotations: the specific open-data endpoint path and the 15-minute cache, which alerts agents to potential data staleness.

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?

Three short sentences, each earning its place: the main functionality, the endpoint reference, and the cache behavior. No fluff or repetition of schema details.

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 a rich output schema, complete parameter descriptions, and safety annotations, the description covers the remaining essentials: purpose, endpoint, cache, and use case. It is adequately complete for an agent to invoke correctly, though it could optionally mention the 365-day window or pagination, both already present in the schema.

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?

The input schema has 100% parameter description coverage, so the schema fully explains each parameter. The description's 'intervalo informado' phrase loosely reinforces the date-range parameters but adds no additional semantic value 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 resource: 'Lista ARPs' whose vigência ends within a given interval. This clearly differentiates it from siblings like compras_arp_listar or compras_arp_consultar by focusing on the end-of-vigency date range criterion.

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 provides a clear use context: 'Permite ao gestor identificar atas próximas do vencimento.' This tells the agent when this tool is relevant, though it does not explicitly state exclusions or name alternative sibling tools.

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

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

Beyond the annotations, the description discloses useful behavior: the upstream returns one row per (numeroItem, unidade, tipo), repeated numeroItem values are not duplicates, a `resumo_por_item` aggregation is attached to avoid ambiguity, and there is a 15-minute cache because balance changes throughout the day.

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 well-structured, front-loaded with the main purpose, and uses tight sections for complexity, risk context, payload shape, aggregation, and cache behavior. It slightly overshoots with an internal provenance note ('achado bateria A v0.3.5') that carries little value for an agent selecting the tool.

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 read-only, idempotent query tool, this is complete: it covers when the result matters, what the payload looks like, why repeated rows should not be treated as errors, what aggregated summary is available, and how current the data is. The output schema exists, so return-value structure does not need to be fully repeated here.

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 parameter documentation already explains `numero_ata`, `unidade_gerenciadora`, `pagina`, and `tamanho_pagina`. The description adds no parameter-specific semantics beyond what the schema already provides, making the baseline 3 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?

The description clearly states the verb and resource: it returns the remaining balance (`saldo`) per ARP item, and even defines `saldo` as 'quantidade ainda disponível'. The resulting concept ('saldo por item') is distinct enough to set it apart from sibling tools such as `compras_arp_itens_listar` and `compras_arp_unidades_item`.

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 gives a strong when-to-use signal: the tool is described as critical for adhesion decisions because the ata may be valid but the balance zero. It does not, however, name alternative tools or explicitly say when not to use this one, so it falls short of a 5.

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

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

Annotations already cover the read-only, idempotent, non-destructive profile. The description adds useful behavioral context by naming the underlying Dados Abertos endpoint and the 15-minute cache, which is meaningful beyond the annotations. It does not contradict annotations.

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 three short sentences with zero filler. The core purpose is front-loaded in the first sentence, followed by the endpoint reference and a brief cache note. Every sentence earns its place.

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 simple listing tool, the description is complete: it states the resource scope, the endpoint, caching behavior, and the semantic distinction from actual adesões. The output schema exists, annotations cover safety, and the input schema fully documents parameters, so nothing needed for correct invocation is missing.

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?

The description itself does not elaborate on parameters, but schema description coverage is 100%, including the disambiguation note for numero_ata versus numeroControlePncpAta. Per the baseline rule, a fully covered schema makes 3 appropriate even without parameter-specific info in the description.

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 uses a specific verb+resource combination: 'Lista UGs participantes (potenciais caronas) de um item da ARP.' It clearly defines the returned entities as potential carona units, which distinguishes it from the related sibling compras_arp_adesoes_item. The added explanation 'quais unidades podem usar a ata como carona (adesão)' reinforces the precise scope.

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 clearly implies when to use the tool: to determine which UGs are eligible to use an ARP item as carona/adesão. It does not explicitly name alternatives or exclusions, but the phrase 'potenciais caronas' provides enough contextual contrast with actual adesão tools. A direct reference to compras_arp_adesoes_item would make it a 5.

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

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

Beyond the readOnly/idempotent/destructive annotations, the description discloses substantial behavioral detail: the composite data-source flow, deduplication by PNCP control number, the split response payload, and the 60–90s latency on cold cache with expected <1s with Redis. This gives the agent realistic expectations for execution time and response shape.

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 dense but well-structured, starting with the one-line purpose, then composition, limitations, and latency warning. Every paragraph earns its place, and formatting with bold emphasizes the key caveat sections without unnecessary filler.

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?

Given the complexity of the federated operation, the description covers data sources, filtering boundaries, internal logic, latency, and output payload indications. With an output schema present and annotations marking the operation as safe and idempotent, nothing essential is missing for an agent to invoke the tool correctly.

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 100%, so the baseline is 3, but the description adds meaningful parameter semantics: max_resultados controls the most recent deduplicated results, and codigo_catmat/codigo_catser only filter the Dados Abertos leg while PNCP runs best-effort by modality. This adds value beyond the schema's field descriptions.

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 clear statement that the tool federates Dados Abertos and PNCP to find similar contratações, which is a specific verb and resource. It further clarifies the composition by mentioning item-level querying, PNCP deduplication, and returning the most recent max_resultados, making it easily distinguishable from sibling tools.

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 states the intended use case ('Insumo para mapear benchmarks de outros órgãos') and gives important limitations, such as PNCP not accepting catalog-item filters and CATMAT/CATSER only applying to the Dados Abertos side. It does not explicitly name alternative tools or exclusion conditions, but the context is clear enough for an agent to decide when to call it.

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

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

The description goes well beyond the readOnly/idempotent annotations: it discloses that termo is deliberately not sent to the upstream endpoint (sending it would return ~340k items), that the tool emits _aviso_filtro when the structural cut is too broad, and that results are cached for 24h. However, the input schema's termo description ('Aceita fragmento — a API faz match parcial') directly contradicts the main description's 'Não existe busca por substring nesta API', giving the agent two opposing models of the tool's core behavior.

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?

Every sentence earns its place: the critical warning is front-loaded, the explanation of why termo is not sent upstream prevents a costly mistake, and the workflow and cache notes are compact and actionable. Though long (~230 words), the length is justified by the counter-intuitive behavior it must convey, and the emoji/bold formatting makes the warning stand out.

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?

Given rich annotations, 100% schema coverage, and an existing output schema, the description covers all essentials and even adds payload-level behavior (_aviso_filtro) and cache semantics. It falls just short of complete because the conflicting termo semantics between the schema and the description are never reconciled, which could mislead an agent at invocation time.

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 100% schema coverage the baseline is 3, but the description adds decisive meaning beyond the schema: termo's real role (ordering/marking, not filtering) is only explained here, and it reinforces codigo_pdm as the most precise cut and codigo_grupo as strongly recommended. The gain is offset by the schema's contradictory claim that termo does partial matching, which muddies the semantics of the only required parameter.

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 opening line 'Busca itens CATMAT' states a specific verb and resource, and the body sharpens the purpose: this tool searches the CATMAT catalog using structural filters (codigo_grupo, codigo_classe, codigo_pdm), with termo used only for ordering/marking results. The workflow explicitly names sibling tools (compras_catmat_listar_grupos, compras_catmat_listar_classes, compras_catmat_listar_pdms), distinguishing it from neighboring catalog tools.

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 'Workflow recomendado' section gives an explicit 4-step sequence that names the sibling tools and lands on this tool, telling the agent exactly when to call it. It also marks codigo_grupo as FORTEMENTE RECOMENDADO because the upstream text filter is broken, and states what NOT to expect (no substring search, termo never sent upstream), leaving no ambiguity about when this tool is appropriate.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond the schema by disclosing the 24h cache, and it does not contradict the annotations.

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 compact and front-loaded with the core action, followed by the returned data, a practical use case, and the cache note. Every sentence earns its place and there is no redundancy.

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 only one parameter, a fully covered input schema, an output schema, and annotations covering safety, the description provides all necessary context: what it does, what it returns, when to use it, and the 24h cache behavior. Nothing essential is missing.

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 input schema fully documents the codigo_item parameter, including type, length, and example. The description only says 'pelo código', adding no semantic value beyond the schema; 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?

The description opens with a specific verb and resource: consult details of a specific CATMAT item by code. It then enumerates the returned fields (nome, PDM, grupo, classe, características, NCM, unidades), which clearly distinguishes this lookup tool from sibling tools like compras_catmat_buscar or listar_classes.

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 an explicit use case: confirm the item code before searching prices or listing similar contracts. It does not name alternatives or state when not to use the tool, but the context is clear enough for an agent to select it appropriately.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds useful behavioral context beyond annotations, notably the 'Cache de 24h' behavior and the hierarchical relationship of classes to groups. There is no contradiction with annotations.

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 compact and front-loaded: the first sentence states the action and optional filter, the second adds hierarchy context with an example, and the third notes caching. Every sentence earns its place without redundancy.

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 simple read-only list tool with three optional, fully documented parameters and an output schema, the description is complete. It explains the data hierarchy, optional filtering, and caching, so an agent has enough context to invoke it correctly.

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 three parameters. The description adds context about the group filter and hierarchy but does not meaningfully extend parameter semantics beyond what the schema provides.

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 specific verb+resource: 'Lista as classes do CATMAT', with an optional group filter. It also places classes in the hierarchy with a concrete example, which clearly distinguishes it from sibling tools like compras_catmat_listar_grupos.

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 conveys that this tool is for listing CATMAT classes, optionally filtered by group, and clarifies the hierarchy level. However, it does not explicitly say when to prefer it over alternatives such as compras_catser_listar_classes or compras_catmat_listar_grupos; usage is implied rather than stated.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds useful behavioral context about caching (24h) and the total number of groups (~79), which helps the agent manage expectations about data freshness and scale. No contradictions with annotations.

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 concise and well-structured: a clear listing statement, hierarchy context, usage guidance, and a caching note. All sentences add value without redundancy.

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 simple two-parameter list endpoint with a complete input schema and output schema, the contextual information provided (hierarchy, usage, cache, total count) is sufficient for an agent to invoke it correctly. No missing essential details.

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?

The input schema fully documents both parameters (pagina, tamanho_pagina) with descriptions. The tool description does not add additional parameter details, so the baseline score of 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?

The description clearly states that the tool lists CATMAT groups, defines them as the highest hierarchy level, and provides examples. It also distinguishes this from sibling tools by mentioning descent to classes/PDMs/items.

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 explicit guidance: use this tool to frame contracting in the correct group before descending to classes/PDMs/items. It also notes that groups change rarely and caching is appropriate, helping the agent decide when to call this vs. other catalog tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavior beyond annotations: the endpoint has no textual filter, one class call returns dozens of named PDMs, and results are cached for 24h. No contradiction with the annotations exists.

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 front-loaded with the core action, then builds context in tight, purposeful paragraphs: endpoint, hierarchy role, example, limitation, sibling routing, and cache. Every sentence earns its place by aiding tool selection, parameter choice, or understanding behavior, with no redundancy.

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?

Given zero required parameters, 100% schema coverage, a present output schema, and comprehensive annotations, the description supplies all remaining context needed: the endpoint, hierarchy position, no-substring-search limitation, recommended sibling workflow, example scale, and cache behavior. An agent can invoke and integrate this tool correctly without guessing.

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 all six optional parameters are already documented. The description adds meaningful extra context, especially for codigo_classe, highlighting it as 'o recorte mais útil' and giving a concrete example (class 7110 has 98 PDMs), which helps the agent choose effective parameters before calling.

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 the specific action and resource ('Lista os PDMs do CATMAT') and immediately establishes the catalog position: grupo → classe → PDM → item. It clearly distinguishes this from search tools by stating 'Isto é navegação hierárquica, não busca', so an agent can tell it apart from compras_catmat_buscar and related siblings.

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 explicitly explains when to use this tool: to descend the hierarchy and locate material families before requesting items, because the API does not support substring search. It names the alternative approach (scanning thousands of items and deduplicating client-side), and gives a concrete workflow: combine with compras_catmat_listar_grupos and compras_catmat_listar_classes, then pass codigo_pdm to compras_catmat_buscar.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral context beyond that: a 24-hour cache and the specific catalog data returned. No contradiction with annotations.

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 compact and front-loaded: purpose first, then return fields, then use case, then cache behavior. Every sentence earns its place with no redundant filler.

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 straightforward read-only lookup with one documented parameter, an output schema, and complete annotations, the description covers everything needed: what it returns, why to use it, and the caching caveat. There are no material gaps.

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?

The input schema already describes codigo_item as a 4-6 digit integer with an example, giving 100% schema description coverage. The description only refers to 'pelo código' and does not add new parameter meaning beyond what the schema already provides, so the baseline of 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 opens with a specific verb+resource statement: 'Consulta detalhes de um item CATSER pelo código.' It further specifies the exact fields returned (nome do serviço, descrição, seção/divisão/grupo/classe, unidades de medida) and names the intended pre-price-search workflow, which helps distinguish it from sibling list/catalog tools.

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 explicitly states when to use it: 'Use para confirmar o código antes de pesquisar preços ou contratações similares.' This gives clear contextual guidance pointing toward related workflows, though it does not explicitly name sibling alternatives or state when not to use it.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive behavior. The description adds a meaningful 24-hour cache trait, informing the agent that results may be stale, and clarifies the optional group filter scope.

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 short sentences: the first states the action and optional filter, the second provides the cache behavior. No filler or repetition of schema details.

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?

The description, combined with rich annotations and a full input/output schema, covers the essential behavior of this simple list tool. It notes the only non-obvious operational detail (24h cache) and the optional filter, so an agent can invoke it correctly. It does not discuss when to prefer this over sibling listing tools, but that gap is captured in the usage_guidelines dimension.

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 all three parameters (pagina, codigo_grupo, tamanho_pagina) are fully documented in the schema. The description only reinforces the optional group filter captured by codigo_grupo, adding no syntax or format details 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 uses the specific verb 'Lista' with the resource 'classes CATSER' and an optional group filter, making the operation unambiguous. It naturally distinguishes from siblings like compras_catser_listar_secoes (sections), compras_catser_consultar (single consult), and compras_catmat_listar_classes (CATMAT classes) through the resource term and verb.

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 implies the tool is for listing CATSER classes and can optionally be narrowed by group, but it provides no explicit when-to-use guidance or mention of alternatives. An agent must infer from the tool name and sibling list which tool to choose.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds beyond those by disclosing 'Cache de 24h', a meaningful behavioral trait. It also provides conceptual context about hierarchy placement, enhancing transparency.

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 compact and front-loaded with the main purpose. The three components (what, when, cache) each earn their place. No filler or redundancy.

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 simple paginated list tool, the description covers what it lists, where it fits in the hierarchy, when to use it, and caching behavior. Parameters are fully documented in the schema, and an output schema exists, so return details are not needed.

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%, with both parameters documented (defaults, max page size). The description adds no parameter-specific information, but it is not required to because the schema already handles it. 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?

The description states a specific verb ('Lista') and resource ('seções do CATSER'), and clarifies that these are the highest level of the CATSER hierarchy. This distinguishes it conceptually from sibling tools like compras_catser_listar_classes even without naming them.

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 explicitly says when to use this tool: 'Use para enquadrar a contratação de serviços em uma seção antes de descer para divisões/grupos/classes/itens.' This gives clear context, though it does not name alternative tools or state when not to use it.

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

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

Annotations already carry readOnly/idempotent/destructive hints, and the description adds genuine context on top: it aggregates via parallel calls to Portal da Transparência and Comprasnet, raises ComprasAuthError when TRANSPARENCIA_API_KEY is unset, and has a 10-minute cache. It does not speculate on partial-failure behavior when one of the parallel sources fails, which would have made it a 5.

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 the core purpose followed by composition, error behavior, usage directive, and cache — each sentence earns its place. There is mild redundancy between 'CEIS + CNEP + CEPIM + leniência + impedimentos' in the first line and the parallel-composition sentence, but the text overall is appropriately compact.

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 1-parameter tool with 100% schema coverage, a rich output schema, and informative annotations, the description covers the main operational context: sources, return shape (verdict + consolidated list), auth prerequisite, cache, and when to call it. A minor gap is the unspecified behavior when one of the parallel upstream systems is unavailable.

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 100% — the schema already describes cnpj as 'CNPJ do fornecedor (14 dígitos, com ou sem pontuação)'. The description adds no further parameter-level detail, so the baseline of 3 applies since the schema carries the full semantic load.

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 + resource ('Consolida sanções de um fornecedor') and enumerates the exact sources aggregated (CEIS, CNEP, CEPIM, leniência, impedimentos). This clearly distinguishes it from the sibling sancao_* tools (compras_sancao_ceis, compras_sancao_cnep, etc.), which fetch single lists, whereas this one consolidates them.

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?

Provides an explicit usage directive: 'Sempre use antes de homologar pregões/contratos', which tells the agent when to invoke it. However, it stops short of naming the per-source alternatives as lower-cost options for when only one list is needed, so some exclusion guidance is missing.

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

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

The annotations already declare readOnly, idempotent, non-destructive behavior. The description adds useful behavioral detail: it aggregates totals per period into a single bucket and returns totals plus absolute and percentage deltas. No side effects or destructive actions are mentioned, and none contradict the annotations.

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 compact and well structured: a one-sentence summary, a brief implementation note, a statement of the return shape, and two illustrative examples. There is no fluff or redundant repetition of schema information.

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?

Given the high schema coverage and the existence of an output schema, the description sufficiently complements the schema by clarifying that the tool compares two periods and returns aggregate deltas. It could mention output details or pagination behavior more explicitly, but those are largely covered by the schema and annotations, so it is reasonably complete.

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?

The input schema already describes every parameter, including formats, enums, defaults, and special requirements such as esfera requiring a value metric. The description does not add significant extra parameter semantics beyond the schema-provided details, so a baseline score of 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?

The description clearly states the tool's purpose: comparing two periods side by side for the same modality. It identifies the underlying aggregate call, explains that it wraps it twice, and gives concrete typical questions, which makes the intended use unmistakable.

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 explains that this is a wrapper over compras_aggregate_contratacoes_por_periodo and provides typical use cases, so when to use it is fairly clear. It does not explicitly name alternative sibling tools or state a condition for choosing one over another, but the wrapper framing and examples convey the intended context.

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

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

The annotations already declare read-only and idempotent behavior, and the description adds the cache trait ('Cache 15 min.') and specifies the returned fields. It does not mention error responses or rate limits, but the overall behavior is transparent enough given the annotations.

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 concise and well-structured: it starts with the purpose, then lists the response contents, explains the identifier options, and ends with the cache note. Every sentence adds useful information without fluff.

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?

The description is self-contained and covers the tool's purpose, identifier variants, returned details, and caching. It does not explicitly state error handling (e.g., 404 when identifier not found), but the parameter description mentions upstream HTTP 500 behavior for invalid tipo_identificador, which provides some context.

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?

The input schema already provides highly detailed descriptions for both parameters, including examples and the enum constraint, so the coverage is 100%. The description repeats some of that information but adds little new semantic detail beyond reinforcing the identifier formats and cache behavior.

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 clearly states the tool's purpose: 'Consulta uma contratação 14.133 pelo identificador.' It specifies the resource type (contratação 14.133), the action (consultar), and the key input (identifier). It also lists the returned details (objeto, valor estimado, modalidade, instrumento convocatório, status), distinguishing it from listing or item-based sibling tools.

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 provides explicit guidance for choosing between the two identifier formats ('Use tipo_identificador='idCompra'...' or 'numeroControlePNCPCompra'...'), which is helpful. However, it does not explain when to use this consult tool instead of alternative sibling tools like listar or itens_listar, leaving the selection implicit.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the bar is lower, and the description adds substantial value beyond them: the 15-minute cache, the upstream quirk that `temResultado: null` (not `false`) is recorded for items without a winner, and the scale warning that an unfiltered query returns 'tudo que o Brasil incluiu no PNCP nessa janela.' These behavioral traits meaningfully shape how an agent calls the tool and interprets results.

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 efficiently structured with bold section headers (Uso principal, Higiene da amostra) that make it scannable. Every sentence earns its place: purpose, endpoint, primary use, sample hygiene, scale warning, and cache duration are all non-redundant, and the scale warning is strategically placed after the usage guidance that mitigates it.

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 13-parameter tool with a full output schema and rich annotations, the description covers everything an agent needs to invoke it correctly: primary use case, which filters to combine, what to avoid, a subtle upstream behavior (temResultado null), and data freshness. Return values are already documented via the output schema, so their absence from the description is not a gap.

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 100% schema description coverage, the baseline is 3, and the tool description pushes beyond it by explaining parameter interplay: `cod_item_catalogo` is the filter that 'transforma esta tool em pesquisa de preço' and, used together with `tem_resultado`/`situacao_item`, yields the estimated-versus-homologated price rows for the ETP map. It also reinforces which filters to combine for statistically valid samples, adding strategic meaning the individual schema entries do not.

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 opening sentence, 'Lista itens de contratações 14.133 incluídos no período,' states a specific verb (Lista), resource (itens de contratações 14.133), and temporal scope. The 'Uso principal — pesquisa de preço por item' paragraph further defines its identity as the item-level price-research tool, which implicitly sets it apart from sibling item/result/contract lister tools. The purpose statement is unambiguous and actionable.

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 context for when to use the tool — price research by item via `cod_item_catalogo`, with explicit sample-hygiene instructions ('passe `tem_resultado=True` (ou `situacao_item='2'`) antes de calcular média ou mediana') and a strong warning against using it with only date filters ('quase sempre grande demais para ser útil'). However, it never names sibling alternatives (e.g., compras_pesquisar_preco_material or compras_contratacoes_14133_resultados_listar) nor states explicit when-not-to-use conditions, so routing decisions are left partly to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the endpoint and the fact that either idCompra or PNCP control number is accepted. It does not disclose auth requirements, rate limits, pagination edge behavior, or response structure, but the annotations lower the burden here.

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 two concise sentences with no filler. The main purpose is front-loaded, and the identifier-format note adds useful invocation detail. Every sentence earns its place.

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?

The rich schema, detailed parameter descriptions, output schema, and annotations mean the agent has enough to invoke the tool correctly. The main gap is the absence of explicit routing guidance among the many similar item-listing siblings. Apart from that, no critical calling information is missing.

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%, and the input schema already provides detailed explanations for all four parameters, including format examples and default values. The description largely restates what the schema says about accepted identifiers. It adds the endpoint but little parameter meaning beyond the schema, so the 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?

The description states a clear verb and resource: 'Lista itens de uma contratação 14.133 específica.' The word 'específica' helps distinguish it from broader listing siblings, and the endpoint is named. However, it does not explicitly contrast itself with sibling tools like compras_contratacoes_14133_itens_listar, so differentiation is implied 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?

The description gives no guidance on when to use this tool versus alternatives such as compras_contratacoes_14133_itens_listar or compras_pncp_contratacao_itens. It only explains identifier formats, which is parameter context rather than usage direction. There are no exclusions, prerequisites, or alternative routing.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds operational facts beyond those: the exact endpoint, 15-minute cache, and the response behavior of returning both codigoModalidade and modalidadeIdPncp. This gives the agent useful expectations without contradicting the annotations.

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 compact and front-loaded with the primary purpose. The endpoint line, coverage statement, semantic warning, and cache note all earn their place; there is no filler or redundant restating of the tool name.

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 complex 11-parameter read-only list tool with an output schema, the description is complete: it identifies the data source, legal scope, cache behavior, a critical semantic pitfall, and the relevant alternative tool. No essential selection or invocation information is missing.

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%, and the schema already contains detailed per-parameter guidance, including the modalidade equivalences and the codigo_orgao_pncp warning. The free-text description repeats the modalidade semantic warning but adds little new parameter-level meaning beyond what the schema provides, so the baseline of 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 states a specific verb and resource: 'Lista contratações da Lei 14.133 publicadas no PNCP (via Dados Abertos)', and adds concrete scope details about endpoint and modalities. It also indirectly distinguishes itself from PNCP-native siblings by emphasizing the Dados Abertos source.

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 context about what the tool covers and explicitly routes to an alternative for PNCP cheat-sheet modalidade queries: 'Para consultar usando o cheat sheet PNCP nativo, use compras_pncp_contratacoes_publicacao'. It does not enumerate exclusions against other sibling list/consult tools, but the main confusion point is addressed.

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

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

Annotations already provide readOnly, idempotent, openWorld, and non-destructive hints. The description adds a 15-minute cache and a capability boundary (no CATMAT/CATSER filter), going slightly beyond the annotation baseline without contradicting it.

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?

Every sentence is informative: purpose, returned fields, two usage patterns, sibling alternative, and cache. No redundant or fluff content; the structure uses short paragraphs and bold labels for scannability.

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?

The description covers purpose, key filters, limitations, and cache, while the input schema handles pagination and parameter details. It does not describe the response shape, but an output schema is indicated as present, so this is adequate.

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?

Although the schema already covers all parameters, the description adds actionable semantics: ni_fornecedor for everything a supplier won, valor_total_min for audit queues, porte_fornecedor irregularity, and situacao_resultado 1 meaning 'Informado' to discard canceled results.

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?

Description opens with 'Lista resultados (homologações) de itens 14.133 no período', naming the verb, resource, and temporal scope. It also states the returned data (winner, awarded value, quantity) and explicitly distinguishes this route from the catalog-item sibling by noting it has no CATMAT/CATSER filter.

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 gives concrete use cases: supplier due diligence via ni_fornecedor and materiality audit via valor_total_min with a short date window. It also explicitly directs catalog-item filtering to compras_contratacoes_14133_itens_listar and notes the required date filter.

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

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

As annotations já cobrem o perfil de segurança (readOnlyHint=true, idempotentHint=true, destructiveHint=false), então a descrição não precisa repetir que é uma operação somente-leitura. Ela adiciona pouco além do endpoint e da flexibilidade de identificadores; não detalha paginação, comportamento de resposta ou limites. Isso é aceitável, mas mínimo.

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?

A descrição é compacta, com o propósito na primeira frase e esforço mínimo para transmitir o escopo. O trecho do endpoint truncado agrega pouco valor e poderia ser removido, mas no geral a densidade de informação é boa e bem organizada.

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?

Com schema completo, annotations fortes e output schema presente, a descrição fornece o essencial para o agente selecionar e invocar a ferramenta corretamente. A principal lacuna é a ausência de orientação explícita de escolha entre os siblings de resultados/listagem, mas o escopo 'específica' mitiga o problema.

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?

A cobertura do schema é 100% e as descrições de id_contratacao e tipo_identificador já são detalhadas, com exemplos de idCompra e PNCP. A frase final da descrição apenas reapresenta essa informação, sem adicionar semântica nova. Aplica-se o baseline 3 para schema com alta cobertura.

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?

A descrição abre com verbo e recurso claros: 'Lista resultados (homologações) de uma contratação 14.133 específica'. O termo 'específica' ajuda a diferenciar de ferramentas de listagem ampla, e o foco em 'resultados' o distingue de ferramentas de itens, mas não nomeia ou contrasta explicitamente com o sibling similar compras_contratacoes_14133_resultados_listar.

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?

A descrição indica o contexto de uso — uma contratação 14.133 específica — e que aceita idCompra ou PNCP, o que sugere usá-la quando já se tem um identificador da contratação. Porém, não há orientação explícita de quando NÃO usar, nem alternativas citadas entre os muitos siblings de listagem/resultados.

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

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

Annotations already cover read-only, open-world, idempotent, and non-destructive behavior. The description adds non-obvious context beyond annotations: embedded sub-resources, LGPD-masked CPFs, and a 15-minute cache.

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 three short, front-loaded sentences with no filler: operation, returned content, privacy note, and cache. Every sentence adds value.

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 one required parameter, a full schema description, rich annotations, and an output schema present, the description covers the remaining behavioral facts an agent needs, including LGPD masking, cache behavior, and embedded sub-resources. Nothing essential is missing.

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%, and the id_contrato schema description already explains that it is the internal Comprasnet ID, may differ from the Dados Abertos ID, and should be obtained from compras_contrato_comprasnet_por_uasg. The tool description itself adds no further parameter semantics, 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 states the exact operation: 'Consulta detalhe completo de um contrato no Comprasnet' and identifies the endpoint. The phrase 'sub-recursos embutidos' helps distinguish it from the many sibling sub-resource tools, though it does not explicitly name an alternative, so it stops short of a 5.

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 implies when to use it (when full contract detail is needed), and the schema usefully tells the agent to obtain the id from compras_contrato_comprasnet_por_uasg. However, it gives no explicit conditions for preferring this tool over the many contract-related siblings.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses that the upstream endpoint does not support pagination, that the tool slices results client-side, and that caching lasts 15 minutes. These are valuable behavioral details not covered by annotations.

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 concise and well-structured: a clear one-sentence purpose followed by an attention note about pagination and a cache note. No unnecessary words.

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?

The description, combined with the output schema (which exists per context signals), provides sufficient information for an agent to invoke the tool correctly. Pagination behavior and caching are explained, and the output format is presumably covered by the schema.

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?

The input schema descriptions fully cover all four parameters, and the tool description adds context for pagina and tamanho_pagina by explaining the upstream limitation and the client-side slicing rationale. This adds usability beyond the schema alone.

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 clearly states the tool's function: listing contracts for a UASG in Comprasnet. It specifically mentions the UASG scope and the pagination behavior, making its purpose unambiguous and distinct from other contract-listing tools.

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 explains the tool's internal behavior (client-side pagination, caching) but does not explicitly state when to choose this tool over similar siblings like compras_contratos_listar. The usage context is inferable from the name and description, but explicit guidance is missing.

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

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

Beyond the annotations (read-only, idempotent, non-destructive), the description adds behavioral context about pagination handling and caching, which informs the caller about expected performance and data freshness. No contradictions with annotations.

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 concise, consisting of two short sentences. It contains no redundant or irrelevant information, and all statements add value.

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 simple listing operation with a fully documented input schema and output schema, the description provides sufficient context (endpoint, pagination behavior, caching) to call the tool correctly. It does not omit critical information.

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 100% (all parameters have descriptions). The tool description adds meaning by explaining that pagination is client-side and that some contracts have many entries, which clarifies why the 'pagina' and 'tamanho_pagina' parameters exist and how they should be used.

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 clearly states the action (Lista = Lists) and the resource (cronograma financeiro) with an explicit endpoint, making it easy to distinguish from sibling tools. The verb and resource are specific and unambiguous.

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 provides some usage context (client-side pagination, 15-minute cache) but does not explicitly mention when to use this tool over alternatives or when not to use it. The guidance is implied rather than explicit.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds meaningful behavioral context beyond annotations: pagination is client-side and responses are cached for 15 minutes, which helps an agent set expectations about data freshness and pagination handling.

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 extremely concise with two short sentences, and the core purpose is front-loaded in the first sentence. The endpoint, pagination behavior, and cache duration are all useful and non-redundant with the schema.

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 simple list operation with rich annotations, a full output schema, and complete parameter documentation in the schema, the description covers the essential operational details: endpoint, resource, pagination style, and cache behavior. Nothing critical for correct invocation is missing.

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 three parameters. The description adds value by noting 'Paginação client-side', which clarifies that pagina and tamanho_pagina are applied client-side rather than server-side, supplementing the schema definitions.

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 specific verb and resource: 'Lista empenhos do contrato', and includes the endpoint path '/api/contrato/{id}/empenhos' to remove ambiguity. This clearly distinguishes it from sibling contract-related tools that deal with faturas, garantias, cronograma, or publicações.

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 clearly indicates this tool is for listing contract empenhos, with the contract ID as the key input and client-side pagination behavior. It does not explicitly compare against alternatives or state exclusions, but the resource-specific endpoint and context signal make the intended use evident.

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

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

Beyond the readOnly/idempotent/destructive annotations, it discloses client-side pagination behavior, a 15-minute cache, and a specific LGPD limitation: `infcomplementar` may contain unstructured server names and SIAPE numbers that masking does not cover. These are exactly the behavioral and data-sensitivity traits an agent needs before invoking or interpreting results.

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?

Three short, front-loaded sentences: purpose and endpoint first, then behavior, then a necessary privacy caveat. No redundant restatement of schema or annotations; every sentence earns its place.

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 simple read-only list operation with an output schema and rich annotations, the description covers purpose, endpoint, pagination model, cache freshness, and a data-protection caveat. Nothing an agent needs to invoke or interpret the result correctly appears to be missing.

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 100%, so the schema already documents `id_contrato`, `pagina`, and `tamanho_pagina`. The description adds the key semantic that pagination is client-side, which changes how an agent should interpret `pagina` and `tamanho_pagina`, and it flags the sensitive `infcomplementar` field relevant to interpreting returned data.

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?

Description opens with 'Lista NFs/faturas' and the exact endpoint `/api/contrato/{id}/faturas`, giving a specific verb and resource. This clearly distinguishes it from sibling contract-subresource tools like `compras_contrato_empenhos` or `compras_contrato_garantias`, even though no sibling is named.

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 stated purpose 'Lista NFs/faturas' gives clear context for when to call it: whenever invoices/NFS for a contract are needed. It does not explicitly name alternatives or state when not to use it, but among the many contract-related siblings the resource term is unambiguous.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds useful operational detail beyond annotations: client-side pagination and a 15-minute cache, both of which affect how an agent should interpret calls and pagination parameters.

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 extremely compact: purpose, endpoint, pagination model, and cache TTL in four short fragments. There is no filler, and the most important information is front-loaded.

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 simple read-only list endpoint with a complete input schema and an output schema present, the description is sufficient. It covers what is listed, how pagination works, and cache behavior, so no critical operational detail appears missing.

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?

The input schema fully documents all three parameters, including defaults and maximum page size, so schema coverage is 100%. The description adds only the 'client-side pagination' nuance, which modestly clarifies the behavior of pagina/tamanho_pagina but does not substantially augment 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 names a specific verb ('Lista') and resource ('garantias contratuais') and includes the exact endpoint path, making the tool's function unambiguous. This clearly distinguishes it from the many compras_contrato_* siblings, none of which target guarantees.

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 intended use is inferable: list contractual guarantees for a given contract ID. However, the description does not explicitly contrast this tool with alternatives or state when not to use it, so guidance remains implied rather than explicit.

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

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

Annotations already declare read-only and idempotent behavior, so the bar for additional transparency is lower. The description adds meaningful operational behaviors: client-side pagination because the upstream does not paginate, and a 15-minute cache of the full payload. No contradictions with the annotations.

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 concise, with two short sentences covering the core purpose, endpoint, pagination behavior, and caching. No redundant or filler content is present.

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?

Given the simple parameter set and the presence of an output schema, the description is complete enough for an agent to know what the tool does and how the parameters behave. It does not need to enumerate return fields because the output schema covers that.

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?

The input schema already covers all parameters with descriptions, so the baseline is 3. The description adds extra meaning by explaining that pagination is client-side and that the upstream returns the full payload, which clarifies how pagina and tamanho_pagina should be interpreted.

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 clearly states the tool lists contract amendments ('aditivos do contrato') and includes the specific endpoint path. The verb 'Lista' is specific and the resource is clearly identified by contract ID, distinguishing it from related contract tools.

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 does not explain when to use this tool versus other contract-related alternatives such as compras_contrato_comprasnet_consultar or compras_contratos_consultar. It only provides operational details about pagination and caching, not usage context or exclusions.

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

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

The annotations already cover read-only/idempotent behavior, and the description adds valuable behavior beyond them: client-side pagination and a 15-minute cache. These are practical operational caveats that help an agent invoke the tool correctly.

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 compact and front-loaded: purpose, usage signal, pagination, and cache are covered in a few short lines without filler. Every sentence contributes distinct information.

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?

Given the read-only/idempotent annotations, fully documented parameters, and presence of an output schema, this description is complete enough for safe invocation. The cache and pagination notes cover the main non-obvious calling conventions.

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?

All three parameters are already fully documented in the input schema (100% coverage), so the description is not expected to re-explain them. The pagination note adds some behavioral color but does not need to add schema-level parameter semantics.

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 resource ("Lista ocorrências/penalidades") and gives the endpoint route, so the tool's purpose is clear. It does not explicitly call out how it differs from related sibling tools such as compras_checar_sancoes_fornecedor, leaving some distinction to inference.

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?

"Indicador-chave da confiabilidade do fornecedor" supplies useful usage context, but it does not say when to use this tool over the related sanctions/supplier tools or state when not to use it. The guidance is adequate but implicit.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds value by mentioning client-side pagination and a 15-minute cache, which are behavioral details beyond the annotations.

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 extremely concise: two lines covering the action, resource, endpoint, pagination, and cache. No unnecessary words or redundant information.

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 simple read-only list endpoint, the description provides all necessary context: what it returns, the endpoint, pagination behavior, and cache. No critical information is missing.

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 100% with clear descriptions for each parameter (id_contrato, pagina, tamanho_pagina). The description does not add extra semantic meaning beyond what the schema already provides, but it is consistent and sufficient.

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 clearly states the verb 'Lista' and the specific resource 'publicações DOU' for a contract, with the endpoint path provided. It unambiguously identifies the tool's function without confusion.

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 includes usage characteristics like 'Paginação client-side' and 'Cache 15 min' but does not explicitly explain when to use this tool over alternatives. The context of siblings implies it, but no direct guidance is given.

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

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

Beyond the read-only/idempotent annotations, the description discloses three meaningful behaviors: LGPD-masked CPFs, client-side pagination, and 15-minute caching. These details materially affect how an agent interprets results and pagination parameters.

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?

Three short sentences deliver the core purpose, the endpoint, and the key behavioral caveats with no filler. Each line adds distinct value and the primary action is front-loaded.

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?

The description covers what the tool lists, which contract it targets, data masking, pagination behavior, and caching. The output schema and annotations supply the remaining safety and return-shape details, so nothing needed for correct invocation is missing.

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 100%, so all three parameters are already documented. The description adds a useful note about client-side pagination, which clarifies how 'pagina' and 'tamanho_pagina' behave, but it does not add substantial syntax detail 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 uses a specific verb ('Lista') and a specific resource ('fiscais/gestores') tied to an explicit endpoint path, so an agent knows exactly what data is returned. It is readily distinguishable from sibling contract tools by naming the responsibility role rather than using a generic label.

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 provides clear context for when to use the tool: whenever contract fiscal monitors/managers are needed. It does not name alternative tools or explicitly state when not to use it, but the resource-specific endpoint and role make the use case unambiguous.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds meaningful operational details beyond those annotations: the upstream contract requiring both codigo and tipo, and the 15-minute cache, which informs the agent about freshness. No contradiction with annotations.

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 compact and front-loaded: purpose first, then the required parameter combination, accepted types, and cache note. Every sentence contributes useful information with no filler.

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 two-parameter read-only consult with a rich input schema and an output schema, the description covers the essential call requirements and a staleness caveat. The only notable gap is the lack of explicit navigation among the large sibling set, but the endpoint and parameter semantics provide enough orientation.

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 baseline is 3, but the description adds value by flagging that the upstream requires codigo + tipo even though the schema marks tipo optional with a default. It also enumerates the only accepted type values, helping an agent avoid unsupported identifier formats.

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 first sentence, 'Consulta um contrato no Dados Abertos (endpoint 1.1)', states a specific verb and resource with an endpoint qualifier that helps separate it from legacy or Comprasnet contract tools. It does not explicitly name sibling tools, so it stops short of a 5.

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 useful invocation context: the upstream requires 'codigo + tipo' and lists the accepted type values. However, it does not say when to prefer this tool over closely related siblings such as compras_contrato_comprasnet_consultar or compras_contratos_listar, so the usage guidance is implied rather than explicit.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), and the description adds substantial behavior beyond them: the upstream HTTP 500 failure mode for invalid tipo_identificador values, the multiple-lines-per-item semantics (one per contractual version/alteration) with an explicit warning to check the exclusion field before aggregating, and the 15-minute cache. These are non-obvious behavioral traits an agent needs to interpret results and avoid mistakes.

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?

Every sentence earns its place: purpose, endpoint, when-to-use, exclusion of the sibling, parameter caveat, aggregation warning, and cache TTL. The most decision-critical information (purpose and sibling differentiation) is front-loaded, and the aggregation warning is visually emphasized. The length is proportionate to the tool's complexity.

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 4-parameter tool with an output schema and rich annotations, this description covers all the non-obvious context: the exact usage scenario, the error mode, the duplicate-row pitfall, and the cache duration. The output schema exists, so return-value details need not be repeated. The only minor gap is that the exclusion field is referenced but not named, which the output schema presumably supplies. Overall, nothing an agent needs to call this correctly is missing.

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 baseline is 3. The description's parameter content ('O codigo aceita o idCompra numérico ou o número de controle PNCP... Qualquer outro valor de tipo faz o upstream devolver HTTP 500') essentially restates what the schema already documents for codigo and tipo_identificador, adding no new meaning beyond re-emphasis. It does not introduce any parameter semantics that the schema lacks.

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 begins with a specific verb+resource pair — 'Lista os itens de um contrato específico, pelo identificador' — which clearly states what is listed and the scope (single contract, keyed by identifier). It also differentiates itself from the sibling compras_contratos_itens_listar by explicitly saying what this tool is not (the alternative that requires órgão + validity window and returns items from all contracts).

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?

Gives an explicit when-to-use: 'Use quando você já tem o contrato em mãos e quer só os itens dele.' It then names the sibling alternative (compras_contratos_itens_listar), states its requirements (órgão mais janela de vigência), and explains why it is the wrong choice for this use case (paginating hundreds of irrelevant lines). This is textbook when/when-not/alternative guidance.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior, and the description adds that results are cached for 15 minutes. This extra information about caching and upstream requirements provides transparency beyond the annotations, though it does not describe pagination behavior or error semantics.

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 very concise and front-loaded, with the core action in the first sentence. It avoids unnecessary detail and uses only two short sentences to convey the essential information.

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?

Given the rich parameter schema and the presence of an output schema, the description provides sufficient operational context, including required inputs and cache behavior. It could be slightly more complete by clarifying what data the returned items contain, but the output schema likely covers that need.

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?

The input schema already covers all 8 parameters with descriptions, so the baseline is 3. The description reinforces that codigo_orgao and the date range are required, but it does not add further semantic detail beyond the schema, such as how the optional filters interact or the meaning of the item code types.

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 clearly states the tool 'lists contract items' (Lista itens de contratos), identifying the action and resource. The phrase 'endpoint 2' adds minor ambiguity but does not obscure the purpose. It is distinguishable from related item-listing tools mainly by the required filters mentioned in the description.

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 explicitly mentions that the upstream API requires codigoOrgao and dataVigenciaInicialMin/Max, giving useful usage guidance. However, it does not explain when to choose this tool over the many sibling tools that also list contracts or items, nor does it state when not to use it.

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

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

Annotations already carry readOnly/openWorld/idempotent/destructive hints. The description adds behavioral context beyond them: the upstream endpoint, the required date-window constraint, the 15-minute cache, and the distinction between Dados Abertos and Comprasnet. There is no contradiction with the annotations.

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 four short sentences with no filler. The primary purpose is front-loaded, followed by constraints, an alternative, and the cache note—each sentence earns its place.

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 listing tool with 9 parameters, 3 required fields, a full output schema, and read-only annotations, the description covers the essential operational context: data source, required upstream parameters, sibling routing, and freshness (cache 15 min). Return-value details are already covered by the output schema, so no additional explanation is needed.

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 100%, so the baseline is 3. The description adds extra meaning by explaining why the required parameters exist ('O upstream exige `codigoOrgao` + janela `dataVigenciaInicialMin/Max` (≤ 365 dias)') and by naming the discovery path for `codigo_orgao` via `compras_orgao_listar` within the schema. It does not need to restate every parameter because the schema already documents each one.

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 uses the specific verb 'Lista' with the resource 'contratos federais' and names the exact upstream source 'Dados Abertos /modulo-contratos/1'. It also distinguishes itself from the `compras_contrato_*` family by stating those are for detailed sub-resources.

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 explicitly states when to use the tool (listing federal contracts) and when not to: 'Para sub-recursos detalhados (garantias, faturas, ocorrências), use `compras_contrato_*` que consulta o Comprasnet.' It also flags the upstream requirement of `codigoOrgao` plus a date window, guiding valid invocation.

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

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

Annotations already declare the tool as read-only, idempotent, open-world, and non-destructive, so the description only needs to add behavioral detail beyond that. It adds 'Cache 15 min', which warns about data freshness, and explains that the upstream requires a specific parameter combination with a 365-day limit. Nothing in the description contradicts the annotations.

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 three short sentences, each earning its place: the action, the business purpose/context, and the upstream constraint plus cache behavior. The main action is front-loaded, and there is no filler or repetition of schema details.

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 filtered list tool with a full output schema and strong annotations, the description covers the use case, required parameter pairing, date-window limit, and cache behavior, leaving parameter details to the schema. The only minor gap is not pointing the agent toward the analogous ARP sibling tool, but that is not essential for invoking this tool correctly.

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 all six parameters are already documented with types, defaults, and format. The description adds a cross-cutting constraint — the date window must be at most 365 days and codigo_orgao is mandatory — which partially reinforces the schema's existing 'Janela ≤ 365 dias' note. This is useful but modest added value, consistent with the baseline for full schema coverage.

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 first sentence states the core behavior directly: 'Lista contratos com vencimento na janela informada' — a specific verb, resource, and time-window scope. The phrase 'Inventário do que precisa renovar' adds the business purpose, and the resource word 'contratos' helps distinguish it from the ARP-focused sibling compras_arp_por_fim_vigencia.

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 clearly frames when to use the tool: to build an inventory of contracts that need renewal ('Inventário do que precisa renovar'). It also communicates the key operational constraint that the upstream endpoint requires codigo_orgao plus the min/max validity dates with a 365-day window. It does not explicitly name alternative tools or exclusion cases, but the context is clear enough for selection.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds substantial context beyond that: it states the tool never returns price, documents the exact 7 upstream DTO fields, confirms via raw call and OpenAPI that the price field never existed, and mentions the 10-minute cache. No contradiction with annotations.

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 front-loaded with the most important warning and clearly structured with bold callouts, endpoint, field list, and usage guidance. It is longer than strictly necessary, with some redundant audit detail, but the length is largely justified by the need to correct a misleading tool name and historical docstring.

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?

The description covers purpose, non-goals, the correct sibling alternative, the exact returned fields, the endpoint, cache behavior, and usage boundaries. Combined with a complete input schema and existing output schema, nothing essential is missing for selecting and invoking the tool correctly.

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?

The input schema has 100% description coverage, with all five parameters already documented, including defaults, formats, and an example. The description adds no new parameter-level semantics, so the baseline of 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?

The first sentence states a specific verb and resource: it lists the individual purchases of a CATMAT item. It immediately clarifies the critical scope limitation ('sem valor de preço') and explicitly distinguishes this tool from the price-returning sibling compras_pesquisar_preco_material.

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 explicitly states when to use this tool ('Use esta tool apenas para: descrição detalhada do item...') and when not to use it, directing price queries to compras_pesquisar_preco_material. This is an ideal when/when-not/alternative structure.

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

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

Beyond the generic annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses specific behaviors: it explicitly states the tool does not return price, lists the exact fields returned (idCompra, idItemCompra, etc.), notes the verification date, and mentions the 10-minute cache. This goes well beyond the annotations and helps set expectations about data freshness and content.

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 well-organized and mostly concise, but it contains some redundancy: the warning about not returning price is stated multiple times ('sem valor de preço', '⚠️ Esta tool não devolve preço', 'Nenhum campo de valor'). While this emphasis is understandable, it slightly detracts from conciseness. Structure is otherwise clear with distinct sections for endpoint, warning, alternative, and cache.

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?

Given the presence of a full input schema, output schema (indicated by context signals), and annotations covering safety and idempotency, the description provides sufficient context. It explains the purpose, the exact endpoint, what data is returned (and what is not), and points to the correct alternative for price queries. Nothing essential is missing for an agent to use this tool correctly.

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?

The input schema already provides 100% coverage with detailed descriptions for all parameters (e.g., 'Código CATSER do serviço. Inteiro 4-6 dígitos. Ex.: 27332.'). The tool description adds no additional parameter semantics beyond what's in the schema, so the baseline score of 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?

The description clearly states the tool's purpose: 'Lista as compras individuais de um serviço CATSER' with the specific verb 'Lista' and the resource 'compras individuais de um serviço CATSER'. It also explicitly differentiates from the sibling tool by noting it does not return price and pointing to 'compras_pesquisar_preco_servico' for price data.

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 provides explicit guidance on when to use this tool versus the alternative: 'Para preço unitário de serviço use `compras_pesquisar_preco_servico`'. This clearly tells the agent when to choose the sibling tool, implying this tool is for non-price purchase details. It also mentions cache duration and verification date, adding practical usage context.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses additional behavior: 24h cache, provider configurable via environment variable, and that it returns 'encontrado=false' with a diagnostic error instead of throwing exceptions. This adds meaningful transparency about edge cases and operational details.

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 structured with clear sections (what it returns, when to use, what it does not do). It is informative without being verbose, and each sentence adds value—no filler or redundant content.

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?

The description covers the data returned, the use case, exclusions (sanctions), caching, error handling, and provider configuration. It is contextually rich and provides enough information for an agent to decide when and how to invoke the tool, especially given the output schema exists.

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?

The single parameter 'cnpj' is fully documented in the schema: format (14 digits, with or without punctuation), provider selection (BrasilAPI default, minhareceita via env). The description in the schema covers the parameter completely, and the main description reinforces its purpose.

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 explicitly states the tool's function (public CNPJ data from Receita Federal) and enumerates the returned fields (razão social, CNAEs, QSA, etc.). It also differentiates from sibling tools by positioning itself as a complement to compras_perfil_fornecedor_completo and clarifying that it does not cover sanctions, making the purpose unambiguous.

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 'Quando usar' section provides explicit guidance: use for due diligence, and explicitly directs to sanction tools (CEIS/CNEP/CEPIM/CEAF) when sanctions are needed. It also mentions cache and error behavior, giving clear conditions for its use.

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

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

Annotations already establish read-only, idempotent, open-world, and non-destructive behavior. The description adds useful behavioral context beyond annotations: the exact Dados Abertos endpoint path and the 1-hour cache. No contradictions with annotations.

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 compact and front-loaded: main action first, then endpoint, return fields, and cache behavior. Every line adds information and there is no redundant filler.

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 a single required parameter, a full output schema, and annotations covering the safety profile, the description is nearly complete for a simple lookup tool. It captures the endpoint, cache TTL, and output contents; the only notable gap is explicit routing among the many supplier-related sibling tools.

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 100% and the schema already specifies that cnpj_cpf is a CNPJ (14 digits) or CPF (11 digits), with or without punctuation. The description only restates 'CNPJ ou CPF' and adds no new semantic detail about format, validation, or edge cases.

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 specific action ('Consulta cadastro de um fornecedor pelo CNPJ ou CPF'), identifies the resource (supplier registration), and lists the returned fields (razão social, CNAE, porte, natureza jurídica). It is clear, but it does not explicitly distinguish itself from sibling supplier tools such as compras_fornecedor_cnpj_receita or compras_perfil_fornecedor_completo.

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 intended use is implied by the stated lookup by CNPJ/CPF and the listed return fields, giving an agent some context for selection. However, the description does not name any alternative tools, state when-not-to-use it, or clarify how it differs from the other supplier-lookup siblings.

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

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

Annotations already cover read-only, idempotent, non-destructive behavior. The description adds a useful behavioral detail with 'Cache 1h' and the endpoint. It does not explain open-world or open-ended result behavior, but no contradiction exists.

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 compact and front-loaded: it states the action first, then the endpoint, the use case, and the cache behavior. Every sentence adds value with no fluff.

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 an output schema present, return-value details are unnecessary. The description covers purpose, endpoint, use case, and caching. A minor gap is that it does not explain what happens when both optional item code parameters are omitted.

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%, with each parameter described as 'Códigos CATMAT a buscar' and 'Códigos CATSER a buscar.' The tool description reinforces that these are item codes and relates them to supplier discovery, but adds limited semantic detail 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 states a specific verb and resource: 'Lista contratos e empenhos por itens (CATMAT/CATSER) no Comprasnet.' It clearly identifies the item-based supplier view and differentiates from the many sibling tools by focusing on discovering who currently supplies those items.

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 a clear intended use case: 'Útil para descobrir quem fornece esses itens hoje no governo (potenciais participantes em novos certames).' This is helpful context, though it does not explicitly name alternatives or exclusion criteria relative to sibling tools.

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

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

Annotations already mark it read-only, idempotent, non-destructive, and open-world; the description supplements this with useful behavioral details: it returns sanctioned suppliers from SICAF, uses POST, and has a 1-hour cache. This goes beyond the annotation hints without contradicting them.

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 compact and front-loaded: the purpose statement comes first, followed by endpoint, output, use case, and cache behavior. Every sentence contributes distinct value with no filler.

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 a rich output schema, 100% parameter coverage, and annotations covering safety semantics, the description provides the remaining practical context an agent needs: when to use it, what it returns, and how fresh the data is. Nothing essential is missing.

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 fully documents codigos_catmat and codigos_catser. The description only mentions CATMAT/CATSER generically and does not add parameter-level semantics beyond what the schema provides; 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 identifies a specific verb-resource pair ('Consulta impedimentos no Comprasnet') and scopes it by item lists (CATMAT/CATSER), including the endpoint and return semantics. It does not explicitly contrast itself with sibling tools such as compras_checar_sancoes_fornecedor, so it falls just short of full differentiation.

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?

'Essencial antes de homologar pregões eletrônicos' provides a clear, concrete use-case. There are no exclusions or named alternatives, but the context is sufficient to guide when this check should be run.

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

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

Annotations already declare read-only and idempotent. The description adds a behavioral note about caching ('Cache 1h'), which is additional context beyond annotations. It does not contradict any annotation.

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 brief and well-structured: purpose, endpoint, use case, cache note. No redundant information.

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?

The description covers the essential context for a read-only listing tool with structural filters. It explains when to use it and gives an example. It does not specify return format, but the schema and annotations provide sufficient detail for this tool's complexity.

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 covers 100% of parameters with descriptions. The tool description adds a semantic example (levantar todas as MEs com CNAE de TI) that clarifies how to combine porte_empresa and codigo_cnae, enhancing understanding 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 clearly states the purpose with a specific verb (Lista) and resource (fornecedores), and provides an example use case (mapping suppliers by porte/CNAE), making its intent unambiguous.

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 provides a concrete use case ('Use para mapear fornecedores potenciais por porte/CNAE') and mentions the endpoint, but it does not explicitly distinguish this tool from siblings like compras_fornecedor_consultar. The 'com filtros estruturais' hint implies differentiation but not explicit.

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