get_history

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

The description conveys the read-only nature of the operation and the optional path filter, but it does not disclose behaviors around the `revision` and `limit` parameters, result ordering, or what happens when the path is omitted. Since annotations are absent, the description carries the full transparency burden and only partially meets it.

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 one short sentence, front-loads the primary action, and introduces the optional path scoping after the core purpose. There is no redundant language or wasted context.

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?

The description gives the minimal context for a basic invocation but falls short of being complete: it ignores the revision and limit parameters, does not provide alternatives or exclusions relative to sibling tools, and leaves all parameter nuance to a schema with no descriptions. The presence of an output schema lightens the return-value burden, but not enough to make this a complete tool definition.

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?

With 0% schema description coverage, the description must compensate for parameter meaning. It only addresses `path` ('optionally scoped to a path'); it leaves `revision`, `limit`, and `project_id` semantics to the schema, whose existing titles and defaults are not enough to clarify domain-specific behavior like the meaning of `revision` or `limit` limits.

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 names a specific verb ('Get'), a concrete resource ('commit history'), and its scope ('for a project, optionally scoped to a path'). This clearly differentiates it from sibling tools like get_revision or get_diff, which refer to single revisions or diffs rather than project history.

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 usage is reasonably implied: use this tool when you need the commit history of a project. However, it does not explicitly say when to choose this over closely related siblings such as get_provenance or get_revision, nor does it state any exclusions or non-use cases.

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