editalmd

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

Annotations already declare idempotentHint=true and destructiveHint=true, and the description reinforces this with concrete detail: 201 on create, 200 on repeat with no new query/write, a 20-company cap, and exactly what data is imported (registration data, no partners/contacts, no analysis started). It does not explain why the operation is flagged destructive (e.g., credit consumption or overwrite), which is the one behavioral trait left opaque.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Several short, front-loaded sentences; the core action leads and behavioral facts follow. Each sentence carries information (status codes, cap, import scope), though the telegraphic style packs a lot without transitional framing.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and one simple parameter, the description adequately covers the return codes, idempotency, quantity limit, and import scope, which is what an agent needs to call it correctly. Only the rationale behind the destructive flag remains unexplained.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single parameter already specifies 'CNPJ completo, 14 dígitos com verificação válida'. The description adds no format, validation, or syntax detail beyond what the schema provides, so the baseline of 3 for full-coverage schemas applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb pair (imports and links) plus the resource (CNPJ/company) and its scope ('ao próprio dono'). An agent can tell this creates a company-to-owner association. It does not, however, name or contrast with siblings such as buscar_empresa, remover_empresa, or minha_empresas, so differentiation is left to inference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage through behavioral facts (idempotent repeat returns 200, up to 20 companies) but gives no explicit when-to-use or when-not-to-use guidance and never points to an alternative sibling. The 20-company ceiling is the closest thing to a usage constraint.

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

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

Annotations only flag it as a non-idempotent write with no destructive effect; the description goes far beyond that, disclosing the edm_ token requirement, franchise/price billing via x402 or credit (single N× charge in CNPJ mode), the 30-minute cron, and the email-channel account-session plus EMAIL_ALERTAS=1 gating. This is unusually rich behavioral disclosure for a write tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The CNAE→família mechanism is fully restated twice within one description, and an irrelevant `termos` mode (not in the schema) occupies substantial space. Purpose is front-loaded but the redundancy wastes the reader's attention.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and six parameters, the description still covers the crucial behavioral surface (token, billing, cadence, channel constraints) and even the one notable response field (empresa.cnaes with familia:null). The alert return shape itself is not described, but the operational gaps an agent would hit are largely closed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is already 100%, so the baseline is 3, but the text adds real meaning: max_familias determines how many families become alerts (principal first), and canal=email routes to the verified account email with no confirmation code. It does not clarify uf, destino, or the nested filtros fields beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific resource and keying (new purchase alerts keyed by company CNPJ), which is enough for an agent to know what it does. However it never explicitly differentiates itself from close siblings like criar_alerta, previa_alerta or alertas_compras, so the distinction must be inferred.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explains two operating modes and the financial/cadence conditions, which implies when it is appropriate, but there is no explicit when-to-use-vs-alternative guidance. The referenced `termos` mode is not present in this tool's schema, which muddies rather than clarifies routing.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so safety is covered. The description adds genuinely new context: an auth requirement ('Precisa do token edm_…') and the shape of the result ('prazos e status de entrega'), which go beyond structured fields. It stops short of describing pagination or rate behavior, which the cursor param implies but the text never explains.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, zero filler, with the resource and scope front-loaded before the token requirement. Every clause carries information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only list tool with full schema coverage and no output schema, the description covers what the tool returns at a high level and the auth prerequisite. Pagination behavior across the limite/antes_compra pair is left to the schema, a minor gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with id, limite, and antes_compra all documented in the schema itself (including the pagination cursor semantics for antes_compra). The description adds no parameter-level detail, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific resource (purchases that already matched an alert) and scope (pull channel, with deadlines and delivery status), which reads as a list/query tool. It is distinguishable from create/edit siblings like criar_alerta and editar_alerta, though the verb is implicit and no sibling is named.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no explicit when-to-use or when-not guidance, nor does it point to alternatives such as meus_compras, compra, or vigiar_compra. The 'canal pull' parenthetical hints at the delivery model but leaves the selection condition to inference.

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

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

Annotations only mark it as non-read-only, non-idempotent, non-destructive; the description goes far beyond by disclosing 202/200 response semantics, resumability of interrupted requests, failure behavior (reason + next action), capacity limits (2000 fatos, 100 editais), and that no new charge occurs. This is unusually rich for a mutation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and constraints, densely packed with useful facts in few sentences. Minor redundancy between 'acompanhe por consultar_participacao' and 'Acompanhamento somente por GET', which slightly dilutes efficiency.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 3-param mutation tool with no output schema, the description covers outcomes (status codes), resumption, limits, cost, and scope disclaimers. 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.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so cnpj, id and v are already fully documented in the schema. The description adds no syntax or format detail beyond that, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb pair (inicia/retoma análise) and the resources involved (cadastro, anexos, edital). It clearly distinguishes itself from the tracking sibling by naming consultar_participacao explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit precondition ('Só chame por solicitação do usuário'), routes tracking to consultar_participacao, and explains that an explicit POST resumes a paused run. When-to-use and the alternative are both stated.

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

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

Goes well beyond the annotations: it discloses that OCR is not triggered ('Não inicia OCR'), that automatic reading only occurs on analysis request, the 201 status, explicit size/volume limits (JSON 11.2 MB, PDF 8 MiB, 20 docs/80 MiB/50 pages per company), and that identical files are reused. This is exactly the kind of behavioral context annotations (readOnly=false, idempotent=false, destructive=false) cannot convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded in the first sentence, followed by tightly packed constraints. The telegraphic style (bare numbers, '201') is dense but each clause carries distinct, non-redundant information, so little is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutating, non-idempotent upload with no output schema, the description covers prerequisites, limits, dedup behavior, and OCR timing. It only lightly touches the response (a bare '201'), which is acceptable given no output schema exists.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful limits tied to the payload (PDF up to 8 MiB) and per-company quota constraints not present in the schema. It does not explain the 'tipo' enum values beyond the schema, but the added size/volume semantics lift it above baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (envia/anexar) and resource (comprovante PDF da empresa), making the action clear. It does not, however, differentiate itself from siblings like documento_arquivos, documentos_empresa, or documento_vincular, so an agent must infer the boundary from the name alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear operational context: 'Sessão necessária' states a prerequisite and 'prefira HTTP para arquivos grandes' points to an alternative transport for large files. It stops short of naming alternative tools or stating when-not to use this one, so it is context rather than full routing guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered structurally. The description's one genuine addition is 'without charging', which discloses that no payment is incurred – a useful behavioral fact for a tool sitting next to api_access_buy. Beyond that it says nothing about what state is inspected or returned.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

It is a single short sentence with no wasted padding, which is good. However, the brevity comes at the cost of clarity – the phrase is grammatically incomplete and leaves the core action unstated, so terseness here is under-specification rather than discipline.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the burden of explaining what the agent gets back, and it does not. It also fails to explain what changes when the optional api_pass is supplied versus omitted, which is the central behavioral question for this tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single api_pass parameter is fully documented in the schema, including format and the 'save before buying' guidance. The description adds no parameter meaning on top of that, so the baseline of 3 applies for a fully-covered, single-parameter schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description is a noun phrase ('Monthly data package and private purchase status') with no verb and no clear action, so an agent cannot tell whether this retrieves, verifies, or displays something. It gestures at a status concept but never says what the tool actually does or returns, and it only implicitly distinguishes itself from sibling api_access_buy.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit when-to-use guidance and no reference to the obvious alternative, api_access_buy. The clause 'without charging' hints that this is the non-billing path, but the agent must infer the routing decision entirely on its own.

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

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

Annotations give the safety profile (not read-only, not destructive), while the description adds genuine operational context: payment is explicit, no auto-renewal, retries with the same pass reconcile to one purchase, and the X-API-Pass/X-API-Credits-Remaining headers. The retry-recovery guarantee sits in mild tension with idempotentHint=false, though it can be read as pass-scoped reconciliation rather than general idempotency; more explicit disclosure of what happens on failure or with a spent pass would help.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Six short sentences, front-loaded with the price and validity, then payment and retry rules, then headers. Dense but each sentence carries distinct information; no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and a one-of-many input shape, the description still covers cost, duration, payment requirement, retry reconciliation, non-renewal, scope exclusion and the response header where remaining credits appear. Missing only explicit routing guidance versus the billing/pricing siblings.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the property descriptions already explain the pass format, the signed x402 payment payload, reconciliation via transaction hash, and prepaid credit_token. The description adds only the price/validity and header names, not additional per-parameter semantics, so the schema remains the primary source.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource with concrete economics: 'Buy 1,000 basic data reads for US$1, valid for 30 days.' It also carves out scope by noting that OCR, AI, documents and delivery 'keep their own tariffs,' so an agent can distinguish it from sibling billing/pricing/api_access tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives clear prerequisites ('Requires explicit payment') and lifecycle rules ('No automatic renewal', 'Same pass in retries recovers the same purchase'), plus the operational condition for using the resulting pass ('Send X-API-Pass on eligible data reads'). It stops short of naming an alternative tool or stating when NOT to buy (e.g., when an existing credit_token should be reused).

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds content scope (routes, billing regime, price) but says nothing about auth requirements or how the index is structured. With annotations carrying the safety burden, this is adequate but not rich.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single short sentence with no filler, and the resource is front-loaded. It is efficient, though arguably under-specified rather than maximally informative.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a no-param, read-only index endpoint with no output schema, the description should convey what the caller receives. It lists three content categories (routes, billing, price), which is helpful, but omits any indication of format or scope, leaving the return value partly opaque.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there is no parameter semantics to convey. The schema is trivially complete (100% coverage of an empty object), and the baseline for parameterless tools is 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description identifies the resource ('Índice da API do EditalMD') and enumerates the specific content it surfaces: routes, billing regime, and price. This is clear verb-resource framing for a discovery endpoint, though it does not explicitly differentiate itself from siblings like 'health', 'pricing', or 'api_access'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to call this tool versus alternatives. With siblings such as 'health', 'pricing', and 'api_access' present, an agent gets no signal about which to prefer for discovery versus status versus price lookup.

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

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

