commit-check-mcp

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description's 'Read-only, no side effects' is redundant but harmless. The description adds meaningful behavioral context beyond annotations: it explains the merge order of defaults, config file, and inline overrides, and describes the return structure (commit_check_version, merged config, supported_checks, enabled_rules). This is useful context that annotations 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 three sentences long, with the purpose front-loaded in the first sentence, the return structure in the second, and usage guidance in the third. It is concise and every sentence adds value. It could be slightly tighter by merging the first two, but it is well-structured and not verbose.

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 moderate complexity (3 optional parameters, an output schema, and several siblings), the description is complete. It explains what the tool returns, when to use it, and the merging semantics. The output schema covers return details, so the description doesn't need to repeat them exhaustively. It covers the key contextual points an agent needs to invoke it 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 description coverage is 100%, so each parameter is already well-documented in the input schema. The description does not add syntax or format details for the parameters, but it does reference config_path and 'inline config overrides' in the context of merging, which reinforces their role. This meets the baseline of 3 for high schema coverage; no additional compensation is needed.

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 states a specific verb ('Return') and a precise resource ('commit-check rules that are in effect after merging...'). It clearly distinguishes this describe tool from the sibling validate_* tools, which perform validation actions rather than describing rules. The merging behavior is explicitly articulated, leaving no ambiguity about what is returned.

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 final sentence gives explicit when-to-use guidance: 'Use this before writing a commit message or branch name to learn the expected format instead of guessing, and to debug why a validation failed or was skipped.' This tells the agent exactly the scenario for this tool versus the validation siblings, and even mentions the alternative of guessing. It effectively routes the agent to the right tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description reinforces this with 'Read-only, no side effects' and adds the return shape, which is useful. It doesn't contradict annotations and provides the exact returned fields, going beyond the annotation set.

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?

Two concise sentences. The first states the core action, the second describes the return and the primary use case. No filler, perfectly front-loaded.

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?

For a zero-parameter health-check tool with a comprehensive annotation set and an output schema, the description fully covers what an agent needs: what it returns, when to call it, and that it's safe. Nothing essential is missing.

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 tool has zero parameters, so the description does not need to explain parameter semantics. The baseline of 4 is appropriate because there is nothing to clarify; the schema is empty and the description correctly focuses on output.

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 function: 'Return server and dependency versions.' It specifies a concrete verb and resource, and the 'Useful as a first call to verify the server is running' clarifies its purpose. The sibling tools are all validation-focused, so this stands apart as a health check.

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 gives explicit use context: 'Useful as a first call to verify the server is running and to check version compatibility.' It doesn't explicitly say when not to use it or name alternatives, but given the sibling set is entirely validation tools, the intended use is clear. A slight gap is the lack of explicit exclusions.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description's 'Read-only' matches those. Beyond that, it discloses substantial behavioral detail: the full {status, warnings, checks[]} return contract, precise semantics of 'fail' (the only rejection) vs 'skip' (not approval), per-check field meanings, and the exact remediation protocol ('On fail, apply a non-empty fix verbatim; when fix is '', rewrite following suggest; then validate again'). This goes well beyond what annotations 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 every block earns its place: core purpose first, then the return contract, then usage/omission behavior, then the sibling pointer. The status/check-field detail is dense but essential for correct result interpretation. It could trim some redundancy (e.g. the 'skip' semantics are restated in both the status line and the check field description), but it remains front-loaded and logically ordered.

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?

Despite an output schema existing, the description explains the return contract anyway, which adds agent value by interpreting status meanings and the warn/skip/ignore semantics. For a zero-required-param tool with 5 optional params and complex fallback behavior, the description covers purpose, return format, remediation, parameter omission, repo requirements, and routing. Nothing an agent needs to call it correctly is missing.

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%, so the baseline is 3. The description adds real interaction semantics beyond the schema: it explains that only passed values are checked, that omitting both author_name and author_email causes reads from repo_path's git config with fallback to the latest commit, and that repo_path must be a git repository. This cross-parameter behavior is exactly what an agent needs and is not in the individual parameter 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 opens with a specific verb+resource pair ('Validate a commit author's name and/or email against the configured rules'), names concrete rule types (allowed email domains, name patterns), and explicitly differentiates from validate_commit_context ('For combined validation use validate_commit_context'). An agent can immediately tell this tool apart from its seven siblings without opening schemas.

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?

