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

No annotations are present, so the description carries the burden. It discloses that replication copies the key for cryptographic serving, explicitly states no key material is exported, keeps the key within APC HSMs, and preserves ARN semantics and usage restrictions. It does not mention permissions, latency, or confirmation 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 front-loaded with purpose, followed by a tightly scoped behavioral note and a compact Args section. Every sentence adds value, and the examples are minimal and clear.

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 annotations and no output schema, the description covers purpose, usage context, behavioral implications, and both parameters. It is missing operational expectations such as response shape, whether replication is synchronous, and any prerequisites, but overall it is strong.

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%, and the description compensates by explaining key_identifier accepts an ARN or alias and replication_regions takes a list of region codes with a concrete example. It could add constraints like allowed region values or limits, but the core meaning is clearly conveyed.

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 action: making an existing key usable from additional regions via replication. The DR and processor-proximity examples clarify intent, and the description clearly distinguishes this from create/remove operations.

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 concrete scenarios for use (DR region, moving workload closer to processor) and clarifies the key must already exist. It does not explicitly list exclusions or alternatives like remove_key_replication_regions, 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?

With no annotations provided, the description carries the full burden of behavioral disclosure and does so thoroughly. It reveals that the operation is persistent, not itself approval-requiring, causes covered calls to return MpaStatus PENDING, and logs requester_comment in CloudTrail plaintext. These are the non-obvious behavioral facts an agent needs.

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

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

The description is front-loaded with the main purpose, then covers behavioral consequences, then provides compact but complete parameter details. The PCI analogy is short and adds useful context without bloating the text. Every sentence earns its place.

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

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

For a three-parameter tool with no output schema and no annotations, the description covers purpose, behavior, and all parameter constraints very well. The only minor gaps are that it doesn't describe the tool's own response—only the effect on future covered calls—and it doesn't explicitly mention how to undo the association. Still, an agent has enough to select and invoke it correctly.

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

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

Schema coverage is 0%, so the parameter descriptions add essential meaning. The description gives the only currently supported action value, the exact ARN format for mpa_team_arn, and the max length plus plaintext-logging warning for requester_comment. This substantially exceeds what the bare schema provides.

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

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

The opening sentence states a specific action ('put a sensitive key-management operation behind Multi-Party Approval') and a specific resource (an AWS MPA approval team). It also distinguishes this from the related sibling tools by explaining that associating a team does not itself need approval but changes how the covered operation behaves from then on.

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 gives clear invocation context: call this when you need to require MPA sign-off on a key-management operation. It also clarifies the timing—the association itself doesn't need approval, and future covered calls return PENDING—but it doesn't explicitly name alternatives or say when to use disassociate_mpa_team or get_mpa_team_association 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 no annotations present, the description carries the full burden and does well: it explains that the tool stages findings as GitHub issues, that application happens at the next session start, and that it returns a formatted issue body plus the exact gh CLI command. It could further clarify whether it actually creates the GitHub issue or only prepares the command, and what GitHub authentication is required.

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

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

The description is long but well-organized: trigger, mechanism, return value, finding_type options, then parameter list. Each block adds necessary information, and the most important usage rule is front-loaded.

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

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

