wechat_decrypt_callback

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. The description states the algorithm (AES-256-GCM), the key (APIv3), and the output (transaction plaintext JSON), which is useful. However, it does not disclose potential failure modes (e.g., what happens if decryption fails, invalid key, wrong nonce), whether the tool validates the callback signature, or any side effects. For a decryption tool, the behavior is mostly deterministic, but the lack of error-handling context is a 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 a single, compact sentence that packs in the purpose, algorithm, key, and output format. It is front-loaded with the core purpose and uses technical shorthand efficiently. It could be slightly more structured (e.g., separating the output statement), but it is appropriately concise for a technical 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?

Given the tool's complexity (AES-GCM decryption with multiple parameters, nested cred object, no output schema), the description is somewhat thin. It covers the algorithm and key, but does not explain the relationship between ciphertext, nonce, and associatedData, nor the expected format of the input (e.g., base64-encoded ciphertext). It also doesn't mention that the output is the decrypted transaction JSON, which is stated, but not the structure of that JSON. The cred object's flexibility (env vars vs direct fields) is in the schema, so that's covered. Overall, the description is adequate for a simple decryption tool but lacks detail on input formats and error cases.

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 only 25%, so the description must compensate. The description mentions the key (APIv3) and the algorithm, which relates to the 'apiV3Key' field in the cred object, but it does not explain the meaning of ciphertext, nonce, associatedData, or the cred object structure beyond what the schema provides. The schema has a description for cred (credentials can be omitted, use env vars, PEM fields accept full text or file path), but the other parameters (nonce, ciphertext, associatedData) have no descriptions. The tool description adds context about the algorithm but does not explain the parameters' roles in the decryption process. This is a moderate 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 clearly states the tool's purpose: decrypting WeChat Pay V3 callback resource data using AES-256-GCM with the APIv3 key, and returning the transaction plaintext JSON. It identifies the specific operation (decrypt), the resource (WeChat Pay V3 callback resource), and the algorithm/key. However, it doesn't explicitly distinguish it from the sibling wechat_verify_callback, which is a related but different operation (verification vs decryption).

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 implies usage context: it is for decrypting the 'resource' field in WeChat Pay V3 callbacks. It mentions the algorithm and key, which tells the agent when this tool is applicable (when dealing with encrypted callback resources). However, it does not explicitly state when to use this tool versus wechat_verify_callback or other siblings, nor does it provide exclusions or alternative routing. The context is clear enough for a knowledgeable agent but lacks explicit guidance.

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