Very rich beyond annotations: franquia per credential, 30-day/pilot window, repetition not consuming another unit, no payment, no premium unlock, and required auth headers for reads and GET /geracao. This discloses the billing/authorization side effects that justify readOnlyHint=false.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The core purpose is front-loaded, but the description sprawls across billing, quota windows, premium headers, and pilot budget in an unstructured way. Several sentences earn their place, but the overall flow is dense and could be tightened.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 2-parameter tool with no output schema, it covers limits, cost, credentials, and the premium hand-off. It does not explain the synchronous return vs the separate avaliacao_basico_resultado tool, leaving a small gap in how results are retrieved.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and both parameters (id, agent_pass) are documented in the schema, so the description adds little parameter-specific syntax. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a clear verb+resource with scope: native/OCR text extraction from PDFs up to 50 pages/32 MiB, without review or structured tables. This distinguishes it from the premium sibling variants, though it never names them explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete usage context: 100 documents per agent, no charge, no auto-renewal, and it points to the premium path (save evaluation.access_code and send X-Editalmd-Avaliacao). It does not explicitly say 'use avaliacao_premium instead when you need tables/premium content', but the limitations imply it.

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

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description adds substantial behavioral context beyond them: no charge, per-credential franchise bounded by the earlier of 30 days or pilot end, dedup (re-reading the same document consumes no unit), and premium credential header requirements. This is genuinely useful operational detail, though it could state the return shape more clearly.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded, but the description then crams franchise limits, dedup rules, payment warnings, premium headers, and pilot budget into one dense block, with mild redundancy ('Não cobra' vs 'Não envie pagamento'). Several sentences earn their place; the structure does not.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only, no-output-schema tool, the description covers the key things an agent needs: polling trigger, billing/franchise behavior, dedup, and premium credential headers. It is nearly complete, only lacking any note on pagination across pages or response shape.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so both parameters (id, agent_pass) are already fully documented in the schema. The description reinforces agent_pass as a persistent credential but adds no syntax, format, or edge-case 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.

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence gives a concrete verb+resource: retrieve básico reading text per page with source hash, and it explicitly contrasts with premium ('Básico não abre conteúdo premium'). An agent can distinguish it from avaliacao_premium, though the rest of the text is dominated by billing/pilot prose that dilutes the core purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It implies this is the follow-up poll tool ('Acompanhe a leitura básica após retry_after_s') and notes basic won't open premium content, but it never names or routes against the sibling avaliacao_basico, which is likely the initiation counterpart. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered structurally. The description adds one genuinely non-redundant fact — 'Não cobra' (it does not charge / consume credits) — which is useful for a quota-related tool. It still says nothing about validity duration semantics or what the call yields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

It is a single short fragment with no filler, but it is terse to the point of under-specification rather than efficient — the brevity comes at the cost of basic clarity about the operation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter read-only tool with full schema coverage and annotations, the bar is modest, yet the description still omits what the tool does, what it returns, and when to prefer it over the three sibling avaliacao_* tools. 'Não cobra' is the only substantive addition.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is a single parameter (agent_pass) with 100% schema description coverage, including where the credential comes from and an explicit clarification that it is not a User-Agent. The description adds nothing about the parameter, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a quota composition ('um premium e 100 básicos, com validade') but never states what the tool actually does — it reads like an attribute of a quota rather than an action the agent can invoke. Against siblings avaliacao_basico, avaliacao_premium and avaliacao_basico_resultado, an agent cannot tell what operation this performs or 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.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use guidance is given. There is no indication of when to call avaliacao_cotas versus avaliacao_basico, avaliacao_premium or avaliacao_basico_resultado, nor any prerequisite or trigger condition.

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

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

Goes well beyond the annotations by disclosing the 50-page cap, the credential-scoped franchise window, the global budget dependency, absence of auto-renewal, the fact that repeating the same document does not consume another unit, and the exact auth headers (X-Editalmd-Avaliacao plus X-Agent-Pass) needed for reads and GET /geracao. The 'repetition does not consume another unit' claim sits in mild tension with idempotentHint=false, but it describes unit accounting for a document rather than asserting pure call-level idempotency, so it reads as clarifying rather than contradicting the annotation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded, but the body is a run-on chain of semicolon-free fragments that repeats the 'guarde evaluation.access_code' instruction twice and mixes limits, auth, and billing caveats with no structure. Every clause carries information, but the packaging hurts scannability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description correctly covers the outcome surface: track status via estado_geracao/agent_pass and retrieve evaluation.access_code. Auth, franchise limits, budget caveats, and the no-payment rule are all present; only the explicit relationship to the basic-tier siblings is left implicit.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and both parameters (id, agent_pass) are already documented in the schema, so the baseline is 3. The description enriches context around agent_pass (store it, pair it with headers) and constrains id implicitly to documents up to 50 pages, but adds no format or syntax detail beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: consuming one sponsored premium evaluation unit on a document of up to 50 pages, and it implicitly separates itself from avaliacao_basico by noting that the basic tier does not open premium content. The purpose is clear, though the sibling differentiation is expressed only obliquely through the access-tier remark rather than a direct 'use X instead'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives real when-to-use context: one premium unit per document, up to 50 pages, repetitions retrieve the same access, and the franchise is bounded by the earlier of the agent's 30 days or the end of the pilot. It also states a when-not ('Não envie pagamento') and implies the basic alternative is insufficient for premium content, though it never names avaliacao_basico/avaliacao_basico_resultado as the fallback route.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered structurally; 'does not create a charge' largely restates that. It adds no behavioral detail beyond annotations, such as what the summary contains or whether it hits live billing data.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single tight sentence with the capability up front and the exclusion at the end. It is nearly a fragment, but nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and no input parameters, the description is the only place to explain what a 'billing summary' returns, and it doesn't — no fields, scope, or account context. Adequate to avoid mis-invocation but incomplete for a tool whose value depends on its return content.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Zero parameters, so the baseline of 4 applies. Nothing in the schema requires explanation and the description correctly avoids inventing parameter prose.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States the resource (billing) and hedges it as 'payment discovery and billing summary', which is vague about what is actually returned. It does differentiate from purchase siblings with 'does not create a charge', but an agent still can't tell what billing data this surfaces versus, say, `pricing` or `api_access`.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use guidance and no alternatives named. The negative clause implies a contrast with the buy tools (`api_access_buy`), but the agent must infer that routing rather than being told it.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds the auth requirement ("conta ou convidado"), genuine context beyond annotations, but says nothing about result limits or matching behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence carrying purpose, search keys and access precondition with zero filler. Nothing could be trimmed without losing information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter read-only search with no output schema, the description covers purpose, accepted keys and the auth requirement. Slightly short of perfect because it omits match semantics (exact vs partial) that a search tool's caller might want.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single parameter q is fully documented in the schema (CNPJ completo ou nome de 3 a 120 caracteres). The description restates the accepted key types but adds no syntax or normalization detail beyond what the schema already provides, so baseline 3 is correct.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ("Busca") and resource ("base cadastral") and names the two search keys (CNPJ or razão social). Clear enough to act on, but it does not distinguish itself from siblings such as minhas_empresas or buscar_licitacao.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

"exige conta ou convidado" gives a useful access precondition, which implies when the tool is callable. However, there is no guidance on when to prefer this over adjacent tools (e.g., selecionar_empresa, adicionar_empresa), so usage is only implied.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the description only needs to add context. It does add two useful behavioral facts: the call is free of charge and it returns a defined set of fields (objeto, órgão, UF, modalidade, id). It does not mention pagination ceilings or result-size behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short, front-loaded sentences with zero filler: what it does, what it costs, what it returns. Every sentence carries distinct information and nothing is repeated from the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only search tool with full schema coverage and no output schema, the description adequately supplies purpose, cost, and return shape. The only gap is pagination/result-limit behavior, which the schema's limite parameter partially covers but the description never connects to overall result handling.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so q, uf, limite, and abertas are all documented in the schema with min length, default, and enum semantics. The description only restates the term-based nature of q and adds nothing about formatting, accents, or multi-word behavior. Baseline 3 when the schema does the work.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Busca compras públicas por termo') and names the returned fields (objeto, órgão, UF, modalidade, id). It is clearly a keyword search over procurement records, distinguishable from list-style siblings like meus_compras or salvas, though it never names those alternatives explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'por termo' implies the usage context (keyword-driven discovery) and 'Grátis' signals no credit cost, but there is no statement of when to prefer this over compra, meus_compras, or precos_homologados, and no exclusions. Usage is left to inference.

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

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

