editalmd

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 the useful behavioral fact that a POST here answers 410 with the path, which is non-obvious endpoint behavior the annotations do not convey. It does not, however, describe what the 'check' produces.

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 with little waste, but the first is dense with undefined Portuguese domain terms and does not front-load the core action. The second sentence is relevant but describes a sibling route rather than this tool's own use.

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-param read-only tool with no output schema, the description carries the full burden of explaining the return, and it does not – it never says what the ownership check yields or how an agent should act on it. The complexity is low, but a key piece 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 and the schema is empty, so there is nothing to document; the baseline of 4 applies. The description correctly introduces no parameter concepts that would need explaining.

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 resource – Salvas, Alertas and Vigias tied to the session account – but the verb 'Checks' is vague and the domain terms are left undefined. An agent can infer it verifies ownership of tracking lists, but cannot tell what the tool actually returns or does beyond that.

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 effectively tells the agent when NOT to use it by pointing out that guest `edm_…` lists are moved via `POST /api/auth/claim` and that a POST to this route returns 410. That gives a negative routing hint toward the `claim_guest_tracking` sibling, but there is no explicit positive statement of when this tool should be called.

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

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

The description goes well beyond the annotations (destructive/idempotent hints) by disclosing return-code semantics (201 on creation, 200 when the CNPJ already exists), the ownership precondition, the 100-company cap, and explicit exclusions ('no partners or contacts; no analysis starts'). This is exactly the behavioral context an agent needs 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?

The content is valuable but delivered as one long, run-on paragraph with awkward phrasing ('the organization of the organization key', 'returns the one that the person removed from the list'). The core action is not front-loaded and the conditional branches are hard to parse.

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 returns and does so via status codes and outcome descriptions. Side effects, quotas, and preconditions are all covered; only a clearer statement of alternatives 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?

With a single parameter and 100% schema description coverage, the schema already fully documents the CNPJ format and check-digit requirement. The description adds no parameter-level detail beyond what the schema provides, so the baseline score applies.

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

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

The description names a specific action and resource: importing a CNPJ into a new or existing organization. It is distinguishable from siblings like remove_company and search_companies, though the purpose is buried in verbose conditional phrasing rather than stated up front.

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 describes the two invocation contexts (with vs without X-Organization-Id) and the precondition that the caller must manage the target organization, which implies when it applies. However, it never explicitly contrasts with alternatives such as search_companies or select_company, so usage guidance remains 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 only declare readOnly=false, idempotent=false, destructive=false. The description goes well beyond that: 202 on acceptance vs 200 when reusing a finished analysis, resumability of interrupted requests, explicit POST to resume a pause, failure messages stating reason and next action, and hard capacity limits (2k facts, 100 tenders per company, subject to budget). It also scopes the outcome ('triage with evidence, not a final qualification decision').

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 clause and every subsequent sentence (status codes, resume, limits, follow-up verb) carries operational weight. It is dense and slightly list-like, with a couple of sentences that could be tightened, but there is no filler.

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

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

For an async, non-idempotent job trigger with no output schema, the description supplies everything an agent needs: acceptance vs reuse semantics, resume path, failure reporting, quota limits, and the required follow-up read. Nothing material is left for the agent to guess.

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% (v as SHA-256, id as document ID, cnpj as 14-char identifier), so the schema carries parameter meaning. The description alludes to the company record, attachments and tender but does not add format or constraint 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?

States a specific verb+resource: it starts or resumes an analysis over a company record, its attachments and a tender. It also distinguishes itself from the sibling it must be followed by ('follow it with get_participation'), so an agent can place it in the workflow without opening the schemas.

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 invocation gate ('Call it only when the user asks') and explicit sequencing ('follow it with get_participation', 'Follow-up only by GET'). It stops short of naming when-not-to-use or routing against sibling evaluation/qualification tools, so it is clear context without full exclusions.

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

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

Annotations already cover read-only, idempotent, non-destructive, and closed-world behavior, so the description adds useful context by listing the returned offer and purchase fields. It does not describe rate limits, auth requirements, or how missing api_pass changes behavior, but the annotation coverage lowers that 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 purpose is front-loaded in one compact sentence, and the long return-field list is dense but justified because there is no output schema. The description is not bloated, though the return object could be formatted more readably.

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 tool with rich annotations and no output schema, the description provides enough return-shape information for an agent to understand the result. The main missing piece is an explicit mapping of api_pass presence to discovery versus private-purchase inspection.

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

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

The single optional api_pass parameter is fully documented in the schema, including its private pass format and the warning to save it before buying. The description only hints at it via 'inspect a private purchase' and adds no format or behavior details 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?

The description states two concrete functions: discovering the monthly data package and inspecting a private purchase. This is clearer than a tautology and gives the agent a usable verb/resource pairing, though it does not explicitly differentiate itself from the 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?

The two modes imply when the tool is useful, but the description never explicitly says to call it without api_pass for discovery versus with api_pass for inspection. It also does not mention when to use api_access_buy instead, 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?

The description says 'Same pass in retries recovers the same purchase' and the transaction parameter 'Never creates another charge,' which conflicts with idempotentHint=false. Although it otherwise discloses useful behavior such as no automatic renewal and separate tariffs, the idempotency contradiction is material for a purchase operation.

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 offer is front-loaded in the first sentence, and the remaining sentences cover relevant operational details. The paragraph is dense and could be structured more clearly, but most content 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 absence of an output schema, the description provides substantial operational context: price, validity, retry behavior, no automatic renewal, excluded tariffs, response headers, and prepaid credit behavior. This is sufficient for an agent to understand what the tool does and how it fits into the payment flow.

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 payment, api_pass, transaction, and credit_token. The description adds flow context, such as saving the api_pass before buying and using the transaction hash for reconciliation, but does not add parameter syntax 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: buying 1000 basic data reads for US$1, valid for 30 days. It also scopes what is not included (OCR, AI, documents, delivery) and mentions the prepaid alternative, making the tool's role distinguishable.

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 usage context: buy basic data reads, send X-API-Pass on eligible reads, and skip this purchase if using prepaid credit. It does not explicitly compare against every sibling tool, but the alternative path 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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds nothing beyond that – no note on what the index contains, whether it is static or dynamic, or how large the response is.

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 padding, which is structurally clean and front-loaded. But it is under-specified rather than concise – the brevity removes information an agent needs rather than removing waste.

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 annotations covering return content, the description is the only place the response shape could be explained, and it does not say what 'routes' means (paths, names, descriptions, version list). For a zero-argument discovery endpoint, that omission leaves the agent unable to predict the result.

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 rubric the baseline is 4. There is no parameter surface for the description to clarify, and the empty object schema is self-explanatory.

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 ('the EditalMD API index') and hints at its content ('with the routes'), which is slightly more than a bare restatement of the name. However, it supplies no verb (list/return/get) and the phrase 'with the routes' is too vague to tell an agent what the tool actually yields or how it differs from discovery siblings like health or list_examples.

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 indication of when to call this tool, what situation it serves (API discovery, versioning, capability enumeration), or any alternative among the many sibling tools. The agent must guess the use case entirely.

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 cover the non-destructive, non-open-world profile, and the description adds genuinely useful behavior beyond them: session requirement, the fact OCR is not started, HTTP preference for large payloads, the 201 status, quota/size limits, and dedup of identical files. One tension worth noting is that 'an identical file is reused' hints at repeat-safe behavior while annotations declare idempotentHint=false, though the reuse may apply only to stored content rather than the attachment record, so this is not a clear 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-loaded with the action, then packs constraints into short telegraphic sentences with no filler. The density is high but every clause (OCR, session, HTTP, limits, dedup) carries operational meaning, so it stays efficient rather than 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 mutation tool with no output schema, the description supplies the essentials: authentication/session need, size and quota limits, processing semantics, and the 201 return. Only the response body shape is left unspecified, which is a minor gap given no output schema exists to fill it.

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 four parameters (cnpj, nome, tipo, arquivo_base64) are already documented in the schema. The description restates the 8 MiB decoded PDF limit but adds no format, encoding, or validation detail beyond what the schema provides, so the baseline of 3 applies.

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

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

States a concrete verb and resource (attach a company PDF document) and distinguishes itself from reading-oriented siblings by explicitly saying it does not start OCR and that the automatic reading only happens on an analysis request. An agent can separate this upload tool from get_document / company_documents / analyze_participation without opening any 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?

Gives clear operating context: requires a session, prefer the HTTP path for large files, OCR is not triggered, and analysis is only performed on request. It routes the agent away from expecting immediate processing, but it does not state exclusions relative to siblings such as remove_company_document or list_document_files.

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

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

Annotations already cover read-only, idempotent and non-destructive, so the description's job is to add what the annotations cannot: it discloses that the summary is free, excludes extremes, computes the value for the requested quantity, lists the alternative product/unit groups found, documents the accepted POST/PUT/PATCH aliases (query/termo/busca/search → q, estado → uf, limit → limite), and states that 400 responses include `exemplo` and `doc`. That is substantive behavioral context 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?

Every sentence carries information, but the whole thing is one undifferentiated run-on block that leads with return-value detail instead of the tool's purpose, and mixes output description, data sources, HTTP method aliases and error format without structure. Front-loading is weak.

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 8 parameters, the description does the heavy lifting by describing what comes back (count, median, p25/p75, volume, quantity-specific price, sibling groups) and the error shape. It is close to complete; only the absence of any guidance on result freshness/coverage limits for the two data sources leaves a small 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 coverage is 100%, so baseline is 3, but the description adds real meaning: `produto` and `unidade` are explained as coming from the `grupos` in the response ('500 FL, 1 UN'), `quantidade` is tied to the returned quantity range, and the alias mapping clarifies how POST/GET parameter names correspond. It adds value rather than restating the schema.

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

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

