Git Polite

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

The description adds significant behavioral context beyond annotations. While annotations indicate destructive and non-read-only operations, the description details that it 'creates branches from origin/main', 'cherry-picks commits in order', warns about 'existing branches with the same name will cause an error', clarifies 'the current branch is not changed', and explains it 'uses low-level git commands to avoid changing working directory'. This provides crucial operational insights.

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?

Well-structured and appropriately sized. It front-loads the core purpose, provides usage guidelines with an example, details parameters, return format, and important notes. Every sentence adds value without redundancy, efficiently covering complex functionality in a clear hierarchy.

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 complexity (destructive operation with nested parameters) and 0% schema coverage, the description is exceptionally complete. It explains purpose, usage, parameters, return values (though output schema exists, it clarifies format), and behavioral notes. With annotations covering safety aspects, the description adds all necessary operational context for effective use.

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?

With 0% schema description coverage, the description fully compensates by explaining both parameters. It details that 'branches' is a dictionary mapping names to commit lists with examples of commit references (SHA, branch names, symbolic refs) and ordering. It explains 'parent' as the base commit with default 'origin/main' and that all branches start from it. This adds essential meaning beyond the bare schema.

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's purpose with specific verbs ('unstack', 'transforms', 'creates') and resources ('linear commits', 'parallel branches', 'separate PRs'). It distinguishes from siblings by focusing on restructuring commit history rather than applying changes, auto-committing, diffing, or listing changes.

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?

Explicitly states when to use: 'Use this when you've made multiple changes in sequence but want to create separate PRs for different logical changes.' It also provides a concrete example scenario and distinguishes from alternatives by explaining the transformation from linear to parallel branches.

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