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

Annotations cover read-only, idempotent, and non-open-world behavior, so the safety profile is already handled. The description still adds real context beyond them: 'Free' (no cost/quota concern) and 'offline' (no network dependency), which are not derivable from readOnlyHint/idempotentHint and matter for an agent deciding whether it can call this in a constrained environment.

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 dense sentence, front-loaded with the two most decision-relevant facts ('Free and offline'), then the content inventory. No filler, no 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 zero-parameter, no-output-schema documentation tool, the description is nearly complete: it tells the agent what topics the payload covers and that access is free and offline. A brief note on the return format (structured JSON vs. prose/markdown) would close the remaining gap.

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

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

The tool takes zero parameters, so the schema baseline of 4 applies. The description correctly adds no parameter discussion, which is appropriate here.

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

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

The description enumerates exactly what the tool delivers: what KYA Brasil is, how an agent obtains a credential, which sibling tools serve a verifier, and where the spec and issuer keys live. That content list distinguishes it from the verify/check/revocation siblings, which all perform operations rather than explain them. It lacks an explicit verb ('returns documentation about...'), but the scope 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 and offline' plus the mention of 'which tools to use as a verifier' implies this is the onboarding/orientation entry point, but the description never states when to call it (e.g. 'call this first', 'use before choosing a verify tool'). Usage is inferable rather than explicit, and no exclusions 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?

Annotations only say readOnlyHint and openWorldHint, but the description adds material behavior: the call costs $0.01 via x402/USDC on Base, requires KYA_PRIVATE_KEY to be set, and returns a signed verdict enumerating every evaluated rule that can be used as dispute evidence. None of that is recoverable from the annotations or schema, so the description carries real added value.

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, each doing distinct work: pricing/auth, the decision being made, then the fallback sibling. The only weakness is that the dense parenthetical '$0.01 (x402, USDC on Base; set KYA_PRIVATE_KEY)' puts implementation jargon ahead of the purpose statement, so the tool's job is not the very first thing read.

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

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

With 8 parameters, no output schema and no destructive/denial semantics in the annotations, the description does the essential work: it explains the payment barrier, the credential prerequisite, and the shape of the returned verdict. It stops short of explaining failure/denial behavior or error responses, which would be useful for a paid, decision-returning call.

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

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

Schema coverage is 100%, and each parameter (action, amount, spent_today, counterparty, payment_ref_sha256, etc.) already has a clear schema description, including the note that spent_today is needed for max_per_day because the issuer keeps no record of acts. The prose references actions, mandates and credentials conceptually but adds no syntax, 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?

The description states a precise verb+resource: decide whether an agent may perform a given action under its mandate and whether its credential is currently active. It also distinguishes itself from the sibling kya_check_mandate by delivering a signed, evidentiary verdict rather than a free unsigned answer, so an agent can route between them 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?

It gives an explicit when-to-use rule ('For a free, unsigned answer use kya_check_mandate on the mandate from kya_verify'), which both names the alternative and states the condition that selects it. The paid nature of this tool is stated up front, which is the key selection criterion against its free sibling.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and openWorldHint=false, so the safety profile is covered. The description reinforces and enriches this: 'Nothing is sent anywhere' confirms the offline nature, 'Free' adds a cost dimension the annotations lack, and it discloses the shape of the result ('lists every rule with its result'), which the missing output schema does 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?

Two sentences, front-loaded with the most decision-relevant facts ('Free and offline'), then the mechanics. The rule enumeration is dense but earns its place by previewing what the caller receives in the absence of an output schema.

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

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

For a read-only 8-parameter tool with nested mandate object and no output schema, the description does the essential work: it establishes offline/free behavior, the mandate source, and the returned per-rule breakdown. It could say more about failure/edge behavior when a rule fails, but nothing an agent needs to call it correctly is missing.

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

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

With 100% schema description coverage the baseline is 3, and the description adds real meaning beyond the schema by naming the mandate fields evaluated (ceilings per operation and per day, validity window) and by calling out the '*.domain wildcard' semantics for counterparty, which the schema's plain 'Your CNPJ, domain or wallet address' 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?