The description names the resource precisely: awarded prices (PNCP results plus Ceará TCE-CE items) searched by item description, returned as median/p25/p75 statistics. It is a clear verb+resource statement, though the rambling opening sentence buries the 'what it does' behind a description of the output, and it never contrasts itself with siblings like search_tenders or open_tenders_in_field.

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 rather than stated: the 'price for your quantity' and the drill-down hint ('ask for the product and the unit of one of them to switch') tell an agent how to iterate, but there is no explicit when-to-use versus alternatives and no prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is covered upstream. The description adds the useful hint that the endpoint is "public" (no auth needed) and enumerates the returned payload sections, but says nothing about freshness, cost, or why flags like `dev_gate` and `homolog` exist.

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 one-sentence purpose is properly front-loaded, but the returns block is a dense brace-and-comma dump mixing nested optional keys (`free_now?`, `gratis?`) with no markup. It is information-bearing yet hard to parse, and could be structured more 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?

With no output schema, the description must convey return shape, and it does enumerate top-level and nested fields. However, it only lists names without explaining what `quota`, `payment.homolog`, `credit.header`, or the `?` optionality mean, leaving the agent to infer semantics of a fairly complex payload.

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; there is nothing for the description to clarify. The description correctly implies a no-argument 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?

"Public discovery of payment and prepaid credit" identifies the resource area and signals no-auth discovery, but the phrasing is abstract rather than a concrete verb+resource. It never distinguishes itself from siblings like `pricing`, `api_index`, or `api_access`, even though this tool apparently aggregates those very concepts as return fields.

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 named alternative. An agent cannot tell whether to call this instead of `pricing` or `api_index`, which is the central ambiguity given the overlap.

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

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

Annotations already mark it as a non-readonly, non-destructive, non-idempotent, closed-world write, and the description adds real context on top: renewal semantics per rail, the 402-with-price error, accepted payment headers (X-Credito, PAYMENT-SIGNATURE v2 / X-PAYMENT v1), the `compra` mark guarding against repeat credit debits, single-settle x402 nonces, and receipt-retention after a delivery error. It also clarifies the consequence of idempotentHint=false by naming the exact repeat-debit guard.

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

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

Every sentence carries operational content and the purchase act plus payment rails are front-loaded; there is no filler. It is dense and shifts topic rapidly (renewal, headers, guest ownership, unit costs), which is slightly harder to parse than an ideally partitioned description.

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?

Despite no output schema, the description covers auth paths (wallet agent auth, claim after sign-in), guest purchase ownership, error behavior, and even the shape of an active plan (usage.total / usage.used / usage.remaining). Nothing an agent needs to invoke this correctly appears to be missing.

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

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

The single `plan` parameter is fully documented in the schema (100% coverage) including the allowance sizes for each enum value, so the baseline is 3. The description's unit-cost figures (1 page = 1 unit, price report 25, alert 5, tender watch 3) let an agent reason about tier fit but do not add per-parameter syntax or constraints.

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 plus resource plus scope: 'Buys a plan for the account or paying wallet.' This clearly separates it from read-only siblings like list_plans, consulta_planos, pricing, and from cancel_plan, so an agent knows this is the purchase action.

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 explicit routing by payment rail (Pix and USDC = 30 days no renewal; card = monthly auto-renewing until cancelled) and states the fallback when unpaid: a 402 carrying the price. It also implies when not to buy ('Original PDFs are free'). It stops short of explicitly directing the agent to list_plans/consulta_planos first to pick a tier.

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 says cancellation requires accepting data removal and that 'what the plan added ends,' which conflicts with the annotation destructiveHint=false. This is a material contradiction for a cancellation operation that explicitly accepts loss of plan-added 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?

The key cancellation behavior is front-loaded and useful, but the description becomes lengthy and includes usage-unit pricing details that are not clearly necessary for invoking cancel_plan. Some sentences about page/report/alert/tender-watch units feel tangential to the cancellation action.

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

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

For a complex cancellation tool with no output schema, the description covers important effects: stopping charges, keeping paid periods active, refund timing for recent or unstarted purchases, and exceptions for USDC/credit payments. It still does not describe the immediate response shape, but it provides substantial business context beyond the schema.

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

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

There is one required boolean parameter with 100% schema description coverage, so the schema already explains that it must be true and means accepting loss of plan benefits. The description reinforces this but adds no additional syntax or parameter-specific constraints beyond the schema.

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

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

The description opens with a specific verb and resource: 'Cancels the active plan.' It immediately clarifies scope and consequences, making it clearly distinct from sibling tools such as buy_plan, list_plans, and billing.

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 this is the cancellation action and gives some conditional behavior, including that USDC or credit purchases require an e-mail refund request. However, it does not explicitly state when to use cancel_plan versus related siblings like buy_plan, list_plans, or billing.

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 is otherwise unusually rich — it discloses transactional behavior ('in one transaction'), collision handling ('what collides ... stays with the guest'), scope limits ('only what the guest still has') and the CSRF/bootstrap precondition. However, it states 'A repeat does no harm (it moves zero),' which is idempotent semantics, while the annotations declare idempotentHint=false — a real conflict that could mislead retry logic.

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 action is front-loaded and the sentences are dense with information rather than filler. It is slightly convoluted with parenthetical asides ('(the SDK claim)', '(it moves zero)') and untranslated domain nouns, but no sentence 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 mutation with no output schema, it covers preconditions, atomicity and collision behavior well, but says nothing about the response (counts of moved items are only implied by 'it moves zero') or error cases such as an expired/absent guest session. Enough to invoke, not enough to interpret the result.

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 one parameter with 100% schema description coverage ('Token edm_… of the guest.'), so the schema already carries the meaning. The description only reaffirms the 'edm_…' token origin ('what the guest edm_… created'), adding nothing about format, lifetime or where to obtain it.

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

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

The description names a specific verb and resource set: it brings guest-created 'Salvas, Alertas and Vigias' plus purchased documents into the session account. The domain terms are unusual but the operation is unambiguous. It does not explicitly name or distinguish itself from potential siblings (e.g. account_tracking, list_saved), so it stops short of a 5.

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

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

It gives a clear trigger context: 'Requires the bootstrap/CSRF of this browser; the page does it right after sign-in,' which tells the agent when this runs and what precondition must hold. What is missing is any explicit exclusion or named alternative route for the same goal, so it does not reach 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds that the documents are 'private' and that binary downloads go through a separate authenticated endpoint, which is useful workflow context, but it says nothing about pagination, result limits, or return shape.

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

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

Two short sentences with the listing purpose front-loaded and no filler. The second sentence is slightly awkward in referencing a raw HTTP path inside an MCP tool description, but it is still compact and 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 single-parameter list tool with full schema coverage and read-only annotations, the core is adequate, but with no output schema the description should say more about what is returned (formats, pagination, ordering) and how it relates to the sibling document-fetching tools.

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

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

Schema coverage is 100%, and the cnpj parameter is well documented (14 characters, linked to the owner). The description adds no parameter-level detail beyond the schema, so the baseline 3 is appropriate for a single fully documented 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?

States a specific verb ('Lists') and resource ('private PDFs of the company'), so the agent knows it retrieves a document collection for a company. It does not, however, distinguish itself from nearby siblings like list_document_files, get_document, or get_document_dossier, which an agent would need to tell apart.

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 second sentence implicitly routes binary retrieval to an authenticated HTTP GET /documentos/:arquivo endpoint, hinting that this tool only enumerates and does not fetch binaries. But there is no explicit statement of when to use this vs. the many sibling document tools, so 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 declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds genuinely new operational context — that calls do not consume the daily free limit and that the origin's protection limit still applies — which is exactly the quota/throttling information annotations cannot express. It stops short of describing output shape or latency, so a 4 rather than 5.

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

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

Three tight sentences: return contents first, then scope/behavioral caveats, then alternative routing. Every sentence carries information and the most decision-relevant content is front-loaded.

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

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

There is no output schema, and the description compensates by naming the returned fields. Combined with annotations covering the safety profile and a fully documented single parameter, an agent has everything needed to select and invoke the tool correctly.

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

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

Schema description coverage is 100% and the single cnpj parameter is already documented as accepting input 'with or without punctuation.' The description adds only the phrase 'by CNPJ,' which duplicates the schema rather than extending it, 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 the specific resource (a Brazilian company's registration record, keyed by CNPJ) and enumerates the returned fields (name, status, activity, address). It also explicitly contrasts itself with the sibling consulta_cnpj, so an agent can distinguish the two without opening either 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?

Gives an explicit when-not rule with the alternative named: 'For sanctions, tax status and a live CNIA check, use consulta_cnpj.' It further clarifies scope limits ('does not show contacts or partners and runs no extra checks'), leaving nothing 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 readOnly, idempotent, non-destructive and closed-world, so the safety profile needs no restating. The description does add genuinely useful behavior: hard caps of 20 addresses and 20 companies, and that `pontos_total` carries the true total. It stops short of saying what happens on an invalid CEP or whether the truncated result means a follow-up call is needed.

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 clauses, each carrying distinct information (what it returns, the result caps, the cost profile), with the payload statement front-loaded. Slightly compressed to the point of dropping the verb in the opening 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?

No output schema exists, so the description correctly takes on return-value disclosure: it names addresses, companies, limits, and the `pontos_total` counter, and states the tool is free. A one-clause note on invalid-format CEPs or empty results is the only 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?

Only one parameter and schema coverage is 100%, with the '8 digits' format documented in the schema itself. The description adds nothing about the CEP parameter, 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 and verb: returns addresses at a CEP plus the companies registered there, with coordinates from CNEFE/IBGE. It is clearly distinguishable from consulta_cnpj-style lookups, though it never names the closest sibling (consulta_endereco) to draw the line 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 rather than stated: an agent can infer 'use this to look up a CEP', and the cost note ('free: uses no daily allowance or balance') gives a real reason to prefer it over paid siblings. But there is no explicit when-not and no comparison against consulta_endereco or consulta_cnpj.

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, openWorld), but the description meaningfully adds failure and cost behavior: a source failure returns 503 without charging or using a previous record, the last stored CNIA may be returned otherwise (read conferidoEm), and the free allowance is consumed before lookup balance or per-call payment. That is substantive context an agent cannot get from structured fields, though the fallback/staleness semantics of conferidoEm could be spelled out further.

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?

