git_lint_commits

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

With no annotations provided, the description carries full responsibility for behavioral disclosure. It clearly states that the tool is deterministic, requires no AI, no network, and no credentials. It explains that the suggest parameter is report-only and that mutation is exclusive to git_amend_commits. It also discloses error conditions (suggest with message) and the return format (YAML payload with exit code). This is exceptionally transparent.

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 (over 200 words) but every sentence contributes essential information. It is well-structured with paragraphs and bullet-like lists, front-loading the main purpose and contrasts with alternatives. While slightly verbose, it avoids redundancy and remains focused. The length is justified by the complexity of the tool's parameters and behavior.

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 covers all critical aspects: what it does, what it doesn't do, how parameters interact, return format, and contrast with sibling tools. It mentions the one important error case (suggest+message). It doesn't explicitly state that the tool is read-only, but it implies this by noting that mutation is exclusive to git_amend_commits. Overall, it is sufficiently complete for an agent to use 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?

Although the schema already covers 100% of parameters, the description adds substantial semantic value. It explains the default behavior of range (commits ahead of base branch), the precedence rule when both range and message are set, the error condition when suggest is combined with message, and the role of context_dir in overriding default resolution. These clarifications go well beyond the schema's basic descriptions.

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 the tool's purpose: deterministically validate commit messages against guidelines. It specifies the verb (validate), the resource (commit messages), and distinguishes itself from git_check_commits by emphasizing the deterministic, no-AI approach. It also lists exactly what checks are performed and what is not checked, leaving no ambiguity.

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 explicitly contrasts with git_check_commits, explaining that this tool is used when deterministic validation is desired instead of AI-based checking. It also provides concrete usage scenarios (linting a literal message vs. a range) and explains the default behavior for range, as well as the precedence of message over range. This gives clear guidance on when to use this tool over alternatives.

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