It states when to use the tool ('Use this to check author metadata before committing'), clarifies the crucial parameter-omission behavior (values read from repo_path's git config, falling back to the latest commit), and names the one alternative for combined validation. It could more explicitly enumerate exclusions for the other siblings (validate_commit_message, validate_branch_name), but the names plus the combined-validation pointer give adequate routing guidance.

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

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

Beyond the readOnlyHint annotation, the description discloses the exact return semantics (pass/fail/skip), explains that 'skip' is not approval, and details the required action on failure (apply fix verbatim or rewrite per suggest and revalidate). This goes well beyond the annotations to fully inform the agent of behavior.

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 somewhat lengthy and repeats the status/check field definitions, but it is well organized into purpose, return format, and usage guidance. Every section carries necessary information, so the length is justified, though it could be tightened without losing clarity.

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?

It provides a complete picture: what the tool does, how the result is structured, how to interpret statuses and check fields, and what action to take upon failure. It also tells the agent when to use it and when to use the alternative, leaving no critical gaps for correct invocation.

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 provides detailed descriptions for all four parameters, covering the branch omission behavior and config merging. The description adds useful context about the naming convention and merge-base check, but does not substantially extend the schema. Given the high schema coverage, this is above the baseline but not exceptional.

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 specific action: validate a branch name against a configured naming convention and optionally a merge-base requirement. It also explicitly differentiates from the sibling validate_commit_context, which handles combined message+branch+author validation, so an agent can immediately understand the tool's scope.

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?

It gives explicit timing guidance: 'Use this before creating or pushing a branch.' It also clarifies when to omit the branch parameter (current checked-out branch) and points to validate_commit_context for combined validation, making the choice between tools unambiguous.

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

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

The description explains the return structure, the meaning of statuses (pass/fail/warn/skip), and the required action on 'fail' (apply fix verbatim or rewrite based on suggest). It also mentions config merging and read-only behavior, adding depth beyond the readOnlyHint annotation. No contradictions.

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 detailed but tightly organized; it front-loads the core purpose, then explains the output structure, then provides usage guidance and sibling alternatives. Every sentence adds essential information without redundancy.

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 tool is complex (multiple parameter combinations, output schema, config handling, and follow-up instructions), and the description covers all necessary aspects: what it validates, how to use it, what the output means, and what to do next. It is self-sufficient for an agent to invoke 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?

Each of the 7 parameters is described with examples, defaults, and fallback behavior (e.g., author_name falls back to git config or latest commit). The schema coverage is 100%, and the description clarifies how omitting parameters affects validation.

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 it runs commit message, branch name, and author checks together in a single call, distinguishing it from single-aspect siblings and the repository-state validator. The scope is precise and action-oriented.

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?

Explicitly indicates when to use this tool (multiple aspects) and when to use alternatives (validate_commit_message, validate_branch_name, validate_author_info, validate_repository_state). Also states that at least one parameter is required and omitted aspects are not checked.

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

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

Annotations carry readOnlyHint/idempotentHint/destructiveHint, and the description reinforces them ('Read-only; touches no git state'). It goes far beyond annotations by explaining the full return semantics: status values with the critical 'skip ≠ approval' distinction, warn-vs-skip meanings, every check field, and the actionable workflow (apply fix verbatim, else follow suggest, then re-validate). Rich and non-redundant.

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?

Well-structured and front-loaded with purpose, then rules list, then result semantics, then routing. The return-format explanation is long and somewhat redundant given an output schema exists, though the semantic interpretation (skip is not approval, warn vs skip) adds value the schema structure alone may not convey. Each section earns its place but the whole is dense.

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?

Complete for a validation tool with 4 params and an output schema. It explains when to call it, what it returns, how to interpret results, and how to act on failures. An output schema covers the return structure, so the description's job is routing + semantics, both fully handled. Nothing an agent needs to call it correctly is missing.

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 description coverage is 100%, so baseline is 3. The description relates the config parameter to effective behavior ('whatever the effective config enables') but adds little parameter-specific syntax beyond the schema. The schema already documents config overrides, repo_path and config_path lookup, so the description rightly leaves this to the schema.

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+resource ('Validate a commit message against commit-check rules') and enumerates the rule families checked (Conventional Commits type/format, subject length/case, body, sign-off, WIP/fixup, AI attribution). It distinguishes itself from siblings by explicitly scoping to a single message string, which separates it from validate_commit_context and validate_repository_state.

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?

Gives an explicit when-to-use directive ('Use this when you have one commit message string to check before committing') and names the two alternatives with their exact conditions: validate_commit_context for message+branch+author in one call, validate_repository_state for a latest commit already in a repo. No inference required.

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

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

The description discloses a side effect not captured by annotations: 'may run `git fetch <remote> <ref>` to resolve SHAs, which updates FETCH_HEAD and remote-tracking refs.' It also states that force pushes are always rejected regardless of config, and that a SHA that cannot be resolved is a tool error, never a pass. These details go well beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true) and give the agent accurate expectations of side effects and failure semantics.

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 every sentence adds necessary information. It is front-loaded with the core purpose, then covers side effects, return schema, and usage notes in a logical order. It avoids fluff and repetition, making the length justified by the complexity of the tool (non-trivial statuses, warn/skip semantics, and fix handling).

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 an output schema present, the description goes beyond it to explain the meaning of status values ('only fail is a rejection', 'skip means nothing was validated'), warn vs skip semantics, and the fix/suggest handling. It also covers edge cases (unresolvable SHAs, force push always rejected, config cannot re-enable). Together with the schema, an agent has everything needed to call the tool correctly and interpret results.

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 input schema has 100% description coverage with detailed explanations for every parameter (config, push_refs, repo_path, config_path), including formats, defaults, and behaviors. The tool description itself does not add parameter-specific meaning beyond referencing the rule logic; it focuses on behavior and return format. Since the schema already carries the parameter documentation, a baseline score of 3 is appropriate.

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 states a specific verb and resource: 'Check that a pending push is not a force push' with the exact rule ID (CC301, no_force_push). It clearly distinguishes this tool from the sibling validators (validate_commit_message, validate_branch_name, etc.) by focusing exclusively on push safety, and even notes 'Only the no_force_push rule runs.' This leaves no ambiguity about what the tool does.

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 instructs 'Call this before `git push`.' It also clarifies when the tool is not a pass: 'skip' means nothing was validated and the result is not approval. It explains the failure path (no automatic fix, follow suggest) and the requirement to fetch unresolvable SHAs first. This provides clear when-to-use and edge-case handling beyond the schema.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, so the tool is not purely read-only. The description clarifies the exact side effect: the push check 'may run git fetch, which updates FETCH_HEAD and remote-tracking refs', while 'leaves the working tree and commits untouched'. It also explains the nuanced status semantics ('skip' is not approval) that annotations cannot convey.

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 organized into three logical paragraphs (scope/side effects, return format, usage guidance), and every sentence contributes substantive information. It is somewhat long but not bloated, and the key operational facts (side effects, skip semantics, alternative tools) are front-loaded.

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?

Even though an output schema exists, the description adds critical operational context: the meaning of 'fail' vs 'skip', the advice to 'apply a non-empty fix verbatim', the note about FETCH_HEAD side effects, and the requirement that at least one include_* flag be true. Together these make the tool safely callable without ambiguity.

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 description coverage is 100%, so the schema already documents all seven parameters. The tool description adds no parameter-specific meaning beyond what the schema provides, only a high-level note that include_* flags select checks. Per the rubric, baseline 3 applies when the schema carries the heavy lifting.

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 states a specific verb ('validate') with a clear resource ('local git repository') and enumerates the exact aspects validated (latest commit message/author, checked-out branch, optional push safety). It explicitly differentiates itself from single-aspect siblings by noting it checks 'current state in one call' and later tells the agent to use validate_commit_context or single-aspect tools for uncommitted values.

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?

Provides explicit when-to-use guidance: 'after committing and before pushing, or in a hook', and names the alternatives when not to use it ('To validate values that are not yet committed use validate_commit_context or the single-aspect tools'). It also states the constraint that at least one include_* flag must be true, which is not in the schema.

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