The description states a specific verb and resource ('Evaluates an intended action against a KYA mandate') and enumerates the rules checked, so the agent knows exactly what the tool does. It hints at input provenance ('the credential's mandate from kya_verify, or one you are drafting') but does not explicitly differentiate itself from close siblings like kya_validate_mandate or kya_check_action.

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

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

The context of use is implied ('Free and offline', mandate from kya_verify or drafting) but there is no explicit when-to-use guidance or exclusion relative to alternatives such as kya_validate_mandate or kya_check_action. An agent must infer the choice from the one-line purpose.

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 covered. The description adds "Free" cost context and the default 30-day window, which is thin but useful; it says nothing about result volume, pagination, or ordering.

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 fragments, front-loaded with cost, then purpose, then use case. No padding or redundancy.

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

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

For a simple, single-parameter read-only list tool with annotations covering safety and an open-world hint, the description supplies purpose, default window, and audience. Nothing essential to 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 single `since` parameter is already documented with its ISO 8601 format and 30-day default. The description restates the default but adds no syntax or meaning beyond the schema, 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 (list) and resource (revoked credentials) scoped by a date. It is naturally distinct from the sibling verify/mandate/sign tools, though it never explicitly names an alternative. Clear purpose with no sibling callout.

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 and want to drop revoked ones" clearly identifies the intended caller and scenario. It gives context without naming alternatives or exclusions, which fits the 4 bar.

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=true and openWorldHint=true, and the description is consistent with that. It adds context beyond the annotations: the operation is 'Free', the output is a link handed to a human who signs in the browser, and the agent pre-signs the challenge so the holder 'only signs with the certificate'. It does not cover link expiry or reuse, 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?

Two tight sentences, front-loaded with the distinctive 'Free' marker and followed immediately by what the link is and who receives it. No filler, though the sentences are 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?

With no output schema, the description still conveys that the return is a shareable link, and it covers the safe-read annotation profile and the post-registration sequencing. It leaves the link's validity window and exact payload unspecified, so not fully 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 the baseline is 3. The description earns a bump by explaining the workflow relationship between the three inputs: the agent supplies credential_id and challenge_id and its own signature of the challenge so the certificate holder's browser step is minimized.

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 artifact (a signing link) and its audience (the e-CNPJ/e-CPF holder, owner or accountant). It is readily distinguishable from the sibling verify/check/revocations tools, which audit rather than produce a signing link. It never names a sibling explicitly to route the agent, hence not 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 states clear context: 'Use after a registration' and names the required inputs (credential_id, challenge_id). It does not name an alternative tool or a when-not-to-use condition, so it stops short of a 5.

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

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

Annotations already declare readOnly/idempotent/closed-world, so the safety profile is covered. The description adds real behavioral context beyond that: it returns a normalized mandate (actions deduplicated, counterparties and payment instruments normalized) and rejects card numbers and malformed fields with a reason — useful for predicting success/failure behavior.

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

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

Two sentences, front-loaded with the key constraint ('Free and offline'), then purpose and return/refusal behavior. No filler, though the normalization detail is packed densely into one 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 no output schema, the description carries the return-value burden and does so: it states the mandate is returned normalized and that errors include a reason. For a one-parameter, read-only validation tool this is largely sufficient, missing only what a failure reason looks like structurally.

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, and schema description coverage is 100% — the schema itself enumerates the mandate fields (actions, max_per_operation, currencies, counterparties, etc.). The description adds no format or syntax detail beyond that, so the baseline 3 applies.

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

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

States a specific verb+resource ('checks a mandate against the KYA schema') and adds scope detail: pre-registration validation plus normalization. It does not, however, differentiate itself from the similarly named sibling kya_check_mandate, so an agent could still hesitate between the two.

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?

'before registering an agent with it' implies the workflow position (pre-registration gate), and 'free and offline' hints at a distinction from the online kya_verify family. But no explicit alternatives or exclusions are named, and the kya_check_mandate overlap is left unresolved.

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 context: it is free, it performs a live issuer lookup, and it enumerates return contents including the status lifecycle (active, suspended, revoked, expired) and history. It does not mention error/not-found behavior or rate limits, but for a read-only lookup that is a minor omission.

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 key qualifier 'Free.' and packs return contents, input options and usage trigger into a tight block. The rhetorical opener 'Who answers for this AI agent?' adds a little flavor at slight cost to density, but nothing is truly wasteful.

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

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

With no output schema, the description correctly takes on the burden of describing return values (principal, mandate, status, history) and does so. Both optional parameters are fully documented in the schema, so the only real gap is behavior on missing/invalid credentials or no-match results.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds real semantic value beyond the schema by clarifying the either/or relationship ('Give credential_id, or the agent key') and disclosing that supplying an agent key returns its active credentials (plural), which the schema does not state.

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 (looks up the agent's KYA Brasil credential at the issuer) and enumerates what comes back: principal, mandate, live status, history. It implicitly distinguishes itself from siblings like kya_verify_credential_offline (issuer lookup vs offline) and kya_verify_paid ('Free.'), but never names an alternative 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?

Provides a clear triggering condition: 'Use it before trusting an order, payment or signature that comes from an agent.' That is strong positive guidance, but there are no exclusions or named alternatives telling the agent when to reach for a different verify-family sibling instead.

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

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

With readOnlyHint/openWorldHint already covering the safety profile, the description adds the non-obvious behavior: the issuer key comes from /.well-known/kya.json and is 'fetched once', and a post-issuance revocation cannot be seen, leaving live_status unknown. That limitation disclosure is exactly the kind of context the name ('offline') would otherwise mislead 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?

Three short sentences with the cost note ('Free.') and the scope front-loaded, followed by the limitation and the routing pointer. 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 single-parameter verification tool with no output schema and strong annotations, the description covers cost, scope, mechanics and the key limitation. It stops short of indicating the shape of the verification result (beyond hinting that live_status is a field), which leaves the return contract 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?

Only one parameter and the schema describes it at 100% coverage ('the full credential JSON, including its attestation'), so the schema does the heavy lifting. The description adds the notion that the caller must already hold the document, but no syntax or shape detail beyond the schema — 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 ('Checks a credential document you already hold') plus exactly which checks are performed: the issuer's Ed25519 signature and the expiry. It explicitly separates itself from the sibling kya_verify, so an agent can pick between them 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 the selecting condition for this tool (a credential document you already hold) and names the alternative with its trigger ('use kya_verify for the live status'). It also flags the revocation blind spot as a reason the alternative may be required.

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 closed-world, so the bar is lower. The description adds real value beyond them: it is free/offline, describes the chain validation semantics, states the return (the key that must sign the sub-agent's requests), and explains that an action passes only if every level allows it.

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

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

Front-loads the key qualifier ('Free and offline') and is dense with no filler. The middle sentence is long and comma-heavy, but every clause carries distinct information about what is checked.

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 explains the return value (the signing key) and the conditional action evaluation. For a read-only verification tool with 100% schema coverage, this covers what an agent needs, though it does not sketch the failure/return shape.

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

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

Schema description coverage is 100%, so the schema already documents all 9 parameters thoroughly. The description adds the action-evaluation-on-every-level semantic that helps interpret action/amount, but adds little about the other params, so the baseline 3 is appropriate.

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

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

States a specific verb and resource: verifying a sub-agent's delegation chain, and enumerates what it checks (signatures, depth, lifetime, mandate containment). It is clearly distinguishable from credential-level siblings, though it never names an alternative tool 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?

Establishes the context ('a sub-agent acts under a delegation chain') and the conditional behavior when 'action' is given, but offers no explicit when-to-use versus siblings like kya_check_action or kya_verify_paid. Usage is implied rather than routed.

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

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

Goes well beyond the readOnlyHint/openWorldHint annotations by disclosing price ($0.01), payment rail (x402, USDC on Base), the required environment credential (KYA_PRIVATE_KEY), the absence of the free daily limit, and the extra signed receipt in the response. These are exactly the cost, auth, and rate-limit facts an agent needs before invoking a paid 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 dense sentence with the cost and payment prerequisites front-loaded and the differentiation from kya_verify second. No filler and nothing that fails to earn 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 verification tool it covers cost, prerequisite env var, rate-limit contrast, and the added return artifact (signed receipt), which substitutes for the missing output schema at a high level. It does not describe receipt format or payment-failure behavior, leaving a small gap.

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

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

Schema description coverage is 100% for the single credential_id parameter, including format, pattern, and header context, so the schema already carries the semantics. The description adds no parameter detail beyond that, which is the baseline-3 case for a fully documented single param.

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 (verification via kya_verify_paid) and immediately differentiates from its closest sibling: 'Same answer as kya_verify, without the free daily limit, plus a signed receipt.' An agent can tell exactly what it gets versus the free variant without opening the schema.

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

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

The phrase 'without the free daily limit' implies the selection condition (use when the free tier is exhausted or when a receipt is needed), and it explicitly names the alternative kya_verify. It stops short of an explicit 'use this when / not when' statement, so it is clear context rather than full routing guidance.

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