Annotations already declare readOnlyHint/idempotentHint and destructiveHint=false, so the safety profile is covered; the description adds real context beyond that — 'Grátis' (no cost), how null field values should be interpreted, and the downstream consequence that an alert per CNPJ won't use such a CNAE.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four dense sentences with the core purpose front-loaded and no filler; each sentence adds a distinct behavioral fact. It is appropriately sized for a two-parameter tool, though it slightly blurs description vs schema content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the return-value burden and does name the returned fields (description, family, coverage indicators). For a simple read-only, free suggestion endpoint the description covers modes, defaults, and edge cases, leaving only minor gaps like pagination/limits.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters are already documented and the baseline is 3. The description adds value above that by giving concrete `q` examples (`1412`, `1412-6/01`), clarifying prefix-vs-word matching, and describing the default listing behavior when `q` is absent; `limite` itself is left to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb+resource: search-term suggestions for economic activity (CNAE), explicitly listing what comes back (description, family, coverage indicators). It does not contrast itself with any sibling, but the CNAE domain is distinctive enough that an agent can identify it without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It spells out the two operating modes conditionally — without `q` it lists activities with the most registered suppliers, with `q` it searches by code prefix or description word — and gives the edge-case semantics (null `familia`/`termos` means the CNAE is not in the dictionary and a per-CNPJ alert skips it). Clear context, but no explicit when-not or alternative-tool routing.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial operational context beyond them: an edge-cache TTL of up to 6 hours, the note that deadlines/prices are recomputed per request, and the `Cache-Control: no-cache` and `x-origem-cache` (hit/miss/bypass) mechanics. It also discloses the 50-document cap and the free-vs-paid content split — genuinely useful behavioral detail.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with what is returned before moving into pricing and cache behavior, and each sentence conveys distinct information. The cache-controle details are slightly heavy but remain relevant and do not obscure the core purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the return-value burden and does so reasonably — listing the document fields, the 50-item cap, and free/paid access. Combined with the cache semantics, an agent has enough to call it correctly, though the relationship to the sibling document-access tools is left implicit.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is a single parameter with 100% schema description coverage ('id da compra (vem da busca)'), so the schema already carries the semantics. The description adds no syntax or format detail for the id beyond what the schema states, making the baseline 3 appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource: the ficha (record) of a purchase plus its documents, detailing returned fields (titles, types, pages, availability) and a cap of 50 documents. Clear on what it does, but it does not name or differentiate itself from near-neighbors like documento, documento_acesso, or meus_compras, leaving the agent to infer the boundary.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage by noting the query is free while content access is paid per document, and the schema notes the id 'vem da busca' — a hint that this follows a search. However, it never explicitly says when to choose this over sibling tools such as documento or meus_compras, so routing guidance is only implied.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds rich behavior beyond them: outdated results on mismatched cadastro/anexos/dossiê, data_atual=false for prior days, and partial batches reported via parcial=true with processados/total that never imply completion. This is substantial, non-redundant disclosure for a read tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

It is front-loaded with the core purpose and then packs edge-case semantics into short, dense sentences. Diction is jargon-heavy for a non-Portuguese reader, but each sentence carries distinct information and none is filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the return-value burden and does so: it enumerates what is returned (estado, pendências, atendidos with motivos/ações/evidências), the outdated and partial/processados/total response states, and the data_atual flag. An agent has enough to interpret results correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all seven parameters, including enums like grupo and kind. The description adds domain meaning around the pendências categories and batch semantics, but offers little additional parameter-specific syntax, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('Consulta estado, Pendências e Atendidos com motivos, ações e evidências') and, via 'Nunca inicia análise', distinguishes itself from the sibling analisar_participacao. The resource 'participacao' is domain-specific and not fully explained, but the read-vs-analyze contrast is clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives strong 'when-not' guidance: 'Nunca inicia análise' and 'GET não executa a fila nem inicia IA', routing the agent away from triggering analysis. It stops short of naming the alternative tool explicitly or laying out positive preconditions, so it is clear context without full alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds a genuine behavioral fact — that the POST to this route returns 410 with the path, and that guest edm_ lists migrate via /api/auth/claim — which is useful beyond the annotations. It still does not say what the check returns or what happens on failure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, so not verbose, and the core purpose is front-loaded. The second sentence about the 410 POST is dense and tangential, and references an endpoint path without making clear how it relates to using this tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With zero parameters, no output schema and annotations carrying the safety profile, little is strictly required. Still, for a verification tool the description never explains what the 'confere' result communicates or how an agent should act on a mismatch, leaving a meaningful gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so the schema has nothing to document and the baseline is 4. The description correctly introduces no parameter semantics, consistent with the empty input schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the tool verifies ('Confere') that Saved items/Alerts/Watchers belong to the session's account, which is a specific verb plus a scope. However 'acompanhamento' is not a well-defined resource, and the second sentence about the POST returning 410 muddies whether this is a check or a migration helper. It gestures at siblings (salvas, alertas, vigia) without cleanly distinguishing itself.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit when-to-use or when-not-to-use guidance is given, and no sibling is named as an alternative. The mention of POST /api/auth/claim is contextual background, not a routing rule that tells an agent when to pick this tool over salvas, alertas_compras, or conta_vincular_acompanhamento.

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

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

The inline annotations declare idempotentHint=false, but the description explicitly says repeating the call is harmless and moves zero data, which describes idempotent behavior. This is a direct contradiction. Otherwise it adds useful details about transaction scope, collision handling, and token validation, but the contradiction forces a score of 1.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose and then adds prerequisites and edge cases without excessive padding. It is appropriately sized for a complex linking operation, though a few clauses could be tightened.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation with one parameter and no output schema, it covers the essential behavior: what is transferred, transaction semantics, collision resolution, guest token validation, and repeat behavior. The main completeness gap is that the repeat-behavior claim conflicts with the annotation, leaving the agent uncertain about idempotency.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and already describes guest_token as an edm_… guest token. The description adds meaningful validation context (old, unsigned, or ownerless tokens are refused) and ties the token to the SDK claim from the guest, going beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: it brings guest-created items (Saved searches, Alerts, Watchers, purchases) into the session account. This is clear enough to distinguish it from most siblings, though it never names a direct alternative like conta_acompanhamento.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives a prerequisite (bootstrap/CSRF from this browser) and notes that the page performs it right after login, implying when it should be used. However, it does not explicitly say 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.

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

Annotations already declare readOnlyHint=false and idempotentHint=false, and the description sensibly adds behavior the annotations cannot: payment happens once through x402 and the call produces a token. It omits failure/refund behavior and whether the token expires, but the added context is meaningful for a zero-annotation-style mutation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One front-loaded sentence that opens with the action and packs mechanism and outcome without filler. Slightly dense with parenthetical detail but nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter purchase tool with no output schema, the description usefully discloses the return value (a token that discounts across the house APIs), covering the main gap an absent output schema creates. Remaining omissions like token lifetime or payment failure handling are minor.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single usd parameter is already documented as '1, 5, 10 ou 25'. The description's package list merely restates that enum of allowed values, adding no syntax, currency, or formatting detail beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (recarrega crédito) plus the payment mechanism (x402) and the result (a token), which is well beyond a tautology. It does not explicitly name the alternative credito_saldo, so an agent must infer the buy-vs-check distinction from the sibling list rather than the text.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied: this is the tool that purchases credit, as opposed to credito_saldo which reports balance. There is no explicit when-to-use/when-not statement, no pruning against api_access_buy or billing, and no stated prerequisites for the x402 payment step.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds an auth requirement (the cred_… token) that is not in the structured data, which is genuine behavioral context. Return format is not described, but no output schema exists and the read-only nature makes that a minor gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One sentence, front-loading the resource (balance/statement) before the credential caveat. Nothing is wasted and the key constraint is not buried.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter read-only tool with no output schema, the description covers purpose and the one non-obvious prerequisite (the cred_ token). It is complete enough to invoke correctly; only richer return/format detail is absent, which the missing output schema does not require.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so the baseline of 4 applies. Schema coverage is 100% (trivially, empty object) and there is nothing for the description to compensate for.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific resource and content ('Saldo e extrato do crédito pré-pago'), so an agent knows it retrieves the pre-paid credit balance and statement. It is reasonably distinguishable from credito_recarregar (which tops up credit), though it never names the sibling explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The parenthetical supplies a real precondition ('precisa do token cred_…'), which tells the agent this call needs a specific credential. However, there is no explicit when-to-use vs. when-not guidance or reference to alternatives such as billing or credito_recarregar.

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

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

