preflight_command

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

With no annotations provided, the description carries the full burden and does so strongly. It explicitly says the command is never executed, that diagnostics are content-free, and that more advanced shell features cannot be verified. This gives the agent a clear and honest safety profile.

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, front-loaded with the core behavior, and every sentence earns its place. The second sentence adds exactly the necessary detail about what is resolved and what cannot be verified, without bloating.

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?

The description is complete for a preflight diagnostic tool: it states purpose, safety guarantees, scope of resolution, and limitations. Since an output schema exists, it does not need to describe return values. A small gap is that `cwd` is not explicitly tied to the 'working directory' mention, but the overall context is 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?

The input schema has 0% description coverage, so the description must compensate. It clarifies that `command` is the operation to inspect rather than execute, and that working-directory resolution is involved, which indirectly covers `cwd`. However, it never explicitly names or explains the `wd` parameter's meaning or default behavior beyond the schema's `default: null`.

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 states a specific action and resource: it returns content-free path and executable diagnostics for a command without running it. This clearly distinguishes it from execution-oriented siblings like execute_and_capture by emphasizing safety and static analysis.

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 makes the use context clear: use this when you need path, symlink, git root, or executable-token diagnostics without side effects. It also explicitly lists what cannot be verified here, such as shell expansion, aliases, pipelines, and redirections, signaling when the tool is not suitable. It does not name an alternative, but the boundary is well implied.

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