tenki_git

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

Beyond the annotations, the description reveals important runtime behavior: checkout/diff/log execute in /home/tenki, which is not a git repository, so they fail on repos in subdirectories. It also states the API rejects unsupported operations and notes that only certain operations are supported. This is substantial, operationally relevant context that the annotations alone do not provide.

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 long but information-dense, with the core purpose and supported operations front-loaded. The caveat, workaround, and per-operation argument summaries all earn their place. It loses a point because the 'For reference' section substantially repeats the args description already present in the input schema, making the text slightly more verbose than necessary.

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, the description is highly complete: it covers supported operations, required and optional arguments, a proven failure mode, and a recommended fallback. It does not describe the return value shape (e.g., what stdout/stderr or exit codes look like), and there is no output schema to fill that gap, but the essential calling information is present.

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 already documents the operation enum and a brief args shape, so the baseline is 3. The description adds meaning by marking `repo` and `ref` as required, clarifying value coercion, explaining `create: 'true'` as `-b`, and describing alternative diff argument forms (`base?+head?`). This is a clear improvement over the schema, though it partially repeats the schema's args description.

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 starts with a specific verb and resource: 'Run a git operation in a sandbox.' It then clearly enumerates the supported operations (clone, checkout, diff, log) and explicitly distinguishes this tool from tenki_exec, which is the named fallback for other git commands. This makes it easy for an agent to know exactly when this tool is the right one.

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?

Usage guidance is explicit and actionable. It names the sibling tenki_exec as the alternative for unsupported git commands, and it even provides a live-verified caveat with a concrete workaround (`git -C <directory> ...`). This goes well beyond implied usage and leaves little to inference.

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