Annotations only declare it is a non-read-only, non-idempotent, non-destructive write. The description goes well beyond that, disclosing pricing/quota mechanics (FRANQUIA_ALERTAS free first alert, PRECO_ALERTA per 30 days, single N× charge in CNPJ mode), required tokens (edm_, whsec_), session requirement for email, EMAIL_ALERTAS=1 gating, and the 30-minute cron cadence.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose, but the text is dense and repeats the pricing rule twice ('O primeiro é grátis… os seguintes custam' appearing early and again in detail), and it mixes duas-modos, channels and billing in one long paragraph. Length is partly justified by complexity but not every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 5-parameter tool with a nested filtros object and no output schema, the description covers the essential operational context: channels, prerequisites, billing and the CNPJ edge case (CNAE fora do dicionário → familia null). It is nearly complete, though it does not describe what the creation response returns (alert id, status).

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3, and the description adds semantic depth: termos syntax (space = all words, '|' = any, with example), canal semantics including that destino is ignored for pull/email, and the CNPJ family-generation logic with max_familias and empresa.cnaes output. It clarifies behavior the schema alone does not.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb ('criar') plus resource ('alerta') and a precise scope: purchase alerts by object terms and UF, with three delivery channels and two modes (termos/cnpj). It's clearly actionable, but it never names or routes away from plausible siblings like alerta_por_cnpj or previa_alerta, which its CNPJ-mode narrative actually overlaps.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage context is implied through channel behavior (pull/webhook/email requirements) and the CNPJ-mode explanation, but there is no explicit 'use this when… / use X instead' guidance versus the closely related siblings (editar_alerta, previa_alerta, alerta_por_cnpj). The agent must infer routing.

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

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

Annotations only declare readOnly=false, idempotent=false, and destructive=false. The description adds substantial behavioral context: USDC confirmation on Base safe block versus L1 finality, 30-minute send window, 24-hour observation, late/wrong-chain/failed-extraction cases requiring support, wallet fees, same X-Cobranca preserving charge/address, paid GET returning access code/cookie, and dev simulated payments being invalid.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

It is front-loaded with the purpose and packs many operational constraints into dense sentences. The length is justified by payment complexity, though the structure is somewhat stream-of-consciousness and a few clauses could be tightened.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, but the description covers important follow-up context: paid GET returns acesso.codigo and a cookie, and linking to an account uses POST /api/documento/:id/vincular. It still does not fully specify the immediate return payload of criar_cobranca itself.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline would be 3. The description adds workflow meaning beyond the schema: cotacao must come from estado_geracao and be checked/submitted, and cobranca_token must be generated and conserved by the client before creation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific action and resource: it reserves a USDC/Base address for paying US$0.02 per page without a browser wallet. The purpose is clear, but it does not explicitly distinguish itself from sibling tools such as estado_cobranca or estado_geracao.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides concrete workflow conditions: check cotacao first, preserve cobranca_token, do not generate before real confirmation, consult GET /geracao and submit cotacao, and send within 30 minutes. It lacks explicit when-not guidance or named sibling alternatives, but the prerequisites and timing are unusually well covered.

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

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

Beyond the annotations, it discloses substantial behavior: the token is shown only once with no recovery, it is rate-limited per network and per hour, the webhook secret can be re-read and rotated with a 24h dual-signature grace period, and it even specifies the webhook signature scheme and timestamp window. This is rich operational context well past what readOnlyHint/idempotentHint convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded, but the text is bloated: the HMAC-SHA256 construction of 'id.timestamp.corpo', the 5-minute timestamp rejection rule, and the Standard Webhooks library reference are receiver-side verification instructions, not guidance for invoking this tool. Much of the length does not earn its place for tool selection.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description must explain the return artifacts, and it does: the 'edm_…' bearer token and the 'whsec_…' secret, including where the token goes (Authorization: Bearer) and how the secret is later retrieved. Nothing needed to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there is nothing for the description to disambiguate. The baseline for a no-parameter tool is 4, and the description correctly explains the artifact returned rather than inventing parameter details.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The opening states a concrete verb and resource: it creates the guest owner credential — the 'edm_…' token that unlocks alerts and watches plus the 'whsec_…' webhook signing secret. This clearly maps to the criar_/dono family, though it never explicitly names which sibling to pick instead (e.g. dono, rotacionar_segredo_webhook).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It signals the context ('Sem cadastro') and advises storing the one-time token and later claiming lists via the account page so you don't depend on it. However, it never states explicitly when to choose this over siblings like dono (read) or rotacionar_segredo_webhook (rotate); usage is implied rather than routed.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description still adds genuinely non-redundant behavior: the call is free ('grátis') and it explicitly declines to open content or start OCR, which sets expectations about side effects and downstream cost.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, front-loaded with what is returned, then routing guidance, then the negative scope. Every clause carries information; nothing is filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description usefully enumerates the returned fields (título, tipo, páginas, compra vinculada), and it discloses cost and non-side-effects. The only gap is the lack of differentiation from the numerous sibling document tools an agent must choose between.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is a single required parameter ('id', ID do documento) and schema description coverage is 100%, so the schema carries the semantics. The description adds nothing about the id's format, scope or valid domain, which is acceptable here but not additive.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Consulta') plus the resource ('documento') and enumerates what it returns: título, tipo, páginas and the linked compra. It does not clearly distinguish itself from the many overlapping siblings (documento_leitura, documento_acesso, documento_dossie, meus_documentos), though the explicit 'não abre conteúdo nem inicia OCR' hints at a lighter-weight sibling than documento_leitura.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Names one alternative and the condition for it ('Use compra para listar os documentos relacionados'), which is real routing guidance. However, it gives no guidance for the far more confusable siblings such as documento_leitura, documento_acesso or documento_arquivos, so the when-to-use story is only partially covered.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered structurally. The description adds the useful behavioral fact that this returns access state and a recovery code without triggering a new purchase. Beyond that, it says nothing about permissions, failure cases, or invocation cost.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single compact sentence with no filler, and the key constraint ('sem nova compra') is front-loaded. It is efficient, though it is arguably too terse to be self-explanatory.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description should clarify what comes back; it gestures at 'estado do acesso' and the recovery code, which roughly covers the return. Given only two fully documented parameters and an annotated read operation, this is adequate but leaves the access code's role (input vs. output) ambiguous.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with both id ('Documento comprado') and acesso_codigo ('Código privado de acesso') documented in the schema. The description adds no parameter-level detail beyond that, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names the resource (access status and private recovery code) and an implicit retrieval verb, but it never states the action plainly, so the agent must infer 'get/fetch' from the name. It hints at sibling differentiation via 'sem nova compra' (no new purchase), distinguishing it from compra/meus_compras, but not crisply.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Sem nova compra' implies the retrieval scenario that selects this tool over a purchase flow, which is a light usage cue. However, there is no explicit when-to-use, no prerequisites, and no naming of an alternative sibling such as documento, documento_leitura, or meus_compras.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds that it returns a catalog of links plus pages, which is modest extra value, but says nothing about permissions, rate limits, or return structure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with the core purpose and followed by the practical download pointer. No filler, though the second sentence is more of a routing hint than tool definition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only catalog with full schema coverage and no output schema, the definition is adequate but leaves gaps: no mention of what 'páginas' means or whether results paginate, and no guidance on which credentials are needed for which caller.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and each of the four parameters is documented in the schema (including the access-code semantics), so the description carries little burden and adds no parameter detail. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a clear verb+resource: it is the catalog of a document's original files with download links and pages. However, it does not distinguish itself from close siblings like documento_leitura, documento_dossie, or documento_acesso, so an agent still has to guess at boundaries.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It points to the /api/documento/{id}/original endpoint for downloading the complete original, which is useful procedural context, but it never says when to pick this tool over its sibling tools or what preconditions (access code, agent pass) apply.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds real behavioral context beyond that: it does not initiate AI analysis and reuses the documental access rather than triggering a new analysis on query. These are genuine additions, though they are terse and somewhat cryptic.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

It is front-loaded with the content inventory, and most clauses carry information. Some phrasing is compressed and opaque ('Dados parciais informam cobertura'), which reduces clarity rather than length, keeping it from a clean 4.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read tool with 8 parameters, complex multi-code authentication and no output schema, the description covers the behavioral essentials (AI not triggered, access reuse, export gating) but says nothing about the shape or pagination of returned facts beyond naming content categories. Adequate but with visible gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all 8 parameters are already documented in the schema (including the elaborate acesso_codigo and agent_pass semantics). The description only restates that acesso_codigo matches the leitura, adding no syntax or format 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.

Does the description clearly state what the tool does and how it differs from similar tools?

The description enumerates the resource contents (itens, exigências, atestados, prazos, obrigações with conditions/exceptions/excerpts), which conveys that this returns a structured dossier, but it never states an explicit action verb. The reader must infer retrieval from the name and content list rather than being told outright.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives a useful access condition (reuses the same acesso_codigo as documento_leitura) and a gating rule (export requires the completed version), implying when the tool is usable. However, it never explicitly contrasts when to use this versus documento_leitura or documento, leaving the choice to inference.

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

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

