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 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/non-destructive, and the description adds real value beyond them: it accepts POST/PUT/PATCH with the same parameters in JSON or form, and every 400 response carries `exemplo` and `doc`. That is meaningful behavioral context an agent can act on.

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 long opening sentence front-loads what the tool returns, followed by the search mechanism, the method/alias behavior, and the error shape. It is dense but every sentence carries information, with only mild redundancy in the extended first 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?

With 8 parameters, no output schema, and safety already covered by annotations, the description compensates well by describing the return payload (median, range, volume, value, groups) and the group-switching mechanism. It stops short of explaining limits or pagination behavior, but nothing critical is missing to invoke 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 coverage is 100% so the baseline is 3, but the description goes further by documenting parameter aliases (`query`/`termo`/`busca`/`search`→`q`, `estado`→`uf`, `limit`→`limite`) and clarifying that `quantidade` is the quantity you will sell. This meaning is not present in the schema.

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

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

The description states a specific verb (searches awarded results by item description) and enumerates the response content in detail: result count, median, p25/p75 range, volume bought, and value for quantity. An agent can distinguish this from siblings like search_tenders or who_supplies, though it never explicitly names a sibling.

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 'free summary' framing and the note that other groups can be switched by asking for product+unit hint at when to use it, but there is no explicit when-to-use/when-not guidance or named alternative for a competing tool.

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

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

The 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 the description adds substantially more: a hard cap of 20 addresses and 20 companies, the total-address field name (pontos_total), a 10-lookups-per-day-per-network quota, and the specific free_limit/resets_at error payload. That is rich operational context beyond the 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?

Three sentences, each earning its place: purpose/returns, then truncation caps, then quota/error behavior. The most decision-relevant information (what you get back) is front-loaded with zero filler.

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

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

For a single-parameter read-only lookup with no output schema, the description covers return shape, truncation, and quota behavior, which is most of what an agent needs. It stops short of describing the address record fields or how to route to sibling lookup 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?

There is a single parameter with 100% schema description coverage, so the schema already carries the meaning and a 3 is the baseline. The description only restates 'CEP (Brazilian postal code)' without adding format, normalization, or validation guidance 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?

It states a specific resource and return: addresses at a CEP with CNEFE/IBGE coordinates plus the companies registered there. The lookup verb is implicit rather than explicit, and it never names the closely related siblings (consulta_endereco, consulta_cnpj), so an agent gets a clear purpose but no sibling differentiation.

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

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

The description explains what comes back but never says when to reach for this tool versus consulta_endereco or consulta_cnpj, nor any precondition such as requiring a valid 8-digit CEP. The only implicit guidance is that it returns both addresses and companies, which hints at scope without stating it.

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

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

Beyond the annotations (readOnly/openWorld/idempotent/non-destructive), the description discloses real behavioral traits: 10 free lookups per day per network, the failure shape (`free_limit` with `resets_at`), that checks are live and the registry data is updated daily, that personal data comes back masked, and that omitting `temas` returns the full record while null blocks mean unchecked.

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

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

The purpose is front-loaded, but the body devolves into a single enormous sentence cataloguing every data source, which is hard to scan. The operationally critical facts — free-limit behavior and alphanumeric CNPJ support — are buried at the very end rather than surfaced, so length is not fully earning 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?

With no output schema, the description carries the return-value burden itself and does so thoroughly, enumerating the blocks available under `temas` and their provenance. Combined with the rate-limit, masking and freshness disclosures, an agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is already 100%, so the baseline is 3, but the description adds genuine meaning: it states the tool accepts both the numeric and the alphanumeric CNPJ format (the schema only mentions punctuation), clarifies that basic company data always stays regardless of `temas`, and explains the omit-vs-null semantics of the topic selector.

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

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

The first sentence states a specific verb and resource: fetch a Brazilian company record by CNPJ from the Receita Federal, with an unusually precise inventory of the attached blocks (sanctions, PEP, tax, labor/environmental risk, contracts, regulators). That is far more specific than a sibling like search_companies or consulta_cadastro, but the description never explicitly distinguishes itself from the several other CNPJ-oriented tools in the sibling list (consulta_cadastro, evaluation_basic/premium, add_company), leaving that routing 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?

Usage is only implied: 'useful to vet suppliers' and the note that `sancoes` reflects registry data against the CNPJ root. There is no explicit when-to-use statement, no when-not, and no named alternative such as consulta_cadastro or evaluation_basic for the cases where a lighter lookup or a credit evaluation is what the agent actually wants.

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 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?

Annotations establish a non-readonly, non-destructive, non-idempotent, open-world write. The description adds real behavioral context beyond that: the cron runs every 30 minutes, delivery is pull/webhook/email, email needs an account session and EMAIL_ALERTAS=1, and recipients fall back to the verified account email. This is meaningful operational detail the annotations do not provide.

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

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

