bash

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

Goes far beyond the raw annotations (readOnlyHint:false, destructiveHint:true, openWorldHint:true) by disclosing critical non-obvious behaviors: CWD/env-var state persisting across calls via a resident PowerShell host, exact bash-style exit code conventions (0, 1, 2, 124, 127), output/error formatting emulation, and graceful degradation when PowerShell is unavailable. This deeply enriches the agent's understanding of side effects without contradicting any annotation.

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 long but every paragraph earns its place with non-obvious info: execution model, session persistence, exit codes, and platform requirements. It is clearly front-loaded with the core purpose and uses scannable, comma-separated lists for the command catalog. Deduction for reading as a dense wall of text without subheadings, though it remains efficiently written.

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 the most complex tool type (a shell executor), the description covers all critical aspects: execution/translation model, output formatting, encoding handling, state persistence, exit codes, and platform-constrained failure behavior. Since the output is terminal text and no output schema exists, the description appropriately covers return semantics through formatting and exit-code documentation. Nothing material is left to the imagination.

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%, so the baseline is 3; the description elevates this by detailing what a valid 'command' value looks like (pipes, redirections, variable expansion, command substitution, 108+ coreutils, passthrough of unknown binaries, and expressly unsupported constructs like heredocs). The mention of exit code 124 implicitly ties to the timeout_ms parameter. Slight deduction because most of the value tips toward the command parameter while timeout_ms relies on schema-detailed semantics alone.

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?

Opens with a specific verb+resource statement: 'Execute a Linux/bash-style command on this Windows machine.' The description then differentiates the tool by explaining commands are translated to PowerShell ('no WSL or VM'), clearly scoping its behavior and distinguishing it from the fauxnix_translate and fauxnix_session siblings. Exceptionally clear purpose and scope.

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?

Provides extensive when/how-to-use context: enumerates supported and unsupported syntax, notes that unknown commands (git, node, npm, python) are passed through natively, gives batching advice about sessions, and explains the platform requirement and its 127-error failure mode. However, it never explicitly references the sibling tools or frames exclusions as 'use X instead,' missing full alternative-naming guidance.

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