alipay_verify_notify

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

With no annotations, the description carries the full burden. It does disclose the verification method (Alipay public key), the required input scope, and the return contract. However, it does not state behavior on verification failure (returns false vs throws), whether the tool is side-effect free, or any other runtime 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?

A single compact sentence that front-loads the action and resource, states required inputs, and gives the return shape. No filler or redundancy.

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

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

For a low-complexity verification tool with a rich credential schema and an explicit return contract, the description is nearly complete. The main gaps are explicit failure semantics and a note that this is a pure verification operation with no side effects.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful semantics beyond the schema by specifying that all callback parameters must be passed and must include sign, and that verification uses the Alipay public key — which clarifies which credential field matters.

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 uses a specific verb (验签/verify signature), a specific resource (支付宝异步通知/Alipay async notification), and states the return shape {valid:boolean}. This clearly differentiates it from the sibling wechat_verify_callback by platform and notification context.

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 makes the intended use case clear: verify Alipay async callback notifications by passing all callback parameters including sign. It does not explicitly name alternatives or state when not to use it, but the Alipay-vs-WeChat platform context is unambiguous from the description and sibling set.

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