Dense but purposeful — the failure/cost constraint is stated early and each sentence carries operational content. Minor waste in the unexplained "Additional" opener and the slightly garbled sentence about free allowance ordering, 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 three-parameter, fully documented read-only lookup with no output schema, the description covers billing, failure and staleness behavior well enough to call it correctly. The remaining gap is competitive positioning against consulta_cadastro, which the agent must infer.

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

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

Schema coverage is 100%, so the schema already documents cnpj, temas and cnia_atual thoroughly, including the topic list and masking behavior. The description largely restates that ("Select topics to load only the needed blocks", the cnia_atual 503 rule appears in both places), adding only marginal cost context rather than new parameter meaning. 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 resource (CNPJ lookup) with prepared public records and an optional live CNIA source check, which is concrete. However, the qualifier "Additional" is left unexplained, and the tool never distinguishes itself from close siblings such as consulta_cadastro or search_companies. An agent knows roughly what it does but not why it exists alongside the other CNPJ 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?

There is real guidance for the optional switches ("Set cnia_atual=true when that check is required", "Select topics to load only the needed blocks", "Omit for the full record"). But these are parameter-usage hints, not tool-selection guidance — nothing says when to pick this over consulta_cadastro or search_companies, nor are any exclusions 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?

The description discloses a lot of behavior that the annotations do not: unpaid calls return a 402 with a price in dollars and reais, the body uses x402 v1 while PAYMENT-REQUIRED uses v2, the balance is held by the account holder or by the wallet that confirmed payment, unpaid wallets need the signed challenge to get an mmw_… credential, and a payment grants no login. It also states that a plan adds 30 days plus quota while a package is valid 90 days, and that there is no automatic renewal. This is exactly the extra context the annotations cannot carry.

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 in the first sentence, but the rest is a dense run-on of cryptic clauses such as 'The body uses x402 v1; PAYMENT-REQUIRED uses v2' that require prior knowledge to parse. Most of the information earns its place, but it needs restructuring.

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 has to carry the return path, and it does: the 402 quote, the credential URLs (wallet_start and wallet_token), and the balance-holder semantics. It doesn't cover error cases besides 402, but it is complete enough for this money-moving 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 schema already documents the idempotency mark, the offer list, the x402 payment and the cred_… token. The description only adds the framing that the offer is one package plus three plans and that credit versus x402 are the two payment paths. Baseline 3 applies.

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

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

The description names a specific verb and resource: it buys one package or one of three plans, paid by credit or x402, with or without an account. That is far more specific than the title 'Buy lookups'. It never names the sibling it complements (consulta_planos for choosing a plan, api_access_buy for API plans), so differentiation is implied by subject matter rather than stated.

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

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

