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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds material behavior beyond them: each call is metered as one execution, results arrive inline in roughly two seconds or fall back to an async flow, and the agent must not resend the call but instead reuse the returned IDs with operation_status and operation_output.

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?

Four sentences, no filler, and the trigger condition is front-loaded. The dense latency/fallback sentence earns its length by telling the agent exactly what to do next instead of blindly retrying.

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?

With no output schema, the description compensates by describing the return path: a short inline result versus IDs the caller keeps for operation_status and operation_output. Combined with the metering cost and prerequisite session, an agent has everything needed to call this correctly.

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%, and the schema itself already explains path, sessionId provenance, deadlineAt, and operationId semantics, so the baseline is 3. The description largely restates the required parameters (sessionId from execution_session_open, a new operationId) and adds only workflow framing rather than new parameter-level meaning.

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?

States a specific verb and resource: retrieving the Git branch and changed files of an approved project. This scope is separable from git_diff (content of changes) and git_log (commit history) by inference, but the description never names a sibling, so it lands at 4 rather than 5.

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?

"Use this when the user wants the Git branch and changed files of an approved project" gives a clear triggering condition, and the session/operation prerequisites are spelled out. It stops short of explicit exclusions or naming alternatives such as git_diff or git_log, so no 5.

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