verify_mac

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.