list_history

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

The annotation readOnlyHint:true already establishes this as a safe read operation, and the description's 'Show' is consistent with that. The description adds no additional behavioral context such as pagination limits, default ordering, or that it returns remote data—all of which could be useful but are not disclosed. Since the description carries little burden beyond confirming the read-only nature, a 3 is appropriate.

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, direct sentence with no filler. It front-loads the core action and object, and there is zero waste. The structure is ideal for quick agent parsing.

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 5 parameters and no output schema, the description is quite sparse—it does not mention the output format, pagination, or that it operates on remote repositories. However, the parameter descriptions (especially project_id) carry substantial contextual weight, and the name 'list_history' is self-explanatory. The description is adequate but leaves some behavioral details (e.g., result shape, default limit limitations) to inference.

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% (all 5 parameters have descriptions). The tool description adds no parameter-specific meaning, but the schema itself thoroughly documents limit, since, until, file_path, and especially project_id (which includes extensive guidance on usage and differentiation from local paths). At high coverage, the baseline of 3 is met without extra 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 clearly states a specific verb ('Show') and a resource ('git commit history') scoped to 'the project'. It unambiguously identifies a read operation for commit history, which none of the sibling tools (status_summary, get_diff, etc.) appear to duplicate, so it differentiates well.

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 tool description itself offers no guidance on when to use it or when to prefer an alternative. It does not mention that it operates on remote Typleaf projects only, nor does it warn against using it for local I/O—that guidance exists only in the project_id parameter description, not in the tool-level description. An agent gets minimal context on appropriate invocation context.

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