git_add

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the safety profile is covered. The description adds nothing beyond that—no note that staging mutates the index, whether partial/glob staging is supported, or how the default repo of "." behaves.

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 words are front-loaded with zero padding, which is structurally clean. But at this brevity it is under-specified rather than concise—the short length reflects missing content, not efficiency.

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?

An output schema exists, so return values need not be described. Still, for a two-parameter mutation tool with 0% schema coverage, the description omits parameter meaning, usage context, and staging semantics (e.g., that deletions may need separate flags), leaving real gaps.

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 0%, so the description carries the full burden and fails: it never mentions the required `paths` array or the optional `repo` defaulting to ".". Only the word "files" loosely hints at `paths`, with no guidance on globs, directories, or relative resolution.

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?

"Stage files" names a specific git verb and resource, which is recognizably distinct from git_commit or git_diff. However, it never clarifies scope (single paths vs. the whole repo) or how it relates to the surrounding git toolset, leaving the agent to infer the rest.

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?

There is no statement of when to use this versus siblings like git_commit, git_diff, or git_status, and no prerequisites (e.g., that a repository must be initialized). The agent must infer the staging-before-commit workflow entirely on its own.

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