MCP Compras.gov.br

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.3.15
Disambiguation4/5
Most tools are clearly differentiated by source and purpose, e.g., compras_contratos_listar vs compras_pncp_contratos_listar vs compras_contrato_comprasnet_por_uasg. Some families are large and similar (contratações, price search), and a few names like compras_detalhar_preco_material are misleading without careful description reading, but descriptions generally resolve ambiguity.
Naming Consistency4/5
All tools share a compras_ prefix and snake_case, and most follow a compras_<domain>_<action> pattern. However, there are inconsistencies within families: compras_arp_listar vs compras_arp_itens_listar, and some noun-style names like compras_versao or compras_healthcheck break the verb-first pattern. Overall predictable and readable.
Tool Count1/5
94 tools is far beyond the 25+ threshold and constitutes an extreme count for any server, even one covering a broad governmental procurement domain. While the scope is genuinely large, the sheer number risks overwhelming agents and suggests many tools could be consolidated or composed from fewer primitives. The calibration explicitly marks 50+ tools as extreme.
Completeness4/5
The tool surface covers the major lifecycle areas of Brazilian public procurement: catalogs, price research, procurement events, contracts, ARPs, PGC/PCA planning, suppliers, sanctions, and operational health checks. Obvious gaps are minor, such as no dedicated PNCP ARP detail-by-id tool or a streamlined way to fetch all subresources of a contract in one call, but agents can work around these.
Average 4.2/5 across 85 of 94 tools scored. Lowest: 3.4/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 4 commits in the last 12 weeks
- Last stable release on September 1, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
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 no behavioral context beyond the core listing action, such as pagination behavior, result scope, or what constitutes a 'resultado'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no filler. It states the action, the resource, and the scope efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Strong annotations, complete parameter schema, and an existing output schema make the tool callable with minimal ambiguity. The only notable gap is explicit guidance on when to prefer this tool over similar siblings, which is not essential for a correct invocation once the contracting id is known.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 tool description itself contains no parameter details, but the schema documents `id_contratacao` as the internal id from `listar_contratacoes_14133` and clarifies pagination defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: it lists results for one specific procurement under law 14.133, and the required `id_contratacao` parameter reinforces this per-entity scope. It does not explicitly name sibling alternatives, so differentiation is implicit rather than fully spelled out.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit when-to-use or when-not-to-use guidance relative to sibling tools. The main usage signal is implied by the schema documentation for `id_contratacao`, which tells the agent to obtain the id from `listar_contratacoes_14133`, but no exclusions or alternative preferences are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 fully covered. The description adds genuine value beyond annotations by disclosing the 'Cache 15 min' freshness behavior and the upstream-mandated parameter combination. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences front-load the core purpose and then add constraint and cache context. The phrase 'endpoint 2' is the only wasted token. The size is appropriate for the information conveyed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a full output schema, rich annotations covering safety and idempotency, and 100% parameter coverage, the description need not explain return values or parameter formats. It adds the useful operational facts (cache TTL, upstream mandatory parameter combination). The only material gap is sibling differentiation, which the resource-specific name partially mitigates.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 all 8 parameters including defaults and constraints. The description merely restates the required pair (codigoOrgao + dataVigenciaInicialMin/Max) using upstream camelCase names that map directly to codigo_orgao and data_vigencia_inicial_min/max. This reinforces but does not enrich the schema — baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource — 'Lista itens de contratos' — which clearly separates it from contract-level tools like compras_contratos_listar and compras_contratos_consultar. However, it does not differentiate itself from other item-listing siblings (compras_arp_itens_listar, compras_contratacoes_14133_itens_listar, compras_legado_itens_licitacao_listar), and 'endpoint 2' is opaque internal jargon that adds no semantic value.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use or when-not-to-use guidance, and no alternatives are named despite a large sibling set with overlapping item-listing tools. The upstream requirement about codigoOrgao + dataVigenciaInicialMin/Max is a precondition, not usage guidance. The agent must infer the intended use case purely from the resource name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the description does not need to repeat those. The description adds the specific endpoint and clarifies the operation scope, but it does not disclose additional behavioral details such as result ordering, pagination behavior, or response shape; the output schema mitigates this.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no filler. The core purpose is front-loaded, and the endpoint reference is useful corroborating detail that does not bloat the description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only, idempotent paginated listing tool with a complete input schema and an output schema, the description is nearly sufficient. The main gap is the lack of explicit differentiation from the similarly named sibling compras_contratacoes_14133_itens_listar, which could help an agent choose between them with less ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already explains pagination defaults, maximum page size, and that id_contratacao is the internal identifier returned by listar_contratacoes_14133. The tool description itself adds no parameter-level meaning beyond wording the same scope, 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Lista itens') and a specific resource ('uma contratação 14.133 específica'), so an agent can tell it is a per-contract item listing operation. It includes the exact endpoint, but it does not explicitly distinguish itself from the similarly named sibling compras_contratacoes_14133_itens_listar.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is implied by 'específica' and by the required id_contratacao parameter, whose schema description says it comes from listar_contratacoes_14133. However, the description gives no explicit when-to-use guidance or comparison against sibling item-listing tools such as compras_contratacoes_14133_itens_listar or compras_pncp_contratacao_itens.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this as read-only, idempotent, and open-world, so the bar for description-added behavior is lower. The description adds a useful 1-hour cache note and the endpoint, but the word 'todos' is potentially misleading given the pagination parameters (default page size 50); it does not disclose that retrieving the full set may require iterating pages.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short sentences, with the main action and endpoint front-loaded, followed by use cases and a cache note. It is efficient and free of filler, though the endpoint path could be considered slightly technical for general-purpose guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema, annotations, and moderate complexity, the description is close to sufficient for tool selection and invocation. The main gap is the pagination nuance: the claim 'todos' is not harmonized with the page-size parameters, which an agent needs to know to obtain the complete result set.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 five parameters. The description reinforces the CATMAT/CATSER distinction and hints that quantities are part of the output, but it does not add substantial semantic detail beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states what the tool does: it lists all PGCs that include a given CATMAT/CATSER catalog item, and it names the exact open-data endpoint. The resource and filter are specific, making it distinguishable from generic 'list PGC' siblings, though it does not explicitly contrast itself with related PGC list/aggregate tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides concrete use cases ('Quais órgãos planejaram comprar esse item este ano? Em que quantidade?') and positions the tool as an input to ETP and quantitative benchmarking. It does not explicitly mention when not to use it or name alternative tools, but the stated context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds the endpoint and a 15-minute cache, which is useful context, but it does not describe pagination limits or other runtime behavior; the output schema and parameter descriptions cover much of the rest.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The entire description is two short, front-loaded sentences with no filler. The endpoint and cache information are directly useful and nothing in the description wastes an agent's attention.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that this is a simple read-only list operation with full input schema coverage, annotations, and an output schema, the description is largely sufficient for invoking the tool correctly. The main gap — choosing it over similar sibling tools — is already accounted for under usage guidelines.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and each parameter has its own description, so the schema carries the semantic burden. The description's endpoint template reinforces the required path parameters but adds no meaning beyond what the input schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
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 itens de uma contratação no PNCP', and reinforces it with the endpoint path. It does not explicitly differentiate from similar sibling tools like compras_contratacoes_14133_itens_listar, but the PNCP qualifier clearly narrows the scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: to list items of a PNCP contratação identified by cnpj, ano, and sequencial. However, it gives no explicit conditions or alternatives, and the large sibling list contains many similarly named item-listing tools, so routing guidance is limited to what the name and endpoint already suggest.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint=true, idempotentHint=true, and destructiveHint=false, the description goes beyond annotations by disclosing the concrete REST endpoint and the 15-minute cache behavior. This gives useful context about data freshness and network behavior without any contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short, purposeful sentences: the operation, the endpoint, and the cache TTL. Every sentence earns its place with no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-record lookup with an output schema and safety annotations, the description is nearly complete, adding endpoint path and cache duration. It only lacks explicit routing against the many sibling contract tools, which is already penalized under usage guidelines.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 endpoint template reinforces how each parameter maps to the URL path, but the description adds no new meaning about formats, ranges, or validation beyond what the schema already specifies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Consulta') and resource ('um contrato específico no PNCP'), and the endpoint path defines exactly which contract is retrieved. It does not explicitly contrast with sibling list/consult tools, but the unique identifiers (cnpj, ano, sequencial) make the single-record lookup clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives such as compras_pncp_contratos_listar, compras_pncp_contratacao_por_orgao, or compras_contratos_consultar. The only added context is the endpoint and cache TTL, which do not help with tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, idempotent, non-destructive behavior. The description adds meaningful runtime context beyond annotations: the underlying endpoint, the 15-minute cache behavior, and the interpretive value of the data (demand level and remaining legal adhesion limit). No safety-relevant side effects remain undisclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded. Every sentence earns its place: what the tool does, the source endpoint, the meaning of the output, and cache behavior. There is no repetition of schema content or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With rich annotations, an output schema, and a fully documented input schema, most operational ambiguity is already resolved. The description adds the endpoint, cache behavior, and high-level result interpretation. Missing explicit sibling routing is a minor gap, but nothing critical for invoking the tool is absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline of 3 applies and the description does not need to restate parameter semantics. It does not add parameter-specific guidance beyond the schema, but the schema's per-field descriptions with examples already carry that burden adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
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 adesões (caronas) já realizadas a uma ARP.' It further explains what the data shows ('quem aderiu e com que quantidade'), which distinguishes it from generic ARP listing tools. It does not explicitly contrast with close siblings like compras_arp_saldo_item or compras_arp_unidades_item, 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.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage context is implied: an agent seeking existing adhesions to a specific ARP item, or demand-level information, would select this tool. However, the description does not explicitly state when to prefer this tool over related ARP sibling tools, nor does it provide exclusions or alternative routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds the useful upstream constraint that modalidade is mandatory, but does not add deeper behavioral context such as result coverage or pagination semantics beyond what schema and annotations already provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no waste: the first gives the verb and endpoint, the second gives required and optional filter context. It avoids repeating schema descriptions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a complete input schema, an output schema, and a clear read-only annotation profile, the description plus structured data are enough to invoke the tool correctly. It could further explain when to prefer this over legacy list siblings, but that is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all eight parameters, so the schema carries the semantic load. The description only restates the optional-filter grouping and the mandatory modalidade, adding no syntax, format, or cross-parameter meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with the specific action 'Lista itens de licitações legado' and includes the upstream endpoint path. This clearly distinguishes it from sibling tools like compras_legado_licitacoes_listar (which lists licitações, not items) and compras_legado_licitacao_consultar.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by focusing on item listing and notes that upstream requires modalidade, but it never explicitly states when to choose this tool over siblings or when not to use it. No alternatives or exclusion conditions are named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 value by disclosing the 24-hour cache and summarizing the returned data, which complements rather than 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, all informative and front-loaded. The purpose, return content, and caching behavior are stated with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity, single-parameter read-only lookup with a full output schema, the description is sufficient: it states what is queried, what is returned, and a behavioral caveat (cache). It does not need to restate return structure since the output schema exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents codigo_orgao as an integer with a 4-6 digit description, so the baseline is 3. The description only restates 'pelo código' and adds no new meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Consulta' and the resource 'órgão específico pelo código', and lists returned fields. It is specific enough to distinguish from listing tools like compras_orgao_listar, though it never explicitly contrasts it with siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: use this tool when you have a specific órgão code. There is no explicit statement of when not to use it or what alternative to prefer if the code is unknown or if listing is required.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context on top: the underlying Dados Abertos endpoint, the 'Cache 1h' freshness behavior, and the row-level contents of the response. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short sentences: purpose first, then endpoint, then row semantics and cache. Every sentence earns its place and there is no filler or repetition of schema definitions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the high schema coverage, existing annotations, and presence of an output schema, the description provides enough invocation context: it states what is listed, the endpoint, the row shape, and cache behavior. The only notable gap is explicit positioning among the PGC sibling tools, which is more a routing/usage concern.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents ano, pagina, codigo_uasg, codigo_orgao, and tamanho_pagina. The description does not add parameter-specific semantics beyond mentioning the output item fields, which are not parameters. This matches the baseline for full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Lista itens de PGC (Plano de Gestão de Contratações) do governo federal' and details the row contents (descrição, quantidade, valor unitário estimado, mês previsto de início, categoria de item). This clearly identifies the action and resource, but it does not explicitly differentiate it from sibling tools like compras_pgc_listar_csv or compras_pgc_agregacao.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance is provided. The phrase 'Cada linha representa um item planejado' implies this tool is for item-level PGC details, but the description never names alternatives or conditions, so the agent must infer usage relative to the many PGC siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds the 15-minute cache as a useful operational trait, but no further behavioral context like pagination limits or rate limits. This matches a moderate disclosure level.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise, front-loaded sentences: purpose, scope/endpoint, and cache behavior. Every sentence contributes; no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema and fully described parameters, the description covers purpose, scope, and caching. Minor operational details like maximum date range or pagination behavior are absent but not critical for invoking the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% description coverage with all five parameters explained. The tool description adds no parameter-level meaning, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource ('Lista atas registradas no PNCP no período') and clarifies scope (federal + estadual + municipal). It does not explicitly differentiate from sibling tools like compras_arp_listar, 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.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides an explicit alternative with a rationale: 'mais amplo que Dados Abertos (só federal SISG)', implying when to choose this tool for multi-entity coverage. It does not mention when-not-to-use relative to siblings, so not a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint, so the safety profile is fully covered. The description adds useful non-annotation behavior: endpoint identification and a 15-minute cache, which informs the agent about freshness and API mapping 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no filler: it states the core purpose, the endpoint, and the cache behavior. Every sentence earns its place and the main action is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich input schema (100% param coverage), full safety annotations, and presence of an output schema, little descriptive supplementation is needed. The description adds endpoint and cache details but omits usage guidance relative to closely related siblings, which is a minor completeness gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are already well documented in the input schema. The description adds no parameter-level meaning beyond the word 'período', which roughly maps to data_inicial/data_final but does not compensate further.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 publicados no PNCP no período' and names the exact endpoint `/v1/contratos`. The explicit 'PNCP' reference distinguishes it from sibling tools like compras_contratos_listar, which likely covers ComprasGov contracts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit when-to-use guidance and names no alternatives. While 'no período' implies a date-range listing use case, there is no comparison with siblings such as compras_pncp_contrato_por_orgao or compras_contratos_listar, so the agent must infer selection context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool read-only, idempotent, and non-destructive, so the description's additional context is valuable: the endpoint `/api-de-dados/cnep`, the legal basis, and the 1-hour cache. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: purpose first, then endpoint, legal context, use-case relevance, and cache behavior. Every clause earns its place with no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only query tool with three optional, fully documented parameters and an output schema, the description is nearly complete: it includes the endpoint, legal foundation, purpose, and caching. The main gap is the absence of guidance distinguishing this CNEP lookup from the closely related sibling sanction tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already documents cnpj, nome, and pagina. The description adds no parameter-level detail beyond what the schema provides, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action ('Consulta CNEP') and the resource ('Cadastro Nacional de Empresas Punidas') with the relevant law (Lei Anticorrupção/12.846/2013). It is specific and unambiguous, but it does not explicitly differentiate CNEP from sibling sanction tools such as CEIS, CEAF, or CEPIM, so it misses the top score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the use case — consulting punished companies as an integrity-risk indicator — but it does not explicitly state when to prefer this tool over sibling sanction-list tools or the general sanctions checker. Usage context is present but only by inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 meaningful behavioral context beyond that: CPFs are masked per LGPD, results are cached for 15 minutes, and the response contains embedded sub-resources. This is useful operational information not present in annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three compact sentences with no filler. It front-loads the core purpose, then adds output shape, privacy handling, and caching behavior. Every sentence contributes distinct and relevant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the single well-documented parameter, available output schema, and read-only/idempotent annotations, the description is complete enough for an agent to select and invoke the tool correctly. The included LGPD and cache details add useful operational context without leaving critical gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter has 100% schema description coverage, including the note that id_contrato is the internal Comprasnet ID and may differ from the Dados Abertos ID, with a pointer to the obtaining tool. The tool description itself adds no further parameter-level meaning, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool consults the complete details of a Comprasnet contract, including the endpoint path and the fact that embedded sub-resources are returned. It is specific enough to distinguish from generic contract-listing siblings, though it does not explicitly name alternative tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is implied: the parameter schema directs users to obtain the ID from compras_contrato_comprasnet_por_uasg, and the phrase 'sub-recursos embutidos' suggests this tool is for full-detail lookups. However, there is no explicit when-to-use or when-not-to-use guidance versus sibling contracts tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavior beyond the annotations: it warns that the upstream API does not support pagination and may return over 1 MB, explains that the tool slices client-side using pagina/tamanho_pagina to protect the LLM, and discloses a 15-minute cache of the full payload. This is concrete, non-obvious operational context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a one-line summary followed by a clearly marked caveat. Every sentence contributes distinct information about payload size, pagination behavior, or caching, with no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description, combined with full schema coverage, the output schema signal, and the read-only/idempotent annotations, provides everything an agent needs to invoke the tool correctly. It covers what the tool lists, why pagination matters, how slicing works, and cache behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are already fully documented. The description adds useful context about client-side slicing and caching, but it does not meaningfully deepen the semantic meaning of any individual parameter beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
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 ('contratos de uma UASG no Comprasnet'), clearly identifying a list-by-UASG operation. It is unambiguous about what the tool returns, but it does not explicitly differentiate itself from sibling tools such as compras_contratos_listar or compras_contrato_comprasnet_consultar.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives, and it does not name any sibling or exclusion case. It explains the upstream pagination constraint but not how an agent should choose between this and the many other contract-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 useful non-obvious context: the upstream requires both codigo and tipo, and responses are cached for 15 minutes. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The definition is compact and front-loaded: purpose first, then the critical parameter requirement, then the cache behavior. Every sentence earns its place with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter, read-only lookup with full schema coverage and an output schema, the description covers purpose, required parameter pairing, accepted tipos, and caching. It could be more complete by explaining the Dados Abertos endpoint context or routing versus sibling consult tools, but nothing essential to calling it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already fully documents both parameters, including the enum and default. The description adds value by warning that the upstream requires codigo + tipo despite tipo having a schema default, and by clarifying that the accepted type values change how codigo is interpreted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence names the action ('consulta') and the object ('um contrato') and scopes it to 'Dados Abertos (endpoint 1.1)'. This is specific enough to separate it from list and mutation tools, though it does not explicitly contrast with sibling contract-consulting tools like compras_contrato_comprasnet_consultar.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when the tool applies: looking up a contract in Dados Abertos endpoint 1.1. It provides the upstream's required parameter combination and accepted tipos, but it does not state when to prefer this tool over sibling contract-consulting tools or call out exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds value by stating the exact return structure, the mime-type-dependent raw content format, and the `_erro` fallback instead of propagating exceptions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well organized: a one-sentence purpose, concise return behavior, a clear output block, and an error condition. Every sentence contributes useful information, and the key behavior is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple one-parameter, read-only tool with rich annotations and full schema coverage. The description covers purpose, return fields, content format, and error behavior, so an agent has everything needed to invoke and interpret the result correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema itself explains URI semantics, gives discovery guidance, and provides examples. The tool description adds only the brief reference to 'pela URI', so it does not meaningfully improve on the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Lê o conteúdo de um MCP Resource pela URI', naming a specific verb, resource type, and key selector. It clearly separates reading a resource from listing resources, though it does not explicitly name a sibling alternative in the main description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: call this when you have a resource URI and need its content or metadata. The parameter schema adds the useful prerequisite 'Use `compras_listar_resources` para descobrir URIs disponíveis', but the description itself does not discuss when not to use it or contrast it with sibling tools like `compras_obter_prompt`.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, so the safety burden on the description is low. The description adds that this is the raw CATSER service-price query and directs statistics-seeking calls elsewhere, but it does not disclose pagination behavior or result semantics beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The definition is two sentences, front-loaded with the purpose and ending with useful sibling routing. The endpoint string is arguably unnecessary for an agent selecting/invoking the tool, but it is not misleading and does not bloat the description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a moderately complex 8-parameter read-only tool with a full output schema and complete parameter descriptions, the definition covers the core decision: what it returns (raw service price results) and when to use the composite statistical tool instead. It does not mention other service-price siblings, but the open-world annotation and output schema reduce that gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already documents all 8 parameters including the required `codigo_item_catalogo` and the format examples such as 'Código CATSER do serviço. Inteiro 4-6 dígitos. Ex.: 27332'. The description adds no extra parameter-level meaning, which matches the baseline-3 case.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a concrete action and resource: 'Pesquisa preços praticados em compras de serviço (CATSER)', which immediately identifies the tool as a service-price search and distinguishes it from material-price or consolidated-view siblings. It also names the composite alternative for consolidated statistics, reinforcing its scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells the agent when to choose the alternative `compras_pesquisar_precos_para_etp` with tipo='servico' for consolidated IN 65/2021 statistics. It does not, however, discuss other relevant siblings such as `compras_detalhar_preco_servico` or mention prerequisites, but the main routing guidance is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this as read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds the 15-minute cache behavior, which is useful, but it does not disclose pagination or edge-case behavior such as empty results; the output schema mitigates this somewhat.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with the core purpose, and each sentence adds value: the purpose, the endpoint, and the cache note. There is no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple parameterized read operation, the description is complete: it states the purpose, provides the exact endpoint, notes the cache duration, and the output schema covers return values. No critical calling requirement is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 even without parameter details in the tool description. The endpoint path mirrors the parameter names and adds minor contextual meaning, but the description does not provide additional semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the verb 'Lista' and the precise resource: 'resultados (vencedores) de um item específico de contratação no PNCP.' This clearly distinguishes the tool from item-listing or contract-listing siblings, and the endpoint reinforces the exact scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it through the phrase 'de um item específico', making the intended use clear. However, it does not explicitly name sibling alternatives or state when not to use this tool, such as when results for an entire contratação are needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds a meaningful behavioral detail not in the annotations: 'Cache de 24h.' This tells the agent data may be up to 24 hours stale. It also notes that group filtering is optional, which mirrors the schema defaults.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences with no filler. The description is front-loaded with the verb and resource, then provides a useful illustrative example, and ends with a practical 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.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only listing tool with fully documented parameters, an output schema, and safety annotations, the description is almost complete. It covers purpose, hierarchy, and cache. The only gap is that it does not explicitly differentiate CATMAT from CATSER, even though a compras_catser_listar_classes sibling exists; the name and example partially compensate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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's example ('grupo 71, classe 7110') illustrates the relationship between codigo_grupo and classes but does not add functional parameter semantics beyond what the schema provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states exactly what the tool does: it lists CATMAT classes, optionally filtered by group. The hierarchy example ('dentro do grupo 71 Mobiliário, a classe 7110') clarifies what a class is and distinguishes it from group-level tools. This makes the purpose unambiguous and separates it from siblings 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.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through the hierarchy note and the optional group filter, but it never explicitly names an alternative or states when to prefer this tool over compras_catmat_listar_grupos or compras_catser_listar_classes. The agent must infer the selection criteria from context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already fully cover the safety profile (readOnly=true, openWorld=true, idempotent=true, destructive=false), so the description adds no contradiction. It contributes genuinely new behavioral context beyond annotations: a 'Cache 15 min' disclosure alerting the agent that data may be up to 15 minutes stale, and an enumeration of exactly which details are returned, helping the agent judge result completeness.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short, purposeful elements: purpose sentence, endpoint, return-field summary, and cache TTL. Every line earns its place, the most important information is front-loaded, and there is zero filler or repetition of the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter, read-only, idempotent lookup with an output schema present, the definition is nearly complete: it states purpose, endpoint, return content, and cache behavior, and the schema covers parameter provenance. The only gap is the absence of explicit routing guidance against sibling consult tools, which is partially compensated by the schema's cross-reference to listar_contratacoes_14133.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: the single parameter id_contratacao is already documented with its type, requirement, and provenance (the `id` returned by listar_contratacoes_14133). The tool description adds no parameter-level information, but the high-quality schema makes that unnecessary — baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The first line states a specific verb and resource: 'Consulta uma contratação 14.133 pelo id interno' — a detail lookup by internal ID. The listed return fields (objeto, valor estimado, modalidade, instrumento convocatório, status no PNCP) plus the 'pelo id interno' scope clearly separate it from sibling list tools such as compras_contratacoes_14133_listar and compras_contratacoes_14133_itens_listar.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance appears in the description. Usage is only implied: the endpoint name and the parameter schema's note that id_contratacao is the 'campo `id` retornado em listar_contratacoes_14133' hint at a list-then-consult workflow, but the description itself never states when to prefer this tool over sibling consult/detail tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, open-world, and non-destructive behavior. The description adds the date-window inclusion behavior and the specific endpoint, which is useful context. It does not mention pagination behavior or result characteristics, but with strong annotations the bar is met.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences plus the endpoint path deliver the essential information with no filler. The main action and scope are front-loaded, and the use case sentence adds practical value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a paginated listing tool with rich annotations and a full input schema, the description is largely complete. It clearly identifies the resource, the time-window scope, and the practical purpose. It could have noted the distinction from items-by-contract siblings more explicitly, but the endpoint and phrasing make the intended usage recoverable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are already fully documented with formats, defaults, and maximums. The description only reinforces the 'período' concept without adding new semantic value beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Lista') and clear resource ('itens de contratações 14.133') with an explicit time scope ('incluídos no período' / 'janela específica'). This distinguishes it from siblings like itens_por_contratacao, which are tied to a single contracting process rather than a date window.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states a clear use case: discovering what was bid/licitado in a specific date window. It does not explicitly name alternatives or say when not to use it, 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnly/idempotent/non-destructive behavior, and the description adds only an implementation detail (endpoint) plus the upstream year requirement. There is no disclosure of return behavior or pagination beyond what the schema and output schema already provide, so it meets but does not exceed the annotation-covered baseline.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences front-load the purpose and then give the critical upstream constraint. The bolded emphasis on dt_ano_aviso makes the most important call detail prominent without extra prose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 100% schema coverage, strong annotations, and an output schema, the description only needed to add the required-year caveat, which it does. It could improve by naming a sibling alternative, but nothing essential is missing for a correct read-only call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 9 parameters are documented in the schema, so the baseline is 3. The description goes further by explicitly warning that upstream requires dt_ano_aviso as an integer year (e.g., 2024) and 'não janela de datas,' which prevents a likely date-range misuse beyond the schema's simple 'Ano do aviso' note.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 compras sem licitação (dispensa/inexigibilidade) do regime legado.' This clearly separates the tool from legacy licensed-bidding siblings and states exactly what it returns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for legacy no-bid purchases and gives the endpoint, but it does not explicitly say when to choose this over siblings like compras_legado_licitacoes_listar or compras_legado_pregoes_listar. The dt_ano_aviso guidance is an invocation constraint, not an alternatives comparison.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 behavioral context beyond those hints: the exact Dados Abertos endpoint, a 1-hour cache, and the fact that it returns counts and totals per category/group. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the headline summary appears first, followed by endpoint, return content, use case, and cache behavior. Each of the three sentences earns its place with 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.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present and robust annotations covering safety, the description sufficiently covers purpose, output type, endpoint, and cache behavior for a low-complexity read tool. It is slightly incomplete in not positioning itself relative to the PGC sibling tools or mentioning pagination behavior, though the schema already documents defaults and limits.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 recontextualizes parameters ('num ano', 'órgão') and the aggregation theme, but does not add substantial per-parameter meaning beyond what the schema already states for ano, codigo_orgao, pagina, and tamanho_pagina.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's specific resource and granularity: 'Resumo agregado do PGC de um órgão num ano' and 'Retorna contagens e valores totais por categoria/grupo'. It is distinct from plain listing tools by emphasizing aggregation and totals, but it does not explicitly name or contrast sibling PGC tools such as compras_pgc_listar or compras_pgc_listar_csv.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear usage context: 'útil para diagnóstico rápido do volume planejado pelo órgão', indicating when an agent should reach for this tool. It stops short of explicit when-not-to-use guidance or naming alternative sibling tools, so it does not fully satisfy the 5-level bar.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 adds useful context by disclosing the 1-hour cache and the upstream requirement for codigo_classificacao_superior, as well as the legal and federative scope of PCA under Lei 14.133. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short sentences that deliver purpose, endpoint, scope contrast, required filter, and cache behavior with no filler. The main action is front-loaded in the first phrase, and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists and annotations cover safety, the description provides essential context: what PCA is, the legal framework, federative coverage, the required classification code, and caching. It could more explicitly route around the other PCA listing siblings, but nothing an agent needs to invoke the tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 tool description does not need to re-explain individual parameters. The only parameter-related addition in the description, that codigo_classificacao_superior is required upstream, is largely redundant with the schema's required flag and property description. It adds minimal semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Lista PCAs (Planos Anuais de Contratações) no PNCP', a specific verb and resource, and expands the acronym. It also distinguishes the data scope from PGC ('Diferente do PGC ... federais + estaduais + municipais'). However, it does not explicitly differentiate this tool from related PCA sibling tools such as compras_pncp_pca_por_usuario or compras_pncp_pca_por_classificacao_superior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear selection cue by contrasting PCA with PGC and explaining the coverage difference, which helps an agent choose between this tool and compras_pgc_listar. It also states that the endpoint filters by item category and that codigo_classificacao_superior is required upstream, indicating the intended call pattern. It does not mention when to prefer the PCA-specific sibling tools, but the main alternative is addressed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 useful behavioral context beyond those hints: the specific endpoint, a 1-hour cache, and the legal/regulatory significance of CEIS data. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded, with each sentence earning its place: purpose, endpoint, legal context, usage directive, and cache behavior. It contains no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only query tool with complete parameter schemas and an output schema, the description covers the essential context: what CEIS is, why it matters, when to use it, and caching behavior. It could more explicitly contrast CEIS with other sanctions registries, but the sibling list and the CEIS naming provide enough orientation for selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All four parameters are fully described in the input schema, including CNPJ format, Nome, pagina, and orgao_sancionador, so schema description coverage is 100%. The description adds no parameter-level detail, but with full schema coverage the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb and resource: 'Consulta CEIS — Cadastro de Empresas Inidôneas e Suspensas.' It identifies the exact registry being queried, which implicitly distinguishes it from sibling sanction tools like CNEP, CEAF, and CEPIM. It does not explicitly name those siblings, so it stops just short of a top score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance: 'Use sempre antes de homologar pregões e contratos,' supported by the legal consequence that sanctioned companies cannot contract with public administration. It does not state when not to use it or point to alternatives such as compras_checar_sancoes_fornecedor for a broader sanctions check.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already carry the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the description does not need to restate it. It adds practical details like 'Cache 1h' and the endpoint, but no additional behavior such as result interpretation or pagination behavior, making 3 appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three brief sentences with no filler. It front-loads the purpose, then adds endpoint, applicability, and cache information, each earning its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only query tool, the description plus schema and annotations cover most needs: inputs are documented, output schema exists, and safety is declared. It could clarify behavior when no filter is provided or whether cnpj and nome can be combined, but these are minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: cnpj, nome, and pagina are all documented with their formats and defaults. The description itself adds no parameter-level 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Consulta CEPIM — Entidades Privadas Sem Fins Lucrativos Impedidas', naming a specific verb, target registry, and subject. This clearly differentiates it from sibling sanction tools such as CEIS, CNEP, CEAF, and leniency agreements.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states a clear applicability: 'Aplicável a contratações via convênios e termos de fomento com OSCs.' This gives the agent a concrete condition for choosing this tool, though it does not explicitly exclude the sibling sanction-list tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnly, idempotent, openWorld, and non-destructive behavior. The description adds useful behavioral context beyond the annotations by disclosing the source endpoint and the 15-minute cache, which informs freshness expectations. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded: the core function appears in the first sentence, followed by endpoint, business purpose, and cache TTL. Each sentence adds a distinct piece of information with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With all parameters documented by the schema, annotations carrying the read-only behavior, and an output schema present, the description supplies the remaining operational context (purpose, endpoint, cache). Nothing essential is missing for an agent to select and call this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the parameters are already fully documented with formats, defaults, and constraints (e.g., max 365-day window, pagination limits). The description's 'intervalo informado' only gestures at the date parameters without adding semantic detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the function: 'Lista ARPs cuja vigência termina dentro do intervalo informado' – a specific verb, resource (ARPs), and date-range scope. It does not explicitly differentiate from sibling ARP tools like compras_arp_listar or compras_arp_consultar, though the finite date-window condition makes the distinction inferable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The statement 'Permite ao gestor identificar atas próximas do vencimento' gives a clear intended-use context (finding ARPs near expiration), and the 'intervalo informado' wording ties usage to the required date parameters. It does not name alternatives or provide when-not-to-use guidance, so it falls short of the strongest definitions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
As anotações já declaram readOnlyHint=true e idempotentHint=true; a descrição adiciona 'Cache de 24h', que é uma característica comportamental relevante e não redundante. Não contradiz as anotações e oferece contexto útil sobre atualidade dos dados.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Descrição enxuta com o objetivo na primeira linha, seguida de retornos, caso de uso e cache. Cada frase agrega informação e não há redundância ou enchimento.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Para uma ferramenta simples com um parâmetro bem documentado, anotações de segurança e output schema presente, a descrição é suficiente: informa o que retorna, quando usar e uma limitação temporal. Nada essencial falta para invocar corretamente.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
O schema cobre 100% do único parâmetro com tipo, formato, restrição e exemplo. A descrição apenas repete 'pelo código', sem acrescentar semântica além do que o schema já documenta. Baseline 3 é adequado.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
A descrição começa com verbo e recurso específicos: 'Consulta detalhes de um item CATMAT específico pelo código', além de listar os dados retornados. Diferencia-se implicitamente de compras_catmat_buscar e compras_catser_consultar, mas não nomeia explicitamente nenhum irmão, deixando a distinção menos direta.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
A frase 'Útil para confirmar o código antes de fazer pesquisa de preços ou listar contratações similares' dá contexto claro de quando usar. Não há exclusões explícitas nem alternativas nomeadas, então perde um ponto por omitir o 'quando não usar'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 valuable behavioral context with 'Cache de 24h', informing the agent that results may be up to 24 hours stale, which is useful operational knowledge 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two short sentences that state the action, the optional filter, and the caching behavior. Every word earns its place, and the main purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only listing tool with a fully documented input schema and an output schema, the description is complete. Combined with the annotations, it tells the agent what the tool does, how results may be filtered, and what freshness to expect. No critical operational detail is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all three parameters (pagina, codigo_grupo, tamanho_pagina) already documented with defaults and constraints. The description adds only that filtering is optional, which is already reflected in the schema's nullable/default codigo_grupo parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 as classes CATSER' (lists CATSER classes), plus the optional group filter. This distinguishes it from sibling tools like compras_catmat_listar_classes and compras_catser_listar_secoes by naming the exact catalog and entity type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is implied by the resource name and description: use this tool when you need CATSER classes, optionally filtered by group. However, there is no explicit guidance about when NOT to use it or which sibling alternative to choose, such as compras_catser_listar_secoes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
As annotations já cobrem readOnlyHint, openWorldHint, idempotentHint e destructiveHint. A descrição adiciona valor além delas: cache de 15 minutos, endpoint específico, escopo federal e comportamento do payload retornando tanto `codigoModalidade` quanto `modalidadeIdPncp`. Não há contradição com as annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A descrição é organizada em blocos curtos e informativos: propósito, endpoint, escopo, aviso semântico e cache. Não há filler, e o aviso mais importante vem em destaque. Perde um ponto por duplicar parcialmente a nota semântica que já existe no schema do parâmetro.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Dado que há output schema e parâmetros totalmente documentados, a descrição cobre bem o essencial: escopo, endpoint, atenção semântica, cache e alternativa nativa. Não menciona limites de paginação ou critérios para escolher siblings de consulta/detalhe, mas isso é menor diante da riqueza do schema e das annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
O input schema documenta 100% dos 7 parâmetros, com descrições, formatos e defaults. A descrição reforça o cuidado com `codigo_modalidade_dados_abertos`, mas essa informação já está presente no próprio schema do parâmetro. Portanto, o valor adicional sobre a semântica dos parâmetros é mínimo — o baseline 3 é adequado.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
A descrição abre com verbo e recurso específicos: 'Lista contratações da Lei 14.133 publicadas no PNCP (via Dados Abertos)' e ainda cita o endpoint exato. Ela diferencia explicitamente o filtro de modalidade da tabela Dados Abertos/SIASG da tabela cheatsheet PNCP, apontando o sibling `compras_pncp_contratacoes_publicacao` como alternativa. Isso é suficiente para distinguir a ferramenta dos demais tools de listagem/consulta.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
A descrição informa quando usar a ferramenta: contratações da Lei 14.133 no governo federal, incluindo pregões, dispensas e inexigibilidades. O aviso semântico também diz explicitamente quando NÃO usar o filtro `codigo_modalidade_dados_abertos` e aponta a alternativa PNCP nativa. Porém, não há orientação mais ampla sobre quando preferir `listar` em vez de `consultar` ou `itens_listar`.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, idempotent, non-destructive behavior; the description adds useful operational context: the 365-day range restriction and 15-minute cache. These details help the agent reason about freshness and constraint failures 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded with the action before use case and constraints. The parenthetical 'endpoint 1.2' adds little agent value, but the overall length and organization are efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a filtered list operation with a full input schema and existing output schema, the description covers the use case, required upstream fields, range limit, and cache behavior. It does not discuss pagination or alternative sibling tools, but the schema and annotations fill most of the operational gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers 100% of parameters, so the baseline is 3; the description adds only the upstream field names and re-states the ≤365-day limit already present in data_vigencia_final_min's schema description. It does not provide substantial new parameter guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a concrete verb and resource: 'Lista contratos com vencimento na janela informada', which is more specific than a generic contract list and distinguishes this tool by date-window scope. The phrase 'Inventário do que precisa renovar' reinforces its purpose for renewal planning.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly identifies the use case ('Inventário do que precisa renovar') and states the upstream requirement for codigoOrgao plus the date range. It does not explicitly name sibling alternatives or state when not to use this tool, stopping 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.
Behavior4/5
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 useful behavioral context beyond those: the specific Dados Abertos endpoint, the return fields, and the 1-hour cache behavior. No contradictions with annotations; the additional context earns a strong score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short sentences, each carrying distinct information: purpose, endpoint, return fields, and cache behavior. No filler or repeated content, and the core purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read-only query with a fully documented schema, an output schema, and annotations covering safety, the description is complete. It tells the agent what will be returned, where the data comes from, and caching behavior. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already explains the CNPJ/CPF format and punctuation tolerance. The description reiterates that the lookup is by CNPJ or CPF but adds no extra parameter semantics beyond what the schema provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb (consulta) and resource (cadastro de fornecedor) filtered by CNPJ/CPF, and lists the returned data fields (razão social, CNAE, porte, natureza jurídica). It does not explicitly contrast itself with supplier-related siblings like compras_fornecedor_cnpj_receita, but the endpoint and field list give enough specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context is explicit: use this tool to query supplier registration data by CNPJ or CPF. It does not mention alternatives or exclusions, but the query criterion and returned fields make the intended use case clear. Given the many sibling tools, some when-not guidance would improve it, but it is not ambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so safety is covered. The description adds meaningful behavior beyond annotations by revealing the PNCP endpoint and the 'Cache 1h' freshness limitation, which is important for an agent deciding whether cached results are acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very compact: three short sentences plus an endpoint line. It front-loads the core purpose, then gives the use case and cache hint, with no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool with full schema coverage, rich annotations, and an output schema, the description provides everything an agent needs: endpoint, date-period semantics, a concrete monitoring use case, and cache behavior. No critical operational detail is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all four parameters, including date formats, the ~30-day maximum window, and pagination defaults. The description's mention of 'num período' adds no semantic value beyond what the schema already provides, 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists 'PCAs atualizados num período (PNCP)', identifying a specific verb, resource, and date-range scope. It also gives the exact endpoint and a concrete monitoring use case, which distinguishes it from sibling tools like compras_pncp_pca_listar, though it does not explicitly name an alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers a clear use context: 'Útil para monitoramento: descobrir quais órgãos revisaram seu PCA recentemente.' This tells an agent when to use the tool, but it does not provide exclusions or explicitly compare it to related PCA tools, so it falls short of full alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 meaningful behavioral context beyond those annotations by disclosing that CPFs are masked under LGPD with an example format and that results are cached for 1 hour. This gives the agent important expectations about data format and freshness without contradicting any annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured, opening with the resource name, then the endpoint, subject matter, a practical use case, and two critical behavioral caveats. Every sentence earns its place with no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity, full schema coverage, output schema presence, and comprehensive annotations, the description supplies all essential context: what the registry is, when to use it, the data format mask, and cache behavior. Nothing necessary for correct selection or invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all three parameters (cpf, nome, pagina) are already documented in the schema. The description adds the LGPD masking format, which is relevant to interpreting cpf results, but it does not need to re-explain parameter meanings given full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool consults CEAF, the Cadastro de Expulsões da Administração Federal, and defines the subject matter as federal public servants expelled from public service. It identifies the endpoint and resource precisely, but does not explicitly differentiate CEAF from sibling sanction tools like compras_sancao_ceis or compras_sancao_cnep, relying on the acronym and scope rather than an explicit contrast.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear usage context: it is useful when a suspicious responsible party or proxy is identified. It does not, however, provide when-not-to-use guidance or mention which sibling sanction list tools should be used instead for other scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context beyond those hints: active-then-inactive fallback lookup, `ativa: false` for extinct UASGs, the upstream `statusUasg` limitation, and 24h cache behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, return fields, and primary use case, with edge-case behavior following. The restoration announcement adds some time-sensitive tangential information, but it does not obscure the invocation-relevant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has a single well-documented parameter and an output schema, the description is complete: it covers what the tool returns, when to use it, the extinct-UASG edge case, upstream limitations, and cache behavior. Nothing needed for correct selection and invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already documents `codigo_uasg` as the numeric UASG code. The description's phrases 'pelo código' and 'resolver codigo_uasg' add no new format or semantic detail beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Consulta uma UASG específica pelo código') and lists the returned fields. It does not explicitly differentiate from siblings like compras_uasg_buscar or compras_uasg_listar, but the by-code lookup scope is clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says the tool is useful for resolving `codigo_uasg` before filtered queries, which provides a clear use case. It does not provide explicit exclusions or name alternatives for when to use a different tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it as read-only, idempotent, open-world, and non-destructive. The description adds useful context beyond that by stating it reports the state of sensitive configurations without exposing their values, which is important for an AI agent to know before invoking.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, front-loaded sentences in Portuguese deliver the tool's purpose, return content, and practical use cases with no filler. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With zero parameters and an output schema present, the description covers what the agent needs to call the tool successfully. The only completeness gap is the lack of clarification about how this tool relates to the similarly named compras_healthcheck sibling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero parameters, so the baseline is 4. The description correctly adds no parameter-specific information, and nothing is lost because there is nothing to document.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as a healthcheck/diagnostic returning version, upstream sources, and sensitive configuration state—more specific than a mere 'version' label. It does not explicitly differentiate from the sibling compras_healthcheck, so it falls short of full sibling distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives concrete scenarios: confirm server responsiveness, check installed version, verify accessible APIs, and confirm whether the Transparência key is configured. It does not mention when not to use it or compare it with compras_healthcheck, so it lacks exclusions/alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, but the description adds significant behavioral detail: count mode makes one call per bucket reading only totalRegistros, value modes paginate up to 25 pages/12,500 records per bucket and signal truncado=true, internal concurrency is 4 calls, and cache is 30 minutes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with the core purpose, and organized into bolded mode sections followed by a one-line concurrency/cache note. Every sentence adds information; there is no filler or redundant repetition of schema fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
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 documentation is not required. The description covers mode selection, performance expectations, pagination limits, truncation signaling, concurrency, and cache behavior, giving an agent everything needed to call the tool correctly and anticipate its costs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, giving a baseline of 3. The description adds meaning beyond the schema by explaining metrica modes (count reads totalRegistros, value modes sum pages), the esfera filter's effect only in value mode, and the practical impact of MAX_PAGES_PER_BUCKET and truncado.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Série temporal de contratações no PNCP por bucket', clearly indicating a time-series aggregation over contracting data. It conveys the operation and resource, and the bucketing concept distinguishes it from simple list/consult tools, though it does not explicitly contrast with any named sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides internal mode guidance: count is recommended for trend analysis, value modes are slower and should only be used when necessary, and page limits/truncation are warned. However, it does not state when to use this tool versus sibling alternatives such as compras_comparar_periodos_contratacoes or compras_indicadores_por_periodo.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the read-only, open-world, idempotent, and non-destructive profile. The description adds useful behavior beyond that: it names the public Dados Abertos endpoint and discloses the 15-minute cache. It also clarifies that the returned units are potential rather than actual caronas.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded with the main purpose. There is slight redundancy between 'potenciais caronas' and 'unidades podem usar a ata como carona', but the endpoint and cache statements are tight and informative, so the structure remains efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
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 fully documented input schema, an output schema, and safety annotations, the description covers the purpose, the data source, the carona semantics, and cache behavior. Nothing needed to call or interpret the tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 five parameters, including pagination defaults, limits, and the distinction from numeroControlePncpAta. The tool description adds no parameter-level meaning beyond what the schema provides, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a concrete verb and resource: 'Lista UGs participantes (potenciais caronas) de um item da ARP.' This is reinforced by 'Determina quais unidades podem usar a ata como carona (adesão)', which clearly conveys what the tool does. The 'potenciais caronas' framing also helps distinguish it from the related actual-adhesion sibling compras_arp_adesoes_item.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly defines when to use the tool: to list the UGs that may use the ARP item as a carona/adhesion. It does not explicitly name alternatives or exclusions, but the intended context is unambiguous and the endpoint reference adds operational clarity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 by specifying what the tool returns (winning supplier, awarded value, homologated quantity) and identifying the underlying endpoint, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded: it states the core purpose in the first sentence, then supplements with endpoint and practical use. Every sentence contributes value, with no redundant restatement of the tool name or schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's output contents and its practical role as a price source for ETP. With an output schema present and full parameter documentation, it is reasonably complete. It does not explicitly differentiate from all closely related sibling tools, but the core calling context is clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are already fully documented with formats, defaults, and meanings. The description's reference to 'no período' aligns with the two required date parameters but adds no new semantic detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Lista resultados (homologações) de itens 14.133 no período') with a clear resource: auction results/homologations under law 14.133 filtered by date range. It distinguishes itself from siblings like 'resultados_por_contratacao' by emphasizing the period-based listing, and also names the exact endpoint.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear use case: it is the primary source of practiced prices for ETP ('fonte primária de preço praticado para o ETP'). It does not explicitly mention when not to use it or name alternatives such as 'resultados_por_contratacao', but the period-based scope implies its intended context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
As annotations já cobrem readOnly, idempotência e não-destrutividade. A descrição adiciona informações relevantes além disso: cache de 15 minutos e 'paginação client-side'. Essa informação é útil para o agente entender frescor dos dados e comportamento de paginação, embora a expressão 'client-side' possa gerar alguma ambiguidade com os parâmetros de página.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A descrição é curta e objetiva, com três frases que entregam propósito, contexto de uso, comportamento de cache e paginação. Não há palavras redundantes nem repetição do que já está no schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Para uma ferramenta de leitura simples com output schema presente, annotations completas e schema com 100% de cobertura, a descrição cobre o essencial: o que lista, para que serve e comportamentos relevantes. A única pequena lacuna é a ambiguidade da expressão 'paginação client-side' em relação aos parâmetros de paginação.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
A cobertura do schema é 100% e todos os parâmetros já possuem descrições adequadas: id_contrato, pagina e tamanho_pagina. A descrição não acrescenta detalhes semânticos novos além do endpoint, que reforça o papel de id_contrato; portanto, fica no baseline de 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
A descrição começa com verbo específico e recurso claro: 'Lista ocorrências/penalidades' do contrato, reforçado pelo endpoint '/api/contrato/{id}/ocorrencias'. A frase 'Indicador-chave da confiabilidade do fornecedor' acrescenta propósito semântico e ajuda a diferenciar de ferramentas de sanções genéricas de fornecedores.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
A descrição indica claramente quando usar a ferramenta: para avaliar a confiabilidade do fornecedor por meio de ocorrências/penalidades em contratos. Não menciona exclusões, alternativas ou quando não usar, mas o contexto de uso é suficientemente claro.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the operation read-only, open-world, idempotent, and non-destructive. The description adds valuable behavioral context beyond that: the upstream requires `codigoOrgao` and a date window capped at 365 days, and results are cached for 15 minutes. This is useful but not exhaustive—rate limits or pagination behavior are not mentioned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: it leads with the core purpose, then gives the upstream constraint, the routing guidance to sibling tools, and the cache behavior. Every sentence earns its place with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich input schema and presence of an output schema, the description covers the essential invocation context: purpose, upstream requirements, alternative tooling for sub-resources, and caching. It could more explicitly clarify the relationship with `compras_contratos_consultar` and `compras_contratos_listar_por_fim_vigencia`, but the current content is sufficient for correct tool selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the input schema already provides detailed parameter descriptions including defaults, formats, and the 365-day window constraint. The description reinforces that the upstream requires `codigoOrgao` and the date window, but it does not meaningfully add parameter-level semantics beyond what the schema already conveys.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action and resource: 'Lista contratos federais' from 'Dados Abertos /modulo-contratos/1'. It also differentiates itself from the sub-resource sibling family by directing users to `compras_contrato_*` for garantias/faturas/ocorrências, though it does not explicitly distinguish itself from `compras_contratos_consultar` or `compras_contratos_listar_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.
Usage Guidelines5/5
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 versus alternatives: it lists federal contracts from Dados Abertos, and it tells users to use `compras_contrato_*` for detailed sub-resources that consult Comprasnet. It also surfaces the mandatory upstream requirements (`codigoOrgao` + date window ≤ 365 dias), giving the agent actionable selection and invocation context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations already declaring readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, the description adds useful behavior beyond them: it specifies the exact return fields, notes that missing prompts or required arguments produce an '_erro' diagnostic, and states that exceptions are not propagated. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core action, followed by a compact return contract in a code block and a terse error-handling note. It is slightly repetitive ('devolve o texto pronto' / 'conteúdo renderizado pronto para usar') but well-organized and appropriately sized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a 2-parameter tool with 100% schema coverage, an output schema, and rich annotations, the description is complete: it covers return shape, error semantics, and the downstream workflow. Nothing an agent needs to invoke the tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 only confirms that missing required arguments trigger the error path, while the schema already documents 'nome' and 'argumentos' with examples, types, and constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb-resource pair ('Renderiza um MCP Prompt e devolve o texto pronto') and further defines the output as the content of PromptMessage[0]. This clearly distinguishes the tool from siblings like compras_listar_prompts, which enumerate prompts rather than render them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: after obtaining the rendered text, the LLM normally follows its instructions and invokes other tools. It does not explicitly name alternatives or exclusions, but the parameter schema points to compras_listar_prompts for discovering prompt names, which provides sufficient routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, idempotent, non-destructive behavior. The description adds value by disclosing the client-side `esfera` filtering behavior and the 15-minute cache, plus the update/retification semantics, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, each adding distinct information: what the tool lists, why it is useful, and operational caveats (client-side filter, cache). No filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only PNCP listing tool with a rich output schema and fully documented parameters, the description covers purpose, use case, cache behavior, and the one important filtering caveat. It could be stronger only by explicitly contrasting this endpoint with the publication-focused sibling tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, including date formats, page defaults, and modalidade code mappings. The description only echoes that `esfera` is a client-side filter and adds no new parameter-level details beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a concrete action and object: 'Lista contratações alteradas no período (PNCP)' and identifies the exact endpoint. The monitoring purpose — finding retified/republicated notices — clearly distinguishes it from sibling listing tools such as compras_pncp_contratacoes_publicacao.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly states when to use the tool: for monitoring edits, retifications, and republications of contracting notices. It does not explicitly name alternatives or exclusion criteria, but the 'alteradas' framing strongly implies contrast with publication-focused sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
As anotações já cobrem readOnlyHint, idempotentHint, openWorldHint e destructiveHint=false. A descrição acrescenta valor ao informar o cache de 1h e o endpoint específico, mas não detalha autenticação, limites de rate ou formato de paginação — embora o schema e o output schema já cubram parte disso.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A descrição é curta e funcional: frase principal, endpoint, exemplo de uso e cache. Toda frase contribui com informação relevante, e a função central é apresentada logo no início, facilitando a decisão rápida do agente.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Combinada com o schema (parâmetros obrigatórios, paginação) e o output schema, a descrição contém informações suficientes para invocar a ferramenta corretamente: propósito, endpoint, exemplo de agregação e cache. Faltam apenas orientações explícitas sobre alternativas e uma explicação da sigla PCA, que não são críticas.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
A cobertura do schema é 100%, então os parâmetros já estão documentados. A descrição adiciona um caso de uso útil para o parâmetro 'codigo_classificacao_superior', mas basicamente reitera que a filtragem é por categoria superior, sem aprofundar semântica de formato, validação ou dependências entre parâmetros.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
A descrição afirma claramente o que a ferramenta faz: listar itens de PCA filtrados por categoria superior do item. O verbo 'Lista' e o recurso 'itens de PCA' são específicos, e a menção ao endpoint com 'codigoClassificacaoSuperior' reforça o comportamento, distinguindo-a de outras ferramentas de PCA, como listar, atualizar ou por usuário.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
A descrição comunica claramente quando usar a ferramenta: para agregar planejamentos por categoria, com exemplo concreto ('todos os itens de TI planejados para o ano'). Porém, não menciona explicitamente alternativas ou exclusões, como 'use compras_pncp_pca_listar quando não houver filtro por categoria', deixando essa distinção implícita.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 behavioral context beyond that: a 24-hour cache, the rarity of changes, and the approximate total of 79 groups. This helps an agent calibrate freshness expectations, adding real value beyond the structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with the core action, and every sentence adds value: hierarchy context, usage guidance, cache behavior, and expected result size. There is no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple paginated list tool with a rich output schema and complete parameter descriptions, the description covers everything essential: what is listed, where it sits in the hierarchy, how to use it in a contracting workflow, and data freshness expectations. Nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters ('pagina' and 'tamanho_pagina') already documented in the input schema. The description does not add parameter-level detail, but the baseline of 3 applies because the schema carries the full burden and does so adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 os grupos do CATMAT (Catálogo de Materiais).' It further clarifies that groups are the highest CATMAT hierarchy level and gives concrete examples, making the tool's scope unmistakable. The phrase 'antes de descer para classes/PDM/itens' positions it against the likely sibling tools without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool: 'Use esta tool para enquadrar a contratação no grupo correto antes de descer para classes/PDM/itens.' It gives clear contextual guidance but does not explicitly name sibling tools as alternatives or state when not to use it, so it falls just 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only and idempotent behavior. The description adds useful behavioral context beyond that: the fields returned and a 24-hour 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: purpose, return contents, use case, and cache are each stated in a single essential line. No filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one well-documented parameter, strong annotations, and an output schema present, the description provides everything an agent needs to decide when to call the tool and what to expect. Nothing material is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers the only parameter fully, including type, meaning, and an example. The description adds no significant parameter-level detail beyond referring to 'código', so the schema bears the explanatory weight.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Consulta detalhes de um item CATSER pelo código'. It enumerates the returned fields and clearly distinguishes this tool from price search and similar-contracting siblings by positioning it as a code-confirmation step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear usage context: 'Use para confirmar o código antes de pesquisar preços ou contratações similares.' This tells the agent when to invoke it, though it does not explicitly 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, non-destructive behavior, so the description's main added value is the 'Cache de 24h' note, which is important for freshness expectations. It also clarifies that the hierarchy is based on CPC ONU, adding useful context beyond the structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: it front-loads the main action, briefly explains the hierarchy and usage context, and ends with the caching behavior. Every sentence provides useful information without repetition or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that this is a simple paginated listing tool with an output schema and safety-relevant annotations, the description covers all necessary context: what is listed, where it fits in the hierarchy, when to use it, and the cache duration. 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage with clear meaning for 'pagina' and 'tamanho_pagina', including defaults and maximum. The tool description adds no additional parameter semantics, so the baseline of 3 is appropriate because the schema carries the explanatory burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 as seções do CATSER' (lists CATSER sections). It also differentiates this tool from related catalog tools by noting that sections are the highest hierarchy level, above divisões/grupos/classes/itens, which distinguishes it from sibling tools like compras_catser_listar_classes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit usage context: use it to frame service contracting at the section level before descending to lower hierarchy levels. While it does not name alternative sibling tools, the hierarchical guidance makes the selection clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 valuable behavioral details beyond those annotations: implicit granularity='ano', aggregation into one bucket per period, and the specific outputs (totals A/B + absolute delta + percentage delta). 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tight and well-structured: a one-sentence purpose, implementation note, output summary, and two illustrative use cases. Every sentence contributes information without redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich input schema, an output schema, and comprehensive annotations, the description is complete enough for an agent to invoke the tool correctly. It explains the comparison semantics, the aggregation behavior, the return calculation, and gives realistic example queries, leaving no obvious selection or invocation gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all 10 parameters are documented. The description adds little parameter-specific meaning beyond what the schema already provides, except reinforcing that only one modality is compared and giving domain examples. This is the expected baseline when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Compara') and states the resource and scope: comparing two periods side-by-side for the same modality. It also positions itself as a wrapper over a sibling tool, making its distinct role immediately clear relative to the large sibling list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains it is a wrapper over compras_aggregate_contratacoes_por_periodo called twice, which implies when the simpler aggregate would be used. It also gives concrete typical use-case questions. It lacks an explicit 'use sibling X instead when Y' exclusion, but the wrapper statement and examples provide clear selection context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds genuinely useful behavioral context beyond annotations: client-side pagination and a 15-minute cache, both of which affect how an agent should interpret results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no filler. The primary purpose is front-loaded, and the additional behavioral notes (pagination, cache) are compact and relevant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, read-only listing tool with fully documented parameters, annotated safety hints, and an output schema, the description provides everything an agent needs: the resource, endpoint, pagination behavior, and caching semantics. No critical operational detail is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all three parameters are already documented with types, defaults, and constraints. The description adds no further parameter-level detail beyond the endpoint path, which is acceptable given the schema fully carries that burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action and resource: 'Lista empenhos do contrato' (lists contract empenhos) and provides the exact endpoint path. This distinguishes it from sibling contract sub-resource tools like compras_contrato_faturas and compras_contrato_cronograma.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the usage context: use it to list empenhos for a specific contract by id_contrato. However, it provides no explicit guidance on when not to use it or how it compares to sibling tools, leaving selection partly to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable behavioral details beyond these annotations: client-side pagination and a 15-minute cache, which affect how results should be interpreted and paginated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: a single clear purpose sentence followed by two brief behavioral notes. Every sentence earns its place with no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
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 a complete input schema and an output schema present, the description provides sufficient context: endpoint, resource, pagination behavior, and caching. Nothing critical is missing for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents all three parameters with descriptions and defaults, so the schema carries the semantic weight. The description's mention of client-side pagination adds a slight behavioral nuance but does not substantially improve parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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, 'garantias contratuais', reinforced by the exact endpoint path. It clearly distinguishes itself from sibling contract-related tools that deal with empenhos, faturas, ocorrências, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes the tool's purpose clear — listing contractual guarantees for a given contract — so an agent can infer when to use it. It does not explicitly state when not to use it or name alternatives, but the context is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
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 valuable runtime context: pagination is handled client-side because the upstream API does not paginate, and the complete payload is cached for 15 minutes. This sets correct expectations for freshness and pagination behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the first sentence states the resource and endpoint, and the second sentence covers the two key behavioral traits. Every sentence earns its place with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (one required parameter, simple schema, output schema present, and annotations covering safety), the description covers the remaining operational context—cache duration and client-side pagination. An agent has enough information to call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with parameters id_contrato, pagina, and tamanho_pagina already documented including defaults, maximum, and pagination semantics. The description does not add parameter-specific meaning beyond the schema, so the schema carries the burden and baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with a specific verb ('Lista') and identifies both the semantic resource ('aditivos do contrato') and the exact endpoint path (/api/contrato/{id}/historico). Among many contract-related sibling tools, this clearly distinguishes it as the tool for listing a contract's amendments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies that the tool is used to retrieve contract amendments, but it does not explicitly state when to prefer it over related contract tools or provide exclusions. No alternatives are named, so the agent must infer usage context from the name and endpoint.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. Beyond that, the description adds valuable operational context: results are paginated client-side and cached for 15 minutes, which informs freshness expectations. No contradiction with 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely compact: one sentence identifying the resource and one sentence with two high-value operational facts. It is front-loaded and contains no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
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, the description is complete: it names the resource, includes the exact endpoint, explains pagination behavior, states cache duration, and the output schema covers return values. No critical information is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters already have complete schema descriptions, so the baseline applies. The description adds only the 'Paginação client-side' hint, which slightly enriches the pagination-parameter semantics but does not need to compensate for any schema gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 publicações DOU', reinforced by the endpoint path /api/contrato/{id}/publicacoes. This clearly identifies the tool as a reader for a contract's official gazette publications and is unambiguous against the long sibling list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context is clear: use this tool to list DOU publications for a given contract, with a required id_contrato. It adds client-side pagination and a 15-minute cache as practical usage notes, though it does not explicitly mention when not to use it or name alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 context beyond that: the exact HTTP endpoint and a 1-hour cache TTL. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short, purposeful sentences. The core behavior is front-loaded, followed by the endpoint, the practical use case, and the cache TTL. No redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (two optional array parameters), full schema coverage, rich safety annotations, and presence of an output schema, the description provides what an agent needs to select and invoke the tool correctly. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters described as CATMAT/CATSER codes to search. The description adds the item-level framing but no additional syntax, format, or relationship details 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.
Purpose5/5
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 contratos e empenhos por itens (CATMAT/CATSER) no Comprasnet'. The item-code scope and the supplied endpoint clearly distinguish this tool from siblings like contract listing or empenho-by-contract tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly explains when the tool is useful: discovering which suppliers currently provide given CATMAT/CATSER items, supporting identification of potential bidders in future tenders. It does not mention when not to use it or name alternative tools, so it stops 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.
Behavior4/5
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 annotations: the specific POST endpoint, the SICAF data source, and the 1-hour cache, which informs freshness expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core purpose. Every sentence adds value: the query semantics, the endpoint, the practical use case, and the cache behavior. No filler or redundant restatement of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only, idempotent lookup with two well-documented optional parameters and an output schema, the description covers all necessary aspects: what it does, when to use it, source of data, and cache behavior. Nothing essential is missing for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 both parameters. The description reinforces that the parameters are CATMAT/CATSER item code lists but adds no substantial new meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Consulta impedimentos no Comprasnet por lista de itens (CATMAT/CATSER)'. It clearly identifies the output (fornecedores impedidos) and the item-list scope, which distinguishes it from supplier-centric sanctions tools in the sibling list. The mention of SICAF-sanctioned suppliers adds precise domain context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context with 'Essencial antes de homologar pregões eletrônicos', telling an agent when this check is needed. It does not explicitly name alternatives or state when not to use it, but the context is strong enough to guide selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, idempotent, non-destructive behavior; the description adds operational context beyond those signals: it identifies this as a Dados Abertos endpoint and discloses a 1-hour cache freshness window. This gives the agent important stale-data awareness without contradicting 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: purpose, endpoint, return semantics, negative scope, use case, and cache behavior each get one focused sentence or clause. No filler or redundant elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a fully documented schema, a present output schema, and safety annotations, the description supplies the remaining operational context: endpoint identity, data semantics, non-purchase scope, intended temporal analysis, and cache behavior. An agent has everything needed to call and interpret the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of parameters with complete descriptions, so the description need not repeat them. It adds only the high-level grouping 'por período (ano/mês)' that maps to ano/mes, which is marginal extra value over the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb-object pair ('Métricas operacionais da API por período') and immediately scopes the resource to API usage metrics (requisições, latência, downloads), adding a clear negative ('não dados de compras') that differentiates it from procurement-data tools. The underlying endpoint is named, leaving no ambiguity about what is being invoked.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a clear use case ('Útil para análise temporal de disponibilidade do upstream') and an explicit exclusion ('não dados de compras'). It does not name alternative sibling tools or state exactly when to prefer them, so it stops short of full when/when-not coverage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds useful behavior beyond that: the specific endpoint path and the fact that the response returns the CSV inside the `csv` field. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short, front-loaded with the core meaning ('Versão CSV de compras_pgc_listar'), and every sentence earns its place: dataset identity, endpoint, usage context, and return format. There is no wasted wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich annotations, complete parameter schema, output schema, and the explicit sibling comparison, nothing essential is missing. An agent can correctly select and call this tool with the provided information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters `ano`, `codigo_uasg`, and `codigo_orgao` are already fully documented in the schema. The tool description itself adds no parameter-level detail, which matches the baseline of 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Versão CSV de `compras_pgc_listar` (mesmo dataset, formato planilha)', which states the verb (listar), resource (PGC data), and format (CSV) precisely. It explicitly differentiates itself from the sibling `compras_pgc_listar` by pointing out it is the same dataset in spreadsheet form.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It names the alternative `compras_pgc_listar` and gives a concrete use case: 'Útil para colar no ETP ou planilhar localmente'. However, it does not explicitly state when NOT to use this tool versus the JSON version, so it stops short of full exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only/idempotent/non-destructive behavior, and the description adds useful behavior beyond them: the 15-minute cache and the guarantee that the complete contracting header is 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences deliver purpose, endpoint, return scope, and cache behavior with no filler. The main lookup verb and key are front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, fully documented parameter set with rich annotations and an output schema, the description covers the remaining operational details an agent needs (endpoint and cache TTL). Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters are already fully documented in the schema with types, formats, and lengths (100% coverage). The description adds only the composite-key relationship and endpoint mapping, which are helpful but do not materially extend the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Consulta'), a specific resource ('contratação específica'), and the exact composite key (CNPJ + ano + sequencial). The endpoint path further distinguishes it from sibling contract/listing tools by identifying the exact URL pattern.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly frames the tool as a direct lookup for one specific contracting record by exact identifiers, which is clear context for agent selection. It does not explicitly name alternatives or state when not to use it, but for a simple idempotent lookup that gap is minor.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 extra behavioral facts: the exact endpoint, a 15-minute cache, and the client-side nature of the esfera filter. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short, purposeful segments: what the tool lists, why it is useful, and operational notes. The most important information is front-loaded, with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the robust annotations, 100% parameter documentation, and presence of an output schema, the description covers the remaining context an agent needs: use cases, endpoint, cache behavior, and the client-side filter caveat. Nothing essential is missing for selecting or invoking the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are already fully documented. The description mentions the esfera client-side behavior, but this largely repeats the schema text rather than adding new parameter-level meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Lista contratações') and a unique scope ('com prazo de proposta aberto no PNCP'), clearly separating it from sibling PNCP listing tools such as compras_pncp_contratacoes_publicacao or compras_pncp_contratacoes_atualizacao. The endpoint path reinforces the resource identity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: mapping open opportunities for suppliers and identifying ongoing contracting in comparable agencies. It does not name explicit alternatives or exclusion conditions, so it stops 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.
Behavior4/5
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 these by specifying a 1-hour cache and explaining the real-world significance of active leniency agreements, which is useful context an agent cannot derive from the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short, purposeful sentences: the core action, the endpoint and business context, and the caching behavior. Everything earns its place and the main purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter read-only tool with full schema coverage, an output schema, and rich annotations, the description is complete. It adds the cache detail and a concrete use case, so no essential operational information is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters clearly documented ('CNPJ do sancionado' and 'Página'). The description adds no additional parameter-level meaning beyond what the schema already provides, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 leniency agreements ('acordos de leniência') signed with the CGU, and gives the exact endpoint. This clearly differentiates it from sibling sanction-list tools like compras_sancao_ceis or compras_sancao_cnep.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly frames when the data is useful: risk analysis for high-value contracting ('análise de risco em contratações de alto valor'). It does not explicitly name alternative tools or list exclusion criteria, so it stops 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the annotations by documenting the upstream 404-vs-400 behavior, the required statusUasg parameter, server-fixed 500-record pagination, and a 24h cache. These are operational traits an agent cannot infer from readOnlyHint/idempotentHint and materially change how results should be interpreted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average but structured with paragraphs and each section covers a real behavioral surprise. The historical diagnosis section could be trimmed, but it explains why a 404 should not be treated as a routing bug, so it earns most of its space.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only listing tool with an output schema, the description covers the key operational facts: required-equivalent parameter behavior, defaults, pagination reality, and cache. Nothing necessary to call or interpret the tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Even with 100% schema description coverage, the prose adds decisive meaning: 'ativo' feeds the hidden required statusUasg parameter, defaulting to True, and 'tamanho_pagina' is ignored by the upstream route despite being declared with a max of 500. This corrects a misleading schema and gives the agent the true contract for two parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Lista UASGs (Unidades Administrativas de Serviços Gerais) do governo', a clear verb+resource statement, and gives a concrete sense of scope (~22 mil UASGs ativas). It does not explicitly contrast with siblings like compras_uasg_consultar or compras_uasg_buscar, so it is clear but not fully differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains that 'ativo' defaults to True and that active UASGs are the dominant use case, which gives context for the common call pattern. However, it never states when to prefer this listing tool over the sibling consultar/buscar tools or 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, non-destructive behavior. The description goes beyond that by disclosing a 15-minute cache and an upstream constraint that the validity window must be ≤365 days. These are concrete behavioral details an agent needs to anticipate staleness and API rejection.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: purpose, endpoint and constraint, usage tip, and cache behavior. Every sentence earns its place, 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.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present and rich annotations, the description covers the essential calling context: required date window, upstream endpoint, cache TTL, and optional filters. It does not emphasize sibling differentiation, such as when to prefer compras_arp_saldo_item or compras_arp_unidades_item, but for actually invoking this tool it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 value beyond the schema by explicitly stating that both date bounds are required and that the window cannot exceed 365 days, plus explaining that optional filters help locate atas with a specific item. This supplements the schema rather than merely repeating it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific action and object: 'Lista itens de ARPs na janela de vigência informada.' This clearly distinguishes the tool from sibling ARP tools like compras_arp_listar (which lists ARPs) and compras_arp_consultar (which consults an ARP), making its scope unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it lists ARP items within a validity window and requires dataVigenciaInicialMin/Max with a ≤365-day window. It also advises using optional filters to locate atas with a specific item. It does not explicitly name alternatives or exclusions, but the usage context is clear enough for an agent to choose it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 non-obvious behavioral context: the specific Dados Abertos endpoint and 'Cache 1h', which informs freshness expectations. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: action first, then endpoint, use case, and cache note. Every sentence contributes, and there is no repetition of schema or annotation information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 8-parameter list tool, the output schema and annotations already cover return shape and safety. The description adds endpoint, cache behavior, and the key use case. It does not explicitly distinguish itself from compras_fornecedor_consultar, but this is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema carries full parameter documentation. The description adds value by highlighting the intended combination of porte_empresa and codigo_cnae via the example 'todas as MEs com CNAE de TI' and framing these as structural filters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states a clear verb and resource: 'Lista fornecedores no Compras.gov.br com filtros estruturais.' It also provides a concrete differentiating example ('levantar todas as MEs com CNAE de TI'), which distinguishes it from sibling supplier tools like compras_fornecedor_consultar.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use para mapear fornecedores potenciais por porte/CNAE' with a concrete example. It does not name alternatives or state when not to use it, but the intended context is clear enough for an agent to choose this tool over lookup-oriented siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description richly discloses behavior beyond the annotations: it performs parallel probes against real upstream routes with short timeouts, retries timed-out routes serially before marking them 'fora', distinguishes silent contract-field failures from route failures, and explains credential-dependent 'pulado' status. The `pronto_para_uso` field is also defined as the honest summary, which gives agents a clear expectation of the tool's semantics. No contradiction with the read-only/idempotent 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average and includes a historical anecdote, but the main purpose is front-loaded in the first line and the rest is organized into clear sections: why it exists, arguments, status values, and retry behavior. The story about the 2026 outage earns its place by motivating the tool's existence, though some trimming would tighten it.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool of this complexity—parallel probing, multiple statuses, retries, credential skips, and a derived readiness flag—the description covers essentially everything an agent needs to call it correctly. The presence of an output schema means return-value details are already structured, so the description's focus on semantics, edge cases, and timing is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents both parameters in detail. The description reinforces `profundidade` with 'instantâneo' vs. probe behavior and gives examples for `modulo` (e.g., `pesquisa_preco`, `atas`, `pncp`), but adds little meaning beyond what the schema entries already state. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a concrete statement of what the tool does: reports, in ~30 seconds, what is up on the server right now. It explicitly positions itself as an extension of the sibling `compras_versao` (version/config plus upstream probes), and frames this as a health check with per-module status, clearly distinguishing it from the many query-focused siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance: run this before a demo or before instructing a process, so outages are discovered here rather than on stage. It also explains the `profundidade` choice and mentions that `compras_versao` is the more basic alternative, though it stops short of an explicit 'use compras_versao instead when only version/config is needed' exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds useful context beyond annotations: resources contain static reference data (domain tables, glossary, server metadata), and this tool returns metadata only, not content. This is meaningful behavioral context despite the safety profile being 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a one-line core purpose, a short discovery-context note, a sentence about resource content, and a compact return example. It is slightly more verbose than strictly necessary for a zero-parameter tool, but every section earns its place and nothing is redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter listing tool with an output schema already present, the description is complete. It explains the purpose, when to use it, what the resources contain, the return shape, and points to the sibling for reading content. An agent has everything needed to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is nothing for the description to explain. With 100% schema coverage and no parameters, the baseline of 4 applies and the description appropriately does not attempt to document nonexistent parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 os MCP Resources disponíveis com URI, nome e mime-type.' It clearly distinguishes this listing tool from the content-reading sibling compras_obter_resource(uri), and from compras_listar_prompts, so an agent can tell them apart without needing the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives concrete context: it is a discovery tool for clients without resource-attachment UI, like Claude.ai web, while desktop clients have dedicated pickers. It also directs users to compras_obter_resource(uri) for content. It does not explicitly state when not to use it, but the guidance is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool as read-only, idempotent, and non-destructive, so the description does not need to restate those. It adds useful behavioral context beyond annotations: the underlying Dados Abertos endpoint, upstream enforcement of the date window, and a 15-minute cache. This informs the agent about data freshness and operational behavior 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well structured: core action first, then endpoint and constraint, then a targeted alternative, then cache behavior. Every sentence serves a purpose, and no redundant filler exists.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the strong annotations, complete input schema, and available output schema, the description covers the operational context an agent needs: what is listed, the upstream endpoint, the mandatory date window rule, the cache freshness, and a clear routing to an alternative sibling. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% parameter coverage, so the schema already documents each parameter thoroughly. The description only references the date-window constraint that also appears in the schema, adding little new parameter-level meaning. Baseline 3 is appropriate because the description provides minimal added value for parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 Atas de Registro de Preço (ARPs) por janela de início de vigência.' This clearly identifies what the tool does and distinguishes it from related ARP tools, especially compras_arp_por_fim_vigencia, without any ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states the intended use case (listing by start-of-validity window), names the upstream constraint (required date window ≤ 365 days), and gives a direct alternative for a different use case: 'Para listar atas próximas do vencimento, use compras_arp_por_fim_vigencia.' This leaves no doubt about when to choose this tool versus a sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Mesmo com annotations cobrindo read-only, idempotência e não-destrutividade, a descrição acrescenta muito comportamento: estrutura do payload com 1 linha por (numeroItem, unidade, tipo), explicação de que múltiplas linhas não são duplicação, existência do agregado resumo_por_item e cache de 15 minutos. Não há contradição com as annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
O texto é organizado em blocos curtos com negrito, cada um com propósito claro: definição, criticidade, estrutura do payload, resumo agregado e cache. Nenhuma frase é redundante; até a menção ao achado da bateria A justifica a existência do resumo_por_item.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
A descrição cobre o essencial para uso correto: o que é saldo, por que importa para adesão, como interpretar as múltiplas linhas por item, que há um resumo agregado pronto e que o saldo tem cache de 15 minutos. Como existe output schema, não é necessário detalhar a estrutura de retorno novamente.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
A cobertura do schema é 100% e as descrições dos parâmetros já explicam numero_ata, unidade_gerenciadora, pagina e tamanho_pagina. A descrição do tool não acrescenta semântica nova de parâmetros, apenas menciona campos de saída como numeroItem, unidade e tipo, que não são parâmetros de entrada. Baseline 3 é adequado.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
A descrição abre com 'Devolve o saldo (quantidade ainda disponível) por item da ARP', combinando verbo específico, recurso e escopo. Isso a distingue claramente dos irmãos como compras_arp_itens_listar, compras_arp_unidades_item e compras_arp_adesoes_item, ainda que não os nomeie.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
A descrição contextualiza fortemente quando usar: 'Crítico para adesão: a ata pode estar vigente mas com saldo zerado. Sem saldo, não há como aderir.' Isso orienta a decisão de uso com clareza, embora não mencione explicitamente alternativas ou quando não usar este tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent annotations, the description reveals meaningful behaviors: it calls Portal da Transparência and Comprasnet in parallel, returns a boolean verdict plus a consolidated list, raises ComprasAuthError when TRANSPARENCIA_API_KEY is missing, and caches for 10 minutes. This is substantial added transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: purpose, composition, return value, error condition, and usage guidance each occupy one clear segment. There is no filler or redundant restatement of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a consolidation tool with one input and an output schema, the description covers the essential operational context: what is aggregated, how sources are queried, what is returned, when it should be used, what can fail, and caching behavior. An agent has enough information to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes the only parameter, cnpj, including format and accepted punctuation, so schema coverage is 100%. The description adds no additional parameter-level semantics, which matches the baseline of 3 for full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and object: 'Consolida sanções de um fornecedor', naming the exact data sources (CEIS, CNEP, CEPIM, leniência, impedimentos). This clearly distinguishes the tool from the many sibling lookup tools such as compras_sancao_ceis or compras_sancao_cnep, since its role is consolidation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage context: 'Sempre use antes de homologar pregões/contratos', which tells an agent when this tool is appropriate. It does not explicitly contrast with the individual sanction-list siblings or state when not to use it, so it falls just 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint/idempotent annotations, the description discloses cache behavior, client-side pagination, and a critical LGPD masking caveat about the `infcomplementar` field potentially containing personal data not covered by masking. This adds substantial behavioral context far beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: purpose first, then behavior, then the LGPD warning. Every sentence adds value, and there is no redundant text or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list operation with an output schema and safety annotations, the description covers purpose, endpoint, pagination, caching, and the key privacy caveat. Nothing needed to invoke the tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already has 100% coverage, describing all three parameters (`pagina`, `id_contrato`, `tamanho_pagina`) including defaults and max value. The description does not add significant parameter-level meaning beyond 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Lista NFs/faturas' and gives the endpoint '/api/contrato/{id}/faturas', clearly identifying a specific verb and resource: listing invoices for a given contract. This is unique among sibling tools, none of which target faturas, so an agent can distinguish it immediately.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear practical context: pagination is client-side, results are cached for 15 minutes, and LGPD-sensitive free-text fields may contain unmasked server names and SIAPE numbers. It does not explicitly name alternatives or exclusions, but the purpose and these usage notes give enough guidance for the agent to select and use the tool correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description adds important behavioral details: CPFs are masked for LGPD compliance, pagination is client-side, and results are cached for 15 minutes. These are non-obvious traits that materially affect how an agent interprets results and parameters, and they do 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: it states the core action, then flags the key caveats (LGPD masking, client-side pagination, cache). Every sentence provides useful information and there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a three-parameter read-only tool with a full schema and an output schema, the description is sufficient. It covers the main behavioral concerns an agent needs to invoke the tool correctly and interpret results, without needing to explain return shape since an output schema exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 value by clarifying that pagination is client-side, which changes the meaning of 'pagina' and 'tamanho_pagina'—they are not necessarily server-side pagination controls. This is useful semantic context beyond the schema text.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with a specific verb and resource: 'Lista fiscais/gestores', and reinforces it with the endpoint path '/api/contrato/{id}/responsaveis'. This clearly distinguishes the tool from sibling contract-related tools such as compras_contrato_faturas or compras_contrato_garantias by naming a unique resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage is implied by the resource: an agent can infer this is the tool to list contract fiscal/manager personnel. However, there is no explicit when-to-use guidance or exclusions naming alternative tools, which would be valuable given the large set of sibling contract tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the bar is lower. The description adds useful behavioral details beyond annotations: the endpoint path, the 1-hour cache, and the scope limitation to operational metrics rather than market indicators.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences with no filler. The purpose and endpoint are front-loaded, followed by return fields, usage guidance, and cache behavior. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only metrics tool with an output schema, the description is complete: it specifies the endpoint, the returned metrics, the intended use case, an explicit exclusions, and cache behavior. Nothing needed to select and invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and both parameters (página, tamanho_pagina) already have clear descriptions in the schema. The tool description does not need to add parameter detail, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies a clear, specific resource: consolidated operational metrics of the Dados Abertos API, and lists the exact endpoint and metrics returned. It distinguishes itself from sibling tools by explicitly stating it is not for public market indicators, helping an agent tell it apart from related indicator tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use this tool: for diagnostics and observability, and when not to use it: not for public market indicators. This gives clear selection guidance even without naming a specific sibling alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds useful behavioral context: the upstream endpoint and the important constraint that id_compra must be a string, not a numeric id, which prevents a likely misuse.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the primary purpose appears in the first sentence, and the endpoint/parameter nuance follows without redundancy. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read operation with an output schema present and strong annotations, the description is complete. It identifies the exact input, where that input comes from, and the upstream behavior, leaving no critical gap for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the schema already documents id_compra as a SIASG string returned by the listing tool. The description adds extra semantic value by emphasizing that upstream expects a string and explicitly rejecting a numeric id, addressing a real boundary condition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Consulta'), a specific resource ('licitação legado'), and the lookup key ('pelo id_compra'). The endpoint path further disambiguates it from sibling listing tools like compras_legado_licitacoes_listar.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the intended workflow: the id_compra is returned by compras_legado_licitacoes_listar, so this tool is for consulting a specific legacy procurement after listing. It does not explicitly name alternatives or exclusions, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, idempotent, non-destructive behavior, so the bar for additional disclosure is lower. The description adds useful non-obvious behavior by revealing the upstream endpoint and warning that the date parameters are named min/max, not inicial/final, which prevents a likely misconfiguration.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, no filler, and the core purpose is front-loaded. The critical upstream naming note is highlighted in bold, and the historical relevance context is given in one clause. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, annotations cover safety, and the input schema documents all eight parameters, the description supplies the missing pieces: the endpoint, the upstream naming gotcha, and the legacy relevance context. Nothing an agent needs to call or interpret the tool correctly is omitted.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 adds semantic value by explicitly warning that the upstream API uses data_publicacao_min/max rather than inicial/final, which is a genuine trap beyond what the schema property names alone communicate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 pelo RDC', expanding the acronym and giving the endpoint path. This clearly differentiates the tool from legacy siblings like compras_legado_licitacoes_listar and compras_legado_pregoes_listar, which cover other procurement regimes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: RDC was mainly used for megaevent and World Cup infrastructure works, and its relevance is residual today. This helps the agent judge when this legacy data is appropriate, though it does not explicitly name alternatives or state when not to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent annotations, the description discloses real behavioral traits: it iterates over pages up to max_paginas, aggregates unit values, computes a full statistical summary, discards IQR outliers, and caches results for 10 minutes. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight blocks lead with the main action, then composition, then output and cache. Every sentence contributes information; there is no filler or repetition of schema fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich schema, output schema, and annotations, the description covers what's needed to invoke it correctly: purpose, methodology, source tools, aggregation logic, ETP-ready output, and cache behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema descriptions already cover 100% of parameters with details like page size, defaults, and the IN SEGES/ME 65/2021 recommendation. The description itself adds little parameter-level meaning beyond naming max_paginas in the composition narrative, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and object: 'Agrega preços praticados' applying a named methodology, then details the exact calculations and the ETP-ready output. This clearly distinguishes the tool from sibling aggregation/search tools by its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Saída pronta para colagem em ETP' line gives a clear use case, and the methodology reference (IN SEGES/ME 65/2021) indicates when it applies. It does not explicitly name alternatives or say when not to use the tool, so it stops 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the read-only annotations, the description discloses important behavioral traits: the client-side application of the esfera filter, the fact that _total_registros remains unfiltered, the ~30-day maximum query window, and the 15-minute cache. This gives the agent crucial operational expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well structured: main purpose, endpoint/scope, then operational caveats. Every sentence adds useful information, and there is no filler or redundancy beyond the modalidade codes already present in the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 9-parameter schema and the presence of an output schema, the description covers the essential constraints an agent needs: date window, cache behavior, client-side filtering, and total-count semantics. Nothing critical is missing for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 value by explaining the client-side esfera behavior, the maximum date window, and the common modalidade codes, which supplements the schema's parameter descriptions without repeating them wholesale.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 publicadas no PNCP no período'. It adds the endpoint and notes coverage of all federal entities, making it readily distinguishable from sibling tools focused on proposals, updates, or specific organs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use is clearly implied: list PNCP contract publications by date range. However, there is no explicit guidance about when to prefer this tool over close siblings like compras_pncp_contratacoes_atualizacao or compras_contratacoes_14133_listar, and no exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavior beyond the read-only/idempotent annotations: cache duration of 24h, coverage of state and municipal organs, and explicit 404 handling where it returns an informative `_erro_upstream` with alternatives instead of raising an exception. No contradiction with 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, followed by the endpoint, use case, coverage, cache, and error behavior. Every sentence earns its place, and the bold 404 section is a well-structured, useful addition without unnecessary repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a single documented parameter, rich annotations, and an output schema present, the description covers what an agent needs: purpose, endpoint, intended use, cache semantics, coverage, and error behavior. Nothing critical is missing for calling this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single `cnpj` parameter, and the schema already documents format, length, and an example. The description adds no new parameter-level semantics beyond 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Lista unidades administrativas de um órgão no PNCP' and identifies the exact PNCP endpoint. It also explains the practical purpose: discovering unit codes before filtering contracts. The verb-resource combination is specific and distinct 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.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it is useful before filtering an organ's contracting/contract data, and it notes broad coverage of states and municipalities. It does not explicitly list exclusions or alternative sibling tools for when not to use it, so it stops one short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 context beyond those: the specific PNCP endpoint and a 1-hour cache TTL. This is relevant for freshness expectations and goes beyond what annotations and schema provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short, purposeful elements: what it does, endpoint, and usage guidance with cache note. Every sentence earns its place, and the main purpose is front-loaded before the alternative and technical details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only, paginated list tool with rich annotations, a complete input schema, and an output schema present, the description provides all essential context: purpose, endpoint, usage alternative, and cache behavior. Nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so every parameter is already documented in the input schema. The description only reinforces the id_usuario concept in prose without adding meaning not already present; baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description starts with a specific verb and resource: 'Lista PCAs vinculados a um usuário/sistema integrador específico.' It clearly differentiates this tool from the likely alternative compras_pncp_pca_listar by naming that sibling and the condition that selects it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says this is less common and that analysts generally prefer compras_pncp_pca_listar with cnpj_orgao. This gives an agent concrete routing guidance without having to infer it from tool names or schemas.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent annotations, the description reveals that search is executed locally by scanning upstream pages, that results are cached for 24h, that pagination applies after local filtering, and that the payload includes `_busca_local`, `_paginas_varridas`, and `_universo_varrido` to expose truncation. It also documents the upstream `nome` parameter quirk that could cause silent universe-wide results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The definition is front-loaded with an excellent one-sentence purpose and uses structured sections, which helps readability. However, it contains changelog noise such as '✅ Restaurada em 2026-08-05', a counterfactual rationale, and repeated cache information that could be condensed into a few concise operational notes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with unusual local-search behavior, this description covers performance cost, cache duration, truncation visibility, upstream contract pitfalls, and result filtering semantics. An output schema exists, so the description does not need to enumerate return fields, and the mention of debug payload fields is a useful supplement.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers all three parameters, so the baseline is 3. The description adds valuable meaning by clarifying that `pagina` and `tamanho_pagina` paginate the locally filtered result set, not the upstream API pages, which changes how an agent should interpret those parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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: 'Busca UASGs por trecho do nome (match parcial, ignora acento e caixa).' This clearly distinguishes it from sibling tools like compras_uasg_listar and compras_uasg_consultar.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes it clear that this tool is for searching UASGs by a name fragment, which tells an agent when to call it. It does not explicitly name alternatives or exclusions, but the introductory phrase provides enough contextual guidance for routine selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent annotations, the description discloses important runtime behavior: three PNCP modality calls made in parallel, 30-60s per call, 60-90s total cold-cache latency, and <1s with Redis warm cache. It also explains the deduplication and ordering behavior. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded: one-sentence summary, then composition details, then a bolded latency warning. Every sentence adds operational value; there is no filler or repetition of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only, idempotent search tool with full schema coverage and an output schema, the description is nearly complete: sources, algorithm, ordering, use case, and latency are all covered. The main gap is that it never explicitly states that at least one of codigo_catmat or codigo_catser should be provided, even though all parameters are marked optional in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, and the description adds value by clarifying that codigo_catmat/codigo_catser identify the target item and that max_resultados applies after deduplication. It does not add much for uf or periodo_meses, but the schema already documents those adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource: federating Dados Abertos + PNCP to find similar contracts ('contratações similares'). It distinguishes this tool from list/consult siblings by detailing the unique composition: filtering by CATMAT/CATSER, deduplicating by CNPJ + year + sequential, and returning the most recent max_resultados.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear intended use case: 'Insumo para mapear benchmarks de outros órgãos' (input for mapping benchmarks of other agencies). It does not explicitly name alternatives or state when not to use this tool, so it stops short of a 5, but the usage context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal readOnly/idempotent/non-destructive, and the description adds substantial behavioral context: the tool does not return price, lists the exact 7 upstream DTO fields, confirms the field never existed upstream, and notes 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The first line front-loads the purpose and the critical 'no price' warning, followed by the alternative and use cases. The audit trail and DTO field list are informative but somewhat longer than strictly necessary, with the 'no price' point repeated multiple times.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the annotations, 100% schema coverage, and presence of an output schema, the description covers everything needed: endpoint, exact returned fields, the key limitation, the correct sibling, use cases, and cache behavior. Nothing essential for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, including defaults and date formats, so the schema already carries parameter meaning. The description adds no parameter-level semantics beyond the general CATMAT item context, which matches the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Lista as compras individuais de um item CATMAT', and immediately clarifies the critical scope — 'sem valor de preço'. It names the sibling that does return price, so an agent can distinguish this tool without inspecting schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly tells when to use the tool ('apenas para: descrição detalhada do item como comprado, objeto da compra e rastreio do idCompra') and when to use the alternative (`compras_pesquisar_preco_material` for unit prices). This is direct, actionable routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent annotations, the description discloses the exact returned DTO fields, explicitly warns that no price field exists (with a verification date), and notes the 10-minute cache. This is substantial behavioral context that annotations do not provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The key behavior and the critical no-price warning are front-loaded in the first sentence. The description is slightly repetitive about the absence of price, but every section (endpoint, DTO fields, alternative, cache) earns its place without excessive verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with an output schema and full parameter documentation, the description covers the essential context: what it returns, what it omits, which sibling to use instead, the endpoint, and caching behavior. An agent has everything needed to call and interpret this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 five parameters including defaults and formats. The description adds no extra parameter-level detail beyond what the schema provides, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists individual purchases of a CATSER service and immediately clarifies that it does NOT return price values, which is crucial given the tool name. It distinguishes itself from the sibling compras_pesquisar_preco_servico by naming exactly what that alternative returns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says that for unit price of a service, use compras_pesquisar_preco_servico, which returns precoUnitario and supplier. This gives a clear when-to-use versus when-not-to-use directive, leaving no ambiguity about the primary alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 useful context beyond that by framing the tool as an alternative discovery path and by documenting the return shape and the follow-up rendering tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with the core purpose, followed by usage context and a return example. The code block is slightly redundant given that an output schema exists, but it is compact and immediately understandable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-argument, read-only discovery tool, the description is complete: it states what is listed, when to use it, when not to rely on it, what the response looks like, and how to proceed to render a prompt. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the description does not need to explain input semantics. The baseline of 4 applies, and the return example usefully clarifies the shape of argument metadata even though no input arguments exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 os MCP Prompts disponíveis com nome, descrição e argumentos'. It clearly distinguishes this discovery tool from the rendering tool compras_obter_prompt, so an agent can separate them immediately.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use this tool — for clients like Claude.ai web that lack a dedicated prompts UI — and names the environments where it is not the primary path (Claude Desktop, Cursor, MCP Inspector). It also directs the agent to compras_obter_prompt for the next step.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish a safe read-only, idempotent profile, and the description adds substantial operational context beyond them: the upstream endpoint, 10-minute cache, a documented upstream 404 failure mode, and the fact that the tool returns `_erro_upstream` instead of raising an exception. This is exactly the kind of behavioral disclosure that helps an agent handle 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with the core purpose and sibling alternatives. The upstream-break narrative is detailed and slightly verbose, though it supports troubleshooting; the information is useful enough that only minor trimming would make it fully tight.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 8-parameter schema, the output schema, and the unusual upstream behavior, the description covers all essential context: purpose, endpoint, sibling routing, response contents, caching, and error behavior. Nothing an agent needs to select or call this tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so the baseline is 3 even without additional parameter detail in the description. The description mentions endpoint-level parameter history (`codigoItemCatalogo` replaced by `tipo` + `codigo`) and response fields, but it does not add meaningful semantics to the parameters beyond what the schema already documents.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Pesquisa preços praticados em compras de material (CATMAT) pelo governo.' It clearly differentiates the tool from siblings by noting that compras_detalhar_preco_material does NOT return a price and that compras_pesquisar_precos_para_etp provides consolidated statistics instead. This leaves no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit routing guidance: for consolidated average/median statistics, use compras_pesquisar_precos_para_etp; for unit prices of materials, this is the tool. It also explicitly warns that compras_detalhar_preco_material does not return prices, helping the agent avoid the wrong sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Read-only and idempotent hints already cover the safety profile, and the description adds non-obvious behavior: malformed purchase-format IDs produce an explicit diagnostic instead of a silent `encontrada=false`, and results are cached for 15 minutes. These are meaningful behavioral details not available from annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short paragraphs with no filler: purpose, endpoint, output, edge-case behavior, and cache policy. Each sentence earns its place, 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.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read-only lookup, the description plus the rich schema and output schema cover everything needed: what it returns, how the input is identified, what happens on misuse, and caching behavior. Nothing required for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents the single parameter with format, example, source field, and a warning about confusing purchase/ata IDs. The tool description adds further semantic value by explaining the failure behavior when the identifier uses the purchase-format, reinforcing why the `-NNNNNN` suffix matters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Consulta uma ARP específica pelo identificador PNCP' and clarifies that it returns the complete ata header. The word 'específica' plus the PNCP identifier distinguishes it from the sibling list/search tools without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
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 this tool: to fetch one specific ARP by its PNCP ata identifier. The schema adds guidance on where the identifier comes from (compras_arp_por_fim_vigencia) and warns against confusing it with numeroControlePncpCompra, though it does not explicitly enumerate sibling alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint/idempotent annotations, it discloses two meaningful behaviors: client-side pagination (with a concrete reason: some contracts have 200+ monthly entries) and a 15-minute cache. These are exactly the operational details an agent needs to interpret results correctly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short lines, no filler: main action, endpoint, pagination behavior, cache. All information is front-loaded and every sentence carries operational value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, all parameters are documented, and annotations cover read-only/idempotent safety, the description covers the remaining operational context (pagination and cache). Nothing material is missing for correct invocation and result interpretation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 value by showing id_contrato is the path parameter from the endpoint and explaining that pagination is client-side, which clarifies the roles of pagina and tamanho_pagina. It still does not detail page semantics beyond the schema defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb and object – 'Lista cronograma financeiro' – and includes the exact endpoint (/api/contrato/{id}/cronograma), making the operation unmistakable. This distinguishes it from sibling contract-resource tools such as empenhos, faturas, and garantias.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The resource name and endpoint make it clear this is the tool for a contract's financial schedule, giving an agent enough context to choose it over related contract detail tools. It does not explicitly name alternatives or exclusion conditions, 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior, lowering the burden on the description. The description still adds valuable behavioral detail: 24h caching, provider selection (BrasilAPI/MinhaReceita), and graceful error behavior returning encontrado=false with a diagnostic in _erro instead of throwing exceptions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a concise summary up front, a field list, a bolded usage section, and a final behavior/error note. Every sentence serves a clear purpose: identity, return contents, when to use, alternatives, and runtime behavior. It is informative without being bloated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the single parameter, rich annotations, and existing output schema, the description covers all essential context: data source, exact returned information, relationship to sibling tools, non-coverage of sanctions, cache duration, and error semantics. An agent has everything it needs to decide when to call this tool and how to interpret failures.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: the single cnpj parameter is already fully documented with length, formatting, and provider configuration via env variable. The description adds no additional parameter-level meaning beyond what the schema provides, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states this is a public CNPJ data lookup from Receita Federal and enumerates the exact returned fields (razão social, CNAEs, QSA, capital social, etc.). It explicitly positions itself as a complement to compras_perfil_fornecedor_completo and distinguishes itself from sanction tools, so an agent can select it correctly among many sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is a dedicated 'Quando usar' section explaining it complements compras_perfil_fornecedor_completo for due diligence. It also explicitly states what this tool does NOT do — it does not check sanctions — and directs the agent to the CEIS/CNEP/CEPIM/CEAF sanction tools instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
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 materially useful behavioral context by documenting a confirmed upstream bug where the uasg filter returns HTTP 400, explaining why the parameter was removed, and offering a workaround. This goes well beyond the structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four focused sentences: purpose, endpoint, bug, workaround. Each sentence earns its place, and the main purpose is front-loaded before the caveat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list operation with a complete input schema and an output schema available, the description covers the domain, endpoint, known failure mode, and workaround. Pagination and date requirements are already handled by the schema defaults and descriptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents all seven parameters, so the description does not need to repeat parameter-level details. It adds extra meaning by explaining the missing uasg parameter and pointing to the response field uasg for client-side filtering, which helps agents understand the parameter space more fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description names the verb 'Lista' and the specific resource 'licitações do regime legado (Lei 8.666/93)', which clearly distinguishes it from the 14.133-related sibling tools. The endpoint string reinforces the target without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly places the tool in the legacy-regime context and gives a practical workaround for UASG filtering: list without the filter, then filter client-side. It does not explicitly compare against alternative sibling tools or state when not to use it, 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even though annotations already mark this as readOnly, idempotent, and non-destructive, the description adds highly valuable behavior beyond those hints: it documents a confirmed upstream bug, explains that co_uasg/co_orgao cause HTTP 400 with a specific Hibernate error, and provides a client-side filtering workaround. This prevents agents from repeatedly attempting unsupported parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, then the endpoint, then the critical bug and workaround. Every sentence serves a purpose; the length is justified by the non-obvious upstream failure mode. No fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only listing tool with rich annotations, full schema parameter descriptions, and an output schema, the description covers the remaining practical gaps: endpoint identity, why certain filters are missing, and how to achieve the intended client-side filtering. 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.
Parameters4/5
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 goes further by clarifying which upstream-documented filter parameters are intentionally absent and how to compensate using coUasg/coOrgao in the result, which is meaningful parameter-related guidance not present in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 pregões eletrônicos do regime legado', making it clear this is a read-only listing tool for legacy electronic bidding processes. It also distinguishes itself from the many 14.133 and broader licitação siblings by explicitly naming 'regime legado' and 'pregões eletrônicos'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear operational guidance: it tells the agent that UASG/orgão filters were removed due to an upstream bug and instructs to 'chame sem filtro e filtre client-side' using result fields. It does not explicitly name sibling alternatives or state when not to use this tool, but the legacy-regime scope and workaround make usage conditions reasonably clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent annotations, the description discloses concrete runtime behavior: parallel fetching of the three secondary endpoints, a 10-minute cache, and an explicit diagnostic when the PNCP identifier is in 'compra' format instead of 'ata' format, avoiding the previously silent cabecalho: null failure. This is substantial added transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well organized: purpose first, then composition, then data-source prerequisites, then caching and failure behavior. Each sentence contributes unique information and 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.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with four parameters, a true output schema, and readOnly/idempotent annotations, the description supplies the missing context: what endpoints are composed, how the parameters map to them, where prerequisite IDs come from, cache behavior, and a known edge-case failure mode. Nothing essential for invoking it correctly is absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers all parameters at 100%, so the bar is a baseline of 3. The description adds meaningful relational semantics: numero_item gates the extra endpoints, numero_ata + unidade_gerenciadora form the compound key for those endpoints, and numero_controle_pncp_ata has a format warning. This goes beyond the schema without being exhaustive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Dossiê completo de uma ARP em uma chamada', naming a specific verb, resource, and scope. It then enumerates the composition (header, saldo, adesões, unidades participantes), which clearly distinguishes this aggregation tool from the granular sibling endpoints like compras_arp_consultar and compras_arp_saldo_item.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: it is a composite single-call dossier, conditional on numero_item, and it states that the required IDs come from compras_arp_listar or compras_arp_itens_listar. It does not explicitly name alternatives for when only a header or a single component is needed, so it stops short of full when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnly/openWorld/idempotent/non-destructive hints, so the bar is higher — and the description clears it. It discloses parallel composition of four upstream sources, a configurable provider (CNPJ_PROVIDER, default brasilapi), partial-failure behavior when the CGU WAF blocks or the API key is missing, and a 10-minute cache. This is exactly the behavioral context annotations cannot express.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured and front-loaded: the one-sentence purpose leads, followed by a scannable bullet list of data sources. The exclusion rationale, alternative, API-key caveat, and cache line each earn their place — no filler. The length is justified by the tool's genuine complexity (four parallel aggregations with distinct upstream dependencies).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex aggregator with an output schema present, nothing an agent needs to call it correctly is missing: data source composition, upstream endpoints, provider configurability, the contracts exclusion with alternative, environmental dependencies, failure semantics, and cache duration are all covered. The output schema handles return-value documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% — the `cnpj` parameter is fully documented in the schema (format, length, punctuation allowed). The description reinforces that CNPJ is the lookup key across all four blocks ('pelo CNPJ' appears three times), which adds confirmation but no substantially new semantic information. Baseline 3 is appropriate given the schema carries the load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific statement of what the tool produces: 'Perfil consolidado do fornecedor (cadastro + Receita + sanções + impedimentos)' — a clear verb+resource definition. The four data components are enumerated in a bulleted breakdown, and the description explicitly states what the tool does NOT include (contracts), distinguishing it from sibling 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.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when-not-to-use guidance: contracts are excluded because upstream endpoints require `codigoOrgao`, and names the alternative directly: 'Se você já souber o órgão, use compras_contratos_listar(codigo_orgao=X, ni_fornecedor=Y, ...)'. It also flags the operational precondition that sanctions depend on TRANSPARENCIA_API_KEY and may degrade gracefully.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
As annotations já indicam readOnly/idempotent, e a descrição adiciona contexto comportamental relevante: paginação interna até max_paginas_varridas, filtro client-side case-insensitive com normalização de acentos, curto-circuito em max_resultados, cache de 15 min e a limitação de o schema upstream não trazer UF. Não contradiz as annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A informação é bem estruturada: propósito, limitação, output e cache são separados claramente. Há pequeno excesso contextual ('Achado da bateria A v0.3.5' e referência ao roteiro), mas não compromete a legibilidade.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Para uma tool com 5 parâmetros, annotations e output schema, a descrição cobre tudo que um agente precisa: motivo de existência, comportamento de paginação, limites, formato de retorno, cache e limitação conhecida com solução alternativa para UF.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
O input schema já cobre 100% dos parâmetros com descrições detalhadas, então a baseline é 3. A descrição agrega ao explicar como os parâmetros interagem na execução real: varredura interna, paginação, curto-circuito e contexto de proteção de latência.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
A descrição abre com verbo e recurso específicos: 'Busca ARPs vigentes cujo objeto contém uma palavra-chave'. Também diferencia a tool ao explicar que resolve a limitação do endpoint upstream, que não aceita filtro por texto.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Há orientação explícita de quando usar e quando não: busca por palavra-chave no objeto, e para filtro por UF a descrição manda cruzar com compras_uasg_consultar em vez de tentar via esta tool. A alternativa é nomeada e a condição de uso é clara.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as read-only and idempotent, but the description adds substantial non-obvious behavior: the three textual filters are ignored, the response returns all ~11.8k active organs, there is a 24h cache, and the tool was previously broken due to a missing statusOrgao parameter. This goes well beyond what annotations express.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and endpoint, and the behavioral warnings are clearly separated with bolded labels. Some historical restoration details could be trimmed, but the structure makes the caveats easy for an agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a listing tool with no required parameters, an output schema, and read-only annotations, the description covers scope, returned fields, the broken-filter caveat, the alternative lookup tool, and cache behavior. Nothing critical is missing for a correct invocation decision.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 earns extra value by correcting misleading schema semantics: nome, esfera, and poder are described as filters in the schema, but the description warns they do not work and are ignored by the upstream. Pagination parameters are already well documented in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Lista órgãos cadastrados no Compras.gov.br' and identifies the exact Dados Abertos endpoint. It also lists the returned fields, making it clearly distinct from the lookup sibling compras_orgao_consultar.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when not to rely on it: nome, esfera, and poder filters are ignored upstream. It also points to the alternative for specific lookups: 'Para localizar um órgão específico use codigo_orgao em compras_orgao_consultar.' This directly routes the agent to the right tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint/idempotentHint annotations, the description discloses that the upstream textual filter is currently ignored and returns the entire ~340k CATMAT universe, that the tool emits _aviso_filtro when it detects this, and that results are cached for 24h per term+filters+page. This is rich behavioral context that annotations alone do not provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average, but it is tightly structured with a warning callout, a numbered workflow, and a short cache note. Every section carries necessary information given the upstream bug, and the most urgent warning is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists and annotations cover safety, the description is complete for correct invocation: it covers purpose, current upstream behavior, a reliable workflow, parameter semantics, a payload warning, and caching behavior. No essential operational detail is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents all parameters (100% coverage), but the description adds critical usage semantics: termo is sent but currently has no effective filtering power, while codigo_grupo and codigo_classe are the real reducers. It also explains the cache key. This goes beyond the schema, though the mention of codigo_pdm, which is not present in the schema, is a minor confusing detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with Busca itens CATMAT, a specific verb and resource, and clarifies this is the final search step in a workflow after listing groups and classes. It implicitly differentiates the search tool from the list/consult siblings and states the result is a CATMAT item search with textual and structural filters.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides an explicit Workflow recomendado with numbered steps, telling the agent to call compras_catmat_listar_grupos and compras_catmat_listar_classes first, then call this tool with codigo_grupo/codigo_classe while the textual filter is broken. It also states that structural filters still work and termo is kept for compatibility, which is a clear when/when-not guide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as readOnly, idempotent, and non-destructive, but the description adds genuinely useful behavioral context: it is a local tool that does not call upstream, its source is the official PNCP table, and there is a critical ecosystem-wide distinction between two modality-code tables. This helps an agent understand edge cases around data equivalence without needing external knowledge.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: the core purpose is stated first, followed by the local/source facts, then the crucial disambiguation warning. Every sentence adds value, and the warning about the two tables is essential, not filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter reference tool with an output schema present, the description provides all necessary context: what the data is, where it comes from, how it relates to other tools, and how to handle the Dados Abertos enum discrepancy. Nothing important is missing for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the empty input schema carries no burden. The description appropriately focuses on what the returned codes mean rather than parameter details, which is the relevant semantic context for a parameterless reference tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as a local cheat sheet for PNCP contracting modality codes, with a specific scope and source (official PNCP table from Lei 14.133). It distinguishes itself from related tools by explicitly warning that its `codigo` is the PNCP enumeration used across all `compras_pncp_*` tools, whereas Dados Abertos/SIASG uses a different enumeration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance on when this tool's codes apply and names the alternative endpoint (`compras_contratacoes_14133_listar`) for the different Dados Abertos/SIASG enumeration. It also explains the `equivalente_dados_abertos` field and its `None` value, which helps an agent choose correctly between the two encodings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![MCP_Compras MCP server](https://glama.ai/mcp/servers/opedrosoares/MCP_Compras/badges/card.svg)](https://glama.ai/mcp/servers/opedrosoares/MCP_Compras)

Score Badge

Copy to your README.md:

[![MCP_Compras MCP server](https://glama.ai/mcp/servers/opedrosoares/MCP_Compras/badges/score.svg)](https://glama.ai/mcp/servers/opedrosoares/MCP_Compras)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/opedrosoares/MCP_Compras'

If you have feedback or need assistance with the MCP directory API, please join our Discord server