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

Annotations already declare destructiveHint=false and idempotentHint=true, and the description is consistent with both. It adds real context beyond the annotations: the change only removes the block from the public page rather than destroying it (reversible visibility toggle), and the store/payment model is the business's own rather than something transacted in this chat. It does not describe the response payload or permission requirements.

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?

Two sentences of store/payment preamble precede the actual action, which is buried in the final sentence. The context is defensible for disambiguation in a very large tool list, but the definition of what the tool does is not front-loaded, and "Nothing is bought or sold in this chat" is tangential to invoking this 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?

For a mutation tool with no output schema, the description covers effect (hidden, not deleted), scope (the business's own public store page), and the ID's provenance. Ownership/permission prerequisites and whether store layout is affected are left implicit, but nothing essential for a correct call is missing.

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% and the schema itself already says blockId comes "from list_store_blocks", so the description's parenthetical repeats rather than extends it. No additional meaning is given for workspaceId or idempotencyKey. Baseline 3 is appropriate when the schema carries the parameter documentation.

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+resource: "Take a block off the public store page without deleting it." This cleanly separates it from delete_store_block (destroys) and show_store_block (reverses), which an agent can distinguish without opening any 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?

"Without deleting it" implicitly routes the agent away from delete_store_block and toward this tool when the block should be preserved, and it names list_store_blocks as the source of blockId. It does not state explicit when-not conditions (e.g. use show_store_block to reverse), so it stops short of a 5.

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