The description explains the purchasing procedure in detail (unpaid call returns a 402 quote, then sign the x402 payment), which is real invocation guidance. But it never says when to pick this over consulta_planos, pricing, billing, or api_access_buy. An agent can infer the flow but has to guess at 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, not open-world), so the bar is lower; the description still adds real behavioral value by disclosing the result caps (up to 20 addresses and 20 companies), the quota exemption, and the fact that the origin's protection limit applies.

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 clauses, front-loaded with the core purpose before the quota and limit caveats. Only minor friction from unexplained internal jargon ('pontos_total', 'the origin's protection limit').

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 naming the `pontos_total` field and the caps on returned addresses/companies is genuinely useful. Quota and limit caveats round it out; only the sibling differentiation and any error/empty-result 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?

There is only one parameter and schema coverage is 100%, so the schema fully documents that 'cep' accepts input with or without a hyphen. The description adds nothing about the parameter format, which is the expected baseline 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+resource: retrieve addresses and companies at a Brazilian CEP. Clear enough to act on, but it never distinguishes itself from near-name siblings like consulta_cep or consulta_cnpj, so an agent cannot tell from the description alone which of the CEP/CNPJ tools 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 implies a use case (looking up addresses/companies for a postal code) and adds quota-relevant context ('without counting against the daily free limit'), but gives no explicit when-to-use vs. when-not, and no guidance on choosing it over consulta_cep or consulta_cnpj.

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

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

Annotations already cover read-only/idempotent/closed-world, but the description adds real behavioral context beyond them: output varies by credential type (X-Credito vs X-Wallet-Token), balance is shared across Radar CNPJ, PontoFato and EditalMD, and wallet credentials are issued per-portal. That is exactly the kind of auth-dependent behavior an agent needs before deciding to call it.

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

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

Two sentences, front-loaded with the returned payload and followed by the credential branching, with no filler. Slightly dense in the second sentence but every clause carries operational meaning.

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 parameters and no output schema, the description carries the burden of saying what comes back, and it does list the four data groups plus the conditional on credentials. Minor gap: it doesn't indicate the shape of the plan/offer data (currency, tiers, whether prices are per-call), though that is largely nameable from the response 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?

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. The mention of header-based credentials is useful naming even though no schema properties exist.

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 what the call returns (free allowance, the single package, the three plans, the balance) and frames it as a 'lookup service', so an agent knows this is a read of pricing/plan/balance data rather than an operation on CNPJ records. The opening phrase 'CNPJ and address lookup service' is slightly confusing since siblings consulta_cnpj/consulta_endereco do the actual lookups, and no sibling is explicitly named to distinguish this from pricing or billing.

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 through the credential conditions ('without a credential... with an account...'), which implicitly tells the agent that an anonymous call returns offers and an authenticated call returns balance. There is no explicit 'use this instead of pricing/billing/api_access when...' guidance, so the agent must infer the split among four closely related commercial 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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely useful behavior beyond that: it does not consume the daily free quota, it omits contact data, and `incompleto` flags a partial source response. The partial-failure semantic is the kind of detail annotations cannot express.

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

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

Three short sentences, front-loaded with the core action and result semantics; each sentence adds a distinct fact (ranking, quota exemption/hidden contacts, `incompleto` meaning). 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, the description carries the return burden and does reasonably well, disclosing result count, ordering criterion, contact omission and the `incompleto` sentinel. It could say slightly more about what each suggestion contains (e.g., name vs CNPJ fields), but nothing critical for correct invocation is missing.

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

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

Schema description coverage is 100%, so the sole `q` parameter (3-120 chars, name/CNPJ/phone/e-mail) is already fully documented. The description echoes the same accepted inputs without adding syntax, normalization or prioritization rules, 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 and resource ('Suggests up to 8 Brazilian companies') plus the accepted key types (CNPJ, name, partner, phone, e-mail), so an agent knows this is a fuzzy autocomplete-style lookup rather than a full record fetch. It contrasts implicitly with consulta_cadastro/consulta_cnpj by capping results at 8 and noting it hides contacts, but never names a sibling 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?

Usage is only implied: signaling that it is free of the daily limit and returns a short ranked shortlist hints at exploratory/pre-lookup use, but the description never says when to choose it over search_companies, consulta_cnpj or consulta_cadastro. No explicit when-not conditions are given.

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

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

Beyond the annotations it discloses the 30-minute cron cadence, the fact that webhook and email channels also push non-PNCP tenders (TCE-RS LicitaCon, TCE-PE), and that unmapped activities come back in the response without an alert. It still omits what happens on duplicate creation and whether plan/quota limits gate creation.

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 and channel behaviour are front-loaded, which is good, but the prose is telegraphic and fragmentary ("Two modes.", "The cron checks every 30 minutes.") and repeats schema content about `termos`. The `cnpj`/`max_familias` sentences are dead weight for 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?

For a nine-parameter tool with nested objects and no output schema, the description covers auth, channel delivery and side effects but says nothing about what is returned (alert id, created record) or how failures surface. The nested `filtros` and `destinatarios` behaviour is carried entirely by the schema.

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

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

Schema coverage is 100%, so the baseline is 3. The description restates the `termos` space/pipe semantics that the schema already documents and calls out name, organization and recipients as optional, but adds no new detail for the nine parameters; the stray `max_familias` reference points at a parameter that does not exist here.

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 definition makes clear it sets up a standing alert for new procurements filtered by object terms and UF, and it names the delivery channels. It blurs the boundary with the sibling `create_alerts_by_cnpj` by describing a `cnpj` mode ("up to `max_familias`") that has no corresponding parameter in this tool's 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 gives real prerequisites: account session or guest token, and email requires a session plus `EMAIL_ALERTAS=1`. What it does not do is route between siblings — there is no statement about when to use this versus `preview_alert`, `update_alert`, or `create_alerts_by_cnpj`, so the agent must infer the choice.

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 cover the safety profile (readOnly=false, destructive=false, openWorld=true, non-idempotent), and the description adds genuinely useful context beyond them: a 30-minute cron evaluation, the edm_ token requirement, that email needs an account session plus EMAIL_ALERTAS=1, and that unmapped CNAEs return a null family. The main gap is that nothing is said about what the creation response contains or how the per-family alerts are identified afterwards.

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

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

Every sentence contains information, but the ordering is scattered: it opens with family mechanics, detours into a `termos` mode, then appends cron and email prerequisites at the end. The front-loaded material an agent needs (what it creates, required CNPJ, token) is split across the first and last third.

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?

This is a ten-parameter mutation tool with nested objects and no output schema, so the description carries real weight. It covers family behavior, scheduling, and email prerequisites, but leaves the response format, the effect of canal=pull vs webhook, and organization_id entirely to the schema, and it never reconciles the phantom `termos` mode with the actual CNPJ-only input.

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 and the schema already documents all ten parameters including nested filters and recipients. The description adds meaning for max_familias and the family mapping, but spends its parameter-focused prose on `termos`, which is not a parameter of this tool, so the net added value is modest and partly misleading.

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 ('Alerts for new procurements by the company CNPJ') and explains the distinctive CNAE-to-family fan-out, which an agent could not infer from the name. It is docked one point because it introduces a 'By `termos`' mode that has no corresponding parameter in the schema, muddying what this specific tool actually 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?

Usage context is implied rather than stated: the cron cadence, the token requirement, and the email prerequisites tell the agent the operational setting, but there is no explicit guidance on when to pick this over siblings such as create_alert, preview_alert or update_alert. The 'Two modes' framing suggests a choice the agent cannot actually make through this schema.

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 adds substantial behavioral context beyond annotations: it warns that 'The token appears only once: keep it', that 'The token has no recovery', that there is a limit 'per network and per hour', and that after secret rotation 'the previous secret still signs for 24 h'. These details are essential for safe invocation and are not present in the annotations.

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

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

The description is long and includes extensive implementation details about webhook signature verification ('HMAC-SHA256 of id.timestamp.body') and secret rotation that are not necessary for selecting or invoking create_owner. The first sentence is front-loaded, but the remainder is verbose and partially off-topic.

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 absence of an output schema and zero parameters, the description covers what is created (token and secret), how to use the token, recovery limitations, rate limits, and secret rotation behavior. It is thorough, though some details about webhook verification go beyond what an agent needs to call this specific 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 takes zero parameters, so there are no parameter semantics to explain. Per the rubric, this baseline is 4; the description does not need to compensate for schema gaps.

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

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

The description states a clear action: 'Creates the guest (token edm_…, issued by the account library) that opens alerts and watches, and the secret whsec_… that signs the webhooks.' It identifies the specific resources created, but does not explicitly distinguish this tool from siblings like get_owner or rotate_webhook_secret.

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 explaining 'No sign-up' and that the token should be kept and sent in 'Authorization: Bearer in the alert and watch tools.' However, it does not state when to choose this tool over alternatives (e.g., get_owner) or provide explicit when-not-to-use 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?

The description adds real context beyond the annotations: this is a paid x402 operation whose output is a charge token. But with idempotentHint=false and destructiveHint=false, the risk an agent most needs to know is unstated — that repeating the call spends money again and there is no undo. The cryptic return-key list does not compensate for that missing caution.

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, front-loaded with the action and payment mechanism. The return-key enumeration is dense but earns its place since there is no output schema; the untranslated keys (guarde, usar, saldo_em) make it harder to parse but it stays compact.

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

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

For a one-parameter purchase whose annotations cover the safety profile, the definition covers the payment flow and the return shape, which is the main unknown. The only gap is guidance on repeat invocation and how the returned token is subsequently supplied to other APIs.

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 'usd' parameter is fully documented with an enum of 0.1/1/5/10/25. The description adds nothing about the parameter, 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 ('Tops up prepaid credit') and adds the mechanism (pay once with x402, receive a token charged across the house's APIs). That distinguishes it from a pure balance read like credito_saldo, but it never names the sibling, so an agent must infer the distinction.

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?

Implies usage ('pay once ... get the token that is charged in any API'), so an agent can infer this is the step before paid calls. However, it gives no explicit when/when-not against credito_saldo, buy_plan, api_access_buy, or billing, all of which sit adjacent to this action.

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 new behavior: unauthenticated calls return 401 with an x402 manifest in the Link header, and when billing is configured the body carries accepts[] mirroring the smallest POST top-up, while the call itself neither charges nor opens credit. It stops short of describing response shape or limits in full, so not a 5.

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

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

The text is dense and front-loads the credential-dependent return behavior, which is good, but it mixes English and Portuguese across sentences and leans on unexplained identifiers ('cred_…', 'mmw_…', 'x402 manifesto'). No sentence is pure filler, yet the phrasing forces the agent to decode jargon rather than parse clean facts.

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 parameters and no output schema, the description carries the burden of explaining what comes back, and it does: balance/statement under one credential, wallet plus payment recovery under another, plus 401 and accepts[] behavior. It is close to complete for a zero-arg read tool, with only exact field names and pagination of the 20 payments left unclear.

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 for a parameterless tool is 4, and nothing in the text misleads about inputs.

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 concrete resource (balance and statement) and further splits the behavior by credential type: cred_… returns balance/statement, mmw_… returns wallet balance plus up to 20 recoverable payments. That is specific and goes beyond the title. It loses a point for the cryptic 'cred_…'/'mmw_…' prefixes and for not differentiating itself from siblings like my_account, estado_cobranca, or credito_recarregar.

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 'use this when…' guidance and no named alternative such as credito_recarregar for topping up or estado_cobranca for charge state. The only usage-adjacent statements are negative/behavioral — that the GET does not charge or open credit, and that a missing token yields 401 — which clarify side effects rather than selection criteria.

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 does add real context beyond the annotations: the 30-minute payment window, 24-hour observation, no L1 absolute finality, support required for late or wrong-network payments, and wallet/exchange fees. However, it is silent on what this POST itself returns and on failure semantics, and the claim that the same X-Cobranca header keeps the same charge/address sits in tension with idempotentHint=false without clarifying when a new charge is actually created.

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?

Long, run-on and poorly front-loaded: after a strong first sentence it mixes payment-finality notes, support policy, fee warnings, downstream GET/POST steps and dev-environment caveats in no clear order. Several sentences ('Each buyer pays, even when the text is ready') are ambiguous and could be dropped or rewritten.

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 charge-creation tool with no output schema, it does cover timing, network and failure handling, and describes what a paid GET returns (acesso.codigo plus cookie). But it never states what this call returns (address/QR payload, expiry, status) and the vincular flow is described only vaguely, leaving the agent unable to predict the response.

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

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

Schema coverage is 100%, so all three parameters are already documented and the baseline is 3. The description adds only marginal meaning, namely that the token travels as X-Cobranca and should be reused across GET and retries, and that cotacao originates from GET /geracao; it does not explain the relationship between the document id and the quote.

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 specific verb and resource: it reserves an exclusive address/QR for paying with USDC on Base, i.e. it creates a charge. That is distinguishable from the sibling estado_cobranca, which only checks status. The rest of the description drifts into payment reconciliation detail, so the core purpose is stated once and then buried.

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?

Implicit prerequisites exist ('Check GET /geracao and send cotacao', the 30-minute send window), but they are embedded in prose rather than framed as when-to-use conditions. No sibling alternative is ever named (e.g. estado_cobranca for polling, consulta_comprar for pricing), so the agent must infer routing from names alone.

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, destructiveHint=false and closed-world, so the safety profile is covered. The description adds the useful detail that the purchase is "still anonymous" and supplies a return shape { documento_id, vinculado, recuperacao }, but it never explains what the access code does, whether the code is consumed, or what a successful/failed check 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 with no padding, and the return shape is stated compactly at the end. Slightly awkward wording, but every sentence carries 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?

The return shape compensates for the missing output schema and annotations cover the safety profile, so the core call is described. What is missing is the routing context — when to use this versus documento_vincular or claim_guest_tracking — which matters given a crowded sibling set of document-related 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 both `id` and `acesso_codigo` are already documented in the schema, and the baseline of 3 applies. The description adds nothing about the access code — arguably the tool's central input — nor about how the anonymous-purchase state interacts with the required `id`.

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 an action ("checks the link" / "allows exporting the code") tied to an anonymous purchase document, but the phrasing is vague and partly mistranslated — it is unclear whether the tool validates an access code, retrieves a document, or claims an anonymous purchase. It does not distinguish itself from close siblings such as documento_vincular, get_document, or claim_guest_tracking.

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 statement and no mention of alternatives, even though siblings like documento_vincular (link a document) and claim_guest_tracking (claim anonymous tracking) sit squarely in the same territory. The agent must infer the routing decision from the name alone.

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 the operation is 'idempotent for the same owner', while the annotations declare idempotentHint=false, a direct conflict about repeat-call behavior. Valuable context is present (no new charge, session + private proof required, ownership cannot be transferred), but the explicit contradiction with the structured hint makes the behavioral signal untrustworthy.

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 that front-load the core action and the no-charge guarantee before prerequisites and ownership rules. Slight redundancy between the 'global right' and 'another owner cannot claim it' clauses, 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?

With no output schema, the description must carry the outcome burden, and it does explain the resulting state (account records the global right, subsequent access via the code) plus prerequisites. It falls short on error conditions and conflicts with the idempotency hint, leaving an agent unsure about retry behavior.

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, giving a baseline of 3. The description adds conceptual meaning ('private proof of the purchase', a cookie also being accepted, the code continuing to open the document itself) but no syntax or format detail beyond the schema.

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

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

The first sentence gives a specific verb ('Links') and a precise resource/relationship ('anonymous purchase to the authenticated account') plus a cost guarantee ('without a new charge'). An agent can distinguish this from nearby tools such as documento_acesso, get_document, or claim_guest_tracking, though no sibling is named 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 rather than stated: 'Requires a session and private proof of the purchase' establishes prerequisites and the anonymous-purchase context. However, it never says when to prefer this over alternatives like claim_guest_tracking or documento_acesso, nor what to do if the proof is missing.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful operational context beyond that: it states the lookup 'does not write or make a blockchain RPC', is 'free of charge', requires reusing the 'X-Cobranca' header and honoring 'Retry-After', which is exactly the rate-limit/retry information an agent needs on a status-polling endpoint.

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 sentences with little padding, but the phrasing is awkward and mixes languages ('Reads the address, confirmation, receipt and release...', 'When it is gerando...', 'pronto releases the reading links'), so the most important state-dependent guidance is buried mid-paragraph rather than front-loaded.

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

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

With no output schema, the description carries the burden of explaining what is returned. It gestures at the response contents and names the status values (gerando, pronto, revisao) with what each implies, but never clarifies the response shape or the set of possible states, so an agent still has gaps about what a successful read yields.

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 both parameters are fully documented in the schema, including the 64-hex-character token generation and reuse rules. The description reinforces token reuse ('Reuse X-Cobranca') and ID retention ('keep the ID'), but adds no syntax or constraint details beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description names a verb ('Reads') and a resource ('your charge'), but the enumeration 'the address, confirmation, receipt and release' is ambiguous about whether these are return fields or separate resources. It implicitly contrasts with 'criar_cobranca' by reading vs creating, but never states plainly that it returns the current state of a charge, leaving the agent to infer from the tool 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?

There is real conditional guidance: 'When it is gerando, use GET /geracao for phases/pages' and 'In revisao, keep the ID and the transactions for support, without paying again.' However, it points at a raw HTTP path rather than the sibling tool 'generation_status', and it never explains when to call this tool versus 'recibo' or 'original_status', so the routing is only partly actionable.

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 and idempotentHint=false but say nothing about cost or lifespan; the description adds that calls consume credential-bound units, expire at the earlier of 30 days or pilot end, and depend on a global budget. It also clarifies duplicate documents don't re-consume quota. This is meaningful behavioral context beyond the annotations, though it omits whether the call is synchronous or produces a retrievable artifact.

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 text is dense and back-loaded with pilot rules, budget caveats, and premium header names (X-Editalmd-Avaliacao, X-Agent-Pass) that are irrelevant to selecting or invoking this basic tool. Those sentences do not earn their place and distract from the core page/size limits stated in sentence one.

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 quota-consuming, credential-gated text extraction it covers limits, quota, and expiry, which is substantive. However, it never explains how the extracted text is retrieved (the evaluation_basic_result sibling implies an async or separate fetch) and provides no output-contract hint, leaving a gap for a mutation-style call with no output schema.

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

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

Schema coverage is 100% and both parameters (id, agent_pass) are fully described in the schema, including the caveat that agent_pass is not the User-Agent. The description adds no parameter-level detail beyond generic credential discussion, so the baseline of 3 applies.

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

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

The description states a specific verb and resource: extracting basic native or OCR text from a PDF, bounded at 50 pages / 32 MiB, excluding review or structured tables. It partially differentiates from evaluation_premium ('does not open premium content'), though it never names the sibling that offers premium text. Clear enough for an agent to identify the operation.

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 conveys quota context (up to 100 documents per agent, duplicates don't consume a unit) which implies this is a metered operation, but it never states when to choose this over evaluation_premium or how the result surfaces (evaluation_basic_result is a sibling). The premium paragraph describes headers rather than routing conditions, 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?

Adds substantial behavior beyond annotations: per-credential allowance bounded by the agent's 30-day limit or pilot end, idempotency in quota terms, premium-content exclusion, pilot global-budget dependency, and no auto-renewal. These are real operational constraints not present in 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?

Front-loads the return/retry purpose, but the premium header sentence ('keep evaluation.access_code...') and pilot-budget caveat make it feel like multiple concepts are packed into one block without clear grouping. Several sentences earn their place; the premium instruction is the least clearly scoped to 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 no output schema, the description supplies the key return shape ('text per page with the hash of the source') and covers quota/pilot constraints. It leaves retry_after_s origin and polling/error behavior implicit, but the core call context is present.

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 id and agent_pass are fully described there. The description adds quota meaning to agent_pass ('per credential') and references premium headers, but it does not add syntax or selection 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 that it returns the text per page with the source hash after the basic reading's retry_after_s. The 'follows...after retry_after_s' phrasing identifies it as the result/continuation of evaluation_basic, but it never names evaluation_basic or explains how the retry value is obtained, so sibling differentiation is implicit.

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?

Explicitly says to call it after retry_after_s and notes that repeating the same document consumes no additional unit. It also states basic does not open premium content, giving a when-not boundary, but it stops short of naming evaluation_premium or evaluation_quota as 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 only declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false. The description adds real behavioral context beyond them: it consumes a single sponsored premium unit, allowance is per credential, expiry is the earlier of 30 days or pilot end, repeats of the same document do not consume another unit, the pilot depends on a global budget, and there is no automatic renewal. The claim 'repeating the same document does not use another unit' sits in mild tension with idempotentHint=false, but can be read as result-level rather than side-effect-level idempotency.

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 first sentence is well front-loaded, but the remainder is a run-on jumble that mixes quota rules, header names, HTTP paths, and credential field names without clear ordering or grouping. Several ideas (access code, allowance, expiry) are repeated or interleaved, making it hard to extract an actionable sequence.

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 quota-consuming tool with no output schema, the description does cover consumption, allowance, and repeat behavior, which is the important operational surface. But it never explains what the premium access returns or how 'evaluation.access_code as avaliacao_codigo' relates to the declared inputs, leaving the access-code flow 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% for both required parameters (id, agent_pass), so the baseline is 3. The description gestures at header usage ('X-Editalmd-Avaliacao together with X-Agent-Pass in the reads and in GET /geracao') and references an 'evaluation.access_code' that is not a declared parameter, which adds some auth context but is too garbled to clearly extend parameter meaning.

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 ('Uses your only sponsored premium on a document of up to 50 pages') and adds a scope constraint (50-page cap). It also differentiates from the sibling evaluation_basic via 'Basic does not open premium content.' The remaining sentences dilute the purpose, but the core action is identifiable.

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 implied routing guidance ('Basic does not open premium content') and quota context ('allowance per credential, until the earlier date of the agent's 30 days and the end of the pilot'), which hints at when the premium path is required. However, it never explicitly says when to choose this over evaluation_basic, evaluation_quota, or generation_status, and the mid-sentence 'follow it with generation_status' reads as a parameter instruction 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, destructiveHint false, and openWorldHint false, so the safety profile is clear. The description adds useful domain context about the allowance contents and expiry, but does not disclose auth requirements, rate limits, or output behavior beyond that.

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 a single, compact sentence with no wasted words. It is front-loaded with the core resource concept, though it could more directly state the tool's action.

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 one-parameter read-only tool with full schema coverage and annotations covering safety, the description is adequate but incomplete. It explains what the allowance contains, yet without an output schema it does not clarify what the tool actually returns or how the result should be interpreted.

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 agent_pass parameter is fully documented in the schema, including its distinction from User-Agent. The description adds no parameter-level 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?

The name and description indicate the tool concerns an evaluation quota or allowance, and it specifies the allowance composition (one premium, 100 basic documents, expiry date). However, it lacks a clear action verb such as 'retrieve' or 'check' and does not distinguish itself from siblings like evaluation_basic or evaluation_premium.

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 offers no explicit guidance on when to use this tool versus alternatives, nor any prerequisites or conditions. Usage is only faintly implied by the allowance details.

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

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

Annotations already establish readOnly/idempotent/non-destructive safety, but the description adds real behavioral context: ordering by relevance, automatic exclusion of canceled and expired agreements, cost-free nature, and the content-negotiation behavior of Accept: text/html. This is meaningful disclosure beyond the annotation profile, though it does not cover pagination 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?

Front-loads what the tool returns, then layers filtering, the adesao flag, and the related endpoint/header notes. It is dense but each sentence carries information; the back half reads as a slightly run-on sequence of notes rather than a tight 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?

With no output schema, the description correctly enumerates the returned fields and ordering, and documents the validity/cancellation filter plus the HTML-tab alternative. It is nearly complete for an agent to call it correctly, lacking only pagination guidance (pagina) and result-count expectations.

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

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

Schema coverage is 100%, so the schema already documents all three parameters; the description's restatement of adesao=1 adds little beyond it. The baseline of 3 is appropriate since the schema carries parameter meaning and the description does not extend it.

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 (valid framework agreements / ata de registro de preços on PNCP) and enumerates the returned fields (managing agency, validity, carona acceptance, link). An agent knows exactly what this retrieves and its ordering (most relevant first), and it is clearly distinguishable from the procurement-record lookup it references.

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: it is free, filtered to non-canceled agreements valid today or later, and `adesao=1` narrows to agreements accepting joining. It also routes the agent to the procurement record endpoint for the agreements a specific compra generated and notes the Accept: text/html variant. It stops just short of explicit when-not-to-use guidance against named 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. The description adds two useful traits beyond that: it is free and does not start processing. However, it does not explain auth requirements, return shape, or error behavior, so the addition is modest.

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 sentence with no filler, and the 'without starting processing' caveat earns its place. However, the phrasing 'follows the real phases' is awkward and not front-loaded as a clear action.

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?

Rich schema descriptions and safety annotations cover much of what an agent needs, so the short description is not fatal. Yet because there is no output schema, the description should clarify what 'phases and completion' actually returns; it only hints at it.

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 every parameter is documented in the schema, including the document id and the multiple auth-code parameters. The description adds no parameter-level meaning, so the baseline score of 3 is appropriate.

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

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

The description says it 'follows the real phases and the completion,' which gestures at status tracking, but it never states a clear verb and resource such as 'returns generation progress for a document.' It relies on the title for the generation context and does not distinguish this from sibling tools such as original_status.

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 'without starting processing' implies it is for checking status rather than triggering generation, but there is no explicit when-to-use guidance, prerequisites, or named alternative. An agent must infer how this differs from original_status or get_document.

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 only generic annotations (readOnlyHint=false, destructiveHint=false), the description carries the behavioral load and does it well: per-page pricing, no charge on an unknown/changed quote, 202-then-GET follow-up, 502 pago_nao_registrado with recibo for refund/support, and how the purchase is recorded against the account/guest right. It states consequences and failure modes rather than just restating the mutation hint, though the delivery/return shape is never 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 dense run-on block of payment jargon that is not front-loaded: the first thing the agent reads is a price, not what the tool produces. Sentences like 'with the edm_… guest (Bearer), the right is the guest's and the code comes along' pack several distinct rules without structure, forcing re-parsing.

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 paid, stateful operation with no output schema, the description does cover charging rules, retry/idempotency behavior, and error paths. It still omits what a successful response contains, how the markdown is delivered (inline vs. via get_tender_markdown), and how it relates to generation_status or document access 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 coverage is 100%, so the baseline is 3. The description adds a little beyond the schema — confirming pages/hash/total against the quote, noting guest Bearer vs X-Credito vs account session, and warning to retain acesso.codigo — but it leaves several of the seven parameters (agent_pass, avaliacao_codigo, idempotencia) to the schema alone.

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

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

The opening sentence describes a commercial transaction ('Buys individual access to the document for US$ 0.02/page') rather than the operation itself; the actual purpose only surfaces obliquely in 'A ready text reuses the OCR; a necessary generation is included.' Nothing distinguishes it from siblings like get_tender_markdown, documento_acesso or get_document, so the agent must infer this is the paid markdown generation endpoint.

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 usage context: send cotacao when authorizing payment, follow up a 202 via GET, keep acesso.codigo for later reopening, and choose between x402, credito_token, and guest/agent credentials. However, there are no explicit when-to-use/when-not rules relative to the several sibling tools that also expose document access.

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

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

Annotations already cover read-only, open-world, idempotency, and destructive hints. The description adds meaningful behavioral context beyond those: paid per call, no account required, an output cap of 10 items, and a warning that text matches do not imply equivalent specs or valid bid prices.

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 reasonably short and front-loads the core purpose, but the middle sentence ('Collecting procurement items and calculating the returned price summary') is somewhat redundant and the wording is awkward.

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 9-parameter tool with no output schema and limited annotation detail, the description does not explain the structure of the returned price summary or how the main parameters shape results. It provides output-limit and caveat context, but leaves too much to the schema and 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 the schema already documents all 9 parameters in detail. The description adds little parameter-level meaning, and its 'up to 10 items' phrasing is potentially confusing against the `limite` parameter allowing 1 to 100, though the schema remains authoritative.

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 resource and outcome: a winning-price summary for procurement items, with full summary and up to 10 items. It is clear enough to distinguish from generic search, but it does not explicitly differentiate itself from sibling pricing/award tools such as awarded_prices or pricing.

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 mentions that the tool is paid per call and requires no account, but gives no explicit guidance on when to use it versus sibling tools. The caveat about text matching not establishing equivalent specifications is useful, but it is a warning rather than a selection rule.

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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely useful behavior beyond them: the tool is free, results are edge-cached up to 6 hours, `Cache-Control: no-cache` forces an origin read, and `x-origem-cache` reports hit/miss/bypass. This is exactly the kind of staleness and cost disclosure that helps an agent call it correctly.

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

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

The resource definition is front-loaded, followed by legal-context and cache details. It is efficiently sized, though the header-level cache mechanics push slightly past what's strictly necessary.

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

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

With no output schema, the description carries the burden of describing the return content, which it does (published proposal end and challenge deadline). For a single-parameter read tool this is nearly complete, with only error/edge behavior left unstated.

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 `id` parameter is documented as the procurement id from search. The description adds no format, range, or sourcing 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 names a specific resource (the procurement's deadlines) and enumerates its content (end of proposals, last day to challenge). It implicitly contrasts with the broader `get_procurement`, but never names a sibling to differentiate itself 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 context is implied by the cost note ("Free") and the cache behavior, which hints at when a fresh read is worth forcing. However, there is no explicit when-to-use vs. an alternative (e.g., get_procurement) or prerequisite 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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds non-obvious behavior beyond that: the call is cost-free, it does not open document content, and it does not trigger OCR — useful boundaries an agent could not infer from the schema.

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

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

Two tight sentences, front-loaded with the resource and its payload, followed by the exclusion. The middle routing sentence ('Use get_procurement to list the related documents') is slightly ambiguous in direction but costs little.

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 describing returns, and it does so by naming the fields returned. For a single-id read tool with complete annotations, this is nearly sufficient; only error behavior for an invalid id is unaddressed.

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

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

There is one parameter ('id') with 100% schema description coverage, and the description adds no syntax or format detail beyond the schema. Baseline 3 applies when the schema fully carries parameter meaning.

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 (free lookup of a document) and enumerates exactly what is returned: title, type, pages, and linked procurement. It does not explicitly differentiate itself from close siblings like get_document_dossier or list_document_files, so it lands just short of a 5.

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

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

Gives an explicit exclusion ('does not open content or start OCR') and routes the agent elsewhere ('Use get_procurement to list the related documents'). It is clear context, but the neighbouring-tool routing is somewhat indirect and no other alternative (e.g. get_document_dossier) is compared against.

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

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

Annotations already cover read-only/idempotent/non-destructive, and the description adds real value on top: it reuses the same acesso_codigo as the reading, triggers no new AI analysis, and discloses the partial-data/coverage semantics plus the important caveat that an unfinished dossier is not evidence a requirement is absent. That is substantive behavioral context beyond structured fields.

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?

Written as a run-on string of fragments with no front-loaded statement of what the tool does; safety caveats and access notes are interleaved before the reader knows the purpose. Multiple sentences ('It does not start AI.', 'It does not start AI... with no new analysis') restate the same point.

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?

At 8 parameters with no output schema, the definition covers auth and coverage semantics but leaves the return shape vague — 'inspect complete, coverage and issues' gestures at output fields without describing them, and the pagination cursor ('after' = previous `next`) implies a next-token response that the description never mentions.

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%, including the credential parameters and the kind filter, so the description need only complement it. The only added semantics is that acesso_codigo mirrors the reading access, which the schema already explains at length; 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 content well (items, requirements, attestations, deadlines, obligations, with conditions/exceptions/excerpts), so an agent can infer what comes back. But there is no clean verb+resource statement and no explicit differentiation from nearby siblings like get_document, get_deadlines, get_reading_manifest or get_qualification — the reader has to piece the purpose together from scattered clauses.

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?

Useful cues exist: start from the prepared dossier instead of rebuilding extraction, an export requires a finished version, check the original and source dates before a bid decision, and 'does not start AI' implies no new cost. However, none of these are framed as 'use this tool when X, use sibling Y when Z', so the routing guidance stays implicit and buried.

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

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

Annotations already declare readOnly, idempotent and non-destructive behavior, so the safety profile is covered. Beyond that, the description adds genuinely useful behavioral context: the auth requirement (edm_ token or session) and critically the 24-hour grace period where the previous secret continues to sign after rotation, including the observable two-part 'v1,' header. That is non-obvious operational behavior the agent could not get from structured fields.

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 owner-state information is front-loaded, which is good, but the description then spills into detailed HMAC/base64/Standard-Webhooks implementation notes and a 5-minute timestamp-rejection rule that are tangential to retrieving owner state. These earn little or nothing for an agent deciding to call get_owner and bloat an otherwise short 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?

With no output schema and no parameters, the description carries the burden of explaining what is returned, and it does list the returned fields (account/guest type, notice e-mail, allowance, signing secret) plus the auth requirement and rotation grace behavior. An agent has enough to call it correctly; only the exact response shape remains loosely specified.

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. There is no parameter surface 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?

The opening clause identifies the resource (owner state) and lists the fields it carries (account/guest, notice e-mail, allowance, secret). However, the bulk of the description is about webhook signature verification rather than the tool's own purpose, and it never distinguishes itself from siblings like create_owner or rotate_webhook_secret. The core verb is implied rather than stated ('The owner state...' rather than 'Returns the owner state').

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 a stated prerequisite (requires the edm_ token or account session), but no when-to-use guidance, no exclusions, and no routing to alternatives such as rotate_webhook_secret when the secret needs changing. Usage must be inferred from the tool name.

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

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

Beyond the read-only/idempotent annotations, the description discloses that it triggers no processing, that stale company/attachment/dossier inputs return outdated, the reference-date behavior (data_atual=false for a previous day), and that validated batches surface as parcial=true with processados/total without meaning pending requirements are done. This is substantial behavioral context an agent could not derive from annotations or schema.

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 what-it-does sentence is front-loaded and each subsequent sentence carries a distinct behavioral fact (no triggering, staleness, reference date, partial batches). It is dense and jargon-heavy but not padded with restated name/title.

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 fairly complex domain, the description still explains what is returned (state, pending/met items, reasons, actions, evidence) plus edge-case semantics like outdated results and partial batches. Combined with read-only annotations, an agent has enough to call and interpret it correctly.

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

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

Schema description coverage is 100%, so the seven parameters are already documented, giving a baseline of 3. The description adds domain meaning for the group sub-states (precisa_comprovar, divergente, acompanhar) and the partial-batch counters, but does not clarify the v/id/cnpj/after/limit parameters themselves.

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: it reads the participation 'state', pending items and met items with reasons, actions and evidence. It also distinguishes itself from the analyze_participation sibling by emphasizing that it never starts an analysis. The domain jargon (state, batches) keeps it from being maximally crisp, but an agent can tell 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?

Gives clear when-not signals: it 'never starts an analysis', 'GET does not run the queue and does not start AI', and a different company/attachments/dossier return outdated results. However it never names analyze_participation as the explicit alternative, so the routing is inferred 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses caching behavior not available anywhere else: edge cache up to 6 hours, the Cache-Control: no-cache bypass to read origin, and the x-origem-cache header values (hit/miss/bypass). This is exactly the kind of behavioral context annotations cannot carry.

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, then cost, then caching behavior. Every sentence carries information, though the header-detail sentence is dense and slightly implementation-oriented for a tool description.

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 sketches the return contents (titles, types, pages, availability, up to 50) and fully explains the caching contract. An agent has enough to call it correctly, though the precise record fields remain unspecified.

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 is documented as 'Procurement id (from the search).' The description adds no further meaning about the id beyond what the schema provides, so the baseline 3 applies.

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

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

The description names a specific resource and its return contents: 'The procurement record and its documents in the collection (up to 50), with titles, types, pages and availability.' It does not, however, differentiate from siblings like get_participation, get_document, or get_document_dossier, so an agent must infer the boundary between these related fetches.

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. 'Free' and the cache semantics hint that this is the cheap read to prefer when freshness isn't required, and the schema note 'id (from the search)' implies the search-then-fetch workflow. But no alternative tool is named and no explicit when-to-use/when-not is 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?

Adds real behavior beyond annotations: no new analysis is triggered and the list is sourced from an existing analysis, which is essential cost/latency context given readOnlyHint=false and idempotentHint=false. It does not elaborate on access credential requirements, but those are carried at 100% schema coverage.

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 sentences, front-loaded with what the tool returns, then the no-new-analysis constraint, then the scope exclusion. 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, the description does the work of describing return content (conditions, exceptions, evidence by page) and scope limits. Minor gaps remain on result shape or whether results are bounded by the analyzed pages, but an agent has enough 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?

Parameter descriptions are fully covered in the schema (100%), including the id source get_procurement and the access/agent credential semantics, so the baseline of 3 applies. The description adds no parameter-level guidance of its own.

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 specific resource (the tender's qualification list) and what it contains: literal excerpts of conditions, exceptions and evidence, keyed by page. It is clearly distinct from the dossier and analysis tools, though the opening is a noun phrase rather than a verb and relies on 'the available analysis' being understood from context.

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?

Explicitly says the lookup does not start another analysis, and routes other needs to the dossier ('Deadlines, proposals and the other obligations are in the dossier'). It also gives an exclusion boundary: it 'does not state what the company has', so an agent knows not to use it for company-side evidence.

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 safe-read profile (readOnly, idempotent, non-destructive). The description adds genuine value beyond them: 'It does not start OCR' discloses a non-side-effect, 'The same authorization opens the ZIP and the images' explains auth reuse, and the `document_approved: false` note clarifies a field's meaning so it doesn't mislead.

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 return contents are front-loaded and each sentence carries distinct information. Phrasing is choppy and slightly cryptic ('the examples are free'), but no sentence is clearly wasteful.

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

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

With no output schema, the description compensates by enumerating the return fields (pages, images, SHA-256, version) and covering auth plus the 'only ready resources' constraint. Reasonably complete for a read tool, though sibling differentiation remains thin.

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

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

Schema coverage is 100% and the schema descriptions for acesso_codigo and avaliacao_codigo are already detailed. The description adds only marginal meaning ('the examples are free', authorization reuse), so the schema carries most of the burden – 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 names the specific resource (document manifest) and enumerates its contents: pages, images, SHA-256 and version. This is clear enough to distinguish it from generic reads like get_document, but it never explicitly contrasts itself with close siblings such as list_document_files or get_document_dossier.

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

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

It provides partial context: 'Send acesso_codigo; the examples are free' and 'Only ready resources' tell the agent how to authorize and a precondition. However, there is no explicit when-to-use-vs-alternatives guidance against the many sibling read tools, leaving routing largely 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, destructiveHint=false and openWorldHint=false, so safety is covered. Beyond that, the description adds genuinely useful context: this call is credential-gated, can fail without the right code, and free examples bypass the paywall. What it omits is what happens on an auth failure or how large the returned Markdown can be.

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 short, but the structure is poor: the opening sentence is a run-on that buries the purpose under authorization clauses, and the trailing "The examples are free." is cryptic and unattached to any concrete action. Two sentences, yet neither is front-loaded with what the tool returns.

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 covers the credential model reasonably well, and the schema points to get_procurement for `id`. It still leaves gaps on the result shape (raw Markdown? size? truncation?) and on error behavior, which an agent calling a paid, gated endpoint would benefit from knowing.

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 each parameter already carries a detailed description (including how the account cookie and guest token relate to acesso_codigo). The description restates the credential pairings but adds no syntax, format, or interaction 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?

"Reads the Markdown" names a verb and a resource, but the sentence spends most of its words on credential plumbing rather than stating plainly that it returns the Markdown rendering of the tender identified by `id`. It never distinguishes itself from siblings like get_document, get_document_dossier, or gerar_markdown, leaving an agent to guess which retrieval tool produces 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?

Usage is implied through access conditions: hold acesso_codigo, or hold avaliacao_codigo plus agent_pass for the sponsored premium, and examples are free. There is no explicit when-to-use/when-not-to-use statement and no named alternative, so the routing decision against get_document or gerar_markdown 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, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered elsewhere. The description adds that the response concerns origin health plus collection volume, but does not explain what 'health' means (availability? latency? freshness?) and there is no output schema to fill that 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?

A single compact sentence with no redundancy, and the resource is placed first. It is arguably over-terse rather than padded, so no waste occurs, but the brevity trades away needed detail.

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-param, annotation-covered tool the remaining burden is explaining the return value, and with no output schema the description should do more than 'health of the origin'. It hints at the contents (origin status, collection size) but leaves the shape and interpretation of the result undefined.

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 carries no semantics to document and there is nothing for the description to disambiguate. Baseline 4 applies for a parameterless definition.

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 ('health of the origin and size of the collection') and adds scope detail ('procurements and documents with text'), which helps distinguish it from data-fetching siblings. However, there is no verb and 'origin' is ambiguous — it does not say whether this checks an upstream source, a connector, or the dataset overall.

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 indication of when to call this (diagnostics, preflight check, monitoring) or what to do with the result. No sibling duplicates a health check, so there is no explicit alternative to route to, but the description still provides no usage context at all.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so safety is covered. The description adds genuine context beyond that: the auth requirement ('Requires the token edm_…') and the fact that results carry deadlines and delivery status. It omits return format/pagination behavior, keeping it just short of a 5.

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

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

Two short sentences, front-loaded with the resource definition followed by the auth requirement. No filler, no redundancy; 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, non-destructive list tool with full schema coverage and annotations handling the safety profile, the description covers purpose, content of results, and the auth token. Pagination is delegated to the schema (antes_compra), and no output schema exists, so the remaining gaps 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%, so all three parameters (id, limite, antes_compra) are already documented in the schema. The description adds no parameter-level detail beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb+resource: returns procurements that already matched an alert, plus the payload dimensions (deadlines, delivery status). The '(pull channel)' qualifier adds useful scope. It does not, however, explicitly differentiate itself from siblings like preview_alert or list_watch_events, which an agent might confuse it with.

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 '(pull channel)' phrase hints that this is the polling counterpart to a push mechanism, but the description never states when to use this tool versus preview_alert, list_watch_events, or create_alert. No prerequisites or exclusions are given, leaving the agent to infer usage.

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

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

Annotations already establish the read-only, idempotent, non-destructive, closed-world profile, and the description adds meaningful behavior on top: the two query modes, that the call is free, and the null-semantics rule ('a null `familia` or `termos` means the CNAE is not in the dictionary yet; an alert by CNPJ does not use it'). This is exactly the kind of beyond-annotations context the dimension rewards.

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 capability and then branches cleanly into the no-`q` and with-`q` behaviors. It is slightly dense with parenthetical asides (examples, the CNPJ-alert caveat), but every sentence carries information rather than 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 does its part by naming the returned fields (description, family, coverage indicators) and explaining the null-value case. For a 2-parameter, optional-input read tool this is close to complete, though pagination/ordering behavior around `limite` is not described.

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 `q` and `limite` are already documented, and the description's explanation of `q` (prefix or word) largely restates the schema. The prefix example `1412-6/01` adds a useful format cue, but `limite` is not addressed and no syntax beyond the schema is given, so the baseline of 3 holds.

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 returns search-term suggestions for economic activity codes (CNAE), enriched with description, family and coverage indicators. It is clear what the tool does, though it never names or contrasts a sibling tool (e.g., consulta_sugerir), so sibling 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?

It explicitly spells out the two operating modes: without `q` it lists the most-registered-supplier activities, with `q` it searches by code prefix or description word. That is strong context for invoking it, but it stops short of stating when to prefer this tool over alternatives or any prerequisites/exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds real value by disclosing the return payload shape (download links and pages), which matters because there is no output schema. It says nothing about access failures, pagination, or how the code-based authorization params affect results.

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

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

Two short sentences, front-loaded with what the catalog contains, with no filler. The second sentence about the API endpoint is borderline since it references an HTTP route rather than tool behavior, but it is still compact and actionable.

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 listing tool with fully documented parameters, rich annotations, and no output schema, the description covers what it returns and where to go for the full file. Authorization subtleties (access codes, agent pass) are handled in the schema, so little is missing.

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

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

Schema description coverage is 100% and every parameter — id, agent_pass, acesso_codigo, avaliacao_codigo — is documented in detail in the schema itself. The description adds no meaning 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 precisely — the catalog of a document's original files, including download links and pages — so an agent knows it retrieves file metadata rather than document content. The verb is only implied by 'catalog of', and it never names the nearby alternatives (get_document, original_status, request_original) that an agent might confuse it with.

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: read this to enumerate a document's original files. The second sentence points at the raw API route '/api/documento/{id}/original' for the full download, which is a useful routing hint but not a sibling-tool alternative, and no condition is given for choosing this over get_document or original_status.

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, and closed-world, so the safety profile is covered. The description adds that the examples are 'free' (no cost implication), which is useful context, but it does not describe return structure or format beyond naming the underlying artifacts.

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 efficient sentence with the key context (what the examples contain, and their purpose before generation) front-loaded. Slight awkwardness in 'real free proofs' but no wasted sentences.

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-param, no-output-schema list tool with full annotation coverage, the description is adequate: it explains what the examples contain and why to use them. It stops short of describing the shape/ordering of the returned list, which would help an agent consume results.

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 to document and the baseline of 4 applies. The description correctly implies no filtering inputs are needed.

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 (Lists) and resource (real free proofs/examples) and clarifies what those examples contain — Markdown, original PDF, and a ZIP with images. This distinguishes it from generation siblings like gerar_markdown, though the phrasing 'proofs' is less crisp than 'examples'.

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 clause 'before you generate another document' implies a when-to-use context (inspect samples first), but no explicit alternatives, exclusions, or prerequisites are named, leaving usage largely 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?

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds a genuinely useful behavioural detail — the operation is scoped by session or organization key — but says nothing about what the result contains or how many companies are typically 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 short, but the single sentence is a semicolon splice that front-loads a definition rather than the tool's purpose. Size is fine; information ordering is poor.

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 and no parameters mean the description is the only place to explain what the agent gets back — presumably the caller's linked companies — and it omits that entirely. For an account-scoped listing tool, the auth-scope hint helps but the core contract 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 of 4 applies. The auth note about session vs. organization key is the only argument-like behaviour and is mentioned, if vaguely.

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 never states the action ('list') — it defines what a company is ('the account organizations with EditalMD') and how to authenticate. The reader must infer the verb entirely from the tool name. It also does nothing to distinguish this from neighbours like search_companies, select_company, or add_company.

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 the session or the organization key' is authentication mechanics, not usage guidance. There is no statement of when to call this instead of search_companies or company_documents, and no prerequisites or exclusions.

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

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

Annotations already establish a safe read, so the description spends its space on genuinely additive behavior: unauthenticated calls return `account: null`, Pix/USDC purchases are 30-day non-renewing while card subscriptions auto-renew until cancelled, and allowance is drawn down before prepaid credit. These are non-obvious operational facts an agent could not derive from the schema.

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

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

The purpose is front-loaded in the first sentence and every subsequent sentence carries distinct information (auth nullability, renewal terms, unit costs, credit consumption order). It is dense but not padded, though the unit-cost list is close to reference material that could live elsewhere.

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 steps in to describe the shape of the active plan (usage.total/used/remaining) and the null-account case, plus the billing model. It stops short of naming the fields describing the plans for sale themselves, which leaves some return-shape uncertainty.

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 to disambiguate and the baseline of 4 applies. The description instead spends its budget on response and billing semantics, which is the right allocation here.

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 names the resource precisely: the plans available for sale plus the caller's active plan, with the auth-dependent variant called out. It's clear enough that an agent knows this returns plan data rather than performing a purchase or cancellation. It does not, however, differentiate itself from near-neighbours like `pricing`, `consulta_planos`, `billing` or `my_account`.

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 call this versus `pricing`, `consulta_planos`, `billing` or `my_account`, all of which plausibly overlap. The description is entirely about what comes back and how billing works, leaving the agent to infer the selection criteria from the sibling list alone.

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 safety is covered. The description adds two facts not in the annotations — a 200-item cap and that the call is free — which is useful context. It still omits ordering, what happens when more than 200 tenders are saved, and the returned shape.

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

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

A single front-loaded sentence with no filler; the cap and cost note are packed into the same clause. Every element 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 parameterless, read-only list tool with no output schema, the description covers what is returned (saved tenders), whose they are (the owner's), the maximum count (200), and the cost (free). Only ordering and truncation behavior remain unstated, which is a minor gap 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 takes zero parameters, so the baseline is 4. With an empty schema there is no parameter meaning for the description to add or omit, and nothing is misrepresented.

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 ('Lists ... tenders saved by the owner') and scopes the result set to the owner's saved items, which separates it from search_tenders and open_tenders_in_field. It does not name a sibling explicitly, but the 'saved' resource is unambiguous against the surrounding tool set.

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 mention of when to prefer it over search_tenders, and no stated prerequisites such as needing saved items to exist. The word 'free' hints at cost behavior but says nothing about when this call is the right choice.

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

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

Annotations already establish readOnly, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description adds genuine context beyond that: it discloses the shape of the returned data (change events with before/after and timestamps plus a current snapshot) and an auth prerequisite (the edm_… token).

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 what the tool returns before the auth note. Almost no waste; the parenthetical efficiently conveys the event structure.

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 describing returns, and it does so reasonably by describing the change-event shape and the snapshot. Combined with full schema coverage and complete annotations, an agent has enough to call it correctly; only pagination/result-size behavior is unaddressed.

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

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

Schema description coverage is 100%, so both the required 'id' and the 'limite' range are already documented in the schema. The description adds no parameter-level detail (no mention of id semantics or the 1-100 limit), 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?

States a specific verb (list) and resource (events of a watched procurement), and disambiguates the resource by unpacking what an 'event' actually is: what changed, from what to what, and when, plus the current snapshot. It is clearly distinguishable from watch_procurement, 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?

Usage is only implied: the mention of 'a watched procurement' signals it is meant to be called after watch_procurement, but there is no explicit when-to-use, when-not, or alternative routing (e.g. vs list_alert_matches or get_procurement). Adequate but leaves selection to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the return shape { ok, results }, but does not explain result fields, error behavior, or pagination details.

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

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

The description is two sentences with no wasted text, front-loading what the tool searches before giving the return shape. The return note is useful because there is no output schema.

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

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

For a simple read-only lookup tool with full schema descriptions and rich annotations, the description is mostly complete. It states the resource domain and return envelope, though it omits sibling routing guidance.

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

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

Schema description coverage is 100%, so the parameter meanings are already documented in the input schema. The description adds little beyond naming reference categories, and does not clarify the relationship between q and codigos beyond what the schema 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?

The description states a specific verb and resource: search Radar CNPJ reference data such as municipality names and activities. It is clear enough to understand the tool's function, though it does not distinguish it from sibling tools like list_cnaes.

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 guidance on when to use this tool versus alternatives such as list_cnaes or consulta_cnpj. The description implies lookup usage but does not state exclusions or prerequisites.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the account is derived from the session cookie in the MCP request rather than an input identifier, and it clarifies that the account is global with no per-product activation. It still says nothing about what the counters/identity actually contain or their freshness.

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 with no padding; the core identification of the resource comes first. The second sentence is arguably tangential framing, but it is short and pre-empts a plausible agent question about product activation.

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 comes back, and it only gestures at 'identity and private counters' without naming the fields or shape. For a zero-required-parameter read tool the gap is moderate, not fatal, but an agent cannot anticipate the response.

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 single optional 'locais' parameter (comma-separated document IDs, 90 max, 1529 chars) is fully documented in the schema. The description mentions no parameters at all, adding nothing about the filter's role or how results change when it is supplied, which is the baseline-3 case.

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 ('the identity and the private counters of the account session') but uses a noun phrase rather than a clear verb+resource statement, and never says outright that the tool retrieves/returns that data. It also does not distinguish itself from nearby siblings such as account_tracking or my_documents, so an agent must 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?

There is no statement of when to call this tool, what prerequisites exist, or which sibling to prefer for related account data. The only guidance-like sentence ('there is no activation per product') addresses a domain concept rather than tool selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description usefully adds the auth requirement (session cookie plus browser CSRF), which annotations do not express. However, it says nothing about pagination behavior or result shape despite the presence of a cursor parameter.

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, front-loaded sentences with no filler. The resource scope comes first and the auth constraint second, which is a sensible ordering, though the brevity contributes to the thinness noted in other dimensions.

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, single-parameter listing tool with annotations carrying the safety profile and no output schema, the description covers the essential auth requirement but omits what the collection actually contains and how paging works. Adequate but with clear gaps an agent would have to discover empirically.

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 single 'antes' cursor parameter is already fully documented in the schema as an exclusive hex cursor. The description adds no additional meaning about the cursor or pagination semantics, 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 identifies a specific resource ('the private collection of the account') with a scoping adjective ('private'), but supplies no verb and never clarifies it is a listing/retrieval operation. It does not distinguish itself from siblings such as list_document_files, company_documents, or get_document, leaving the agent to infer the relationship from names 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?

The only guidance is an authentication prerequisite ('Requires the account session (cookie and the browser CSRF)'), which is a how-to-call note, not a when-to-use note. There is no statement of when this tool is preferred over list_document_files, company_documents, or get_document, and no exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely non-obvious context beyond that: the call is account-private and requires a session cookie plus a browser CSRF token. It omits any note on pagination behavior, which keeps it short of 5.

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

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

Two short sentences with zero filler; the scope statement comes first and the access requirement second. Nothing is redundant with the title or annotations, and both sentences carry 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 should at least indicate what a call returns (a collection of the account's procurements) and how the cursor pages through it. It covers scope and auth but leaves the return shape and pagination flow to inference, which is thin for a list 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 coverage is 100%, so the single cursor parameter ("antes", hex, exclusive cursor of the client) is already fully documented in the schema, setting the baseline at 3. The description adds no syntax, ordering, or pagination semantics beyond what the schema says.

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