kya-brasil

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

Annotations already establish readOnlyHint and idempotentHint, so safety is covered. The description adds genuinely new behavioral context beyond that: the call is free (notable given paid siblings exist) and it exposes where schemas and signing keys live, which tells the agent this is a discovery/documentation endpoint.

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

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

One sentence, front-loaded with the most decision-relevant token ('Free.') and then a tight list of covered topics. Every clause earns its place and 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 a parameterless informational tool with no output schema, the description adequately tells the agent what topics the response will address (product, flow, prices, schemas, keys). It could note the response format or whether the content is static documentation, but nothing essential to calling it correctly is missing.

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

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 for the description to disambiguate. The baseline of 4 applies; no parameter semantics are needed or missing.

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 (KYA Brasil overview) and enumerates exactly what it covers: the product, credential flow, prices, and schema/key locations. That distinguishes it clearly from action-oriented siblings like kya_verify or kya_revoke, though it never uses an explicit verb such as 'returns' or 'explains'.

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 leading 'Free.' implies this is the no-cost orientation call to make before using paid siblings such as kya_verify_paid, which is useful routing context. However, it never explicitly says when to use this versus the other 14 tools, so the guidance remains 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?

Annotations already declare readOnlyHint and openWorldHint, so safety is covered. The description adds real behavioral context: the result is a 'signed verdict', it evaluates only the reserved mandate fields, it also checks credential active status, and it explicitly reports the fields it did NOT evaluate. That partial-evaluation disclosure is genuinely useful 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?

Two sentences, front-loaded with the verdict question, no filler. Dense but every clause carries information; only slight loss for the awkward parenthetical parameter 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, so the description should carry more of the return-value burden. It hints at a 'signed verdict' and the unevaluated-field list but does not describe the verdict shape, failure semantics, or error cases for an 8-parameter check tool, leaving a meaningful gap.

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

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

