run_gh

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read operation. The description adds that it's 'allowlisted,' implying command restrictions, and notes the resource-allowlist behavior. It doesn't disclose what happens when a non-allowlisted command is attempted, error handling, or return format, but with solid annotations covering the safety profile, the description's constrained-command disclosure is useful context.

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, zero waste. Every clause adds value: 'allowlisted' constrains scope, 'read-only' signals safety, and the resource-allowlist caveat is essential guidance. Highly front-loaded with purpose stated immediately.

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 flexible command-runner tool with 0% schema coverage and no output schema, the description is reasonably complete regarding usage intent but leaves gaps. It doesn't explain what commands are allowlisted, how failures are surfaced, or the role of hostname/account parameters. Given the tool's complexity (arbitrary CLI args with safety implications), it should do more to describe acceptable invocations and limitations.

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 carries the full burden of explaining parameters. It merely mentions 'args' implicitly via 'GitHub CLI command' and 'account' via the auth context, but doesn't actually describe any of the three parameters (args, account, hostname). The signature permits arbitrary commands via args up to 40 items, which is a risky and important semantic detail that's 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 clearly states it runs an allowlisted, read-only GitHub CLI command. It names the verb (run), the resource (GitHub CLI), and importantly specifies scope (allowlisted, read-only). It differentiates from siblings by noting that when a resource allowlist is present, only auth status is available and typed tools should be used for other reads, distinguishing it from the many typed read tools.

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 provides guidance on when to use this vs alternatives: when a resource allowlist is active, only auth status is accessible; otherwise, use typed repository tools for reads. This gives clear exclusions and points to alternatives. It doesn't explicitly enumerate the allowlisted commands or example invocations, but the 'read-only' and 'allowlisted' constraints plus the pointer to typed tools give solid context.

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