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

With no annotations, the description carries full burden and explains key behaviors: it is a read-only identity declaration ('No card is issued. No money moves'), how merchants may challenge, and the response includes agent_disclosure text. Missing idempotency details, but otherwise thorough.

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 informative but verbose, including marketing-like phrases ('Prove it before you shop') and repetition. It could be more concise while retaining key info, so a score of 3 reflects moderate conciseness.

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 the description only partially explains return values (mentions agent_disclosure text). It lacks details on error responses, status codes, or what happens on failure, leaving gaps for a tool critical to shopping flow.

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

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

Schema coverage is 100% and both parameters have clear descriptions. The description adds context about the merchant parameter ('The merchant or website the agent intends to visit') but does not add meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states what the tool does: it declares the agent's identity to merchants before shopping, distinguishing it from siblings like kya_getCard (payment). It uses specific verb+resource: 'declare identity' and explicitly says 'Call this BEFORE any shopping 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 description provides explicit when-to-use guidance: 'Call this BEFORE any shopping action — browsing, searching, or buying.' It also tells the agent what to do when challenged and mentions alternative kya_getCard for payment, fulfilling the guidelines dimension fully.

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?

Discloses card is single-use, self-destructs after use, user's real card never enters chat, and MFA approval needed. No annotations exist, so the description adequately covers behavioral traits.

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?

Five sentences each adding value, front-loaded with main purpose, uses imperative language, no fluff. Efficient and well-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?

Describes process and lifecycle but lacks explanation of output (return value). No output schema is provided, so this gap is notable. However, the moderate complexity and clear process partially compensate.

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 decent descriptions for each parameter. The description does not add significant extra meaning 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?

Clearly states the tool gets a single-use virtual Visa for purchases, with specific verb 'Get' and resource 'card'. Differentiates from sibling tools by referencing prerequisites (kya_getAgentIdentity) and follow-ups (kya_reportPurchase).

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 requires calling kya_getAgentIdentity first and kya_reportPurchase after, establishing a clear usage sequence. Does not explicitly state when not to use or alternatives, but the context implies it's for purchases only.

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?

No annotations are provided, so the description carries full burden. It discloses that a 'Kya-Token' header is returned and suggests usage, but omits behavioral traits like access requirements, idempotency, or side effects. It does not state if the operation is read-only or has any destructiveness.

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 concise with two short paragraphs, front-loading the core purpose. It includes usage examples efficiently. Some minor redundancy exists, but overall it is well-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?

Given no output schema, the description only mentions the return of a 'Kya-Token' header without detailing the response format. It covers usage context well but lacks completeness about the returned data structure. Complexity is low (1 param), so the gaps are moderate.

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 sole parameter 'merchant' has a helpful schema description. The tool description adds no further meaning beyond what the schema already provides. With 100% schema coverage, baseline 3 is appropriate as no extra value is added.

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 tool returns 'Kya-Token' identity headers for HTTP requests, specifying the verb ('Get') and resource ('identity headers'). It distinguishes itself from the sibling 'kya_getAgentIdentity' by indicating a prerequisite call.

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 tells when to use: for attaching headers to Playwright, browser extensions, or any HTTP client. It advises calling 'kya_getAgentIdentity' first, providing a prerequisite. However, it does not explicitly mention alternatives or when to avoid using this tool.

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

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

No annotations are provided, so the description must disclose behavioral traits. It only says 'report that you did not present' without explaining what the report does, whether it is idempotent, or any side effects. The deprecation note hints at irrelevance but does not clarify 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?

The description is extremely short—two sentences that clearly communicate deprecation and purpose. Every word earns its place, with no redundancy or fluff.

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

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

Given the tool's simplicity and no output schema, the description still fails to provide necessary context such as return values, prerequisites (e.g., need to call kya_getAgentIdentity), and how it relates to sibling tools like kya_reportBadgePresented. The deprecation note helps but does not compensate.

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 input schema itself documents all parameters effectively. The tool description adds no additional meaning beyond what the schema already provides. Thus, a baseline of 3 is appropriate.

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

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

The description clearly states the tool reports that the agent did NOT present a Badge at a merchant. The verb 'report' and the negation 'did NOT present' make the purpose explicit. Although the deprecation note might confuse, the core purpose remains 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?