Front-loads the core purpose but is dense with untranslated jargon (UF, cnpj, max_familias, termos) and references a mode ('by cnpj', max_familias) that the schema does not expose, which reads as noise or confusion rather than earning 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 an 8-parameter write tool with nested objects and no output schema, the description covers authentication, channels, timing, mode semantics and recipient behavior adequately. The lingering gaps are routing versus siblings and the unexplained cnpj/max_familias reference.

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 uf, nome, canal, termos, destino, filtros and destinatarios. The description largely restates this ('a space requires all groups; | accepts alternatives'), and its mention of `max_familias`/cnpj mode corresponds to no visible schema parameter. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb+resource: creates an alert for new procurements, scoped by object terms and state (UF). It even enumerates delivery channels and two operational modes. However, describing a 'by cnpj' mode overlaps with the sibling create_alerts_by_cnpj without distinguishing when to use which, so it does not cleanly separate itself from siblings.

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

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

Gives context on authentication ('use the account session or guest token') and the extra requirement for email ('EMAIL_ALERTAS=1'), which is useful. But it never states when to prefer this tool over create_alerts_by_cnpj, preview_alert, or update_alert, leaving the routing decision 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 it as a mutating, non-idempotent, open-world write. The description adds real context beyond that: the required `edm_…` token, a 30-minute cron cadence, and the EMAIL_ALERTAS=1 / account-session requirement plus recipient fallback for email delivery. It omits rate limits and what the response body contains, keeping it 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?

The prose is dense and jargon-heavy, and the 'Two modes' section references a `termos` mode that has no corresponding parameter, which is confusing rather than useful. Much of the content earns its place, but it is not cleanly front-loaded or trimmed.

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 mutation tool with nested objects and no output schema, the description covers auth, scheduling, email delivery prerequisites and the family/null-family return behavior adequately. It lacks any note on the response shape or error cases but is otherwise complete against what annotations and schema already provide.

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 carries the parameter burden and the baseline is 3. The description reinforces a few semantics (family priority 'main first', the `max_familias` cap, unmapped CNAEs returning a null family), but adds little detail about `filtros`, `destinatarios` or `organizacao_id` beyond what the schema already states.

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 (alerts for new procurements) and scope (by company CNPJ) and explains the family mechanism that generates one alert per CNAE family. It is clear about what it produces, but never uses an explicit creation verb and does not distinguish itself from the sibling `create_alert`, leaving the agent to infer the difference.

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

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

No when-to-use / when-not-to-use guidance is given, and no alternative sibling (`create_alert`, `preview_alert`) is named. The 'Two modes' passage contrasts `termos` and `cnpj`, but `termos` is not even a parameter in this schema, so it does not function as actionable usage direction.

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

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

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?

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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds one meaningful behavioral fact: it does not start processing, clarifying that a 'generation' call here is purely observational rather than triggering work. It says nothing further about polling behavior or state transitions.

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, so it is appropriately sized. However, the wording is muddled ('follows the real phases and the completion') and not cleanly front-loaded, so brevity does not translate into clarity.

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

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

The tool is a status/read operation with no output schema, so the description should clarify what status information is returned and what the phases mean. It gestures at 'phases' and 'completion' but never defines them, leaving the agent unable to interpret 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 description coverage is 100% with all four parameters (id, agent_pass, acesso_codigo, avaliacao_codigo) documented in the schema itself. The description adds no parameter-level 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 says it 'follows the real phases and the completion,' which hints at status polling but never states a specific verb+resource (e.g., 'retrieve the generation status of a document by ID'). The phrasing is vague and reads like a translation, so an agent cannot cleanly distinguish it from the sibling '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?

'free, without starting processing' implicitly signals this is a safe polling call that does not trigger generation, which is a useful usage cue. However, there is no explicit when-to-use guidance, no prerequisites, and no mention of the alternative tools (e.g., original_status) an agent would pick between.

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?

The annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior. Beyond that, the description adds operational constraints: credential reuse from reading, no AI start, no new analysis on read, partial data indicating coverage, and export requiring a finished version.

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 front-loaded with the dossier contents and then follows with operational notes. The sentences are compact, though the repeated emphasis on 'does not start AI' and 'no new analysis' is slightly redundant.

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 dossier tool with full schema parameter coverage and no output schema, the description covers the main return categories, access credential, AI behavior, partial-coverage signal, and export condition. It omits pagination behavior and exact response shape, but those are minor relative to 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 description coverage is 100%, so the schema already documents all eight parameters. The description adds only minor semantic context by linking acesso_codigo to reading access, which is useful but not compensating for any schema gap.

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

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