Annotations already cover readOnly, idempotent, and non-destructive traits. The description adds meaningful behavioral context beyond that: no OCR is started, only ready resources are returned, and `document_approved: false` indicates automatic extraction without blocking reading. The repetition of 'Não inicia OCR' slightly weakens the conciseness but the substance is valuable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is fragmented and repeats 'Não inicia OCR' twice, which wastes space. The key scoping information is present but not optimally front-loaded. It is functional but not tightly written.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description usefully lists the manifest contents (páginas, imagens, SHA-256, versão). It also covers relevant behavioral caveats and authorization notes. Annotations handle the safety profile, so the description is complete enough for an agent to call this read-only manifest tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already fully documents all four parameters. The description only references acesso_codigo and notes that examples are free; it adds little to parameter meaning beyond what the schema provides. Baseline 3 is appropriate 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.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific resource ('Manifesto do documento comprado') and enumerates the returned fields (páginas, imagens, SHA-256, versão). It distinguishes itself from related actions by noting it does not start OCR and that the same authorization unlocks ZIP and images via the API, but it does not name the sibling tools that handle those alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides some implied usage context: send acesso_codigo, examples are free, and it does not initiate OCR. However, it never explicitly states when to prefer this tool over siblings like documento_acesso, documento_arquivos, or documento_dossie, nor does it offer clear exclusions beyond the OCR note.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds that documents are private and that binary retrieval happens via an authenticated HTTP GET /documentos/:arquivo, which is useful context beyond the annotations but does not describe pagination, ordering, or scope of the returned list.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with no filler, and the core purpose is front-loaded ahead of the download note. It could be slightly tighter, but nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter read tool with no output schema, the description covers what is returned at a high level and how binaries are fetched, which is adequate. It omits sibling disambiguation and scope details, leaving some gaps an agent would need to resolve elsewhere.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With one parameter and 100% schema description coverage, the schema already documents 'cnpj' as a 14-digit identifier tied to the owner. The description adds no further parameter meaning, so the baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Lista os PDFs privados da empresa' tells the agent it retrieves a company's private PDF list. It is clear on what, but does not differentiate from close siblings such as documento, documento_arquivos, or meus_documentos, so the agent must guess which listing tool applies.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit when-to-use or when-not-to-use guidance and no named alternative. The second sentence describes a download mechanism rather than telling the agent which conditions select this tool, so usage must be inferred.

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

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

The description asserts 'idempotente para o mesmo dono', while the annotations declare idempotentHint=false; these directly conflict about repeat-call behavior. The ownership rule ('outro dono não pode reivindicar') is useful context, but the idempotency claim contradicts the structured metadata.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four short sentences, front-loaded with the linking action and prerequisites. The closing sentence about the code still opening the document is slightly tangential but adds behavioral context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers prerequisites, ownership exclusivity and post-call effect for a tool with no output schema. The main gap is the unresolved idempotency conflict with the annotations rather than missing scope.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so both parameters are already documented. The description adds only mild meaning by framing acesso_codigo as the 'prova privada da aquisição', which is close to the schema's 'Código privado de acesso'.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Vincula aquisição à conta da sessão usando a autorização privada comprada.' An agent can tell it links a purchased document to the session account, but nothing distinguishes it from near-name siblings such as documento_acesso, salvar_compra or conta_vincular_acompanhamento.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Prerequisites are stated ('Exige sessão e prova privada da aquisição'), which implies when the tool is callable, but there is no explicit when-to-use vs. when-not guidance and no named alternative among the many document/compra siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds real context beyond that: the credential requirement, and the rotation behavior where the prior whsec_ still signs for 24 h after POST /api/dono/segredo, producing two v1, parts in the header.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose and returned fields are front-loaded, which is good, but the bulk of the text is a low-level HMAC-SHA256 recipe (id.timestamp.corpo, 5-minute timestamp tolerance, Standard Webhooks library compatibility) that is tangential to selecting or invoking this tool. That detail is useful but disproportionately long for a zero-parameter read.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description responsibly enumerates the return fields (conta/convidado, notification email, franquia, whsec_). It also covers auth and secret rotation. It is nearly complete for a simple read; the signing algorithm is arguably more than needed here.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so the baseline is 4. The description correctly implies no input arguments and instead documents the returned fields and the signing secret's format (base64 after the whsec_ prefix), which is the relevant semantic content for a no-arg call.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific resource and enumerates what it returns: owner state (account or guest), notification email, quota, and the whsec_ webhook-signing secret. An agent can tell this is a read of the owner/account record. It does not, however, distinguish itself from account-adjacent siblings like minha_conta or criar_dono.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The auth prerequisite is given explicitly ("precisa do token edm_… ou da sessão da conta"), which signals when the call is valid. But there is no explicit when-to-use/when-not, and no routing away from alternatives such as minha_conta or rotacionar_segredo_webhook; the retrieval-for-webhook-verification use case is only implied.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds useful context beyond annotations: authentication mechanisms, paid vs. evaluation access, free examples, and pricing for the adjacent gerar_markdown tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three compact sentences with no filler, and the core action plus access modes are front-loaded. It could be slightly more structured (e.g., separating purpose from pricing), but every sentence contributes relevant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only tool with full schema coverage and no output schema, the description adequately covers the non-obvious access paths and alternatives. It omits any note about what the tool returns (Markdown content, implied by the name) and failure behavior, but otherwise gives an agent enough to invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so all four parameters are fully documented in the schema itself. The description names acesso_codigo, avaliacao_codigo, and agent_pass in prose but adds no syntax, format, or usage detail beyond what the schema already provides. Baseline 3 is appropriate when the schema carries the load.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a verb (Lê) and a resource (Markdown), but the resource is only a format, not the specific document type (edital) implied by the name. It references gerar_markdown as a purchase alternative but does not clearly distinguish itself from other read tools like documento_leitura. Purpose is inferable but not sharply framed.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Describes access conditions (acesso_codigo purchased, or avaliacao_codigo + agent_pass) and notes free examples plus a paid alternative (gerar_markdown). However, it never states when to choose this tool over siblings like documento_leitura, nor does it explicitly say when it cannot be used.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: reactivation past the quota incurs payment, and filters replace the entire scope rather than merging. That is useful non-obvious detail beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, no filler, and the two most decision-relevant facts (what it edits/pauses, and the payment precondition) are front-loaded. Nothing here repeats the tool name or wastes a clause.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, non-idempotent mutation tool with 7 fully-described params and no output schema, the description covers the mutation intent, the cost precondition and scope-replacement semantics. It omits any note on session/auth requirements (the schema mentions 'exige sessão' only for the email channel), which is a minor gap but not fatal.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so every parameter is already documented in the schema (including the 'PATCH substitui o recorte inteiro; {} limpa' note on filtros). The description's 'Filtros substituem o recorte inteiro' largely restates that schema text, adding little. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a precise verb+resource ('editar alerta') and enumerates the two modes of operation: editing interest vs. pausing/reactivating, scoped to 'o alerta do dono'. It is clearly distinguishable from criar_alerta or previa_alerta, but it never names a sibling to sharpen the boundary, so it stays at 4.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives one real precondition ('Reativação além da franquia exige pagamento'), which tells the agent when the operation may fail or cost money. However, there is no explicit when-to-use-this-vs-criar_alerta/previa_alerta routing guidance, so usage is only implied.

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

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

Annotations already declare readOnly, idempotent and non-destructive, but the description adds substantial context beyond them: it is free, enforces a 30-second minimum interval, reuses the X-Cobranca header, and must respect Retry-After. It also explicitly states the query neither writes nor performs blockchain RPC, which is meaningful reassurance for a status/payment tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded in the first sentence, followed by operational constraints and then state-specific handling. Several clauses are telegraphic fragments, but there is little genuine waste for the amount of behavioral information conveyed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, so the description carries the burden of describing what an agent gets back, and it names the lifecycle states (gerando, pronto, em revisao) and what each implies. That is close to complete for a status tool, though the exact shape of the returned status fields is left to inference.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters (id and cobranca_token) are already documented, including the token format. The description reinforces that the same cobranca_token must be reused (via X-Cobranca header) but adds no format or constraint details beyond the schema, matching the baseline 3 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.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: queries payment and release status using the same cobranca_token. It also carves out scope by stating it does not initiate work ('não inicia trabalho'), which separates it from the create/start path. It stops short of naming a sibling tool directly, so it is clear but not fully differentiated from the large set of cobranca/geracao tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives conditional routing: when in the 'gerando' state use GET /geracao for phases/pages, and when 'pronto' the read links are released. It also instructs to reuse X-Cobranca, respect Retry-After, and not to pay again while 'em revisao'. This is practical when/when-not guidance, though it routes to an HTTP path rather than naming sibling tools explicitly.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description usefully adds that the call is free and does not trigger processing, which is genuine value beyond the annotations, but it says nothing about the authorization requirement implied by the four credential-bearing parameters.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One front-loaded sentence with no filler; the cost/processing constraint is stated compactly. It is short enough to be efficient but borders on under-specification for a tool with complex access semantics.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only tool with a fully documented schema and no output schema, the description is minimally adequate: it conveys status-checking without side effects. It never describes what the returned phases look like or how to interpret completion, which an agent polling for a terminal state would find helpful.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents id, agent_pass, acesso_codigo and avaliacao_codigo in detail. The description adds no parameter-level meaning, which 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.

Does the description clearly state what the tool does and how it differs from similar tools?

The verb 'acompanha' and object 'fases reais e a conclusão' make it clear this reports progress/completion of a generation, but what is being generated (markdown? dossiê?) is left implicit and no sibling such as estado_cobranca or gerar_markdown is named. An agent can guess it is a status/polling tool but without confident disambiguation from its many siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

'gratuitamente, sem iniciar processamento' implies the intended usage: check status without spending credits and without kicking off work. That is useful implied guidance, but there is no explicit when-to-use/when-not statement and no named alternative for actually starting a generation.

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

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