The description labels the tool as deprecated and 'no longer needed', suggesting it should not be used, but provides no guidance on when to use it if needed, or what alternatives exist (e.g., sibling tools like kya_reportBadgePresented). Prerequisites like calling kya_getAgentIdentity first are implied by the schema but not 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the purpose and deprecation, but does not explain side effects, permissions, or what happens upon invocation (e.g., whether data is stored, if there are rate limits, or what the response format 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?

The description is extremely concise: two sentences with the deprecation warning front-loaded. Every word adds value, and there is no redundant or unnecessary 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?

The tool has no output schema and the description does not mention return values or behavioral outcomes. However, the deprecation note and alternative endpoint provide the most critical context (do not use). For a deprecated tool, this is adequate completeness, though for an active tool it would be lacking.

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

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

Schema coverage is 100% with parameter descriptions already provided. The description adds no additional semantic context beyond the schema's own descriptions, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: reporting how a merchant responded after presenting a Badge. It also includes a deprecation notice and points to the verify endpoint as the alternative, which distinguishes it from siblings like kya_reportBadgeNotPresented and kya_reportBadgePresented.

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 states that the tool is deprecated and should not be used; outcomes are now tracked automatically via the verify endpoint. This provides clear when-not-to-use guidance and a direct alternative, which is excellent for agent decision-making.

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?

No annotations provided, so description carries the burden. It discloses the tool triggers a kyaLabs record and mentions a 7-second check when Extended Auth is enabled, but does not clarify idempotency, side effects, or error behavior. Lacks full 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?

Two concise paragraphs: first states purpose and timing, second adds conditional logic. No redundant sentences, front-loaded with key 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?

Covers purpose, timing, and conditional behavior well. However, no output schema exists and description does not mention what the tool returns (e.g., success/error), leaving a gap for agent to understand invocation outcome.

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

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

Schema coverage is 100%, so baseline is 3. The description adds no parameter-specific guidance beyond what the schema already provides, so no extra value.

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?

Clearly states the tool reports presenting a badge to a merchant, specifies timing relative to checkoutPatch merge, and differentiates from sibling kya_reportBadgeOutcome with conditional logic.

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 tells when to call (immediately after merging checkoutPatch) and when not to (Extended Auth enabled: no need for outcome; otherwise call kya_reportBadgeOutcome). Provides clear usage context.

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

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

No annotations provided. Description adds that it 'closes the audit trail,' indicating a finality/write side effect. However, lacks details on idempotency, permissions, or rollback 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, no unnecessary words. Front-loaded with the key action and mandatory usage. Highly 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?

No output schema but 6 parameters well-documented. Description covers the core requirement (mandatory after purchase) and closing audit trail. Could mention error states or return format, but it's reasonable for a reporting 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?

All 6 parameters have schema descriptions (100% coverage). Description adds no further parameter-level detail beyond stating the overall purpose. Score matches baseline as 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?

Description clearly states the tool reports purchase outcome after using a virtual card. It distinguishes from sibling tools like kya_reportBadge* by focusing on purchase audit.

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 states it must be called after every purchase attempt to close the audit trail, giving clear when-to-use guidance. No explicit when-not, but context implies it's for purchases only.

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 no annotations, the description fully covers behavioral traits: automatic Kya-Token injection, shopping journal recording, 5MB max size, 30s timeout, no redirect following, and HTTPS requirement. This leaves little ambiguity about the tool's operation.

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

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

Description is concise (6 sentences), front-loaded with the main action, then elaborates on identity, prerequisites, and constraints. Every sentence adds value without 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?

Given no output schema, the description mentions return values (status, headers, body) and behavior on redirects. It also covers prerequisites and limits. Slight gap: what happens if getAgentIdentity is not called? Still, sufficient for the tool's 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?

Input schema has 100% coverage with descriptions for all three parameters. The description does not add significant meaning beyond schema, except context that URL should be HTTPS. Baseline of 3 is appropriate as schema already documents params adequately.

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 tool fetches a web page with a badge identity, distinguishing it from a generic web_fetch by specifying use case (shopping at merchant sites). The verb 'fetch' and resource 'web page' are explicit, and the context of automatic identity attachment sets it apart 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?

Provides explicit prerequisites (call kya_getAgentIdentity first), when to use (instead of web_fetch when shopping), and constraints (HTTPS only, redirects not followed). It also instructs on handling 3xx status by checking Location header, offering clear guidance for the agent.

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