git_stage

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does this exceptionally well by revealing two critical behaviors: (1) every path is validated against FSGUARD_ROOT, and (2) a path escaping the root causes the entire call to fail, staging nothing. This goes far beyond what the schema provides and directly affects how an agent should reason about success/failure and safety.

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 a single, compact sentence that leads with the core purpose ('Stage files for commit') and immediately follows with the crucial safety behavior. There is zero filler, and the most important operational detail (path validation) is front-loaded. 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?

For a tool with two parameters, no output schema, and no annotations, the description covers the purpose and a key safety behavior but omits essential operational details. It does not state what a successful staging returns, whether the repo_path must already be initialized (though sibling git_init_repo implies it may be), or how paths are interpreted (relative to repo_path?). While the safety note is valuable, the description leaves an agent guessing on parameter semantics and success indicators, so it is not fully complete.

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 schema has 0% description coverage for its two parameters (repo_path and paths). The description does not explicitly explain these parameters beyond implying that 'paths' are files to stage and 'repo_path' is the repository location. It fails to clarify format (e.g., absolute vs relative paths), whether paths are relative to repo_path, or any constraints on repo_path. Given the low coverage, the description should have compensated with parameter details, but it does not.

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: 'Stage files for commit.' This is a specific verb ('stage') with a clear resource ('files for commit'), which distinguishes it from sibling Git tools like git_init_repo, git_repo_status, git_commit_repo, git_diff_repo, and git_log_repo. No ambiguity about what it does.

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 implies usage context: you stage files before committing. It does not explicitly mention when not to use it or alternative tools (e.g., 'use git_commit_repo to commit the staged files'), but the purpose is clear enough that an agent could infer its place in the workflow. It also highlights a critical constraint (path validation against FSGUARD_ROOT) that acts as guidance for safe usage, though it does not name alternatives.

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