With annotations already declaring read-only, idempotent, and non-destructive behavior, the description adds useful context about what the tool returns: five free real samples in Markdown, original PDF, and image ZIP formats. It does not add further behavioral details such as pagination or access requirements, but the annotation coverage lowers the burden.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The definition is a single, front-loaded sentence that communicates the verb, output quantity, formats, and usage context without any filler. Every part of the sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has no parameters, no output schema, and annotations that cover the safety profile, the description provides enough context about what it returns and when to use it. It could specify the return structure more precisely, but it is adequate for a simple listing tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so there are no parameter semantics to clarify. The schema description coverage is 100%, and the baseline for a no-parameter tool is 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Lista') and resource ('cinco provas reais gratuitas') and explains the purpose of checking Markdown, original PDF, and image ZIP formats. It is clear what the tool does, though it does not explicitly distinguish itself from related siblings like gerar_markdown or edital_markdown.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'antes de gerar outro documento' gives a clear timing condition for using the tool: before generating another document. It does not name alternatives or exclusions, but the context of use is well communicated.

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

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

Annotations are thin (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the description must carry the load, and it does: per-page cost, paid-before-delivery semantics, session cookie+CSRF vs guest Bearer (edm_…) vs X-Credito agent auth, the 502 `pago_nao_registrado` receipt-preservation case, and 'unknown/altered quote does not charge'. That is substantial behavioral context beyond what structured fields declare, though the delivery format is not described.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single dense run-on block with no front-loaded purpose statement and heavy repetition of payment/access rules ('Cada comprador paga', 'inclusive pronto' restated). Many clauses do earn their place factually, but the lack of structure and ordering makes it hard to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a multi-mode paid tool with 7 params, no output schema, and nested objects, the description covers cost, auth variants, retry/polling, error handling, and body-size limits reasonably completely. The main gap is a clear statement of the actual produced artifact and its relationship to sibling document tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so param meaning is already documented in structured data. The description ties several params to transport details (credito_token via X-Credito, avaliacao_codigo with X-Agent-Pass, retaining acesso.codigo across sessions), which adds modest value, but largely restates what the schema already provides. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The title ('Gerar markdown') and phrases like 'Texto pronto reutiliza OCR; geração necessária incluída' hint at generating markdown text from a document, but the opening sentences are dominated by pricing and access mechanics rather than stating plainly what the tool produces. An agent can infer intent but the core verb+resource is never cleanly front-loaded, and no sibling (e.g. edital_markdown) is distinguished.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is real procedural guidance — 'Não use POST como polling', 'Após 202 acompanhe por GET', 'Consulte GET ou 402, confira páginas/hash/total e envie cotacao' — which constrains correct invocation. However, there is no routing guidance against alternatives such as edital_markdown or documento_leitura, so when-to-use-this-vs-another is only implied.

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

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

Goes beyond annotations by disclosing auth needs (acesso_codigo/examples), that there is no additional charge at this stage, and that the call does not trigger another analysis. There is mild tension with readOnlyHint=false, but the description never claims read-only and the non-read-only hint may reflect access/credit bookkeeping, so it is not a hard contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core action (qualification list with literal excerpts) before prerequisites and scope caveats. Several sentences each carry distinct information, with only mild redundancy in the pricing/analysis caveats.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 4-param tool with no output schema, it describes the returned content (condições, exceções, evidências por página) and what it explicitly does not cover (prazos, propostas, company assertions). Sufficient for an agent to call it correctly, though return shape details are left implicit.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents id, agent_pass, acesso_codigo and avaliacao_codigo thoroughly. The description reinforces the acesso_codigo requirement and the 'five examples' option but adds no syntax beyond the schema. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a concrete purpose: listing the edital's habilitação (qualification) requirements with literal excerpts, and clarifies scope ('sem afirmar o que a empresa possui'). It also distinguishes itself from the dossie sibling by noting deadlines/proposals live there. Clear, though the Portuguese phrasing is dense.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explains access prerequisites (acesso_codigo of the purchased document or one of five examples) and routes other obligations (prazos, propostas) to the dossie. Also states 'A consulta não inicia outra análise', a useful usage caveat. No explicit when-not beyond the dossie pointer.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safe, repeatable read profile is covered. The description adds that the response concerns source health and archive size broken down into purchases and text documents, which is useful scope context, but it doesn't describe what 'health' means, what errors or statuses appear, or latency/cost.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single short sentence with no filler, and the resource ('origem', 'acervo') is front-loaded. It could be slightly clearer in wording, but nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, read-only probe with annotations covering safety and no output schema, the description is minimally sufficient. However, without an output schema, the agent gets no idea what the returned health/size payload looks like or in what units the archive size is reported.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there is nothing for the description to disambiguate – baseline 4 applies. The schema is empty and fully consistent with the described no-argument probe.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a resource and a rough capability: health of the source plus collection size for purchases and text documents. It is more than a tautology (the title 'Health' alone would be), but 'saúde da origem' is vague – it doesn't say which checks or metrics are reported, and no sibling is named or contrasted.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no prerequisites, and no indication of when this diagnostic is relevant versus the many data-fetching siblings (compra, meus_documentos, etc.). The agent is left to infer that this is a status/health probe.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds genuinely useful context beyond that: this is a private, account-scoped resource requiring a browser cookie plus CSRF token, which matters for how an agent must be authenticated. It still omits pagination/return behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded, with no filler; both sentences carry information (scope and auth). It is terse rather than padded, though terseness here edges toward under-specification.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter read tool with full schema coverage and annotations covering safety and idempotence, the main gaps are what the tool actually returns and how it relates to sibling listing tools. Given the structured fields carry most of the burden, this is adequate but not complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single 'antes' cursor parameter is fully documented in the schema itself. The description adds no additional meaning about the cursor or filtering, so the baseline 3 for high coverage applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

"Coleção privada da conta" is a noun phrase that largely restates the name ("meus_compras") rather than stating a verb+resource action like listing or returning the account's purchases. It does not differentiate this tool from near-siblings such as 'salvas', 'compra', or 'salvar_compra', so an agent cannot tell which one actually reads saved purchases.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use or when-not-to-use guidance and no reference to alternatives among the many purchase-related siblings. The only conditional information is the auth prerequisite (account session), which is a precondition rather than usage routing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context the annotations don't: the account session requirement (browser cookie + CSRF). However it says nothing about pagination direction, result set size, or what is returned.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with no filler, and the scope statement precedes the precondition. It is efficiently written, though the brevity comes partly from omitting necessary information rather than from tight editing.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-optional-parameter read tool with an output schema absent, the auth requirement is the most important missing piece and it is supplied. The definition still leaves unclear what the tool actually returns and how it differs from the crowded document-tool family, which is the key ambiguity an agent faces here.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the sole cursor parameter "antes" is already documented in the schema as an exclusive client cursor. The description adds no pagination semantics beyond that, so the baseline 3 applies when the schema does all the work.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

"Coleção privada da conta" names a resource and scope but no verb — it doesn't say whether the tool lists, fetches, or searches documents. It also does not distinguish itself from the many document siblings (documento, documentos_empresa, documento_leitura), so the agent must infer purpose from the name alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no statement of when to use this tool versus documento, documentos_empresa, or the other documento_* siblings, nor any exclusion criteria. The only directive is the auth prerequisite, which is a precondition rather than usage guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuine context by naming the auth mechanism (account cookie sent in the MCP request) and the account model, but it does not describe what the counters contain or what the response looks like.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with the core purpose, no filler or repetition. It is efficient, though the terseness borders on cryptic given the undefined 'contadores'.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Complexity is low (read-only, one optional param), which keeps the bar modest, but there is no output schema and the description only generically mentions 'identity and counters'. An agent cannot tell what fields or counters to expect, leaving a real gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%: the sole optional parameter 'locais' is fully documented in the schema (up to 90 comma-separated document IDs, max 1529 chars, checks ownership). The description adds nothing about this parameter, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description identifies the resource as session identity plus private counters tied to the account cookie, which is more than a restatement of the title. However, 'contadores privados' is left undefined (counters of what?), and there is no differentiation from near siblings like conta_acompanhamento or minhas_empresas. An agent gets a rough idea but not a precise scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use, when-not-to-use, or alternative tool is stated. The remark that 'the global account is already the person, there is no per-product activation' clarifies the account model but does not tell an agent when to call this tool versus another account-related sibling.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint, so the safety profile is covered. The description adds one genuinely useful behavioral fact — that the list is private and scoped to an account session or a guest "edm_" identity — but the reference is truncated with an ellipsis, leaving the guest mechanism underspecified.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

It is a single short sentence with the resource front-loaded, which is structurally sound. But "e seleção" sits in the purpose clause without adding meaning, and the truncated "edm_…." reference weakens the sentence rather than shortening it cleanly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema and no parameters, so the description is the only place an agent could learn what this returns — yet it says nothing about the returned company fields, ordering, counts, or which company is flagged as selected. For a zero-parameter read tool with no output schema, that is a substantive gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so per the baseline the description is not expected to document any. Its mention of session/guest context is the closest thing to an input qualifier, though it is not a declared parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names the resource ("lista privada de empresas") and identifies it as the user's own list, which distinguishes it loosely from buscar_empresa. However, the trailing "e seleção" is ambiguous — it is unclear whether this tool performs a selection or merely reflects the currently selected company, and no sibling is named for contrast.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

"use a sessão da conta ou o convidado edm_…." is an authentication hint rather than usage guidance. It never states when to call this instead of buscar_empresa, selecionar_empresa, or listar siblings, nor any prerequisite or exclusion.

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

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

Annotations already declare read-only, idempotent, non-destructive, so safety is covered. The description adds substantial operational behavior: edge cache of up to 6 hours, per-request recomputation of prazos/preços, `Cache-Control: no-cache` forcing an origin read, and the `x-origem-cache` header reporting hit/miss/bypass. That is real value beyond the annotations, though no auth or rate-limit notes are given.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the resource and its two returned dates, then legal justification, cost, and cache semantics. Every sentence carries information, though the lei/artigo citation and the cache-header detail make it longer than strictly necessary for selection.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description does the work of naming the returned values and flagging that the impugnação date is an estimate (3 business days before the session, national holidays). It omits the output shape and any error behavior for an invalid id, but covers the essentials for a one-parameter read tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

One parameter with 100% schema description coverage; the schema already explains that `id` is the compra id from the search. The description adds nothing about the parameter, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States the resource precisely ('Prazos da compra') and enumerates the two values returned: proposal-publication end and the last day for impugnação, with the legal basis (Lei 14.133 art. 164). It lacks an explicit verb and does not distinguish itself from siblings like 'compra', so an agent must infer the boundary, but the data it yields is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied: pass a compra id (from 'busca') and receive that purchase's deadlines. There is no explicit when-to-use/when-not, nor any naming of the sibling ('compra') that would return the broader record instead. Adequate but leaves routing to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real behavioral context: the free tier vs. paid endpoint, that 400 responses include `exemplo` and `doc`, that `Accept: text/html` opens the Preços tab, and that the paid detail is billed per query. This goes meaningfully 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very long and heavily redundant: the contents of the free summary (n, median, p25/p75, grupos, volume, quantidade) are enumerated twice in near-identical wording. The purpose statement is not front-loaded as a clean lead, and the repetition costs the agent reading effort without adding information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the full burden of explaining return values, and it does so in detail (n, mediana, faixa p25/p75, `comparacao`, `grupos`, `amostra`, `detalhe`). Combined with the alias and method notes, an agent has enough to call the tool correctly, though the duplication makes the return contract harder to parse than necessary.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds value the schema lacks: alias mappings (`query`/`termo`/`busca`/`search` → `q`, `estado` → `uf`, `limit` → `limite`) and the workflow meaning of `grupos`/`produto`/`unidade` (pass back a group's produto and unidade to switch). It does not explain the `catmat` parameter beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a concrete verb+resource ('Consulte resultados homologados por descrição do item') and the free summary returns comparables for a catalog product in the same unit. However the purpose is buried in a long run-on opening sentence, and it never distinguishes itself from sibling tools such as compra or buscar_licitacao; the only differentiation is against a paid route (GET /api/precos/detalhe), which is not a sibling tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It clearly frames the free summary versus the paid full detail (x402 or credit), which is genuine when-to-use guidance for cost-sensitive selection. It also documents alternative HTTP methods and parameter aliases, but gives no explicit when-not-to-use condition or naming of competing sibling tools.

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

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

