Kiểm chữ ký webhook (offline)

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

With no annotations and no output schema, the description carries the behavioral burden. It delivers genuine value by disclosing the HMAC-SHA256 algorithm and the no-network-call behavior. However, it does not disclose what happens on signature mismatch (return false vs. error), the return shape, or how the timestamp tolerance rules behave.

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 (~25 words) and front-loads the algorithm, purpose, inputs, and offline trait in the first sentence. The second English sentence is largely redundant with the first, adding only the 'locally' gloss, so there is minor waste, but overall it is well-sized.

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 tool with no output schema, no annotations, and 0% parameter descriptions, the description should specify the return value on success/failure and how raw_body must be formatted (e.g., exact HTTP body vs. parsed JSON). The description explains the computation at a high level but leaves the agent unable to predict the tool's response, which is a significant gap for a verification utility.

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 adds real semantics by showing how raw_body, timestamp, and secret combine into the HMAC computation, and signature is implied by 'so chữ ký'. However, tolerance_sec and skip_time_check are left entirely to their self-descriptive names, which is thin compensation for the 0% schema coverage.

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 (verify), a specific resource (MONA Pay webhook signature), the exact algorithm (HMAC-SHA256), and the input composition (raw body + timestamp + secret). The added 'offline'/'không gọi mạng' trait clearly differentiates it from network-triggering siblings like monapay_test_webhook and monapay_generate_webhook_snippet.

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 offline/local framing gives implied usage context: use this to verify a signature without making network calls. However, it never explicitly names alternatives or states when NOT to use it, leaving the agent to infer the boundary against siblings like monapay_test_webhook.

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