Schema description coverage is 88%, so the schema already documents nearly every parameter (including notes like spent_today for max_per_day and payment_ref_sha256 checked against mandate.payment_instruments). The description adds only a grouped listing of the fields, 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 (check/evaluate) and resource (an action against the agent's mandate plus credential validity), and enumerates the fields involved. It is clearly distinct from siblings like kya_verify or kya_prove, though it does not name them explicitly.

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

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

Usage is implied (check an action before performing it) but the description gives no explicit when-to-use/when-not guidance and never contrasts with the many sibling verification tools such as kya_verify or kya_prove. The agent must infer the placement in the workflow.

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 and openWorldHint, so safety is covered. The description adds genuinely new behavioral context: the call is free, it requires an e-CNPJ-signed request, and it spells out the exact signed-text payload. It stops short of describing auth failure modes or the response shape.

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

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

Compact and front-loaded, opening with the scope and cost before the signing mechanics. The fragment style ('Free, company only.') is terse but not wasteful, and 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?

With no output schema, the description carries the return-value burden and does so reasonably by describing the credential set it returns. Signing and auth requirements are included, leaving only the exact response structure undescribed, which is a minor gap for a read tool.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema. The description restates the signed_text format ('KYA Brasil: agents <cnpj>' + 'at: <ISO time>'), which mirrors the schema rather than adding syntax beyond it. Baseline 3 is correct when the schema does the heavy lifting.

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

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

The description states what is returned – 'Every credential ever registered for your CNPJ, any status, whoever held the certificate' – which is more specific than the tool name alone. 'Company only' distinguishes it from the kya_person_agents sibling. It lacks an explicit verb like 'list' or 'get', but the returned 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?

'Free, company only' implies when to reach for this over the person variant, but no alternative is named and no exclusion beyond the company scope is given. Usage is implied rather than stated, which is the definition of the minimum-viable 3.

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 openWorldHint and idempotentHint. The description adds real behavioral context: the request must be signed with the company's e-CNPJ, that passing url "-" removes the webhook, and the full set of events delivered. It stops short of stating auth/permission failure modes or response behavior, but it meaningfully exceeds 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?

Two tight clauses with no filler; the cost/scope qualifier and the core action are front-loaded, and the removal semantics are packed into the final clause. Efficient, though the event enumeration is slightly dense.

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 setter with no output schema, the description covers what is set, who may set it, how the request is authenticated, what events flow, and how to clear the setting. Nothing critical is missing, though failure/error 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 coverage is 100%, so the schema already documents cnpj, signed_text, and ecnpj_signature. The description adds one genuinely new data point — that url "-" removes the webhook — but otherwise restates the e-CNPJ signing requirement already in the schema. Baseline 3 applies when the schema carries the load.

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

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

States a specific verb and resource: 'Sets the https URL that receives signed events about your agents', and enumerates the exact event types (credential issued, renewed, suspended, reinstated, revoked). An agent immediately knows this configures a company webhook endpoint, distinct from one-shot operations like kya_prove or kya_revoke.

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, company only.' gives two usage constraints (cost, applicable entity) but never states when to call this versus alternatives or prerequisites beyond the signing requirement. Usage is implied rather than explicitly framed; there is no explicit when-not guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is known. The description adds useful behavioral context beyond that: the tool is free, the e-CPF signature is valid for only 10 minutes, and it specifies exactly what data is returned (live credentials and CPF checks). No contradictions with annotations.

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

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

Two sentences with no wasted words, and the cost/scope information is front-loaded. The first sentence is a bit awkward and fragmented, but the overall structure is efficient.

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 explain the return values more precisely. It vaguely states 'every live credential ... and every CPF check', but does not describe the response structure, format, or pagination, leaving meaningful gaps for a data-fetching 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 the schema already defines both parameters fully, including the exact signed_text format and the CMS/PKCS#7 base64 DER encoding of ecpf_signature. The description adds only the 10-minute validity period for the signature, which is minor and somewhat ambiguously worded.

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 ('every live credential behind your e-CPF and every CPF check') and distinguishes the tool from the company variant with 'person only', but it never states a clear verb or action. It reads as a fragment describing output content rather than what the tool does, and the term 'credential' is used where the tool name says 'agents', creating ambiguity.

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 context ('Free, person only') that implicitly separates this from kya_company_agents, but it never explicitly says when to use this tool versus other siblings like kya_verify or kya_prove. No when-not conditions or alternatives are named.

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

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

Beyond the readOnlyHint/openWorldHint annotations, it discloses price ($0.01), a hard rate limit (3 non-matching answers per credential stop checks), a privacy guarantee (CPF never stored, published, or revealed), a side effect (the person sees every check), and the match return (a verifier-specific subject_ref). This is rich operational context an agent cannot 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?

Dense but front-loaded: cost and scope lead, then match output, then privacy/limit/notification constraints. Every clause carries information. Slightly marred by the clipped fragment 'On a match, a subject_ref of your own for that person', which reads as a sentence stub.

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

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

With no output schema, the description usefully states the return value (subject_ref on match) and covers cost, rate-limiting, privacy, and notification. For a simple two-parameter paid check, this is close to complete; only the non-match return shape is left implicit.

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

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

Schema description coverage is 100%, so both cpf and credential_id are already documented in the schema (cpf used for comparison only, credential_id returned by kya_register). The description reinforces the CPF's comparison-only/never-stored role but adds no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

The description names a specific operation and resource: a signed yes/no answer on whether a supplied CPF matches the e-CPF holder behind a credential, scoped to a person's agent (principal.kind person). This is clearly distinguishable from prove/verify siblings. It stops short of explicitly naming which sibling to prefer, but the matching semantics are concrete.

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 the scenario (you already hold a CPF and want to check it against the e-CPF holder) and names the scope (person-kind principal), but gives no explicit when-to-use/when-not guidance or named alternatives among the many kya_* siblings. Usage is inferable 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 openWorldHint, so the description carries real weight and delivers: it spells out the validation chain (ICP-Brasil roots, CNPJ match, CRL revocation check, ATIVA status), the issuance result (90 days, Ed25519-signed), and that the call is free. It omits failure behavior and error semantics, but that is a minor gap against a strong 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?

Front-loaded with the most decision-relevant fact ('Free'), then the action, then the validation/issuance semantics in dense but readable sentences. No filler, though the run-on middle sentence packs many clauses.

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 minimal annotations, the description does the work an agent needs: it clarifies the validation chain and what is produced. The main gap is that it never disambiguates against kya_renew_prove, an identical-shaped sibling, leaving selection ambiguity.

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 documented (challenge_id source, credential_id UUID, both signature formats). The description adds only the high-level framing 'both signatures', so the baseline 3 is appropriate.

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

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

The description states a clear resource and outcome: it takes the two challenge signatures, validates the e-CNPJ chain, and issues a credential. That is specific enough for an agent to know this is the proof/issuance step. It does not, however, contrast itself with the very similar sibling kya_renew_prove, so an agent must infer which one applies when.

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 invocation guidance ('Send both signatures of the challenge') and implicitly positions itself as the step after kya_register/kya_renew via the challenge_id parameter. But it never states when to call this versus kya_renew_prove, or the prerequisites (that a challenge/credential must already exist from register).

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 supply openWorldHint=true, so the description carries real weight and delivers it: a one-time challenge, a dual signing flow (agent key + company e-CNPJ via CMS/PKCS#7), and a pricing note. It stops short of covering idempotency, reversibility, or what happens after the challenge is signed.

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, front-loaded with the purpose and followed by the return/signing behavior and the pricing note; little waste. The pricing sentence is arguably extra but is useful context for an agent deciding to proceed.

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 rightly explains the return value (a one-time challenge) and the signing sequence. For a multi-party, nested-object registration flow it is fairly complete, though it could point to the follow-up sibling tool needed to complete registration.

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 75%, so the schema already documents most fields; the description nonetheless reinforces the agent-key formats (EVM address, Web Bot Auth Ed25519) and the mandate's schema validation. It omits the erc8004 key kind that the schema allows, a minor 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?

States a specific verb and resource: 'Register an AI agent for a Brazilian company', and enumerates the required inputs (agent key, CNPJ, mandate). It implicitly separates itself from siblings like kya_renew and kya_revoke by naming the registration operation, though it never names an alternative tool explicitly.

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

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

The context of registering a company agent is implied, and the schema's 'principal'/'person' detail suggests a person variant, but the description never states when to use this versus kya_renew, kya_company_agents, or kya_person_agents, nor any prerequisite (e.g., that it is the first step before kya_prove).

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

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

With only openWorldHint=true, the description carries the disclosure burden and does add real value: the renewal requires an e-CNPJ signature that is in force (not revoked) and an ATIVA status at the Receita. It omits failure behavior, whether the prior credential is invalidated, and what the call returns.

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 the action and duration front-loaded, then the preconditions. No wasted text; could only improve by naming lifecycle relationships.

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 sparse annotations and no output schema, the description covers purpose, duration, and preconditions but is silent on return values, error cases, and how it relates to kya_renew_prove. Adequate but with clear gaps for a credential-mutating 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?

Single parameter at 100% schema coverage, so the schema already documents credential_id as the value returned by kya_register. The description adds no syntax or format detail beyond that, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Re-issue the credential') plus a concrete scope ('for 90 more days'). This clearly separates it from initial issuance (kya_register) and the proof step (kya_renew_prove), though it never names those siblings 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?

Implies usage through preconditions ('company signs the renewal challenge with an e-CNPJ in force... must still be ATIVA'), which tells the agent when renewal will succeed. However, it offers no explicit when-to-use vs alternatives or exclusion conditions relative to kya_register/kya_renew_prove.

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 openWorldHint=true, so the description carries most of the disclosure burden and does it well: it states this call is free, that it consumes a renewal challenge, that success re-issues the credential for 90 days, and that success is conditional on revocation status and company registration status. Missing error behavior, but the outcome model is unusually clear.

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 cost fact ('Free.') and the sequencing fact, with no filler. Every clause carries information an agent needs before calling.

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

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

No output schema exists, and the description compensates by spelling out the return outcome (re-issue for 90 days) and the conditions attached to it. Combined with fully documented parameters and the precondition chain, this is close to complete for a 4-param step tool.

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

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

Schema description coverage is 100% and each of the four parameters is documented in-schema (signature formats, challenge_id source). The description's 'send both signatures' adds only a light grouping hint beyond the schema, so baseline 3 applies.

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

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

Specific verb+resource: send both signatures of the renewal challenge, with the resulting action (credential re-issued for 90 days) named. It explicitly positions itself as the second step of the sibling kya_renew, so an agent can distinguish it from kya_renew and kya_prove without opening a 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?

Requires the agent to have completed kya_renew first ('Second step of kya_renew'), which is clear sequencing guidance, and states the success preconditions (e-CNPJ not revoked, company ATIVA). It stops short of naming explicit failure branches or what to do if preconditions aren't met.

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 and idempotentHint, so the safety profile is covered. The description adds two useful traits beyond that: it is "Free" (cost/pricing context the annotations do not carry) and the window defaults to the last 30 days when no "since" is supplied.

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

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

A single tight sentence, front-loaded with the most decision-relevant token ("Free") and then the resource and default. No filler, though the fragment style leaves the intended action slightly implicit.

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

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

For a one-parameter read tool with no output schema and annotations covering the safety profile, the description supplies purpose, default behavior, cost, and target audience. Only the return shape (a revocation list) and any pagination/limit behavior are 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 description coverage is 0%, so the description must carry the load, and it does explain the sole parameter's meaning ("since a date") plus its default of 30 days, which the schema does not state. It leaves the exact date-time format to the schema, which already enforces 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 states a specific resource and scope: credentials revoked since a date, with a default window. It implicitly distinguishes itself from the sibling kya_revoke (which performs a revocation) by describing a listing/query of revocations, though it never names that sibling explicitly.

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

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

"for verifiers that cache credentials" gives a clear audience/context, implying this is a cache-invalidation feed rather than a bulk revocation action. However, it never says when to prefer this over siblings like kya_revoke or kya_check_action, so the 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 destructiveHint=true and openWorldHint=true, so the mutation risk is known. The description adds genuinely useful context beyond that: the call is free, it takes effect at once (irreversible), and it requires an e-CNPJ-signed request, which signals an authentication prerequisite the annotations do not convey.

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

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

Three short sentences with the cost and the core action front-loaded, and no filler. 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 destructive, no-output-schema tool, the description covers cost, immediacy, auth requirement, and where revocations can be listed. It omits what the caller receives on success/failure and whether reason is optional, leaving modest 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 coverage is 75% and the schema itself explains signed_text and credential_id in detail. The description contributes the fact that the request is e-CNPJ-signed, tying to ecnpj_signature, but adds nothing about reason or the exact signed_text format beyond the schema. Baseline 3 is appropriate when the schema does most of 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 (revokes) and resource (the credential), plus the immediacy of the effect and the signing requirement. It is distinguishable from kya_revocations (a listing tool) and kya_renew, but it does not explicitly name or contrast those siblings.

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

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

The phrase 'the company revokes the credential' implies the scenario (a company invalidating a credential it controls), and the mention of /v1/revocations hints at the read-side counterpart. There is no explicit when-not-to-use guidance or named alternative such as kya_renew or kya_revocations.

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 flag readOnlyHint and openWorldHint, so the description earns credit for what it adds: the tool is free, the link is bearer-style ("for whoever holds the e-CNPJ"), signing happens out-of-band in the browser or via the kya-sign CLI, and the issuer never sees the certificate. That privacy and auth-model detail is genuinely beyond the structured fields. It doesn't cover link expiry or reuse behavior, so not a 5.

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

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

Opens with cost ("Free.") and who this is for, then the mechanics and signer options — front-loaded and information-dense with almost no filler. The middle sentence is a long run-on enumerating A1/A3/cloud/CLI, which costs a little readability but each clause carries distinct information.

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

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

There is no output schema, so the description correctly explains what comes back (the /sign URL) and what the recipient sees and can do with it. Combined with the full schema coverage and readOnly annotation, an agent has enough to invoke this correctly; only link lifetime/reuse semantics are missing.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters, and the draft-07 pattern on credential_id is fully specified. The description adds only light framing — that challenge_id comes from register/renew and that agent_signature lets the human sign with the e-CNPJ alone — which does not exceed the schema baseline.

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

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

States a concrete action and artifact — hand in challenge_id plus the agent's signature, receive the /sign URL for the e-CNPJ holder to sign. It also positions itself in the register/renew flow by naming the source of challenge_id, so an agent can place it. Sibling differentiation is indirect (no explicit contrast with kya_prove or kya_renew_prove), which keeps it 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?

Implied usage is clear: this is the step that turns a challenge from kya_register/kya_renew into a signable link for the certificate holder. However there is no explicit statement of when NOT to use it, and no named alternative among the many sibling prove/verify tools that might also be relevant.

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 and openWorldHint, so safety is covered. The description adds genuinely useful operational context beyond the schema: it is free and rate-limited to 50 calls/day per IP, and it enumerates the possible statuses (active, suspended, revoked, expired) that the response can 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?

Two short sentences, front-loaded with cost/rate limit, then the returned fields, then the alternate lookup. Dense and largely waste-free, though the raw '/v1/agents/by-key?kind=&id=' fragment is cryptic shorthand.

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 two optional parameters, the description carries the return-shape burden and does so by naming the fields and statuses returned. Rate limit and lookup modes are covered; what is missing is explicit routing vs the paid/sibling verify 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 both parameters (credential_id, agent.kind/id) are fully documented in the schema, including the alternative-to-credential_id relationship. The description adds only the raw key-lookup URL form, which is marginal beyond what the schema already states, 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?

It states clearly what the call resolves — an agent's current credential (principal company, mandate, status, signature) — and offers a key-based variant. The verb 'verify' is only implied rather than stated, but the resource and returned fields are specific enough to distinguish it from siblings like kya_check_action or kya_revocations.

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 'Free (50/day per IP)' note implicitly contrasts it with the paid sibling kya_verify_paid, and 'Also by key' hints at the two lookup modes. However, it never says explicitly when to choose this tool over alternatives or what the free-tier precondition means for the caller.

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 meaningful behavior beyond the annotations: a signed receipt is produced, there is no daily rate limit, and payment is per call via x402. It does not detail payment failure modes or receipt format, but the key operational traits are 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?

One tightly written sentence front-loads the relationship to the free verification, then adds the differentiating features and payment model. Every clause carries useful information.

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

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

For a one-parameter verification tool with full schema coverage and no output schema, the description covers the key distinctions, cost model, and return artifact at a high level. It could be slightly more complete by clarifying the receipt contents or output shape, but no critical invocation detail is missing.

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

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

Schema description coverage is 100%, and the single parameter is already documented as the credential_id returned by kya_register. The description adds no further parameter meaning or format details beyond the schema, so the baseline score of 3 applies.

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

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

States a specific paid verification operation and distinguishes it from the free sibling by naming its two differentiators: no daily limit and a signed receipt. An agent can tell what this tool does and how it differs from kya_verify without opening both 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?

Clearly positions the tool as the paid alternative to the free verification for cases needing no daily limit and a signed receipt. It gives a clear selection context but does not explicitly state when not to use it or name kya_verify as the fallback.

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