mavis_git

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

With no annotations, the description carries the full burden. It discloses the core behavior (runs git commands) and the security rationale for array arguments, but does not explain output formatting, error handling, or side effects of commands like 'push'. The examples provide some context, but a more detailed behavioral note (e.g., 'commands are executed in the workspace root') would improve transparency.

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 sentences, front-loaded with the purpose, and includes a compact list of examples. Every sentence contributes useful information without redundancy or fluff.

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 simplicity, 100% schema coverage, and absence of output schema, the description is reasonably complete. It clarifies argument passing and provides common usage examples. It misses a warning about potentially destructive commands (e.g., push, reset), but the agent can infer risks from the git context. Overall, it is sufficient for correct invocation in most scenarios.

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 100% for both parameters (cwd and args), so the bar is at baseline 3. The description adds examples that partially mirror the schema's own examples, offering slight reinforcement but no fundamentally new meaning. The security note about array args adds value beyond the schema's generic 'array of strings'.

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 'Run a git command in the workspace' with a specific verb and resource, and provides a range of concrete examples (status, log, diff, add, commit, push) that distinguish it from siblings like mavis_bash. It is immediately obvious what the tool 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 for git commands in the workspace and explicitly mentions passing args as an array to avoid shell injection, which is a security guideline. However, it does not explicitly contrast with alternatives (e.g., 'use mavis_bash for non-git commands'), leaving some implicit inference. The examples clarify common use cases.

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