The description identifies the resource as a dossier and lists its contents: items, requirements, attestations, deadlines, obligations, conditions, exceptions, and excerpts/pages. It distinguishes the operation from AI analysis, though it does not explicitly state a retrieval verb, so an agent must infer 'get' 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?

It gives useful context that the dossier is included in document access, does not start AI, and requires the same acesso_codigo as reading. However, it does not explicitly say when to use this tool versus siblings such as get_document, get_deadlines, or get_reading_manifest, leaving comparison 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 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?

Annotations already declare the safety profile, and the description adds useful context: the lookup 'does not start another analysis' (no costly side computation) and it does not report the company's own status. However, the 'lookup' framing sits uneasily against readOnlyHint=false, and the description never explains why this read-flavored call is flagged as non-read-only. This tension weakens the behavioral disclosure.

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 the tool's purpose and what it returns, with minimal waste. There is mild redundancy in restating that 'this list covers qualification' after already naming it the qualification list.

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, yet the description explains the shape of the return (excerpts with conditions, exceptions and evidence by page) and the scope boundaries. For a read/lookup tool this is nearly complete; only the readOnlyHint=false tension leaves a small unanswered question.

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 the id source (get_procurement) and the credential parameters in detail. The description adds nothing about any parameter. A baseline 3 is correct when the schema carries the full burden.

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 tender's qualification list) and specifies its content — literal excerpts of conditions, exceptions and evidence by page. It also distinguishes itself from the dossier, so an agent can separate it from neighboring document tools, though the verb is implied rather than stated.

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

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

It clearly routes the agent: deadlines, proposals and other obligations live in the dossier, while this tool covers qualification and required attestations, and it explicitly notes it 'does not state what the company has.' That is clear scope guidance with no exclusions beyond the dossier reference.

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, closed-world), yet the description adds real operational context: it does not trigger OCR, the same authorization also unlocks the ZIP and images via the API, only ready resources are returned, and document_approved: false does not block reading. That is meaningful behavior beyond the 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?

It is short and front-loads the returned payload, which is good. But several fragments ('Only ready resources.', 'It does not start OCR.') read as notes rather than a coherent flow, making it feel choppy rather than tightly structured.

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 full schema coverage on four parameters, the description still sketches the return contents (pages, images, SHA-256, version), the credential semantics, and the readiness/approval gating. It is nearly complete for an agent to call it correctly, with only return shape details left implicit.

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

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

Schema description coverage is 100%, so the schema already documents id, agent_pass, acesso_codigo and avaliacao_codigo. The description only reinforces acesso_codigo ('the examples are free') and does not add syntax, format, or interaction detail 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 identifies the resource and its payload ('The document manifest: pages, images, SHA-256 and version'), so an agent knows what data comes back. However, it never states an explicit verb (retrieve/fetch) and does not differentiate itself from close siblings like get_document or list_document_files, leaving overlap unresolved.

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 does not start OCR' and 'Only ready resources' imply when this tool applies and when it does not, and 'Send acesso_codigo; the examples are free' gives an invocation precondition. But no alternative tool is ever named for the OCR or non-ready cases, so the agent must infer the routing itself.

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 useful access-control context: two alternative credential paths (acesso_codigo vs avaliacao_codigo + agent_pass) and a free-example quota. However, it omits pagination, response format, and what happens on missing/failing credentials.

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?

Single sentence that front-loads the read action but crams two authorization modes and a quota note into one clause, making it dense and slightly hard to parse. No filler, but the access-path enumeration would be clearer as separate 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?

With 4 parameters and no output schema, the schema carries parameter definitions, and the description covers the access-code branch logic reasonably. But it lacks return-value expectations, error behavior, and routing vs. sibling document tools, leaving moderate gaps for a tool with this credential complexity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining the two distinct authorization paths and their required parameter pairings (acesso_codigo alone vs avaliacao_codigo plus agent_pass), which complements the schema rather than repeating it. It stops short of fully disambiguating the mandatory 'id' from get_procurement semantics.

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

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

States a specific verb (Reads) and resource (Markdown with the document of given id), so the core action is clear. It is somewhat distinguishable from siblings like get_document or get_document_dossier, though it does not explicitly name how it differs from those. The access-code mechanics add specificity but blur the primary purpose slightly.

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

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

No explicit when-to-use guidance, no mention of alternatives (get_document, get_document_dossier, list_document_files), and no prerequisites stated beyond access codes. The 'Five examples are free' hint offers quota context but not selection guidance. The agent must infer when this is the right tool over the sibling document tools.

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

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

Annotations already declare readOnlyHint, 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, destructiveHint=false and closed-world behavior, so safety is covered. The description adds modest value by saying the result includes download links and pages, but it says nothing about the credential model implied by agent_pass/acesso_codigo, nor about throttling or access restrictions (a public receipt granting no access).

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 description and followed by the alternative path. No filler, though the endpoint reference is arguably less actionable for a tool-selecting agent.

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 characterize the return value; 'download links and pages' is only partially informative and mentions no pagination or ordering. The complex access model (agent credential plus document-specific codes) is left entirely to the schema, so the definition is adequate but not fully complete for this tool.

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

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

