jade.run_command

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

No annotations are provided, so the description must carry the behavioral burden. It discloses that it waits for a verdict, returns pass/fail with output, and that wait=false returns a job ID for polling. It also mentions timeout behavior via schema. However, it does not mention side effects (e.g., does it modify the repo?) or any safety implications, but for a runner tool, the description covers the essential behavior.

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 concise, with three sentences that are information-dense. It front-loads the core purpose (run command by name, wait for verdict) and then provides usage alternatives and next steps. Every sentence earns its place with no fluff.

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?

Given the tool's moderate complexity (3 optional params, async behavior), the description covers the main points: what it does, how to list commands, how to use wait=false, and the timeout bound. It doesn't describe the exact format of the verdict output, but since there's no output schema and the description mentions 'decisive output,' it's reasonably complete. A small gap is not explaining the relationship to run_tests, but that's minor.

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 100%, so the schema already documents all three parameters. The description adds some context (e.g., omit name to list, wait=false returns job ID, timeout is a bound) but largely reinforces the schema. Baseline 3 is appropriate because the schema does the heavy lifting.

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 clearly states the tool runs a declared command by name and waits for a pass/fail verdict with decisive output. It also distinguishes it from the shell by saying to use it instead of a shell for anything check does not cover, and it mentions the sibling declare_command for declaring commands.

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 explicitly says when to use it: instead of a shell for anything check does not cover. It also gives instructions for listing commands (omit name) and for declaring new commands (declare_command it once). This provides clear guidance on alternatives and conditions.

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