preview_local_commit

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

No annotations are provided, so the description carries the full burden. It does disclose a key behavioral trait: 'This tool never creates commits' — a safety guarantee for agents. However, it doesn't explain what 'preview' produces (does it return the plan structure? a dry-run diff?), whether it reads the working tree or staged changes, or what the output looks like. The one disclosed behavior is valuable but incomplete.

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 two short sentences with zero waste. The key safety disclaimer is front-loaded and prominent. Every word earns its place.

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?

This is a three-parameter read-only-ish tool with an output schema, but 0% schema description coverage and no behavioral detail. The description only establishes that it previews and doesn't create commits. It doesn't clarify what the preview contains, how the basecamp_url factors in, whether it inspects local working changes, or what kind of commit plan it previews. For a tool with no annotations and no parameter documentation, this is under-specified.

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 compensate for parameter documentation. The description provides zero information about what repo_path, commit_message, or basecamp_url mean or how they should be formatted. Three required parameters exist with no explanatory added value for any of them.

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 purpose: 'Previews a local commit plan' with the verb 'previews' and resource 'local commit plan.' It's distinguished from siblings like preview_pull_request, preview_remote_branch, and preview_branch_name, though among several preview_* siblings, the distinction relies on 'local commit' specificity which is reasonably clear.

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 states 'This tool never creates commits' which is a negative/exclusion statement, but provides no guidance on when to use this tool vs preview_pull_request or preview_remote_branch. There's no explicit when-to-use context, no alternative tool naming, and no scenario description for when previewing a local commit would be appropriate.

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