Annotations declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, so the agent already knows it is a non-destructive but non-read-only operation. The description adds two useful facts beyond the annotations: the sample is 'gratuita' (free, implying no credit consumption) and it does not persist alerts. It still leaves open whether the call consumes quota or what side effect justifies readOnlyHint=false, so it does not reach the higher bar.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single tight sentence with the key facts (free sample, inputs, no alert creation) front-loaded and zero filler. It is efficient, though it is arguably too terse for a tool with a four-key nested filter object.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a preview tool with no output schema, the description conveys the input modes and the crucial negative constraint that no alerts are created, which is the main thing an agent must know. It omits credit/quota and return-shape details, but with 100% schema coverage and no output schema the remaining gap is modest.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, including the nested filtros object and the CNPJ term-suggestion behavior ('até 8 famílias'), so the schema does the heavy lifting. The description merely restates that the sample is driven by 'termos/filtros' or CNPJ, adding no syntax or precedence detail beyond the schema, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Names a concrete resource and mode ('Amostra gratuita de compras') and distinguishes itself from the alert-creation siblings by explicitly stating 'Não cria alertas', which separates it from criar_alerta/editar_alerta in the sibling list. The one-sentence form is clear, though it does not name the alternative tool by name.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'Não cria alertas' gives an implicit when-not signal and 'Amostra gratuita' implies a preview/trial use case before committing to an alert. However, no explicit condition or named alternative (criar_alerta, alerta_por_cnpj) is provided, so the agent must infer when to prefer this tool.

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

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

The annotations already declare the full safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the description starts from a lower bar. It does add one genuine behavioral fact not in the annotations — that the endpoint is free to call ('no charge') — but says nothing about freshness, caching, or the shape of the pricing data returned.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single short sentence with no filler; the content claim is front-loaded and immediately followed by the cost reassurance. Every clause earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, read-only lookup with no output schema, the description adequately states what is returned (public prices and free allowances) and that the call is free. Only the return format or freshness of the pricing data is left unspecified, which is a minor gap at this complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to clarify. It appropriately does not invent parameter detail.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names the specific resource it exposes: current public prices and free allowances. It is clear what an agent gets back, though the phrasing is a label rather than a verb+resource statement, and it does not explicitly distinguish itself from sibling tools like billing or api_usage that could also look price-related.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit when-to-use guidance and no naming of alternatives (billing, api_access_buy, api_usage). 'No charge' is the only usage-relevant hint, signaling the call itself is free, but which tool to consult for actual account costs versus public list prices is left to inference.

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

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

Annotations only cover the safety profile (readOnly, idempotent, non-destructive), and the description goes well beyond that: it discloses the training source (PNCP homologated winners), the per-item limit (up to 99 highest-value items, 3 CNAEs each), the 3/2/1 positional scoring, the fallback when no items exist (5 most probable, no itens/valor_estimado fields), the cost (free), and a measured accuracy figure (87% as of 27/09/2026).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the purpose, then layers useful behavioral detail (fallback, limits, accuracy, alert CTA). It is dense and slightly long, with some promotional phrasing ('Grátis'), but almost every sentence carries selection-relevant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description does the work of describing return shape (CNAE list, ranking, official description, counts, estimated value share) and the special fallback case. Accurate enough for an agent to call and interpret results, though it does not discuss pagination or error/empty-result handling directly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for the single 'id' parameter ('id da compra (vem da busca)'), so the schema already carries the semantics. The description confirms it operates on a purchase but adds no formatting or sourcing detail beyond the schema, establishing the baseline 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific resource and scope: the CNAEs most likely to win a purchase like this, ranked, with official description and per-CNAE item/value counts. An agent can immediately understand this is a CNAE-recommendation tool and tell it apart from generic search (buscar_licitacao) or company lookup (buscar_empresa) siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear context (use on a purchase to see likely winning CNAEs, free of charge) and routes the agent to an alternative workflow for a related need: create an alert via POST /api/alertas to receive future purchases of those CNAEs. It lacks explicit 'when not to use' exclusions, but the alternative is named.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety and idempotency are covered. The description adds useful content-level context by naming the receipt fields (price, payment mode, content hash), but says nothing about auth requirements, whether the receipt is immutable, or failure modes. With annotations carrying the behavioral profile, a 3 is appropriate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single compact sentence with the resource front-loaded and no wasted words. It is efficient, though so terse that it skirts under-specification rather than achieving a clean, complete statement.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter read tool with no output schema, the description does some of the work an output schema would do by naming the returned fields (price, payment mode, content hash). Combined with full parameter coverage in the schema, an agent has enough to call it correctly; only the trigger condition and error behavior are missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%: the single `id` parameter is documented as coming from the x-editalmd-recibo header, which is the key piece of information. The description adds nothing about the parameter, so the baseline of 3 for schema-covered params applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names the resource ("Recibo de uma entrega") and enumerates its payload — price, payment mode, and content hash — so an agent understands it returns receipt data for a delivery. It never states an explicit verb (fetch vs. create), though the readOnlyHint and the required receipt id make the retrieval reading clear. No sibling tool competes in this space, so differentiation is not a concern.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to invoke this tool, what precedes it, or what alternatives exist. The only implicit cue is that a receipt id must already be known, but the description never says so. The agent must infer the entire call context.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false. The description adds useful behavioral context beyond annotations: analyses that used the receipt become outdated. It does not cover permissions or recovery behavior, but adds meaningful consequence information.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One compact sentence, front-loading the verb and resource, followed by a semicolon-separated consequence. No redundant or filler content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given full schema coverage, destructive/idempotent annotations, and no output schema, the description is largely sufficient. It notes the important downstream effect, though it could elaborate slightly on permissions or deletion permanence.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with both required parameters documented as CNPJ and SHA-256 PDF hash. The description adds no parameter-level meaning 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.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb 'Remove' and a specific resource 'comprovante da própria empresa'. This distinguishes it from siblings like remover_empresa and anexar_documento_empresa by object and ownership scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no explicit when-to-use, when-not-to-use, or alternative-tool guidance. It only states the action and a downstream consequence, leaving the agent to infer usage from the name and sibling list.

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

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