Schema description coverage is 100%, so all four parameters are already explained in the schema and the baseline is 3. The description adds no parameter-level detail beyond what the schema provides, such as how id relates to get_procurement output or how the access codes interact.

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 ('the catalog of the original files of the document') and enumerates its contents ('download links and pages'), so an agent can tell this is a file-listing tool. It gives no explicit verb and does not differentiate itself from close siblings such as get_document, request_original, or 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?

It points to an alternative path ('Use /api/documento/{id}/original to download the full original'), but that is a raw API endpoint rather than a sibling tool, and it never says when to pick this tool over get_document or request_original. Usage is only implied.

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

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

Annotations fully cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=false), so the bar is low. The description adds the fact that it returns exactly five 'real free proofs' with specific formats, which is useful behavioral context, but it doesn't explain whether the list is static, paginated, or filtered.

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

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

A single, front-loaded sentence that efficiently communicates the action and output. No wasted words, though it could be slightly more specific without becoming verbose.

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

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

For a zero-parameter, read-only tool with no output schema, the description is adequate but missing key context: what these examples are examples of, whether they change over time, and how they relate to sibling document tools. An agent can call it but may misinterpret the output domain.

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 are zero parameters, so per the rubric this is a baseline 4. The description correctly implies no parameters 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?

The description states the tool lists five real free proofs (Markdown, PDF, ZIP), giving a concrete verb and resource. However, the name 'list_examples' and title 'Examples' don't clarify what domain these examples belong to, and the description doesn't distinguish this tool from siblings like get_tender_markdown or list_document_files.

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 'before you generate another document' implies the tool is meant for previewing examples prior to generation, which is a clear timing cue. But there is no explicit statement of when-to-use versus alternatives, and no mention of 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, 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 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, idempotentHint, openWorldHint=false, and destructiveHint=false, covering the safety profile. The description adds a real semantic caveat ('Returned numeric codes belong to Receita, not IBGE'), which is useful domain context, but it says nothing about result shape, ordering, or pagination behavior.

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

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

Three short sentences, front-loaded with what is looked up, with no redundancy. The caveat sentence is well-placed but the middle usage sentence is somewhat loosely attached to the rest.

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, yet a read-only lookup with fully described parameters needs little more; the description conveys the domain meaning of returned codes, which compensates for the missing output schema. The only real gap is sibling disambiguation.

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 q, tipo, limit, and codigos, giving a baseline of 3. The description adds no syntax or format detail beyond the schema and only obliquely touches semantics via the Receita/IBGE code note.

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 ('Find') and concrete resources (city names, state codes, activities, and other Radar CNPJ references), so an agent knows it's a reference/lookup tool. It does not differentiate itself from the sibling list_cnaes, which appears to cover the CNAE case, leaving slight ambiguity about which tool to pick.

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

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

Gives one actionable usage rule ('For tender filters, use the city name and state'), which is genuinely helpful context. However, it never states when to prefer this over overlapping siblings like list_cnaes or the consulta_* family, so routing guidance is only implied.

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

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

Annotations already 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.

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

"The private collection of the account" implies a read of the caller's own data but never names the resource (procurements) that the tool returns, so it leans on the tool title rather than stating a verb+resource. It also does not distinguish itself from closely related siblings like get_procurement, list_saved, or my_documents, so an agent must guess how this differs.

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, when-not-to-use, or alternative guidance anywhere in the description. The stated session/CSRF requirement is a precondition, not a usage directive, and nothing tells the agent when to pick my_procurements over get_procurement or list_saved.

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 readOnly, idempotent, non-destructive, but the description adds significant behavioral context: caching for 30 minutes, error handling when the service is busy (estado indicates and itens empty), free cost, and the relationship to alert creation. This is beyond what annotations provide.

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

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

The description is dense and front-loaded with essential information, but it is lengthy and includes tangential details like the alert preview endpoint and alert body. Every sentence has some value but could be tightened.

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

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

Given the complexity (caching, error handling, alert relationship) and lack of output schema, the description provides substantial context. It covers return behavior (estado, itens) and intended use. It doesn't explain the full return shape, but that's acceptable without an 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% for the single 'id' parameter, and the description doesn't add meaning beyond what the schema provides. The description mentions that without a CNAE it uses object terms, but that's about the tool's internal behavior rather than parameter semantics. 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 clearly states the verb+resource+scope: 'tenders with an open proposal period published in the last 7 days' in the same field/state as a given procurement. It is distinctly different from siblings like search_tenders or preview_alert, though the core action is implicit ('the tenders...') rather than a direct verb.

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

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

