explain_blocked_tool

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

With no annotations, the description carries the disclosure burden; 'Explain' and 'suggest' convey a read-only diagnostic behavior, and the rest_request sentence adds a meaningful behavioral distinction across raw permission types. It does not cover edge cases like unknown tool names or profile-dependent results, but the main behavioral profile is clear.

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 with no filler: the core purpose is front-loaded and the rest_request nuance earns its place in the second sentence.

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 simple diagnostic tool, the description covers selection, invocation context, and the needed special case for rest_request. It is not a 5 because there is no output schema and the optional 'profile' parameter remains unexplained, leaving a small gap in full call semantics.

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 33%, so the description must compensate. It clarifies tool_name as the tool whose blocking is being explained and gives semantic grouping for method via 'GET, write, and DELETE raw permissions,' but it never explains the 'profile' parameter, which has no schema description either.

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 uses a specific verb-resource pair ('Explain whether a tool is blocked') tied to 'the current permission mode,' and adds what the output includes (CLI command or safer alternatives). The rest_request special case further distinguishes it from permission-related siblings like describe_permission_modes or generate_permission_change_command.

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?

It is clear the tool is for checking block status and getting a safer path when a tool is blocked, so an agent can infer when to call it. It does not explicitly state when not to use it or name sibling alternatives, so it stops short of full routing guidance.

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