Annotations declare destructive and idempotent. Description adds that only the owner's own link is removed (scope limitation) and that selection is cleared if necessary (side effect). This is valuable context beyond annotations, though it doesn't cover permissions or error cases.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One short sentence with two clauses, no filler. Front-loaded with the main action. It is arguably too terse, but conciseness is good.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-param destructive tool with no output schema and annotations covering destructive/idempotent, the description gives key scope and side-effect info. However, it leaves ambiguous what 'próprio dono' means in a multi-user context and provides no usage routing, so it is only minimally adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%; cnpj is fully described with format and validation. Description adds no additional parameter meaning, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (remove) and resource (vínculo do próprio dono), and constrains scope with 'somente'. It distinguishes from siblings that add or search for companies, but the phrase 'vínculo do próprio dono' is slightly ambiguous (link of the owner vs company itself).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit when-to-use, preconditions, or alternatives. Only implicit context from 'se necessário' for clearing selection. An agent must infer that this is for unlinking the current owner's company.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is carried. The description adds real value beyond that: it clarifies the removal does not spawn a watch or notification and that the record's snapshot is sourced from the acervo, which are genuine side-effect disclosures.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, front-loaded with the action and free of filler. The phrasing is slightly terse/cryptic in the second clause, but nothing is padded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter destructive tool with rich annotations and no output schema, most of what an agent needs is present. It does not state reversibility, whether a confirmation is required, or what the call returns, leaving modest gaps for a destructive operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the 'id' parameter is already documented as the catalog identifier. The description's 'O cliente fornece somente o ID; o retrato vem do acervo' adds only marginal meaning about data sourcing and that no other field is needed — the baseline 3 applies 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.

Does the description clearly state what the tool does and how it differs from similar tools?

States a clear verb+resource: 'Remove a compra da lista pessoal do dono' — an agent knows this deletes a saved purchase from a personal list. It implies a boundary with the watch/notification siblings ('Salvar não cria vigia nem notificação') but never names vigiar_compra or salvas as the contrasting tools, so differentiation is implicit rather than explicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: the agent can infer this is for undoing a save. There is no explicit when-to-use vs when-to-use-alternatives guidance against siblings like salvar_compra, vigiar_compra, or salvas. The line 'O cliente fornece somente o ID' is an input note, not usage routing.

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

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

Adds substantial behavior beyond the annotations: the previous secret keeps signing for 24 h, the `webhook-signature` header carries two `v1,…` parts during that window, and the receiver may accept either. This is exactly the migration mechanism an agent needs and annotations do not express. No contradiction with readOnlyHint=false / destructiveHint=false.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the action, then the auth need, then the rollover mechanics. Four sentences, all relevant; the header-format sentence is dense but earns its place by explaining the dual-signature contract.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and no annotations on the security mechanism, the description covers the grace period and header format well. It omits how/where the caller obtains the newly generated secret, which is the one piece a rotation caller would need next.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Zero parameters, so the baseline is 4. The description usefully notes the auth requirement (edm_… token), but there are no parameters for it to add semantics to.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: rotating the secret that signs webhooks. No sibling tool touches webhook secrets, so there is nothing for it to be confused with; an agent immediately knows what this does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear context for calling it: the auth prerequisite (edm_… token) and the operational rationale (rotate without a failure window). No alternatives exist to route against, so the absence of exclusions is not a real gap, but it never states when NOT to rotate.

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

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

Annotations already declare idempotentHint=true and destructiveHint=true, but the description adds real context beyond them: no charge and no notification on save, a hard cap of 200 per owner, and that no watch is created. It does not explain why destructiveHint is set or what data could be affected, so it stops short of full transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, front-loaded with the core action and quota. Minor redundancy: 'nem notificação' in sentence one is needlessly repeated as 'não cria vigia nem notificação' in sentence two, though every statement still earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter, no-output-schema tool with annotations present, the description covers quota, absence of charge/notification, and the ID-only input contract. The only gap is not addressing the destructiveHint annotation, which an agent might want explained.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with a single documented parameter, so the baseline is 3. The sentence 'O cliente fornece somente o ID; o retrato vem do acervo' reinforces that only the id is needed and the payload is pulled from the archive, but this largely restates what the schema already says.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Names a specific verb and resource ('Salva a compra') and immediately scopes it with what it does NOT do ('sem cobrança nem notificação', 'não cria vigia'), which distinguishes it from alert-related siblings like vigiar_compra and criar_alerta. An agent can identify the operation without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies its niche by clarifying that saving does not create a watch or notification, which helps separate it from vigiar_compra, and it states a quota ('até 200 por dono'). However it never explicitly names an alternative tool or states when to prefer salvar over watch/alert flows, so usage is only implied.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds a rate/result limit ('até 200') and a cost note ('gratuitamente'), which is useful context beyond annotations, but does not explain ordering, pagination, or authorization details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, front-loaded sentence that contains all key information (verb, resource, limit, owner scope, cost) with no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple zero-parameter list tool with no output schema, the description covers the essential call context: what is listed, maximum count, ownership scope, and cost. It does not describe the shape of returned items, but that gap is minor given the tool's simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters and 100% schema description coverage, so there is nothing for the description to compensate for. Baseline for zero-parameter tools is 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Lista') and resource ('licitações salvas'), plus scope ('até 200', 'pelo dono', 'gratuitamente'). It is clear what the tool does, though it does not explicitly name or differentiate itself from nearby siblings like buscar_licitacao or salvar_compra.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the use case (listing saved tenders) but gives no explicit when-to-use or when-not-to-use guidance, no prerequisites, and no alternatives. For a simple zero-param list tool this is minimally adequate.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=true. The description adds real context: the selection is persisted per owner, can be recovered on other devices by linking the account, and repeating the current selection does not write (reinforcing idempotency). However, it never explains the destructiveHint=true flag — what prior selection state is replaced or lost — which is the most consequential behavior an agent should know.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short but wastes space: "não executa análise" appears twice, once at the start and once at the end, and the persistence/linking sentence is a related-feature aside rather than core behavior. Front-loading is fine, but the repetition is avoidable padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter tool with no output schema and annotations covering the safety profile, the description is close to adequate, covering persistence and idempotency. The main omission is the destructive behavior implied by destructiveHint=true, which is neither confirmed nor scoped, leaving the agent unable to judge the consequence of re-selecting.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is a single required parameter (cnpj) and schema description coverage is 100%, with the schema already specifying 14 digits with valid check digits. The description adds no format or validation detail beyond that, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Seleciona empresa cadastrada") and explicitly excludes an adjacent function ("não executa análise"), which helps separate it from analysis tools like analisar_participacao. It does not, however, distinguish itself from near-siblings such as adicionar_empresa, buscar_empresa or minhas_empresas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the usage context (select a company already registered, persisted for the owner, recoverable across devices when the account is linked) and gives an implicit when-not (this is not the tool for running analysis). It never names an alternative tool or states a selection condition, so routing remains inferred rather than guided.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context beyond the schema: it discloses the authentication requirement ('Precisa do token edm_…') and sketches the payload's semantics.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two compact sentences, front-loaded with what the tool returns, and the auth prerequisite is appended without padding. No filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter read-only tool with full schema coverage and no output schema, this is nearly self-sufficient: it names the resource, the returned fields and the required token. Only the sibling routing (vigiar_compra vs this tool) is left to inference.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so both 'id' and 'limite' are already documented in the schema, including the 1–100 range and default of 50. The description adds no further parameter meaning, making the baseline of 3 appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific resource (eventos de uma compra vigiada) and the dimensions returned (o que mudou, de quê para quê, quando) plus the current snapshot. It is clearly distinguishable from the sibling vigiar_compra, which would create the watch, but it doesn't name that sibling explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied — call this to see the timeline of changes for an already-watched purchase — but there is no explicit when-to-use/when-not statement or reference to the alternative (vigiar_compra to start watching). Nothing misleading, just under-specified.

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

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

With readOnlyHint=false the description correctly signals a state-creating operation, and it goes beyond annotations by disclosing the auth requirement (edm_ token), the free-first/subsequent-paid quota model with a 30-day window, periodic check cadence, and the one-shot nature of prazo notifications. It stops short of saying how to inspect or remove a vigia (the vigia_eventos sibling is never referenced).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The pricing statement is stated twice in near-identical form ('A primeira é grátis; as seguintes custam…' then 'A primeira vigia ativa é grátis (FRANQUIA_VIGIAS); as seguintes custam PRECO_VIGIA…'), which is pure waste. The token requirement is also embedded mid-sentence rather than front-loaded, weakening scanability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, and the description compensates by explaining what events are registered and how notifications behave, plus cost and auth. For a 3-param mutation it is largely complete, with only the retrieval/removal path via sibling tools left unaddressed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so canal, destino, and compra_id are already documented in the schema, fixing the baseline at 3. The description adds only the token requirement and no additional syntax or format detail for the three parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Clear specific verb+resource: 'Vigia uma compra', and it enumerates exactly what it watches for (retificação, documento novo, suspensão, prazo adiado, valor, avisos de prazo). It does not, however, contrast itself with plausible siblings like criar_alerta, alertas_compras, or vigia_eventos, so an agent isn't told which monitoring tool to pick.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states a precondition ('precisa do token edm_…') and cost/quota behavior, which is genuine usage context, but there is no explicit when-to-use vs. when-not or any routing to the alert-related siblings. Usage is implied rather than directed.

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