Explicitly gives when to use it ('Useful when the procurement you looked up is already closed'), and names related tools (create_alert, preview_alert). It doesn't state when NOT to use it, but the context is clear.

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

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 behavioral context: it is free, the response is no-store, and it explicitly does not deliver content, grant access, confirm pages, or start a generation. This goes beyond what the structured fields provide.

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

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

Front-loaded with the core action, but the two negative sentences overlap heavily ('does not ask for a download or a generation' vs 'does not... start a generation'), creating redundancy rather than added information.

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

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

For a simple, fully-documented, single-param read tool this is mostly sufficient, but with no output schema the description should hint at the shape of the returned status rather than only enumerating what it does not return.

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

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

There is a single 'id' parameter with 100% schema coverage, and the schema already documents it as a Document ID from get_procurement. The description adds nothing about the parameter, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Reads the status of the original') and distinguishes itself from the download/generation siblings. 'Original' alone is slightly ambiguous, but the title and the 'does not ask for a download or a generation' clause pin down the resource.

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?

Offers exclusionary guidance ('does not ask for a download or a generation'), implicitly routing agents away from request_original and generation_status, and notes it is 'free' so polling is cheap. However there is no explicit 'use this when...' statement, so selection relies on 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?

The description adds real behavioral context beyond the annotations: the call is 'free' and 'does not create alerts', and it has two distinct modes. However, annotations declare readOnlyHint=false, which sits in mild tension with a preview that creates nothing; the description never reconciles this (e.g., whether the call consumes quota). No rate/limit behavior is disclosed.

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 with zero filler; the primary behavior (what it returns) is front-loaded and the negative constraint ('does not create alerts') is placed last for emphasis. Every sentence earns its place.

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

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

For a 4-parameter tool with a nested filters object and no output schema, the description covers the two modes and the non-mutating nature but omits how large a 'sample' is, how the uf/termos/filtros and cnpj paths interact (mutually exclusive or combined), and whether results are limited or paginated. Adequate but with clear gaps.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does add a useful mapping by splitting behavior into two parameter-driven modes (termos/filtros vs. cnpj) and noting CNPJ suggestions are not 'turned on', but it does not add syntax or interaction detail beyond what the schema already documents.

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 operation and its two modes ('free sample of procurements by terms and filters, or editable suggestions by CNPJ') and clarifies what it is not ('does not create alerts'), which implicitly distinguishes it from create_alert. It is clear but never names the sibling it complements, so an agent must infer the create_alert relationship.

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 'free sample' and 'does not create alerts' phrasing suggests a dry-run before persisting via create_alert, but no explicit when-to-use or when-not-to-use guidance is given. There is no routing statement pointing to create_alert/update_alert for the actual write.

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, closed-world). The description adds genuinely non-obvious behavior: the call is free, only the current version of each plan is returned, and omitting `ano` defaults to the current year onward. It does not describe pagination limits or result caps, so 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?

The purpose and returned fields are front-loaded, and each subsequent clause (free, current-version-only, default year, alert alternative, HTML accept) carries distinct information. It is dense but not padded; a slight cost is that several distinct ideas are packed into a single run-on sentence.

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 listing the returned fields, and it covers scope (pre-tender phase), freshness limits, default filtering, cost, and the sibling route for alerts. An agent has everything needed to select and invoke it correctly.

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

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

Schema coverage is 100%, so all three parameters (q, ano, pagina) are already documented in the schema. The description's note about the `ano` default largely restates the schema text, adding little new meaning, so the baseline 3 applies.

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

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

The description states a specific resource (annual procurement plans / PCA published on PNCP) and pins the exact lifecycle phase — 'before the tender opens' — which separates it from search_tenders and get_procurement. It even enumerates the returned fields (item, agency, quantity, estimated value, desired date), so an agent knows precisely what this tool yields.

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 context (use for planning data before a tender exists) and routes the agent to create_alert when the goal is knowing when the tender opens, plus an Accept: text/html tip for the UI tab. What's missing is an explicit when-not / direct contrast against the tender-search siblings, so it falls short of a 5.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds real value beyond that: the removal is non-cascading (organization and PDFs stay) and reversible (re-adding the CNPJ restores it), which is exactly the blast-radius detail an agent needs before a destructive call. No contradiction with the idempotent hint.

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

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

One sentence, front-loaded with the action, and every clause earns its place by conveying scope, permission, and reversibility. No filler or restatement of the 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?

For a single-parameter mutation with no output schema, the description covers reversibility, non-cascading scope, and the auth requirement. What remains unstated (return shape, whether confirmation is required) is minor given the full annotation coverage.

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

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

Schema description coverage is 100% for the single cnpj parameter, including the 14-digit check-digit format, so the schema does the heavy lifting. The description only implies the CNPJ is the re-add identity key without adding syntax or validation detail, matching the baseline 3.

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

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