The description covers the trigger, all parameter semantics, the side-effect model, and the return value, even though no output schema exists. Minor gaps remain around exact GitHub-related prerequisites and whether the gh command is executed by the tool or left for the agent to run.

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%, but the description fully compensates by documenting every parameter with its purpose, example values, and the finding_type enumeration with concrete meanings and target files. This is exactly the context an agent needs to construct valid arguments.

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 opens with a concrete trigger ('Call this whenever you discover a gap while working in any repo') and states the exact resource targets: the knowledge base, HSM command registry, proxy handler list, and compliance rules. It is clearly distinct from the sibling KMS/HSM tools, which operate on keys and HSM commands rather than recording findings for later application.

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 when-to-use guidance with inclusion criteria ('discover a gap', 'belongs in this MCP server's knowledge base...') and clarifies the tool works without AWS credentials. It does not name alternatives or exclusions, but none of the siblings are direct substitutes, so the omission is minor.

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 present, so the description must carry full behavioral weight. It only says 'Create...' which signals mutation but lacks disclosures about permissions, alias-name uniqueness, overwriting behavior, or failure conditions. For a write operation with no annotation support, this is a significant gap.

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

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

The description is appropriately sized: a front-loaded usage sentence, a clear one-line definition, and a structured Args section. No redundant text, though the first and second sentences somewhat overlap in meaning.

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

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

For a two-parameter tool with no output schema and no annotations, the description covers the core purpose and parameters. However, it omits operational context such as duplicate-alias handling, key existence requirements, and permission expectations, leaving some uncertainty for an agent.

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%, and the description compensates well. It documents the required prefix for alias_name with an example, and clarifies that key_arn is optional at creation time. This adds meaning beyond the bare schema types and defaults.

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 specific action ('Create a friendly-name alias for a key') and the resource (alias for a key). The first sentence adds the distinctive purpose: establishing a stable name so application code does not change on key rotation, which differentiates it from other key-management and alias operations.

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

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

It explicitly instructs when to call the tool: 'Call this when establishing a stable name for a key...' This provides a clear triggering context. It does not explicitly name alternatives like update_alias or delete_alias, but the create vs. update/delete intent is implicit, making it adequately usable.

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 behavioral burden. It discloses important constraints: key usage type is fixed at creation, AES keys require CMAC and reject ANSI_X9_24, BDK derive_key_usage is bound at creation, and replication is a persistent key property. This goes well beyond a generic create operation.

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

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

The description is long, but the domain is complex and every paragraph adds essential information. The usage-first instruction is front-loaded, followed by an enforcement warning, and then a clearly structured Args block. A slight trim in wording would improve it, but the structure is effective.

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

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

For a 9-parameter, high-stakes key creation tool with no annotations and no output schema, the description covers parameter semantics, constraints, prerequisites, and side effects thoroughly. It does not describe the response format or what identifiers are returned, which would make it fully complete, but this is a minor gap relative to the rich guidance already present.

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

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

Schema description coverage is 0%, so the description must fully compensate, and it does. It provides concrete allowed values or formats for every parameter, explains algorithm-specific KCV rules, clarifies the BDK-only derive_key_usage, and gives examples for replication_regions. This is exemplary parameter documentation.

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

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

The description opens with a specific action—'creating a new cryptographic key'—and enumerates concrete examples (BDK, ZPK, CVK, MAC key, KEK). This clearly distinguishes create_key from the many sibling tools focused on getting, listing, deleting, importing, or exporting keys.

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 explicitly states when to call the tool and even directs the agent to call explain_key_usage first to validate the key usage code. It does not explicitly name alternatives like import_key for when key material already exists, but the creation context and prerequisite guidance are clear and actionable.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states that all inputs and outputs are hexBinary encoded, lists supported key types (D0, D1, B0, E1/E6), and explains how wrapped_key changes the interpretation of key_identifier. It could add more about response structure or error conditions, but the information given is meaningful.

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 well-organized with a clear trigger statement, supported key types, encoding note, and a compact Args list. Every sentence carries useful information 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 annotations, no output schema, and nested parameters, the description is fairly complete. It covers when to use, supported keys, encoding, and parameter semantics. The only real gap is that decryption_attributes details are delegated to 'mirrors encrypt_data', and the return value is only characterized as hexBinary encoded rather than explicitly described.

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

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

Schema description coverage is 0%, yet the description compensates well. Every parameter is explained with purpose and format: key_identifier distinguishes KEK vs working key, cipher_text is hex-encoded, decryption_attributes is algorithm-specific, and wrapped_key is optional with TR-31 behavior. This adds substantial value beyond the bare schema.

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

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

The description explicitly states the action ('decrypting cardholder data or payment fields') and the specific sources (terminal, acquiring host, issuer), and enumerates supported decryption types (DUKPT, EMV). This clearly distinguishes it from sibling operations like encrypt_data, verify_mac, and generate_pin_data.

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

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

The description opens with 'Call this when...' and provides concrete scenarios, including DUKPT and EMV confidentiality decryption. It does not explicitly list exclusions or alternative tools, but the guidance is specific enough to route an agent correctly.

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 carries the behavioral disclosure burden. It explicitly states that the underlying key is unaffected, which is the most important safety-relevant behavior for a delete operation. It does not mention permissions or irreversibility, but addresses the primary risk.

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 short and front-loaded with the usage trigger. There is minor redundancy: 'The underlying key is unaffected' and 'does not delete the underlying key' convey the same information twice.

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 delete operation, the description covers the purpose, when to use it, the parameter format, and the key behavioral guarantee. The lack of an output schema is acceptable here since the main side effect is clearly disclosed.

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 input schema only provides the parameter name and type string, while the description adds the essential requirement that alias_name must be the full alias including the 'alias/' prefix. This is critical operational detail the schema lacks.

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 operation: deleting an alias, and explicitly notes that it is a friendly name removal rather than key deletion. This distinguishes it from sibling tool delete_key.

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 opening line 'Call this when removing a friendly name that is no longer needed' provides a clear trigger condition. It does not explicitly name delete_key as the alternative, but the statement that the underlying key is unaffected implies the distinction.

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 carries the behavioral burden. It discloses the key behavioral trait ('deletion is scheduled... enters DELETE_PENDING state first') and the waiting period. It does not state whether deletion is reversible during pending, whether associated aliases are affected, or any permission requirements, leaving some behavior implicit.

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 compact and front-loaded, with an Args block that is easy to parse. Minor redundancy exists between the opening 'Call this when...' and the closing 'Schedule a key for deletion,' but no sentence is wasted.

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

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

For a destructive/scheduling operation with no annotations and no output schema, the description covers the core semantics and parameters but omits surrounding context such as cancellation/restore path, final permanence, and effects on aliases or usage. Adequate but 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 coverage is 0%, but the description fully compensates: key_identifier is defined as 'Key ARN or alias' and delete_key_in_days is given a range (3-180) and default (7). Both parameters become semantically meaningful beyond their raw types.

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 uses a specific verb and resource: 'Schedule a key for deletion' and 'decommissioning a test key or retiring a key.' This clearly identifies the operation and distinguishes it from sibling alias operations like delete_alias.

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 opening sentence gives concrete triggers: 'when decommissioning a test key or retiring a key that is no longer needed.' It does not explicitly name alternatives or exclusions, so it does not reach 5, but the intended use context is clear.

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

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

With no annotations, the description carries the burden. It discloses the effect of revoking resource-based grants, but does not discuss side effects on existing access, whether the operation is reversible, required permissions, or behavior when no policy exists.

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 only a few sentences, front-loads the usage signal, and keeps the argument documentation compact. No redundant or filler content.

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 deletion tool, the core decision context is present: when to call it, what it does, and which resource it acts on. Without annotations or an output schema, it could still mention expected behavior on missing policy or return value, but these are minor for this simplicity.

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

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

The schema has no description for resource_arn and coverage is 0%. The description only adds 'Key ARN,' which clarifies the resource type but does not explain ARN format, constraints, or required ownership. This is minimal compensation for the schema gap.

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

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

The description states the specific operation: 'Remove the resource policy from a key.' It also ties the tool to a clear use case ('revoking all cross-account or resource-based access grants'), which separates it from sibling put/get_resource_policy tools.

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

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

The opening 'Call this when revoking all cross-account or resource-based access grants on a key' provides clear context for when to use it. It does not explicitly name alternatives or exclusions, so it falls short of a full 5.

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

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

With no annotations, the description carries the full burden and discloses a non-obvious behavior: the operation is account-level and forward-looking only, so existing keys keep their replication. It does not discuss permissions or reversibility, but for this simple mutation the key side-effect boundary is stated.

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 three short blocks with no fluff: the action, the critical caveat and alternative, and the parameter explanation. The most important distinction is front-loaded.

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

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

For a one-parameter tool with no output schema and no annotations, the description covers purpose, scope, the parameter, and the relevant sibling. It could also mention the opposite enable_default_key_replication_regions or required permissions, but nothing essential to invoking 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?

Schema coverage is 0% and the schema only says 'array of string'. The description compensates by explaining that replication_regions are 'Regions to remove from the default' and gives an example format ['eu-west-1'], which is enough to construct a valid argument.

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 uses a specific verb-resource pair: 'stop new keys from automatically replicating into the named regions' and frames it as an account-level, forward-looking setting. This clearly distinguishes it from remove_key_replication_regions, which is for existing keys.

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

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

It explicitly states when to use the tool (to stop new keys from replicating into regions) and when not to (existing keys are unaffected), and names the alternative remove_key_replication_regions for the existing-key case. That is direct routing 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?

With no annotations provided, the description carries the full burden and does so well. It discloses that the association moves to DELETE_PENDING, may require approval from the currently associated team before clearing, and that requester_comment is stored in plaintext in CloudTrail — all meaningful behavioral details beyond the schema.

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

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

The description is appropriately sized: purpose first, then compliance caveat, then behavioral detail, then parameter explanations. Every sentence adds value and none repeats schema 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 description covers purpose, side effects, approval behavior, and parameter semantics, which is strong for a tool with no annotations and no output schema. It could mention how to verify the resulting DELETE_PENDING state or which sibling tool to use for checking association status, but this is a minor gap rather than a serious omission.

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%, but the description compensates for both parameters. It explains action with a concrete example and requester_comment with length and auditability caveats. It could be stronger by enumerating valid action values, but the semantics provided are meaningful and sufficient for typical use.

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

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

The description opens with a specific verb and resource: 'remove Multi-Party Approval from an operation, returning it to single-principal control.' This clearly distinguishes the tool from its sibling associate_mpa_team and states the exact outcome.

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

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

It provides clear context for when to call, including the compliance-sensitive nature of the action and the fact that it weakens a dual-control boundary. It does not explicitly name alternatives, but the inverse relationship to associate_mpa_team is strongly implied and the caution about confirming intent gives practical usage guidance.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses the account-level scope, the non-retroactive behavior, and the side effect on subsequently created keys. However, it does not mention response behavior or permission requirements, though those are less critical for this additive configuration operation.

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

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

The description is tight and front-loaded: it immediately states the action, then scope, then the sibling alternative, then the argument. Every sentence earns its place without extraneous detail.

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

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

For a single-parameter configuration tool, the description covers the key operational context: what the tool does, its account-level scope, its non-retroactive behavior, and the alternative for existing keys. It does not describe the response format, but no output schema exists and the missing detail is unlikely to prevent correct invocation.

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 compensate. It explains that replication_regions are 'Regions to enable by default' and provides a concrete example, i.e. ['us-west-2']. This gives an agent enough meaning to supply the parameter, though region validation rules are not stated.

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: 'add regions to the account-wide default' so that subsequently created keys replicate there automatically. It clearly distinguishes this from add_key_replication_regions by noting it affects future keys only.

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 explicitly says when to use this tool ('account-level', 'future keys only') and names the alternative for existing keys: 'Use add_key_replication_regions for keys that already exist.' It also clarifies that it does not retroactively replicate existing keys, which prevents misuse.

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 carries the full burden and does well: it discloses hexBinary encoding for all inputs/outputs, supports key type families, and explains that wrapped_key changes key_identifier to act as the KEK. It does not cover permissions or failure behavior, but the core behavioral traits are clearly 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?

The description is front-loaded with when-to-use guidance and then provides dense, valuable detail: key types, encoding, parameter semantics, and illustrative examples. Despite its length, every section earns its place for a complex nested-object API.

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 and four parameters including complex nested objects, the description supplies strong coverage: use cases, supported algorithms, wire encoding, and parameter examples. It does not explicitly describe the response shape or error cases, but the hexBinary output note and detailed examples make the tool adequately invocable.

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 fully document parameters. It does this thoroughly with an Args section and concrete JSON examples for encryption_attributes and wrapped_key, clarifying key_identifier's dual role as working key or KEK and marking wrapped_key as optional.

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 with specific verbs and resources: encrypting cardholder data, PIN blocks, or sensitive payment fields, plus DUKPT and EMV session encryption. It distinguishes itself from sibling tools by naming supported key types and algorithm families, leaving no ambiguity about what it does.

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

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

The opening 'Call this when...' gives explicit use-case context, including DUKPT session encryption and EMV key-based confidentiality. It does not explicitly contrast with alternatives like decrypt_data or re_encrypt_data, so it stops short of full exclusionary 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?

With no annotations, the description carries the burden of behavioral disclosure. It clearly states that no AWS credentials are required and enumerates the returned information: key type, permitted operations, compatible APC calls, and PCI considerations. The word 'Returns' implies a read-only operation, though an explicit no-side-effects statement would make it even stronger.

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

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

The description is front-loaded with the trigger condition, followed by a compact return-value summary and a concise argument definition. There is no filler, and the example list earns its place because the parameter is an unconstrained string.

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

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

For a simple one-parameter lookup tool with no output schema and no annotations, this description covers when to call, what to pass, auth requirements, and what to expect in the response. The main gap is not describing behavior for invalid or unknown key usage codes.

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%, but the description compensates by defining key_usage as a TR-31 key usage code and providing examples such as TR31_P0_PIN_ENCRYPTION_KEY plus a list of valid-looking codes. This is adequate for a single required parameter.

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

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

The description states a specific verb and resource: it explains TR-31 key usage codes and answers 'which key type should I use for X?' It gives concrete example codes and clearly distinguishes itself from the CRUD/list siblings by promising per-code explanatory details.

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

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

It provides explicit trigger conditions: 'Call this whenever a TR-31 key usage code appears' or when someone asks which key type to use. It also notes that it works without AWS credentials. It does not explicitly name alternative tools or when-not-to-use, so it falls just 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?

With no annotations provided, the description carries the behavioral burden. It explains that all wrapping material lives inside key_material, that TR-34 requires an ExportToken from get_parameters_for_export, and that ECDH is needed for AES-192/256. It does not mention permissions, side effects, or whether the key remains in place, but the main behavioral traits and dependencies 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?

The description is long but appropriately so for a complex union-shaped parameter. It is front-loaded with the when-to-use statement, followed by compact illustrative examples and a clean Args section. Every element serves a purpose, and the code blocks earn their 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?

All parameters, wrapping variants, prerequisites, and algorithm-specific guidance are covered. The only notable gap is the lack of any description of the response shape or required permissions, and since no output schema is provided, that information would have improved completeness. Still, the description is strong for a complex 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 0%, so the description must fully compensate, and it does. It defines export_key_identifier as ARN or alias, explains key_material as a single-member union with concrete JSON examples for every export method, and documents export_attributes as optional with named members ExportDukptInitialKey and KeyCheckValueAlgorithm.

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

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

The description opens with an explicit trigger, 'Call this when distributing an APC-generated key to an external HSM or system,' and names the exact wrapping formats: TR-31, TR-34, RSA cryptogram, ECDH-derived, and AS2805. It also contrasts itself with import_key by noting there is no separate 'type' argument, making the tool's purpose unmistakable.

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

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

It gives a clear when-to-use statement and routes to the required companion tool, get_parameters_for_export, for obtaining the ExportToken. It also explicitly distinguishes the key_material parameter from import_key, and notes ECDH is needed for AES-192/256, which helps an agent decide the correct export method.

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 carries the behavioral transparency burden. It clearly states that the tool generates a request or response value and documents the relevant variants, but it does not disclose whether the operation has side effects, what it returns, or any output encoding. This is a notable gap for a cryptographic generation tool.

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

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

The description is front-loaded and logically structured, but the second paragraph repeats information from the first: 'Australian payment network' and 'node-to-node key exchange' appear twice. Trim redundancy would make it tighter.

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?

Parameter semantics and usage context are well covered, but there is no output schema and the description does not describe the return value format or any operation caveats. For a tool whose entire purpose is generating a validation value, the lack of return-value detail leaves 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 0%, so the description must fully compensate. It does: every parameter is explained, including the ARN/alias meaning of key_identifier and the exact enumerated values and meanings for kek_validation_type and random_key_send_variant_mask.

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 deliverable: generating an AS2805 Key Encryption Key validation value for node-to-node key exchange. It clearly differentiates this tool from sibling operations like generate_mac or generate_card_validation_data by specifying the exact cryptographic domain and output.

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 opens with an explicit 'Call this when implementing Australian AS2805 payment network key exchange', giving clear contextual guidance. It does not explicitly state when not to use it or name alternatives, but the intended use case is unambiguous.

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 carries the full burden and does so thoroughly: it discloses required key type, rejection of AES and NoRestrictions E0 keys, exact padding expectations, the fact that APC does not pad, and even the boto3 version constraint for UnionPay. This is a model of behavioral disclosure.

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

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

The description is long but genuinely dense, front-loading the purpose and then using structured sections for constraints, examples, and parameters. Every sentence and example adds decision-relevant value, so the length is justified.

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 description is nearly complete for selecting and invoking the tool: it covers key constraints, all parameters, scheme-specific behavior, and even version compatibility. The only gap is that, with no output schema present, it does not describe the exact response shape or returned fields beyond calling the result an ARQC/APC leg.

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 document each parameter itself. It does so completely: key_identifier is specified as ARN or alias, transaction_data as hex with padding requirements, major_key_derivation_mode with EMV_OPTION_A/B semantics, and session_key_derivation_attributes with per-scheme JSON examples and exclusions.

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

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

The description opens with a concrete purpose: mint a test/reference ARQC, and names specific use cases such as exercising an ARQC verification path, proxy differential testing, and cross-implementation checks. It also explicitly identifies itself as the inverse of verify_auth_request_cryptogram, making the distinction from the nearest sibling clear.

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

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

The description explains when this tool is appropriate — test-vector generation rather than normal issuer-side verification — and names verify_auth_request_cryptogram as the alternative operation. It also clarifies the asymmetric relationship with verification around AES vs TDES E0 keys, which prevents misuse.

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 explains supported algorithms, key types, and optional output-length override, but it does not state whether the operation is non-mutating, whether it consumes key usage, or what permissions are required. This is adequate but leaves side-effect profile implicit.

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 well-organized and front-loaded with usage scenarios, then supported types, examples, and parameter definitions. The examples are necessary because generation_attributes is an untyped nested object. It is slightly longer than strictly necessary, with some redundancy between the opening scenarios and the generation sentence, but every section earns its place.

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

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

For a complex tool with nested parameters, no annotations, and no output schema, the description covers input semantics thoroughly and gives realistic invocation examples. It does not explicitly describe the returned value shape or the precise effect of validation_data_length, which are minor gaps given the clear generate-oriented purpose.

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 input schema has 0% description coverage, so the description must compensate, and it does excellently. It defines key_identifier as ARN or alias, constrains PAN length to 12-19 digits, explains generation_attributes, and provides concrete JSON examples for CVV, CVV2, iCVV, and ARQC. This adds meaning far beyond the bare schema.

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

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

The description clearly names the operation as generating CVV, CVV2, iCVV, or dynamic card verification values, with specific supported key types. This distinguishes it from verification and MAC tools in the sibling list and leaves no doubt about the tool's primary purpose.

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 gives explicit trigger scenarios: implementing card personalization, generating CVV variants, producing test vectors before production code, and validating card data for testing. It does not explicitly name alternatives like verify_card_validation_data or state when not to use this tool, 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?

With no annotations, the description carries full behavioral burden and meets it: it discloses that CMAC always returns the full 16-byte MAC regardless of mac_length, that BIDIRECTIONAL DUKPT is only valid for AES and causes ValidationException with TDES, and that DUKPT key variants have direction rules. It also shows supported algorithms through generation_attributes examples. This is far beyond a minimal description.

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

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

The description is long but densely organized: opening usage statement, key-type summary, generation_attributes examples, DUKPT rules, CMAC caveat, and an Args block. Every section adds operational information an agent cannot infer from the bare schema. The most important usage context is front-loaded before the technical details.

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 four parameters, nested objects, zero schema coverage, and no output schema, this description covers algorithm selection, key constraints, DUKPT derivation variants, MAC length semantics, and an important truncation edge case. It even routes to verify_mac for the associated verification workaround. There is no obvious missing information needed to call the tool correctly.

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

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

Schema coverage is 0%, so the description must explain every parameter, and it does: key_identifier receives an ARN/alias plus valid key types, message_data is hex-encoded, generation_attributes gets algorithm-specific JSON examples, and mac_length is explicitly defined in nibbles rather than bytes with 8/16 examples. This fully compensates for the empty schema descriptions.

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

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

The description opens with a specific call-to-action: generating or validating MACs for ISO 8583 transactions, EMV issuer scripts, and payment message authentication. It lists concrete key types and ISO 8583 fields (64/128), and its closing note references verify_mac, helping an agent distinguish generation from verification. This is more specific than the bare tool name and clearly differentiates from siblings like verify_mac.

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

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

It explicitly says 'Call this when implementing or validating MAC generation...' and even names a secondary use ('verify which MAC algorithm a given M-key type supports'). It provides key-type preferences and points to verify_mac for truncated-CMAC validation scenarios. It stops short of explicit when-not-to-use statements for every sibling, but the targeted context is strong.

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 carries the full behavioral burden. It clearly discloses that three separate keys are required, assigns roles to P0/E2/E1, and calls out that ISO_FORMAT_4 is unsupported. It does not mention the return value or failure modes, but the key and format constraints are well covered.

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 well structured with a clear call-to-action, important warning, key-type summary, and argument list. There is some redundancy between the 'Required key types' block and the Args section, but for a high-stakes cryptographic operation the repetition reinforces critical constraints without becoming rambling.

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

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

Given the complexity—7 required parameters, a nested object, no annotations, and no output schema—this description covers the essential decision points: when to call it, what prerequisites exist, and what each parameter means. The only notable gap is that it does not explicitly describe what the operation returns, which would be useful without an output schema.

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

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

Schema coverage is 0%, and the description compensates by explaining all seven parameters, including ARN/alias expectations and hex encoding. The main weakness is derivation_method_attributes, which is only described as 'Visa, Mastercard, etc.' rather than giving a precise structure or accepted values.

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: generating an EMV PIN change MAC for issuer scripts, CHANGE REFERENCE DATA (INS=24), or offline PIN change MAC assembly. It also distinguishes itself from single-key EMV MAC helpers, making the tool's purpose and scope 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?

Explicitly instructs when to use the tool: 'Call this before implementing any EMV PIN change flow.' It also states when it is not sufficient—single-key EMV MAC helpers (E2 only) cannot replicate this—and explains that all three key types must be provisioned in APC separately.

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 carries the behavioral burden and largely succeeds: it discloses supported schemes with JSON shapes, required key types (V1/V2 PVK, P0 PEK or wrapped KEK), and the ISO_FORMAT_1 PAN exception. It omits the exact response structure and error/side-effect conditions, but the core operational behavior is clearly conveyed.

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

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

The description is long, but its length is justified by the tool's complexity. It front-loads trigger conditions, then uses compact structured examples and an Args list so each sentence earns its place.

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

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

For 7 parameters, nested generation_attributes, and four PIN block formats, the description covers scheme variants, key mapping, and PAN/format special cases. The main gap is the absent output schema and no explicit response-field or error documentation, which prevents a full 5.

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 0%, so the description must compensate, and it fully does. Every parameter receives operational meaning: ARN/alias key identifiers, scheme-specific generation_attributes examples, accepted PIN block formats, PAN length and requirement rules, PIN length range, and wrapped-key behavior. This far exceeds the bare input schema.

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

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

States a specific verb/resource: IBM 3624 and Visa PVV PIN generation, PIN offsets for card personalization, and test PIN block production. The algorithm-specific contexts and 'issuer function' qualifier distinguish this from sibling translation/verification tools even without naming them.

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 opens with 'Call this when' and gives three concrete use cases, plus warns that it is an issuer-side function to use with care in acquirer contexts. It does not explicitly say when to use translate_pin_data or verify_pin_data instead, so the when-not guidance is somewhat implicit.

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 carries the burden of behavioral disclosure. It conveys read-only retrieval and alias-to-ARN resolution, but it omits details about response contents, error behavior for missing aliases, or permission requirements. This leaves some uncertainty for an agent.

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 three short sentences with the use-case guidance front-loaded before the plain operation statement and parameter details. There is no filler or redundant information beyond a minor restatement of the tool's purpose.

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

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

For a simple one-parameter tool, the description is mostly complete: it explains when to call it and how to format the argument. However, with no output schema and no annotations, it does not explicitly describe the return value structure or failure modes, so an agent must infer some behavior from the tool name and purpose.

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?

Although schema description coverage is 0%, the description explicitly documents the only parameter: alias_name must be the full alias including the 'alias/' prefix. This adds critical format guidance that the schema lacks and fully compensates for the missing schema description.

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 operation—resolving an alias to its key ARN or verifying the key an alias currently points to—and clearly identifies the resource (alias). This distinguishes it from sibling tools like list_aliases, which handle broader listing rather than point-in-time alias resolution.

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 first sentence explicitly tells the agent when to call this tool: when resolving an alias or verifying which key an alias points to. It does not name alternative tools or state when not to use it, but the context is clear enough for this simple get operation.

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 carries the load and does disclose the key behavioral trait: the private key remains in the HSM and only the CSR leaves. It stops short of stating permissions, side effects, or return format, but the core safety-relevant behavior is explicit.

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

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

Purpose, security context, and parameter details are each given a concise block, front-loaded with the core purpose. No filler or repetition; the Args section is well-organized.

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 3-parameter tool with no schema descriptions or output schema, the description covers what the tool does, why it is used, what the output is (a PKCS #10 CSR), and exactly how to populate every parameter.

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 this is the only place parameters are documented. It explains key_identifier's ARN/alias format, signing_algorithm's allowed hash values, and certificate_subject's required vs optional fields with an example JSON object.

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 opens with a specific verb and resource: 'get a PKCS #10 CSR for an APC-held asymmetric key.' It clarifies the deliverable is a CSR, not a certificate, and even names the payShield/Futurex counterpart, making it easy to tell apart from sibling certificate/key operations.

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?

States when to use it: when an external CA or partner PKI must issue a certificate, with typical TR-34 and ECDH scenarios. It does not explicitly say when not to use it or name alternatives such as get_public_key_certificate, but the context is clear.

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

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

With no annotations, the description carries the full behavioral burden. It clearly frames the operation as a read-only inspection ('Call this to see') and adds meaningful semantic context about account-level defaults and inheritance for keys created or imported without explicit replication_regions. It does not mention output shape or permissions, but for a zero-parameter read operation this is sufficient.

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 sentences deliver the core action first, followed by the key semantic detail about inheritance. No filler or redundant wording.

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 getter with no output schema, the description is complete. It tells the agent why to call it, what it observes, and how the observed default behaves. Nothing essential 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 has zero parameters, so the baseline is 4. The schema is already complete with an empty properties object, and the description adds relevant context about what the default applies to without needing to explain any parameter syntax.

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: 'see which regions new keys replicate into by default.' It also distinguishes this read-only getter from sibling enable/disable tools by framing it as an inspection action rather than a configuration change.

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 gives explicit usage context: 'before creating keys or when auditing why a key landed in a region you did not expect.' It does not explicitly name alternatives or exclusions, but the context is clear enough for an agent to decide when this tool is appropriate.

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 carries the full burden for behavioral disclosure. 'Retrieve metadata' clearly implies a read-only operation, and listing the metadata fields gives useful context about what the tool exposes. It does not explicitly state that no mutation occurs or describe permission requirements, but for a getter tool the side-effect profile is 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?

The description is concise, front-loaded with the use case, and contains no filler. The three short sections—when to call, what it does, and the parameter format—each earn their 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 simple one-parameter getter with no output schema and no annotations, the description covers when to use it, what metadata is returned, and how to identify the key. It could add a brief note on return shape or explicitly distinguish itself from sibling getters, but nothing critical 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 coverage is 0%, so the description must compensate, and it does. The Args section explains that key_identifier accepts a full ARN (arn:aws:payment-cryptography:...) or an alias (alias/name), which is exactly the information an agent needs beyond knowing the parameter is a string.

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

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

The description names a specific verb ('Retrieve metadata'), a clear resource (a key), and the lookup method (by ARN or alias). It also lists the metadata dimensions (state, algorithm, usage, enabled status), which clearly differentiates it from get_alias and list_keys.

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 first sentence explicitly states when to call the tool: when you need the key's current state, algorithm, usage, or enabled status before using it in an operation. It does not explicitly name sibling alternatives or state when not to use it, so there is a small exclusion gap.

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 carries the burden and mostly delivers: it specifies the returned MpaTeamAssociation fields, the conditional MpaStatus block, and the state values including settling states. It does not describe error behavior or explicitly confirm no side effects, but the 'get' semantics and returned-state detail provide solid transparency.

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

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

The description is front-loaded with the core purpose, followed by usage, return shape, and parameter details. Every section earns its place and there is no filler or restatement of the tool name.

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

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

Because there is no output schema, the description compensates by documenting return values in detail. It covers purpose, usage, parameter, and output. The only notable gap is the representation when no MPA association exists, which an agent checking gating status would need to interpret.

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 0%, so the description must explain the action parameter. It does: 'The operation to inspect' plus a concrete example, IMPORT_ROOT_PUBLIC_KEY_CERTIFICATE. It stops short of enumerating allowed values or where to find them, but it adds meaning the bare string schema lacks.

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 concrete verb ('check') and a specific resource (MPA team association), and identifies the exact questions answered: whether an operation is under MPA, which team approves, and whether changes are settling. This distinguishes it from mutation siblings like associate_mpa_team and disassociate_mpa_team.

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

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

'Use it before an import that may be gated, and when auditing dual control' gives concrete scenarios for calling this tool. It does not explicitly state when not to use it or name alternatives, but the read-only nature and sibling set make the intended context clear.

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

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

With no annotations provided, the description carries the full behavioral burden. It discloses a key side effect: default false 'mints a new token on every call,' and explains the reuse condition requiring same key material type/algorithm with at least 7 days of validity. This is valuable behavioral context beyond the schema, though it does not fully describe the return value or failure modes.

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 well-structured and front-loaded: the first sentence states the critical sequencing rule, and the Args list is compact and informative. Every sentence adds value, with no filler or repetition of schema 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?

Given no output schema and no annotations, the description covers preconditions, parameter choices, default behavior, and reuse guidance. It only lightly implies the return value (the export parameters/signing certificate) and does not describe the exact output shape expected by export_key, but the tool name and context make it reasonably inferable.

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 compensate, and it does. It documents all three parameters with concrete accepted values for key_material_type and signing_key_algorithm, and explains the default behavior and intended usage of reuse_last_generated_token in detail. This goes well beyond the bare type/title info in the schema.

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

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

The description clearly identifies the tool as the prerequisite step for export_key when using TR-34, specifying that it provides APC's signing certificate needed for constructing an export payload. This differentiates it from the related export_key and get_parameters_for_import siblings by stating its exact role in the export flow.

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 gives explicit context on when to call the tool ('before export_key when using TR-34') and provides conditional guidance for setting reuse_last_generated_token to true when retrying or building multi-step payloads. It does not explicitly describe when not to use the tool or name direct alternatives, so it falls just short of full usage coverage.

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 carries full behavioral burden and delivers: APC-enforced key-strength validation rules, the failure mode ('Attempting RSA_2048/RSA_3072/RSA_4096 with an AES-256 key will fail'), and the side-effect semantics of the default token behavior ('Default false, which mints a new token on every call'). Only a precise response-format disclaimer is missing, but the return value is described at a useful level.

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 most critical instruction is front-loaded ('Call this before import_key'), followed by a scannable rules list and then argument details. It is long, but every section earns its place — the key-strength rules prevent a common invocation error given the schema's lack of enums. Slight redundancy between the AES-256 callout and the general rules list, but not 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?

For a 3-parameter tool with no annotations, no output schema, and 0% schema description coverage, the description covers prerequisites, valid inputs, constraints, failure conditions, and the alternative path. The only meaningful gap is that the exact response shape is not specified (no output schema exists), so an agent must infer the field names of the returned wrapping key and import token for the subsequent import_key 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 description coverage is 0% and no enums exist in the schema, yet the description fully compensates: it enumerates all accepted values for key_material_type (5 values) and wrapping_key_algorithm (4 values), ties algorithm choice to key-strength requirements, and explains the boolean's behavior with a concrete usage recommendation. Without this text, the tool would be uncallable correctly.

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 ('you need APC's public wrapping key and import token before constructing the import payload') and a precise calling relationship with a named sibling ('Call this before import_key'). It clearly distinguishes this from both import_key (which it feeds) and get_parameters_for_export (the export counterpart) without 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?

Explicitly states when to use it ('Call this before import_key when using TR-34 or KeyCryptogram') and gives an explicit alternative with a decision condition ('Alternative: use create_key... no import needed, but the key value is not externally known'). An agent knows exactly when this tool is required and when to route elsewhere.

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 present, so the description carries the full burden. It explicitly discloses that only public material is returned, private keys are never exposed, and the certificate/chain are base64-encoded. This is valuable behavioral and safety information beyond what the input schema reveals.

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 compact and front-loaded: the call intent appears immediately, followed by return format and parameter semantics. Every sentence contributes useful information, with no fluff or repetition.

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 tool with no output schema and no annotations, the description covers the essential context: what is returned, encoding, public-only guarantee, and parameter format. Minor gaps like potential errors or the exact shape of the chain are not critical for correct invocation.

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 add meaning. It does so by explaining that key_identifier accepts an ARN or alias of the asymmetric key, which is essential semantic information. It could add examples or clarify alias formats, but it sufficiently compensates for the schema gap.

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

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

The description uses a specific verb ('fetch') and identifies the exact resource: the certificate and chain for an APC asymmetric key. It further clarifies the purpose (handing the public half to a counterparty for TR-34/ECDH, or checking current APC-held material), making it distinguishable from related sibling tools like get_key or get_certificate_signing_request.

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 gives clear, concrete use cases: fetching public key material for TR-34/ECDH exchanges or checking what APC currently holds. It does not explicitly state when not to use this tool or name alternatives, so it stops short of a 5, but the context provided is sufficient for most selection decisions.

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

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

The verb 'Retrieve' and the context 'auditing/inspecting' communicate a read-only operation, with no annotations provided. However, the description adds no detail about permissions, response shape, or behavior when no policy exists, so it only partially covers what the agent needs.

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 compact, front-loaded with the usage trigger, and every sentence contributes information. The Args line is minimal and fits the single-parameter schema.

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

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

For a simple one-parameter getter with no output schema or annotations, the description gives purpose, trigger, and parameter semantics. It lacks return-value formatting and error behavior, but these are minor for this read-only retrieval.

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 0% schema description coverage, the 'Args: resource_arn: Key ARN' line is the only documentation of the parameter. It usefully clarifies that the ARN belongs to a key rather than a generic resource, though it stops short of specifying format or constraints.

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

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

The description uses a specific verb and resource: 'Retrieve the resource policy attached to a key.' This clearly distinguishes it from sibling tools like get_key (key metadata) and put_resource_policy/delete_resource_policy (mutations).

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

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

It explicitly says when to call it: 'when auditing who has access to a key or inspecting a cross-account policy.' It does not name alternatives or when-not conditions, but the stated context makes the intended use clear.

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

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

With no annotations provided, the description carries the full behavioral burden and largely delivers: it discloses that no AWS credentials are required, enumerates the exact command formats detected, and states the three output categories. It stops short of disclosing whether the supplied source code is processed locally or transmitted externally, and says nothing about size limits — meaningful traits for a tool that ingests raw code.

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

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

The description is front-loaded with the usage trigger, then moves through scope, auth, detection capabilities, and returns — a logical order with zero filler. The Args section cleanly separates parameter definition from behavioral prose. Every sentence contributes distinct information, so the length is fully earned.

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 analysis tool with no output schema, the description covers the essentials: trigger conditions, input format, detection scope, and a qualitative account of return values (identified commands, APC migration path, migration notes). It omits the no-match behavior and any output structure, which an agent may need when branching on results — strong, but not exhaustive.

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 compensate, and its Args section defines source_code as 'Raw source code containing HSM socket calls or command strings,' adding both type and relevance guidance. The main body adds language and scale guidance (any language, single file/function suffices). With only one parameter, this level of detail is sufficient for correct invocation.

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

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

The opening line states a precise trigger and resource: analyzing legacy payment code for HSM socket calls, with explicit language coverage. It differentiates itself from the closest siblings by input type — raw source code rather than a discovery log (hsm_analyze_discovery_log) or a single command lookup (hsm_lookup_command). The detection targets and return values are concrete, so an agent knows exactly what this tool does.

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

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

'Call this whenever reviewing legacy payment code that may contain HSM socket calls' is an explicit when-to-use trigger, reinforced by the low-cost signal 'Even a single file or function is worth scanning.' However, it never names sibling alternatives or when-not-to-use cases, so the agent must infer the boundary with hsm_analyze_discovery_log and hsm_migration_notes from context rather than being told.

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 and meets it: it discloses the auth expectation ('Works without AWS credentials'), the redaction behavior of sensitive fields, and — critically — the IMPORTANT caveat that handler_exists reflects _PROXY_HANDLERS in hsm_tools.py, not the proxy source tree, and may be stale until an update is committed and the server restarted. That staleness gotcha is exactly the kind of non-obvious behavior an agent must know to interpret results correctly.

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

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

The description is longer than average but every section earns its place: purpose is front-loaded, the critical staleness caveat is visually highlighted with IMPORTANT, and the line-format spec supports the single parameter. Minor redundancy exists between the output summary and the caveat, but nothing is wasted.

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

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

For a single-parameter analysis tool with no output schema, the description is complete: it states when to call, what to pass, what the return covers, the credential expectation, and the one behavioral trap that could mislead users. Nothing an agent needs to invoke 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?

Schema description coverage is 0%, so the description must fully compensate, and it does: it defines log_content as 'Full text of the discovery.jsonl file (newline-delimited JSON)' and additionally documents the per-line JSON object schema (vendor, cmd, params, payload_len) with examples. An agent knows exactly what to pass and what the payload looks like.

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

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

The description names a specific verb (analyze), a precise resource (apc-hsm-proxy discovery-mode output, a discovery.jsonl file), and the concrete outputs (per-command APC mappings, existing handlers, handlers needing work, migration notes). It is clearly distinguishable from siblings like hsm_analyze_code (code analysis) and hsm_get_apc_mapping (single mapping lookup) because the scope is pinned to a discovery log.

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 opening phrase 'Call this when analyzing the output of apc-hsm-proxy running in discovery mode' gives an explicit triggering condition tied to a specific artifact type. It does not name alternatives or state when not to use it, but the discovery.jsonl condition is precise enough that an agent can route correctly among the analysis siblings.

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

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

No annotations are provided, so the description carries the behavioral disclosure burden. It clearly conveys that this is a lightweight read-only lookup, states exactly what it returns, and notes that no AWS credentials are required. It does not describe behavior for unknown command codes, keeping it from a perfect score.

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 compact and front-loads the most important routing information before the return behavior and parameter documentation. Every sentence earns its place, and the sibling comparison is concise rather than redundant.

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

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

For a simple one-parameter lookup tool, the description is complete: it explains when to use it, what it returns, and the credential requirement. There is no output schema, but the description names the returned fields clearly enough for an agent to understand the result.

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

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

Schema description coverage is 0%, but the description compensates by explaining command_code as 'The HSM command code' and giving concrete examples ('TPIN', 'CA', '31'). It does not specify exact format or validation rules, but with a single required parameter, the provided semantics are sufficient for effective use.

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

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

The description opens with a specific verb and object ('command-code → APC operation lookup') and narrows the tool's output to 'the APC operation and key type.' It explicitly contrasts with hsm_lookup_command, so an agent can disambiguate the tool immediately.

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 gives explicit when-to-use guidance: use this when you already know the command and only need the migration target, and prefer hsm_lookup_command when you need the full description and notes. It also notes the tool works without AWS credentials, which is a clear contextual signal.

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 present, the description carries the behavioral disclosure burden. It explicitly says the tool works without AWS credentials and describes the listing/filtering behavior. It does not disclose details like pagination or output format, but for a read-only discovery tool the provided context is strong.

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 compact, front-loaded with the core purpose, and organized into a purpose paragraph followed by a concise argument list. Every sentence contributes meaningful guidance with 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 two-optional-parameter listing tool, the description provides enough context to select and invoke it correctly. It covers the tool's purpose, parameter semantics, and authentication expectation. The absence of an output schema is partially mitigated by the description making the return concept clear, though explicit output structure or pagination notes would make it 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?

The schema provides only parameter names with no descriptions or enums, so the description fully compensates. It enumerates valid values for category (PIN, MAC, CVV, KEY_MGMT, ENCRYPT, ARQC, P2PE) and vendor (Futurex, Thales), and explains the omit-for-all default behavior for both.

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 action: discover known HSM commands and their APC operation mappings. This clearly distinguishes it from siblings like hsm_lookup_command or hsm_get_apc_mapping by framing it as a discovery/list operation rather than a single-command or mapping lookup.

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 gives clear when-to-use context: migration scoping, HSM integration review, and deciding which APC operations a proxy handler must implement. It also notes that no AWS credentials are required. However, it does not explicitly contrast this with sibling tools or state when to prefer them.

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 exist, so the description carries the burden. It discloses that no AWS credentials are required, specifies vendor coverage quality (authoritative vs directory-level), and lists output fields. It does not discuss failure modes, rate limits, or whether invalid codes return empty results, but the behavioral profile is otherwise well communicated.

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

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

The description is front-loaded with the trigger condition, followed by examples, coverage notes, and an Args section. Every sentence adds useful information and there is no filler or repetition.

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 appropriately explains return fields and scopes the tool's coverage. It lacks explicit handling for unknown codes or an API-specific behavior note, but for a lookup utility the essential context is present.

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

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

Schema description coverage is 0%, so the description must compensate. It does: command_code gets concrete examples and api gets allowed values ('Excrypt', 'Standard', 'International'). It could add case-sensitivity or accepted formats, but the provided semantics are materially richer than the bare schema.

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

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

The description uses a specific verb-resource pair ('lookup HSM command code') and immediately illustrates with concrete examples (TPIN, CA, 31). It also states exactly what is returned (command name, category, description, APC operation + key type), distinguishing it from sibling tools like hsm_list_commands or hsm_analyze_code.

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 explicit triggering conditions ('Call this whenever you see an HSM command code in legacy payment code, documentation, or logs') and notes it works without AWS credentials. It does not explicitly contrast with alternatives like hsm_analyze_code or hsm_list_commands, so no when-not guidance is provided.

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 carries the full burden of behavioral disclosure. It usefully states 'Works without AWS credentials' and says the tool 'Returns detailed migration guidance,' signaling a read-only informational behavior. It does not describe the detailed output structure, but for a notes/guidance tool this is reasonably transparent.

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 brief and well-structured: the invocation scenario is front-loaded, the exclusions are given, and the single argument is documented inline. No sentence is wasted.

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

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

For a one-parameter informational tool with no output schema and no annotations, the description covers the purpose, the exact allowed topics, the kind of return value, and the credentials requirement. Nothing essential is missing for an agent to select and invoke it correctly.

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

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

The schema only declares a required string 'topic' with 0% description coverage and no enums. The description compensates fully by listing the only valid values: 'lmk', 'dukpt', and 'fixed_key', making the parameter unambiguous and directly actionable.

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 use case ('Call this when discussing HSM migration for concepts that have no direct APC equivalent'), enumerates the exact topics covered, and says it returns detailed migration guidance. This clearly identifies the tool's action and resource, distinguishing it from the operational key-management 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?

It gives an explicit trigger condition ('when discussing HSM migration for concepts that have no direct APC equivalent') and lists the specific topics that warrant calling it. It does not explicitly name sibling alternatives or state when not to use it, but the 'no direct APC equivalent' phrasing implies an exclusion boundary.

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 carries the full burden, and it delivers. It explicitly warns that a successful response may not mean the key is imported, explains the MpaStatus PENDING scenario, tells the agent to check MpaStatus before using the key, and directs polling get_key. It also discloses that requester_comment appears in CloudTrail in plaintext. These are exactly the non-obvious behaviors an agent needs.

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

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

The description is long, but every section earns its place. The critical MPA warning is front-loaded immediately after the purpose, followed by compact parameter semantics and concrete JSON examples. The structure is scannable and avoids 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?

Given the complexity, no annotations, and no output schema, the description is notably complete: it covers the external-key import purpose, both formats, prerequisites, MPA status behavior, validation constraints, optional parameters, and even a privacy caution. An agent has enough context to invoke the tool correctly and interpret the 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 description coverage is 0%, so the description must compensate, and it does thoroughly. It gives full key_material dict shapes for both TR-31 and TR-34, enumerates valid key_check_value_algorithm values with AES/CMAC constraints and the HMAC caveat, explains enabled, tags, replication_regions, and requester_comment, including the 200-character limit. Every parameter gains meaning beyond the raw schema.

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

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

The description opens with a specific verb and resource: 'bring an externally generated key into APC via TR-31 key block or TR-34.' This clearly distinguishes import_key from sibling tools like create_key, which would generate a key internally rather than importing external material.

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 gives clear context: it is for externally generated keys, specifies the two supported import methods, and references get_parameters_for_import as a prerequisite for TR-34. It also explains the Multi-Party Approval flow and when to poll get_key. It does not explicitly contrast with create_key or state 'use create_key instead for internally generated keys,' so it stops short of a full when/when-not comparison.

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 behavioral disclosure burden. It conveys that this is a read-style listing operation, but it does not describe response structure, pagination behavior beyond the next_token parameter, or whether the key_arn filter is exact or partial. This is adequate but has clear gaps.

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 and front-loaded with usage context, then lists parameters compactly. There is minor redundancy between 'Call this when auditing...' and 'List aliases...', but no wasted or bloated content.

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 list tool with optional filters, the description covers the main use cases and parameter semantics. It does not describe the return payload, but since there is no output schema and the tool is named list_aliases, the absence is not a critical 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 0%, so the description must explain all parameters. It does: key_arn filters, max_results bounds results to 1-100, and next_token handles pagination. This adds meaningful functional meaning beyond the bare schema titles.

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 lists aliases and can filter by key ARN. It also distinguishes itself from sibling alias tools like create_alias, get_alias, update_alias, and delete_alias by framing the operation as an audit/list 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 explicitly says to call this when auditing all friendly names in the account or finding aliases associated with a specific key. It does not explicitly name alternative tools or exclusions, but the usage context is clear enough among the sibling tools.

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

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

With no annotations provided, the description must carry the behavioral disclosure burden. It adds useful context: the call does not require AWS credentials, which is important operational information, and it describes what is returned. It does not mention pagination or potential rate limits, but for a zero-parameter list operation this is adequate.

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 three short sentences, each with clear value: when to use the tool, the credential requirement, and the return content. Usage guidance is front-loaded and no filler is present.

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 tool with an output schema, the description covers all essential facets: appropriate invocation scenarios, credential requirements, and the nature of the returned data. An agent has enough information to select and call this tool correctly.

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

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

The tool has zero parameters, so the rubric baseline is 4. The description correctly adds no parameter-specific details because there are none to explain.

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 a specific verb and resource: list all TR-31 key usage codes with names, descriptions, and APC support status. This is a directory-style lookup, which sets it apart from sibling tools that create, modify, or explain individual keys.

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

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

It provides explicit contexts for when to call it: designing key infrastructure, selecting key types for payment operations, or answering questions about APC-supported key types. However, it does not name alternatives or explicitly state when not to use it, so it falls short of a perfect 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?

With no annotations provided, the description carries the burden of behavioral disclosure. It implies a read-only listing operation but does not explicitly state that it has no side effects, nor does it describe response behavior or limitations beyond the schema-adjacent argument notes. The provided state values and pagination token are useful context, but the behavioral envelope is only partially described.

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

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

The description is compact and front-loaded with the most important usage signal, followed by a one-line operation summary and a short parameter list. Every sentence earns its place, with no repetition, fluff, or unnecessary detail.

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

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

The definition provides enough to select and invoke the tool correctly: when to use it, what the parameters mean, and how pagination works. It is slightly incomplete because there is no output schema and no mention of what the response contains, but for a straightforward listing tool the missing return-shape detail is a minor 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 schema itself has 0% description coverage and only raw JSON types, but the Args section compensates fully: it enumerates the four allowed key_state values, specifies the max_results range (1-100), and explains next_token as a pagination token from a prior response. This is exactly the semantic value the schema lacks.

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 identifies the action ('List APC keys') and resource, and frames the use case as auditing key existence, finding ARNs, or checking state. It is clear but does not explicitly contrast with siblings like get_key or list_aliases, so it misses the top score.

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 opening sentence gives explicit conditions for use: auditing existing keys, finding a key ARN, or checking key state before an import/operation. However, it does not state when not to use it or name alternative tools for those cases, so it is strong but not fully prescriptive.

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 shoulder the burden of behavioral disclosure. It only says the tool lists tags; it omits read-only guarantees, response shape, pagination mechanics, error behavior, and permission requirements.

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 compact and front-loaded: a usage cue comes first, then the core purpose, then concise parameter notes. Every sentence contributes without repetition or filler.

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

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

For a three-parameter tool with no annotations and no output schema, the description covers the core use case and all inputs adequately. It leaves gaps around output format, permissions, errors, and pagination behavior, so it is functional but not deeply 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?

The schema has 0% description coverage, but the Args block provides a one-line meaning for every parameter, including the max_results range and next_token pagination purpose. It adds value, though it lacks details like ARN format or how pagination tokens should be used across calls.

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: 'List all tags on an APC key.' It also frames the operation as auditing or verifying classification metadata, which clearly distinguishes it from sibling tag-mutation tools like tag_resource and untag_resource.

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

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

It explicitly says 'Call this when auditing the tags on a key or verifying classification metadata,' giving a clear when-to-use signal. However, it does not explicitly name alternatives or state when not to use the 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?

With no annotations, the description carries the burden. It states the tool 'works without AWS credentials' and 'returns' a rule, implying a read-only advisory with no side effects. This is sufficient transparency for a zero-parameter advisory tool, though it does not explicitly declare non-mutating 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 compact and front-loaded: the primary use case is stated first, followed by the credential note and the returned rule. Every sentence contributes meaningful information with no redundancy.

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

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

For a zero-parameter advisory tool with no output schema, the description fully covers what the tool is for, when to call it, credential requirements, and what rule it returns. No critical information 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 has no parameters, so there is nothing for the description to explain. The schema coverage is 100% and the description adds useful context about when the advisory applies, which 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?

Clearly states what the tool does: returns the PCI PIN rule that the PAN must not change during PIN block translation. It also identifies when it applies (PIN translation flows with differing PAN formats, PCI PIN Req 3-3 / ISO 9564 questions), distinguishing it from transactional siblings like translate_pin_data.

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

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

Explicitly explains when to call it: before implementing PIN translation flows where PAN may differ, or when asked about specific PCI/ISO requirements. It does not mention alternatives or exclusions, but the niche advisory purpose makes the use context clear enough.

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 the disclosure burden. It clearly states the tool 'Returns the PCI PIN Req 4 rule', including the key prohibition that even encrypted PIN blocks may not be retained after the authorization response. It also discloses the credential-free behavior, which is useful operational context for a zero-parameter advisory tool.

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

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

Three short, purposeful sentences. The usage trigger is front-loaded, the credential requirement is stated compactly, and the precise advisory content is delivered in the final sentence. No wasted words or repetition of schema fields.

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 advisory tool with no output schema, the description fully covers what the tool does, when to call it, and what it returns. An agent can correctly select and invoke this tool without needing additional structural or behavioral explanation.

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 has zero parameters and 100% schema description coverage, so the schema needs no explanation. The description adds context about when and why to call the tool, though it does not need to describe any parameters since none exist.

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

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

States a specific verb ('Call this before designing...') and a precise resource: transaction logging, audit trails, and database schemas handling ISO 8583 field 52 PIN blocks. It also names the returned content (PCI PIN Req 4 rule), making the tool's advisory purpose unambiguous and distinct from the surrounding KMS/data-operation 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 an explicit when-to-use condition: before designing any logging, audit trail, or database schema that processes ISO 8583 field 52. It also notes that no AWS credentials are required, which helps an agent avoid unnecessary auth setup. It does not explicitly name alternatives or state when not to use it, but the usage context is clear.

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

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

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It explains the general effect—attaching a policy—but does not disclose that this likely replaces an existing policy, whether permissions are required, or what side effects occur. This is a meaningful gap for a mutation tool.

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

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

The description is compact and front-loaded with the main usage trigger, followed by the action and argument hints. Every sentence contributes value, with no filler or redundant restatement of the tool name.

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 description covers when, what, and the arguments, making it minimally usable. But for a mutation tool with no annotations and no output schema, it should also mention overwrite behavior, required permissions, or what the response contains. These omissions leave the definition incomplete.

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 Args section adds needed meaning: resource_arn is a Key ARN and policy is a JSON policy document string. However, it provides no deeper semantics such as policy syntax requirements, size limits, or examples, so it only partially compensates for the bare schema.

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

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

The description clearly states what the tool does: 'Attach an IAM resource policy to a key.' It also names the specific use cases—granting cross-account access or restricting principal usage—which distinguishes it from sibling tools like get_resource_policy and delete_resource_policy.

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 opens with explicit 'Call this when...' guidance for two clear scenarios. It does not explicitly mention when not to use it or name alternative tools, but the usage context is clear enough for an agent to select it appropriately.

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 transparency burden. It discloses the most important behavioral property: 'The plaintext never leaves the HSM boundary' and 'The decryption and re-encryption occur entirely within the APC HSM boundary.' It does not cover permissions, error behavior, or key-state constraints, but the security-boundary disclosure is meaningful and non-obvious.

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 well-structured: usage context first, then a one-line functional definition, then an Args block. It earns its place, though there is some redundancy in repeating that plaintext never leaves the HSM boundary ('without exposing plaintext' and 'occur entirely within the APC HSM boundary' say essentially the same thing in close proximity).

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 7-parameter cryptographic operation with no output schema and no annotations, the description covers when to use it, what it does, the security boundary, and parameter meaning. It is missing precise structure for the encryption-attributes objects and any expectation about the return value, but the provided context is sufficient for an agent to understand the operation and invoke it with mostly reasonable arguments.

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 argument documentation must compensate. The description adds real semantics for all seven parameters: ARN or alias identifiers, hex-encoded ciphertext, algorithm params, and optional TR-31 wrapped keys. It does not fully define the internal shape of incoming_encryption_attributes or outgoing_encryption_attributes, which remain vague 'Algorithm params' objects.

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

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

The description opens with 'Call this when rewrapping payment data under a new key' and restates the operation as 'Re-encrypts data from one key to another without exposing plaintext.' This is a specific verb+resource statement that clearly scopes the tool to re-encryption of existing ciphertext, distinguishing it from siblings like encrypt_data, decrypt_data, and translate_key_material.

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

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

It provides explicit usage conditions with concrete examples: rotating zone encryption keys, moving data between security domains, and transitioning from TDES to AES. It does not explicitly name alternatives or say when not to use this tool, but the use-case framing makes the appropriate context clear.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It explains a significant consequence — the key becomes unusable in the removed region — and warns that in-flight PIN or ARQC traffic will fail. This is meaningful behavioral context beyond the bare schema.

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

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

The description is tight and well-structured: when to use, what happens, what to check first, then a clean Args block. Every sentence contributes useful information, and the most important behavioral warning is front-loaded.

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

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

For a two-parameter tool with no output schema and no annotations, the description covers the essential operational context: purpose, consequence, prerequisite check, and parameter semantics. It could add more about return values or error conditions, but it is sufficiently complete for correct invocation.

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 compensate. It does: key_identifier is explained as 'ARN or alias of the key', and replication_regions is clarified as 'Regions to remove' with a concrete example. This adds real meaning beyond the raw property names.

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 identifies the operation: removing replication regions from a key, with a specific verb ('removing') and resource ('region' / 'key'). It also states the intended use case (decommissioning a region or narrowing blast radius), making it easy to distinguish from sibling tools like add_key_replication_regions.

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 explicitly says when to call it ('when decommissioning a region or narrowing a key's blast radius') and adds a key caution about confirming nothing is still authorizing against the region. It doesn't explicitly mention alternatives or when not to use it, but the usage context is clear enough.

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 the full burden. It clearly discloses the precondition (key must be in DELETE_PENDING state), the timing constraint (before waiting period expires), and the core behavior of canceling the pending deletion. It does not detail post-restore state or side effects, but for this simple operation the behavior is well conveyed.

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 compact and front-loaded: the use case appears first, followed by the core action and a single parameter explanation. Every sentence contributes useful information with no repetition or filler.

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

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

For a simple one-parameter tool with no output schema, the description covers when to invoke it, the required key state, and the parameter format. It could mention what state the key returns to after restoration, but the information provided is sufficient for correct invocation.

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 compensate. It does by explaining that key_identifier accepts a Key ARN or alias and must refer to a key in DELETE_PENDING state, adding meaningful guidance beyond the bare schema property name.

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 verb-resource pair: 'Cancel a pending key deletion' and 'recover' a key scheduled for deletion. This makes the tool's purpose obvious and distinguishes it from sibling tools like delete_key, which schedules the deletion.

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 gives an explicit use case: call when a key was scheduled for deletion by mistake and needs recovery before the waiting period expires. It does not explicitly name alternatives or state when not to use other key-management tools, but the context is clear enough for correct selection.

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

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

There are no annotations, so the description carries the behavioral disclosure burden. It does disclose the core behavior — changing a key from disabled to active — but it does not mention permissions, reversibility, idempotency, or any side effects. This is adequate but not richly transparent.

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 short and front-loaded, but the second sentence ('Activate a key that was created in disabled state') largely repeats the first sentence's trigger condition. The Args section is useful, but one sentence is redundant.

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

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

For a simple single-parameter tool with no output schema, the description covers the key use case and parameter semantics well. It lacks only minor details like permissions and exact API behavior, which are not critical given the tool's low 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?

The input schema only says key_identifier is a string, but the description adds important meaning by specifying it accepts a key ARN or alias. This compensates for the 0% schema description coverage, though it could be even more explicit about accepted alias formats.

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 action — enabling or activating a key — and distinguishes this tool from siblings like stop_key_usage and create_key. It clearly identifies the resource and the state transition involved.

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 explicitly says when to call it: when enabling a key created with enabled=False or one previously disabled with stop_key_usage. It gives clear context, though it does not explicitly list when not to use it or name all alternatives.

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

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

With no annotations provided, the description carries the behavioral burden. It discloses that the key is deactivated rather than deleted and that the disabling is temporary, which is meaningful context beyond the tool name. It does not detail permissions, effects on in-flight operations, or re-enabling behavior, but the core state change is clearly communicated.

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 short, front-loaded with the most important usage context, and includes only necessary information. The Args section is compact and useful, with no filler or repetition.

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

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

For a one-parameter, no-output-schema state-change tool, this is complete. It explains when to use it, what action it performs, how it differs from deletion, and what the parameter should look like. Nothing needed for correct selection and 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?

The schema description coverage is 0%, so the description's 'Key ARN or alias' is essential. It tells the agent what kind of identifier to pass, which is not inferable from the schema's plain 'string' type. This fully covers the single required parameter.

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

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

The description clearly states a specific verb and resource: call this to temporarily disable or deactivate a key. It also explicitly distinguishes the action from deletion with 'without deleting it,' which separates it from sibling delete_key.

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 first sentence gives explicit when-to-use guidance: temporarily disabling a key, especially during key rotation before the old key is confirmed unused. It implies a reversible action, but it does not explicitly name the alternative start_key_usage for re-enabling, which would make the guidance fully complete.

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 burden of behavioral disclosure. It explicitly indicates an upsert behavior through 'Add or update tags', which is useful. However, it does not mention authorization requirements, tag limits, or consequences of adding a tag with an existing key.

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 compact and front-loaded with the key usage directive. Every sentence contributes useful information, and the Args section provides parameter semantics without unnecessary detail.

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

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

For a simple two-parameter tagging operation, the description covers both the when-to-use context and parameter meaning. The lack of an output schema is acceptable for a mutation tool, and no critical information seems missing for correct invocation.

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%, but the Args section compensates by explaining resource_arn as 'Key ARN' and tags as 'List of {Key, Value} dicts'. This adds meaning beyond the raw schema, particularly by clarifying the expected shape and purpose of the tags parameter.

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

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

The description clearly states the verb 'Add or update tags' and the resource 'APC key'. This makes it immediately distinguishable from sibling tools like untag_resource and list_tags_for_resource.

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

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

The opening call-to-action 'Call this when adding classification, environment, or ownership metadata to a key' gives clear context for when to use this tool. It does not explicitly mention when not to use it or name alternatives, but the usage scenario is specific enough for an agent to select it appropriately.

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 carries the burden of behavioral disclosure. It reveals a key security property: the translation happens 'without ever importing the working key into APC storage', and it labels the KCV parameter as optional. It does not mention permissions, failure modes, side effects, or return behavior, so it is not fully transparent.

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

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

The description is front-loaded with the invocation context and even includes complete payload examples, which earns the length. It is slightly redundant because the Args section repeats information already shown in the JSON examples, and the ambiguous 'APC format' sentence could be tightened or removed.

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 nested objects, no output schema, and no parameter descriptions in the schema, the example-rich description is unusually helpful. Still, it omits the return value/response shape, does not specify required subfields of KeyBlockHeaders or exact formats like DerivationData beyond '<hex>', and leaves error/edge-case behavior undocumented, so it is not fully complete for a complex crypto tool.

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

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

Schema coverage is 0% and the schema parameters are untyped objects, so the description is the only source of parameter meaning. It compensates thoroughly with full JSON examples showing the required nested fields for DiffieHellmanTr31KeyBlock and Tr31KeyBlock, plus the accepted KCV enum values.

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 core purpose is explicit: 'Translate an ECDH-wrapped TR-31 key block into a KEK-wrapped TR-31 key block', with a specific verb, resource, and result that distinguishes it from translation tools like translate_pin_data. However, the sentence about needing the key 'in APC format' is ambiguous and slightly muddies the otherwise clear ECDH → TR-31 (KEK) scope.

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 opens with 'Call this when implementing ECDH-based key agreement' and adds 'The only documented use case is ECDH → TR-31 (KEK)', giving explicit selection criteria and a limitation. It also offers concrete examples of incoming and outgoing key material, making the intended context unmistakable.

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 carries the full behavioral burden and meets it with meaningful details: the PIN is 'never exposed in clear text,' compliance rules are enumerated (PCI PIN Reqs 3-3 and 2-2), and the boundary condition 'inside the APC HSM boundary' is stated. It also discloses that fixed TDES PIN keys are prohibited since 2023, a time-sensitive constraint an agent must know. It stops short of describing output format, permissions, or error behavior, but the security and compliance context is strong.

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

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

The description is long but deliberately structured: usage trigger, operation summary, compliance rules, preferred flow, examples, then a compact Args list. It front-loads the most important decision cues. Some redundancy exists, such as 'core HSM operation' following the call-when clause, but overall it earns its length for a 10-parameter HSM tool.

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

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

For a complex 10-parameter tool with no annotations and no output schema, the description covers selection, security, compliance, parameter conditions, and format examples, which is unusually complete. The main gap is that it never states what the tool returns, so an agent may be unsure about the response shape. Despite that, the operational details are sufficient for correct invocation in the described scenarios.

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 compensates thoroughly: every parameter appears in the Args list with meaning, and conditional parameters are explicitly marked, e.g., 'Required when incoming key is a BDK (DUKPT).' The JSON examples illustrate nested structures for translation attributes, DUKPT, AS2805, and wrapped-key paths. This adds substantial meaning far beyond the bare schema.

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

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

The description opens with explicit when-to-use triggers and then states the operation: 'Translates a PIN block between encryption zones inside the APC HSM boundary.' This clearly distinguishes from sibling PIN operations like generate_pin_data and verify_pin_data by focusing on translation between zones. The verb 'Translates' plus the encryption-zone scope is specific and 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?

It gives explicit triggers: 'implementing acquirer PIN routing, verifying a PIN translation flow, or checking whether a given format-to-format translation is legal under PCI PIN.' It also describes the 'Preferred flow,' which guides input/output format selection. However, it never names sibling alternatives or states when to use generate/verify instead, so it lacks explicit exclusions.

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

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

The description clearly indicates the mutation: removing tags from a key. However, with no annotations present, it does not disclose potential side effects, authorization requirements, idempotency, or error behavior. It covers the core behavior but leaves some operational context unstated.

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 compact and front-loaded with the usage trigger, followed by a direct action statement and a short Args block. Every sentence contributes useful information, with no wasted text.

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 two-parameter mutation tool, the description plus input schema provides enough information to call the tool correctly. It does not describe the response format or edge cases, but the operation is straightforward and the absence of an output schema reduces that burden.

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 compensate. It provides concise meanings for both parameters: resource_arn is the key ARN and tag_keys is the list of tag key names to remove. This is sufficient for basic invocation, though ARN format details are not specified.

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 explicitly states the action: 'Remove tags from an APC key' and frames it with a clear trigger ('when removing stale or incorrect tags'). It clearly distinguishes itself from the sibling tag_resource, which adds tags rather than removes them.

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 first sentence provides direct guidance on when to call the tool: 'Call this when removing stale or incorrect tags from a key.' It does not explicitly name alternatives or exclusions, but the purpose and sibling context make the usage clear.

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

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

With no annotations provided, the description carries the behavioral burden. It clearly discloses that this mutates an alias-to-key association and explains the intended effect: application code referencing the alias picks up the new key automatically. It does not cover failure modes or permissions, but the core side effect is transparent.

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 short and front-loaded, but the second sentence repeats much of the first: 'Point an alias to a different key...' essentially restates 'point the existing alias to the new key ARN...'. The core message could be delivered in one sentence plus the parameter details.

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 two-parameter mutation with no output schema, the description is nearly complete: it covers purpose, when to use it, both parameters, and the expected behavioral effect. Minor gaps such as what happens if the alias does not exist or what the API returns are not stated, but the tool's simplicity mitigates their impact.

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 schema provides only property titles and no descriptions (0% coverage), so the description must compensate. It documents both parameters in the Args section, including the critical 'alias/' prefix requirement for alias_name and the semantic role of key_arn as the new target key. This fully compensates for the schema's lack of detail.

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

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

The description opens with a specific use case ('when rotating a key') and a precise action: repoint an existing alias to a new key ARN. This clearly communicates the tool's resource and behavior, and distinguishes it from create_alias or delete_alias.

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

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

It explicitly states when to call the tool—during key rotation—and explains the benefit of keeping application code unchanged. It does not explicitly name alternatives or exclusions, but the 'existing alias' vs. new alias framing makes the boundary with create_alias reasonably clear.

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

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

With no annotations, the description carries the full burden and it does substantial work: it states the required E0 key type, that AES-128 E0 keys are rejected, that UnionPay needs boto3 >= 1.43.49 or fails client-side, and that ARPC generation is optional in the same call. It loses a point because the acronym 'APC' is used twice without being defined and the response/return behavior is not 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?

The definition is front-loaded with purpose and usage, and the parameter examples are dense but valuable. It is slightly overweight: 'ISO 8583 field 55' appears twice with almost the same wording, and the unexplained 'APC' adds noise.

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

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

For a complex 6-parameter tool with nested objects, no output schema and no annotations, the description covers inputs and constraints well but never states what the API returns (verification outcome, generated ARPC hex). Without that, an agent cannot fully know how to consume the result, especially when auth_response_attributes is supplied.

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 0%, so the description fully compensates: every parameter is named with a purpose, key_identifier is typed as ARN/alias of an E0 key, derivation modes are enumerated, and session_key_derivation_attributes/auth_response_attributes get concrete JSON examples for each union member. This goes well beyond the bare schema.

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

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

The description leads with a precise verb and resource: 'Verifies an EMV Authorization Request Cryptogram (ARQC) and optionally generates an Authorization Response Cryptogram (ARPC) in the same call.' It also names the sibling generate_auth_request_cryptogram in the parameter notes, making the verification-vs-generation distinction discoverable.

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 opening sentence explicitly says when to call ('implementing EMV transaction authorization', 'generating an issuer ARPC response', 'validating EMV session key derivation'), which is a clear usage trigger. It does not provide the complementary when-not-to-use or direct alternative routing beyond the sibling mention, so it misses a perfect score.

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 present, so the description carries the burden. It discloses supported key types (C0 CVK, E4/E6 EMV) and that verification is against the issuer CVK, which is useful. However, it does not explicitly state side effects (or their absence), permissions, error behavior, or return format for an unannotated tool.

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

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

The description is compact and front-loaded with the use case before the Args list. The opening sentence and the 'Verify card validation data' sentence are slightly redundant, but supported key types and structured parameter notes earn their place.

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

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

For a 4-required-parameter tool with no output schema and no annotations, the description covers purpose, usage, key types, and parameter basics. It omits the return/response shape and does not fully expand the nested verification_attributes object, leaving an agent to infer success/failure semantics.

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 schema provides only types and requiredness (0% coverage), but the Args block supplies real semantics for every parameter: ARN/alias for key_identifier, 12-19 digit constraint for PAN, algorithm/card-data meaning for verification_attributes, and the value-to-verify for validation_data. Verification_attributes remains somewhat open-ended by pointing to generate_card_validation_data, so it is strong but not exhaustive.

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

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

The description opens with a specific action—validating a card at POS or CNP by verifying CVV/CVV2/iCVV against the issuer's CVK—and then states the core operation as 'Verify card validation data'. It clearly names the resource and supported algorithm families, and the operation is distinguishable from siblings like generate_card_validation_data or verify_mac.

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 explicit trigger contexts: validating a card at POS/CNP, or testing CVK-based validation before writing production logic. It does not explicitly name alternatives to avoid, but the 'validating ... verifying' framing and the reference to generate_card_validation_data make the intended use reasonably unambiguous.

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 carries the full burden and delivers: it warns that truncated CMAC yields ValidationException with no descriptive message, explains that ISO 9797-1 Alg 1/3 are unaffected, and quantifies the workaround cost as 'one extra APC call per verify.' These behaviors cannot be inferred from the schema.

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

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

The description is long but every block earns its place: intent, sibling relationship, critical CMAC warning, workaround, then parameter documentation. The first sentence is immediately actionable and the warning is placed before the Args 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?

The description covers intent, algorithm relationship, edge cases, workaround, and all parameters thoroughly despite no annotations or output schema. It stops just short of stating the success/failure return semantics, such as whether an invalid MAC returns a false result or an exception, which would make the context fully complete in the absence of an output schema.

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

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

Schema description coverage is 0%, but the Args section compensates fully: key_identifier is typed as ARN or alias, message_data and mac are hex-encoded, mac must be full 32H for CMAC, verification_attributes mirrors generate_mac, and mac_length is clarified as nibbles not bytes with the 8/16 mapping and a must-match-generation constraint.

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

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

The description opens with a specific verb and resource: 'verify a MAC on a received payment message or issuer script.' It also anchors the tool's relationship to its primary sibling: 'Mirrors generate_mac — use the same algorithm and key,' so an agent can distinguish verification from generation 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 states the call intent ('Call this to verify a MAC') and gives a concrete alternative path: for truncated CMAC verification, use generate_mac as a workaround to generate the full MAC and compare the leading bytes. The instruction to mirror generate_mac for algorithm and key makes the invocation context explicit.

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 the full burden. It adds useful behavioral detail: supported key types (V1/V2, P0/B0), DUKPT KSN requirements, and the ISO_FORMAT_1 PAN exception. However, it does not state whether the operation is non-mutating or describe auth/error/rate-limit behavior, leaving some ambiguity.

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 well structured with a front-loaded usage statement, supported key types, and a clean Args list. Although detailed, the detail is necessary given 9 parameters and no schema descriptions; there is little 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 the high complexity (9 params, nested objects, conditional logic) and absence of annotations/output schema, the description covers the invocation contract thoroughly. It still omits response/return details and potential error conditions, but these are not critical for selecting and invoking the 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 0%, but the description documents every parameter with formats, examples, and conditional requirements (e.g., dukpt_attributes required with BDK, encryption_wrapped_key changes key meaning, PAN optional only for ISO_FORMAT_1). This fully compensates for the schema gap.

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

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

The description opens with a concrete use case ('implementing PIN verification at an issuer host') and clearly states the operation: validating a cardholder-entered PIN against a stored IBM 3624 offset or Visa PVV. This differentiates it from sibling generation/verification tools by naming the specific PIN verification schemes and formats.

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

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

It explicitly says when to call it: during issuer-host PIN verification and for end-to-end validation before production. It does not explicitly call out alternatives or when not to use it, but the context is clear enough for an agent to route to this tool.

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