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

Goes well beyond the annotations by disclosing the persistence mechanism (stores PayPal/card payer ID on the Blocked List), the lack of any reversal tool, the default confirmation behavior and that it can be toggled off, and the API key scope required. Cancellation path and side effects are made 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 is front-loaded in the first sentence and the key constraint (no unblock) follows. Slightly repetitive on the confirmation point, which is stated twice in adjacent sentences, but overall efficient.

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 irreversible-ish action with no output schema, the description fully covers effect, persistence, confirmation requirements, and auth scope. An agent has everything needed to call it correctly and warn the user.

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 description adds meaning the schema does not: the buyer is derived from the supplied order rather than passed directly, so order_id is the sole required input. With 100% schema coverage the baseline is 3, and the derivation detail earns a bump.

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 (block) and resource (an order's buyer), and explains the consequence precisely: the buyer cannot make future purchases. It is clearly distinguishable from Payhip siblings like add_order_note or get_order.

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?

Explains the intended outcome and notes 'there is no unblock tool; remove a buyer on the Blocked List page', which tells the agent this action is effectively irreversible via the API. It also flags the need to confirm with the user before each call. No explicit comparison to alternative tools, but none exists for this action.

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