States a specific verb and resource ('Removes the company from the list') and scopes it against the org and PDFs, which implicitly separates it from sibling remove_company_document and remove_saved. It stops short of naming the alternative tools, so the agent must infer the distinction from the noun '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?

The parenthetical '(owner or admin)' supplies a real permission prerequisite, which is genuine usage guidance. However, it never states when to choose this over remove_company_document, remove_saved, or list_my_companies, so routing is only implied by the resource 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?

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new behavioral context beyond that: deleting a document invalidates analyses that consumed it, which is a downstream consequence an agent could not derive from 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?

A single front-loaded sentence naming the action first, then the side effect. No filler, no redundancy.

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

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

For a 2-parameter mutation with full schema coverage and annotations covering safety, the description is adequate. It omits whether deletion is permanent or recoverable, and what happens when the referenced document does not exist, which would matter for a destructive operation.

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

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

Schema description coverage is 100%, with both cnpj (14-character identifier) and arquivo (SHA-256 of the private PDF) fully documented in the schema. The description adds no additional parameter meaning, 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 ('Removes a proof from your own company'), and the scoping phrase 'your own company' separates it from remove_company and remove_saved. It does not name a sibling explicitly, but the resource is unambiguous.

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

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

Usage is only implied: an agent can infer this is the tool for deleting an attached document. The clause about dependent analyses going stale gives useful decision context, but there is no explicit when-to-use rule or comparison against alternatives like attach_company_document or company_documents.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely useful scope: the destruction is limited to the owner's personal saved list and does not affect watches or notifications, which prevents the agent from over-estimating the blast radius of a destructive call.

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

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

Three short sentences, front-loaded with the action and scope. The final clause ('the snapshot comes from the collection') is cryptic and slightly dilutes an otherwise efficient description, but nothing is padded.

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

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

For a single-parameter destructive tool with no output schema, the description covers scope, side-effect boundaries, and idempotency context. It omits error behavior (e.g., removing an ID not in the saved list) and whether the removal is permanent, but these are minor against what annotations already convey.

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

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

With one parameter at 100% schema description coverage, the schema already documents 'id' as the procurement identifier. The sentence 'The client sends only the ID' reinforces but does not extend that meaning, and the trailing clause about the snapshot coming from the collection is too vague to add usable parameter detail. Baseline 3 applies.

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

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

The description states a specific verb and resource ('Removes the procurement from the personal list of the owner') and scopes it to the owner's personal list, which separates it from broader destructive siblings like remove_company or remove_company_document. It also implicitly distinguishes itself from watch_procurement by noting that saving does not create a watch or notification, though it never names the sibling directly.

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 note that saving does not create a watch or notification hints that watch_procurement is the tool for alerts, but there is no explicit 'use this when / not when' guidance or named alternative. The agent must infer the boundary from the sibling list.

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

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

Adds real context beyond annotations: the operation is 'Free', it does not trigger OCR, the request body is empty (two bytes at most), and the state machine outcome differs by collector availability (immediate download vs. queued, status becomes 'downloading'). The idempotent and cost claims are consistent with the idempotentHint annotation and the mutating/queueing behavior is consistent with readOnlyHint=false; no contradiction.

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

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

Front-loads the core action and stays within a few sentences, with each clause carrying information about trigger, cost, or state outcome. The parenthetical '(two bytes at most)' is slightly pedantic but not wasteful enough to hurt.

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

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

With no output schema and a one-parameter input, the description covers what is needed to call it correctly: the trigger, the empty body, the cost, and the resulting status. It could be more complete by telling the agent how to observe the resulting 'downloading' status, but the essentials are 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 description coverage is 100% and the single required 'id' parameter is already documented as coming from get_procurement. The description adds no further parameter 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?

States a specific verb and resource: 'downloads the pending original from PNCP now', and explicitly excludes a related action ('It does not start OCR'). This lets an agent separate it from OCR-triggering or document-retrieval siblings, though it never names those siblings directly, so differentiation is implicit rather than explicit.

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

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

Gives a clear triggering condition: 'Use it when the person opens the document' and 'When the person wants the document'. It does not, however, name alternatives such as original_status for checking progress or get_document for already-fetched content, so the when-not side is absent.

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

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

Goes well beyond the annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false) by disclosing the 24 h dual-signing grace period and the exact header shape the receiver must tolerate. This is precisely the behavioral context an agent needs to avoid breaking a consumer, and it also clarifies that the mutation is non-destructive in practice.

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 mutation, then the credential requirement, then the grace-period mechanics and receiver contract. Four sentences, each carrying distinct, load-bearing information with no padding.

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

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

With no parameters and no output schema, the description covers everything an agent needs: what changes, what auth is required, what happens during the transition, and how the receiver should handle it. Nothing material 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?

