Request execution on one client

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

The annotations already mark this as non-read-only, non-idempotent, and open-world. The description adds information annotations do not provide: the call is asynchronous and returns immediately with a pending status and a controller key, and it requires human approval that a shared link cannot replace. These are precisely the behavioral details an agent needs before invoking a gated operation.

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?

Three short sentences, front-loaded with the action; the ordering constraint ('never authorizes') follows; and the follow-up step ('Poll runtime clients') comes last. There is no filler.

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?

Without an output schema, the description still covers the return shape (pending status plus controller key), the human-approval gate, and the next step. What remains missing is an explanation of the 'target' identifier and whether the pending request can expire or be reused. That is a real gap for a 2-required-parameter tool, but the description is otherwise self-sufficient.

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 explain the parameters. It partially does: Check, Build, Run, and Debug map to the operations enum. But it says nothing about 'target', which is an unexplained 64-hex identifier that is opaque without documentation. The most confusing required parameter is left completely unaddressed.

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 and object: it asks the human to approve Check, Build, Run, or Debug operations for a specific client. An agent can tell it apart from siblings such as crabrix_runtime_start or crabrix_runtime_clients because it is the only tool that requests human authorization. It never names those siblings directly, so this is not a perfect 5.

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 gives explicit workflow guidance: call this tool first; it returns immediately with a pending status; then poll runtime clients after the user allows it. It also gives a clear exclusion: 'A shared edit link alone never authorizes execution.' It still does not state when the tool should NOT be used, such as when prior approval is still valid, but the expected sequence is clear.

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