There are zero input parameters, so the baseline is 4. The description's mention of the required edm_… token adds auth context that the empty schema cannot express.

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 ('Changes the secret that signs the webhooks') with unambiguous scope. No sibling tool overlaps with webhook secret rotation, and the agent can tell immediately what this does.

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

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

Names the prerequisite credential (the edm_… token) and explains the operational context in which rotating is safe ('you can change it without a failure window'). It does not discuss when-not-to-rotate or alternatives, but there are no plausible alternatives among the 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=false, idempotentHint=true, and destructiveHint=true, so the description is not carrying the safety profile alone. It usefully adds disclosure beyond the annotations: a per-owner cap of 200, the explicit absence of watch/notification side effects, and where the snapshot comes from. It does not explain why a save operation is flagged destructiveHint=true, which is the notable remaining 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?

Three short sentences, front-loaded with the core action, then limit, then side-effect clarification, then payload semantics. Every sentence carries distinct information with no redundancy or filler.

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

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

For a one-parameter save tool with full annotation coverage and no output schema, the description covers purpose, side effects, quota, and payload handling. The only unresolved item is the meaning of destructiveHint=true on a save operation, which an agent might reasonably want clarified.

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

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

Schema description coverage is 100% for the single id parameter, so the baseline is 3. The description adds genuine meaning beyond the schema: 'The client sends only the ID; the snapshot comes from the collection' tells the agent it need not construct or pass a snapshot payload, which the schema field description does not convey.

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 ('Saves the procurement') and immediately differentiates from the closest sibling by noting that saving 'does not create a watch or a notification', implicitly routing to watch_procurement. An agent can distinguish this from watch_procurement and remove_saved 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?

The clause 'Saving does not create a watch or a notification' gives a clear when-not signal that separates this from watch_procurement, and the 'up to 200 per owner' cap implies a collection-scoped use case. No explicit alternative is named and there is no positive 'use this when' statement, so it falls short of a full 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 usefully adds the auth requirement (account or guest), which annotations do not convey, but says nothing about result volume, scoring, or pagination.

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

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

One compact sentence with the action front-loaded and no filler. It is efficient, though the trailing auth clause is tacked on rather than structured as separate guidance.

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

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

For a single-parameter read tool with full schema coverage and rich annotations, the essentials are present. With no output schema, however, the description should say something about what a search returns (matching behaviour, result list shape), which is omitted.

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

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

Schema description coverage is 100% and the single parameter already documents "Full CNPJ or a name of 3 to 120 characters." The description only restates the accepted input types, adding no format or matching-behaviour detail beyond the schema.

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

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

States a specific verb ("Searches") and resource ("the company registry") plus the two search keys, so the agent knows exactly what the tool does. It does not, however, distinguish itself from near-neighbours such as consulta_cnpj or list_my_companies, which also surface company data.

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

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

The only guidance is an access prerequisite ("requires an account or a guest"). There is no when-to-use/when-not framing and no mention of the obvious alternatives (list_my_companies for saved companies, consulta_cnpj for raw registry lookups), leaving routing to inference.

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

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

Annotations already declare the full safety profile (readOnly, idempotent, non-destructive, closed-world), so the description only needs to add behavioral context. It contributes 'Free' and enumerates the returned fields, but says nothing about pagination, result caps, or how the complex 'filtros' param changes behavior.

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

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

Three short sentences with the core purpose front-loaded and no filler. It is efficient, though the return-value sentence is the only element earning much beyond the first 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?

Because there is no output schema, naming the returned fields (object, agency, UF, modality, id) is genuinely useful. However, for a 5-parameter search tool whose 'filtros' param is a 2048-char JSON DSL, the description offers no extra operational guidance, leaving it only minimally complete.

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

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

Schema description coverage is 100%, so every parameter including the intricate 'filtros' JSON is fully documented in the schema; baseline is 3. The description adds no parameter meaning beyond what the schema provides.

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

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

States a specific verb and resource ('Searches public procurements by term'), which separates it from the many company/document siblings. It does not, however, distinguish it from adjacent tools like get_procurement, open_tenders_in_field, or framework_agreements, so an agent must still 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 use this tool versus alternatives such as get_procurement (fetch a known procurement) or open_tenders_in_field. 'Free' hints at a cost dimension but is not usage guidance, and no prerequisites or exclusions 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?

Annotations declare idempotentHint=true and destructiveHint=true; the description reinforces idempotency ('Repeating the current choice writes nothing') and adds a trait the annotations do not cover — the choice is per-person ('Each person's choice is kept in the account'). It does not explain the destructiveHint or what side effects occur on first selection.

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, zero waste, front-loaded with what the tool does before the idempotency caveat. Every clause earns its place.

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

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

For a one-parameter, no-output-schema tool with annotations present, the description covers purpose, the analysis exclusion, per-person scoping, and idempotency. The only omission is any hint about what the operation returns or what destructiveHint implies.

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 cnpj parameter is fully documented in the schema (14 digits, valid check digit). The description adds no syntax or format detail beyond that, so the baseline 3 is appropriate.

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

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

States a specific verb+resource ('Selects a registered company') and immediately scopes it against a neighbour ('it does not run an analysis'), which separates it from analyze_participation. It stops short of naming the sibling explicitly, so the differentiation is implied rather than crisp.

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 exclusion of analysis implies when this tool is the right pick, but there is no explicit when-to-use statement and no alternative named (add_company, remove_company, search_companies are all plausibly confusable). Usage is inferable but not spelled out.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is largely covered. The description's only added behavioral note (filters replace the whole filter) simply duplicates the schema's filtros description, and it says nothing about the partial-update nature, required permissions, or ownership constraints the schema touches on.

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 terse, front-loaded sentences with no filler; the replace-semantics warning is stated up front. It is efficient but arguably too sparse for a 10-parameter tool with two nested objects.

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 10-parameter partial-update tool with nested objects, no output schema and destructive semantics, the description is minimal, but the fully covered schema plus the destructive/idempotent annotations carry most of the burden. It is adequate but leaves the update-vs-create decision and destructive consequences to inference.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema already documents all ten parameters including nested filtros and destinatarios. The description adds no syntax, format, or default beyond the replace-whole-filter rule that is already in the schema, so it earns nothing extra.

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 ('Edits ... an alert of the owner') and clarifies the scope ('interest, or pauses or turns on again'). The siblings create_alert, preview_alert and list_alert_matches are never named, so an agent gets a clear purpose but no explicit sibling differentiation.

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

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

The phrase 'The filters replace the whole filter' hints at the PATCH-style update contract, but there is no statement of when to use update_alert instead of create_alert or preview_alert, and no stated prerequisites. Usage is only implied.

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

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

Annotations only flag it as a non-readonly, non-idempotent, open-world operation; the description goes well beyond that by disclosing the snapshot-on-creation behavior, the periodic polling model, and the once-only delivery of prazo_impugnacao and prazo_proposta notices. This is genuinely useful behavioral context for a stateful watch tool.

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

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

Front-loads the purpose and token requirement, then layers behavior and notice timing in two further sentences with no filler. Slightly dense but every clause carries information an agent needs to call it correctly.

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 stateful watch-creation tool with no output schema, the description covers what it creates, how often it runs, and what notices fire. The main omission is how the watch is later referenced (e.g. via list_watch_events), but functionally the agent has enough to invoke 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 coverage is 100%, so canal, destino and compra_id are already documented in the schema, including the enum values and the fact that destino is ignored for pull/email. The description adds no additional parameter meaning, 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 ('watches') plus resource ('a procurement') and enumerates exactly which changes it captures (correction, new document, suspension, postponed deadline and value, deadline notices). An agent understands the job immediately, though it does not explicitly differentiate itself from siblings like create_alert or create_alerts_by_cnpj.

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 the token prerequisite ('requires the token edm_…') and the operational note that checks are periodic with the last-check date available in the watch. However, it never says when to prefer this over create_alert or how it relates to list_watch_events, leaving the choice between watch tools 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 the description layers substantial extra behavior on top: the classifier source, the 3-2-1 positional scoring, the 99-item highest-value cap, the no-items fallback (top 5 without `itens`/`valor_estimado`), a measured accuracy figure (87%), and that it costs nothing. This is unusually rich behavioral disclosure.

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 claim is front-loaded in the first sentence, and most later detail is genuinely useful (edge cases, accuracy, cost). But the body is a single dense paragraph mixing algorithm internals, fallback behavior, and a measurement date, which is harder to parse than it needs to be.

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 return contract, and it does: it names the returned CNAEs, their official descriptions, per-CNAE item counts, and estimated-value share, and it explains the reduced shape when there are no items. It is nearly complete, though a clearer note on the single `id` argument's origin would close the last 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?

There is a single required `id` parameter at 100% schema coverage, so the schema already documents it fully. The description confirms it expects a procurement id but adds no syntax, format, or sourcing detail beyond that, so the baseline of 3 applies.

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

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

The opening sentence states a specific resource and result: the CNAEs that usually win procurements like this one, ranked most-likely-first with descriptions and value shares. This is clearly distinct from siblings like list_cnaes or get_procurement, though the description never names a sibling to reinforce the contrast. Purpose is unambiguous but not explicitly differentiated.

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 (pass a procurement id to see its likely winning activity codes) and notes it is 'Free', plus a downstream path (create an alert to track new procurements of these CNAEs). However, it gives no explicit when-to-use versus alternatives and no when-not guidance, so the routing burden 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.