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

Annotations already indicate this is a mutating operation (readOnlyHint=false), and the description adds key behavioral context: it stages files but does not commit, and it describes return values. It could mention side effects like overwriting prior staging but that's arguably implied. No contradiction with annotations.

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 generally concise and front-loaded, but includes some redundancy: 'ready for committing' echoes 'prepare ... before a commit', and the 'Best for' line repeats the opening. Otherwise, every sentence provides useful info, and the return value is specified.

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 git tool with a simple schema and no output schema, the description is complete: it covers its role in the workflow, how to invoke it, alternatives, and expected return values. No significant gaps.

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 baseline is 3. The description adds meaningful parameter semantics by explaining 'stage everything (all=True)' and 'tracked changes only (update=True)', which goes beyond the schema's brief descriptions. It also implies the files parameter for specific selections.

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 and resource: 'Stage files into the index'. It also explicitly differentiates from git_commit ('Does NOT commit — use git_commit for that') and references git_status/git_diff for review, making its purpose unambiguous and distinct among siblings.

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 clear when-to-use guidance: 'prepare modified or new files before a commit'. It further explains the three usage modes (specific files, all=True, update=True) and explicitly states exclusions: 'Does NOT commit — use git_commit for that; review first with git_status and git_diff'. This is a model of usage orientation.

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 are all false, so the description carries the full burden of behavioral disclosure. It adds crucial context: 'stash local changes first, because the session checks out commits automatically' and 'Does NOT inspect history.' This goes beyond the schema and annotations, revealing side effects and scope.

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 functional but contains redundancy: 'Use this to binary-search...' and 'Best for: binary-searching...' say the same thing. The first two sentences overlap in intent. It could be tighter, though the overall structure is logical with sections for purpose, best for, returns, and warnings.

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 session-based tool with side effects and no output schema, the description covers the workflow, return type ('git bisect progress output'), pruning condition ('stash local changes'), and alternative tool. It doesn't explicitly state what happens if commit is omitted for good/bad, but the schema hints that commit is needed for those operations. Overall, sufficiently complete.

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 workflow semantics that clarify how to sequence the operation parameter: 'Start with start, alternate good/bad marks, and reset to end the session.' It also clarifies that 'commit' is the target for marks, adding value beyond 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?

The description clearly states the tool's purpose: 'Drive a bisect session: start, mark good/bad commits, or reset.' It uses a specific verb and resource, and explicitly distinguishes itself from git_log by noting 'Does NOT inspect history — use git_log to understand commits before bisecting.'

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 when-to-use guidance ('Use this to binary-search which commit introduced a regression') and an explicit alternative ('Does NOT inspect history — use git_log'). It also outlines the correct workflow order: 'Start with start, alternate good/bad marks, and reset to end the session.'

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 annotations (readOnly, idempotent, non-destructive), the description discloses the return format (line count summary followed by git blame output with commit hashes, authors, line content), a mutual constraint (start_line and end_line must be provided together), and a prerequisite (file must be tracked by git). No contradiction with annotations.

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 well-structured with short labeled sections ('Best for', 'Returns', 'Does NOT'). Each sentence provides distinct, necessary information without redundancy. It is concise enough while covering purpose, usage, output, constraints, and exclusions.

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 has no output schema, the description compensates by explaining the return value in detail. It covers the main use case, key constraints, and alternatives. The schema already documents all parameters, and the description adds the missing behavioral context needed to invoke the tool 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%, so the baseline is 3. The description adds value by specifying that start_line and end_line must be provided together (a mutual requirement not present in the schema) and that the file must be tracked by git. It also clarifies that a line range is optional, but doesn't add formatting details for the parameters themselves.

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 action ('Render per-line attribution') and resource ('tracked file'), and explicitly distinguishes itself from siblings by noting it does not show current file content or whole-history log and pointing to git_show and git_log. The 'Best for' line further clarifies the tool's exact purpose.

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 includes explicit when-to-use guidance ('investigating who changed a line or when a regression was introduced, to trace how a file evolved') and names alternatives (git_show, git_log) with a clear exclusion ('Does NOT show... use...'). This fully satisfies the when-to-use and when-not-to-use criteria.

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 reveals important operational details beyond the annotations: delete requires confirmed=True and refuses the current branch; force=True replaces an existing branch; behavior in detached HEAD state; and return values (branches list or confirmation text). These enrich the agent's understanding of side effects and prerequisites, complementing the destructiveHint annotation without contradiction.

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 dense paragraph but every sentence provides distinct information: operations, usage context, exclusions, best-for, and return/behavior notes. It is not as lean as a two-sentence example, but it avoids redundancy and front-loads the core purpose. The structure is logical and scannable.

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 tool with 6 parameters and no output schema, the description is thorough: it explains the three operations, return formats, confirmation/force requirements, exclusions, and relevant edge cases (detached HEAD). It covers both selection criteria and invocation details, making it self-sufficient 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?

The schema already describes all 6 parameters, so baseline is 3. The description adds meaningful semantics by explaining how confirmed, force, all, and operation interact (e.g., delete requires confirmed=True, force replaces branch, all shows remotes). It doesn't elaborate on repo_path or name, but these are self-explanatory from schema. Overall, the description adds clear value beyond 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?

The description clearly states 'List, create, or delete branches' with a specific resource (branches) and verb. It distinguishes from siblings by explicitly naming git_checkout and git_tag for operations it does NOT perform, making its unique purpose unambiguous.

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: 'Use this to review existing branches before choosing where to work, to start a feature branch, or to remove a merged one'. Also gives exclusions and alternatives: 'Does NOT switch branches — use git_checkout for that; does NOT manage release markers — use git_tag'. This fully helps an agent select between tools.

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 critical behaviors beyond the destructiveHint annotation: local changes are not discarded without confirmation, force=True requires confirmed=True, and preview=True shows what would be discarded. This contextualizes the destructive nature and prevents accidental data loss.

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 well-structured with clear labels ('Best for:', 'Returns:') and is front-loaded. However, it repeats 'moving between branches' twice, making it slightly less concise than ideal. Still, every section earns its place.

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?

This is a complex tool (branch/tag/commit, force, preview, create) with no output schema. The description fully covers return values ('Switched to branch <name>', impact preview), handling of local changes, and related tools (git_branch, git_stash). It is complete enough for an agent to select and use safely.

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% with each parameter already described, so baseline is 3. The description adds meaningful semantic guidance for force/confirmed/preview relationships and mentions create_branch, which goes beyond the schema. Slight redundancy with target being branch/commit while description includes tags, but overall adds value.

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 and resource: 'Switch to an existing branch, tag, or commit, optionally creating a branch first.' This clearly distinguishes git_checkout from sibling tools like git_branch (which lists branches) and git_stash (which saves changes).

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 usage context: 'Use this to move between branches for different features, to jump to a tag or historical commit, or to start a new branch with create_branch.' It also names alternatives and complementary tools: git_stash for keeping changes and git_branch for listing available targets.

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 destructiveHint=true, so the mutating nature is known. The description adds useful context: the no_commit option, the return message, and importantly that conflicts are 'reported as errors — resolve them and continue'. This goes beyond the annotations and helps the agent anticipate failure modes.

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 short sentences, front-loaded with purpose, then usage, exclusions, and return behavior. No redundant filler; every sentence adds value.

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 having no output schema, the description explains the success return ('Cherry-picked <commits>') and error behavior (conflicts reported as errors). It covers purpose, usage, alternatives, and key option (no_commit). Could mention prerequisites like clean working tree, but for a git tool this is quite thorough.

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 covers all parameters with descriptions (100% coverage). The description mentions commits and no_commit but does not add new semantic detail beyond what the schema already provides. The repo_path parameter is not elaborated, but its schema description is sufficient. Baseline 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 clearly states 'Apply the changes of one or more commits onto the current branch', which is a specific verb and resource. It explicitly distinguishes from siblings by noting 'Does NOT integrate a whole branch — use git_merge or git_rebase for that; use git_revert to undo a commit instead of applying it.' This fully differentiates it from related git tools.

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 provides explicit when-to-use guidance: 'Use this to port a specific fix or feature from another branch when a full merge is too broad'. It also gives explicit exclusions and alternatives, naming git_merge, git_rebase, and git_revert. This is a textbook example of usage guidelines.

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 adds significant behavioral context beyond the annotations: it warns 'DESTRUCTIVE: requires confirmed=True to delete', explains that dry_run previews without deleting, and clarifies scope ('Does NOT touch tracked files, ignored files, or stashes'). It also mentions return values. This aligns with the destructiveHint annotation without contradiction.

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 long but every sentence provides useful information: purpose, safe usage, destructive warning, scope limitations, best-for, and return value. It is front-loaded with the primary action and flows logically.

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 without an output schema, the description states the return format ('list of removed or would-be-removed files, or 'No untracked files to clean.'') and covers safety, scope, and workflow. For a destructive tool with 4 parameters, this is fully complete.

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 four parameters. The description reinforces the confirmed/dry_run relationship but does not add substantial new semantic detail beyond what the schema provides. Baseline 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 opens with a specific verb-resource pair: 'Delete untracked files, or preview them first with dry_run.' It clearly distinguishes itself from siblings by explicitly stating 'Does NOT touch tracked files, ignored files, or stashes — untracked files only' and referencing git_status for viewing untracked files.

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 provides explicit when-to-use guidance ('Best for: removing build artifacts and other untracked clutter') and an alternative ('use git_status to see untracked files before deciding what to clean'). It also instructs to preview first with dry_run, outlining a safe workflow.

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?

While the annotations are all false (not read-only, not idempotent, not destructive), the description adds meaningful behavioral context beyond those flags: it discloses the return value ('confirmation text with the local path') and a critical constraint ('refuses non-empty destinations'). This helps the agent anticipate failure conditions and the nature of the operation, though it doesn't cover every edge case (e.g., authentication).

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 well-organized: it begins with the action, then gives use cases, a non-use clarification, a 'Best for' summary, and a return/constraint note. It is appropriately sized, though the 'Best for' line partially reiterates the earlier 'starting work on an existing project' point, and could be trimmed without losing value.

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 covers purpose, usage scenarios, return value, and a key behavioral restriction (non-empty destination refusal). With full schema coverage and no output schema, the description provides all necessary context for an agent to invoke the tool correctly, including the target directory requirement.

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 already provides descriptions for all four parameters with 100% coverage. The description merely restates 'url', 'local_path', 'branch', and 'depth' without adding new semantic meaning. Therefore, the baseline of 3 applies — the schema carries the load, and the description does not materially enhance parameter understanding.

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 primary action ('Clone a remote repository from url into local_path'), the optional branch/depth pinning, and explicitly contrasts with git_init for empty repositories. This distinguishes it from sibling tools and 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 provides explicit use cases: starting work on an existing project, when a full history is not needed, or when a local copy must be created from a remote. It also clearly tells the agent when NOT to use it ('Does NOT initialize a new empty repository — use git_init for that'), offering a direct alternative.

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 non-read-only, non-idempotent, non-destructive. The description adds key behavioral traits: it doesn't stage files, can amend previous commits, and returns 'No changes to commit' with a staging hint. No contradiction with annotations.

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, front-loaded with primary purpose, and every sentence provides useful guidance (when to use, what it doesn't do, return behavior). No wasted words.

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 and absence of output schema, the description covers use cases, side-effect boundary, and return values. It is complete for an agent to select and invoke correctly among many git siblings.

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 already covers all parameters (100% coverage), so baseline is 3. The description enriches semantics by explaining why amend and no_verify are used and how message relates to the commit, adding value beyond schema 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 'Create a commit with the given message, or amend the last one' — a specific verb and resource. It also distinguishes from siblings by noting it does NOT stage files and is best used after git_add.

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 provides when to use: when staged changes are ready, to amend the last commit (amend=True), or to skip hooks (no_verify=True). It also gives an exclusion ('Does NOT stage files') and directs to git_add/git_status as alternatives.

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 reinforces the annotations with 'Does NOT modify configuration — it is read-only,' and adds critical behavior: 'Returns: the value of the requested config key, or the full git config --list output when key is omitted; an unset key returns a specific message without error.' This goes beyond annotations by detailing the return behavior for omitted and unset keys.

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 concise and logically structured, with each sentence carrying purpose. However, the 'Best for' line largely repeats the earlier 'Use this' sentence, creating slight redundancy; still, it remains efficient overall.

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?

This is a simple tool with no output schema, yet the description covers the core action, usage context, read-only safety, return format for key/none, and unset-key behavior. Combined with fully described parameters, the description is sufficiently complete for an agent to invoke the tool 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?

The schema already provides 100% description coverage for both parameters, including default values and behavior for empty key. The description adds minimal parameter-specific meaning beyond the schema; most of its added value pertains to return behavior rather than parameter semantics.

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 and resource: 'Read git configuration values from the repository, either one key or the full list.' This clearly distinguishes it from sibling git tools, and it explicitly points to git_remote for remote URLs, differentiating 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 provides explicit guidance: 'Use this to verify settings like user.name, user.email, core options, or remote URLs before operating' and 'Best for: checking settings...' It also states the read-only nature and suggests an alternative: 'use git_remote for a friendlier view of remote URLs.' This gives both when-to-use and an alternative.

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 adds valuable behavioral context beyond that: it defaults to a diffstat summary, returns specific strings ('Diff output:' and 'No changes'), and explains what stat=True does. It also clarifies the scope (working tree, index, commits). This enriches transparency without contradicting annotations.

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 well-organized: core purpose first, then usage guidance, return format, and exclusions at the end. Every sentence conveys new, relevant information without fluff. It is longer than typical but each clause earns its place, and the structure makes it easy to scan.

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 read-only diff tool with no output schema, the description fully prepares the agent: it explains the default summary behavior, the return format, how to use source/target/staged, and explicitly notes what the tool does NOT do and which siblings cover those gaps. This is complete for effective invocation and interpretation.

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 defines each parameter. The description adds meaning by explaining how parameters combine in practice: 'stat=False for the full diff', 'compare two commits with source and target', and 'staged=True' to see what would be committed. This goes beyond the schema's per-field descriptions and earns credit, though it does not introduce wholly new parameter details.

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: 'Show differences between the working tree, the index, and commits.' It clearly distinguishes the tool from siblings by stating what it does NOT show (file status or history) and names which sibling tools to use instead (git_status, git_log, git_show). This fully clarifies purpose and differentiation.

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?

Explicit when-to-use guidance is given: 'Use this to review what a change actually contains before staging or committing, to compare two commits with source and target, or to check what would be committed with staged=True.' It also provides when-not-to-use via 'Does NOT show...' and names exact alternatives (git_status, git_log, git_show), making this a model of usage guidelines.

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 key behaviors: it updates remote-tracking branches, does not change the working tree, and describes the return format ('Fetched N refs from 'origin'.' followed by per-ref lines). The annotations provide no safety hints, so the description carries the full burden and 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 concise and well-structured: four sentences covering purpose, usage, exclusions, and return value, with a 'Best for:' section. Every sentence earns its place with no redundant information.

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 minimal annotations and no output schema, the description is complete for a fetch tool. It covers what it does, when to use it, what it doesn't do, and what the return value looks like, along with next steps (git_log or git_diff).

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% parameter description coverage, so the description does not need to add much. It references prune=True in context but does not meaningfully expand on the schema's already clear 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 clearly states the action: 'Fetch refs from a remote (default origin) without merging, updating remote-tracking branches.' It uses a specific verb and resource, and distinguishes itself from git_pull and git_push by noting it does NOT change the working tree.

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?

Explicit guidance is provided on when to use this tool: 'Use this to see upstream changes before deciding to integrate them' and alternatives: 'use git_pull to fetch and integrate, or git_push to send local commits.' It also mentions pruning stale branches with prune=True.

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 mark it as read-only and idempotent, and the description adds important behavioral context: it only searches tracked files, requires the pattern not start with '-', returns 'No matches' when nothing is found, and excludes untracked files and commit messages. This gives the agent a complete picture of the tool's 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 efficient and front-loaded with the tool's core function. There is slight redundancy between 'Use this to find where a string or symbol appears' and 'Best for: finding where a string appears', but the extra detail about not using a shell and the git_log alternative keeps the description informative.

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 covers the essential details: what the tool searches, the output format, the no-match case, the pattern constraint, and exclusions. It does not mention whether the pattern is a regex or fixed string, but the tool is simple enough that this is not a critical omission.

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 provides full descriptions for all three parameters, including the pattern restriction and repo_path default, so the description does not need to add much. The description adds no new parameter details beyond what the schema already covers, making this a baseline 3 given the 100% schema coverage.

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 searches tracked files for a pattern and returns matches in 'file:line:content' format. It also directly addresses the common use case of finding where a string/symbol appears, and differentiates itself from git_log by explicitly stating it does not search commit messages.

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 provides explicit guidance: use this to find where a string appears in the codebase without a shell, and do not use it for commit messages or untracked files—instead use git_log with its grep filter. This clearly states when to use the tool and when to use an alternative.

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 annotations (which only indicate non-read-only, non-idempotent, non-destructive), the description discloses meaningful behavioral traits: it creates missing directories, refuses non-empty directories, validates the target, and returns a confirmation text. This is valuable context an agent needs to anticipate side effects and failure modes.

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 five sentences long, every sentence contributes either purpose, usage guidance, exclusions, or behavioral detail. It is front-loaded with the core action and remains compact without unnecessary filler.

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 simple with a small parameter set. The description covers purpose, when-to-use, what it does, what it refuses, and the shape of the return value. With no output schema, this is sufficient contextual coverage.

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 already documents all three parameters at 100% coverage, so baseline is 3. The description adds extra context by mentioning 'non-standard initial branch or bare layout' and instructing the agent to 'pass an empty or missing target,' which helps map usage scenarios to parameters.

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 an explicit verb-phrase: 'Initialize a new git repository in repo_path, creating the directory if missing.' It clearly identifies the resource (a new git repo) and distinguishes itself from git_clone by explicitly stating it does NOT clone existing projects.

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 provides explicit when-to-use guidance ('Use this when starting a brand-new project...'), an explicit exclusion ('Does NOT clone existing projects — use git_clone'), and a 'Best for' recommendation. This gives the agent clear decision criteria among siblings.

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 read-only/idempotent; description complements with output format ('<short hash> <date> <author> - <summary>'), empty result message, and explicit non-behaviors (no patches/file contents). No contradiction.

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 focused sentences with front-loaded action, then use cases, return format, and exclusions. No filler.

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 6-param read-only tool with no output schema, it explains return format, empty result, and limitations, and provides navigation to sibling tools.

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?

Input schema covers all 6 params with descriptions, so baseline 3. Description groups filters (author, date range, grep) but adds no new parameter syntax or details beyond 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?

Description states it shows recent commits as formatted lines with filtering options, clearly differentiating from siblings by explicitly stating what it does NOT show and directing to alternative tools.

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?

Explicit use cases are provided ('what changed recently', review before branching/merging, find commit by author/message) and it names alternatives (git_show, git_grep, git_reflog) for 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?

Goes beyond the destructiveHint annotation by clarifying the operation does NOT rewrite the current branch's history, which is a critical behavioral distinction from rebase. Also discloses conflict handling: 'conflicts raise a ValueError with details — resolve them and retry.' These are meaningful behavioral traits not evident from annotations alone.

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?

Five sentences, each earning its place: purpose, usage guidance, exclusions, best-for, and return/error behavior. No filler or repetition. The structure front-loads the core action and then logically expands to alternatives and edge cases.

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 tool with 4 parameters, no output schema, and a destructive operation, the description covers all key aspects: what it does, when to use it, what it doesn't do, alternatives, return value, and error handling. An agent can confidently invoke this tool and anticipate outcomes, including failure modes.

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 provides full descriptions for all 4 parameters (100% coverage), so the baseline for this dimension is 3. The description adds contextual meaning by mentioning 'squash=True' for consolidating commits and 'with or without a merge commit' which maps to no_fast_forward. However, this largely rearticulates what the schema already conveys, without adding new parameter semantics.

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: 'Merge a branch into the current branch, integrating its commits.' Clearly distinguishes from siblings by explicitly naming git_rebase and git_cherry_pick as alternatives for different use cases. 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?

Provides explicit when-to-use guidance: 'Use this to bring a feature branch back into its base when histories have diverged, or to squash a branch's work into one commit.' Also gives clear exclusions: 'use git_rebase for that; use git_cherry_pick to port specific commits instead of a whole branch.' This is model guidance for tool selection.

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 indicate readOnly=false and destructive=false. The description adds meaningful behavioral context: the pull performs a merge or rebase into the current branch, conflicts are surfaced as errors, and rebase=True changes the commit graph shape. It also clarifies it does not merely fetch. This goes beyond the annotations, though it could mention prerequisites like a clean working tree or authentication, hence a 4 rather than 5.

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 compact and front-loaded: it opens with the core action, quickly gives the primary use case, the main flag behavior, a sibling alternative, and the return format. Every sentence carries meaning 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?

Given the tool's moderate complexity, the description covers the main use case, the key parameter behavior (rebase), the conflict outcome, and even provides the return value format ('Pulled from 'origin'.' followed by per-ref lines'). It also names the alternative tool. This is sufficient for an agent to decide when to invoke git_pull and what to expect.

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 each parameter is already described. The description adds a small nudge for rebase ('rebase=True to keep a linear history'), but overall it does not add significant meaning beyond the schema's parameter descriptions and defaults. A baseline of 3 is appropriate because the schema already does 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 clearly states the tool's primary action: 'Pull from a remote and merge (or rebase) into the current branch.' It uses specific verbs and resources, and explicitly distinguishes itself from git_fetch ('Does NOT fetch only — use git_fetch...'). This makes the purpose unambiguous and differentiates it from siblings.

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 provides explicit usage guidance: 'Use this to sync local work with upstream changes,' and gives a conditional alternative via rebase=True for linear history. It also explicitly notes when NOT to use it (fetch-only use git_fetch) and how to handle conflicts ('conflicts are reported as errors, resolve and retry').

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 destructiveHint=true, but the description adds specifics: force overwrites remote history and requires confirmed=True, tags behavior, and the return format. This is helpful context beyond annotations, giving agents important behavioral details.

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?

Three sentences, front-loaded with the main action. Every sentence adds value: purpose, usage guidelines, and return info. No redundancy or wasted words.

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 no output schema, the description provides return format, remote divergence handling, and parameter behavior. With annotations and full schema coverage, the agent has sufficient information to select and invoke the tool 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 covers all 6 parameters (100%). The description adds behavioral meaning for force (overwrites history, requires confirmation) and tags (pushes tags), which goes beyond schema descriptions. It doesn't detail branch/remote/repo_path, but those are self-explanatory, so this is above baseline.

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 uses a specific verb ('Push') and names the resource ('commits to a remote'), with a clear default ('origin'). It distinguishes from siblings by referencing git_fetch/git_pull for integration, clarifying this tool is for publishing.

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 explicitly states when to use ('publish local commits', 'push tags for releases') and when not to ('Does NOT integrate upstream work'), and names alternatives ('use git_fetch or git_pull first'). Also notes force requires confirmation, providing clear contextual 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?

Annotations declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false. The description goes beyond this by explaining that rebase rewrites history (use git_log to see rewritten history) and by describing conflict-resolution behavior (mode='continue'/'abort'). It does not repeat the annotations but adds operational context. No contradiction detected.

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 compact and well-structured: it front-loads the primary action, then explains use cases, differentiates from git_merge, provides conflict-handling steps, and ends with return-value guidance. Every sentence earns its place, with no redundant filler.

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?

No output schema exists, but the description explicitly notes returns ('confirmation text or git rebase output') and suggests following up with git_log to see rewritten history. It covers the main operations (start, continue, abort, skip), distinguishes from merge, and explains the conflict workflow. This is complete for the tool's scope.

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% with descriptions for all three parameters. The description enriches semantics by clarifying that mode is for managing an in-progress rebase, and that upstream is the target for a new rebase. This adds meaning beyond the raw schema, particularly for mode's role in the workflow.

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 action ('Rebase the current branch onto an upstream') and also covers the management of in-progress rebases with mode='continue'/'abort'/'skip'. It explicitly differentiates from git_merge by stating it does NOT create a merge commit, making its purpose unambiguous among sibling tools.

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 guidance: 'Use this to keep a feature branch up to date with its base and produce a linear history' and 'Best for: keeping a feature branch up to date with its base'. It also gives an alternative (git_merge) and explains the conflict workflow (resolve and continue, or abort), so when-to-use and when-not-to-use are both covered.

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/idempotentHint/destructiveHint annotations, the description discloses return format ('Returns: "Showing <N> reflog entries for <ref>." followed by reflog text...'), behavior ('recording every local HEAD movement even after branch deletions or resets'), and boundary ('Does NOT show regular commit history'). This gives the agent a clear model of what happens without invoking the tool.

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 well-organized with front-loaded behavior, followed by usage guidance, return format, and exclusions. Every sentence contributes value and is specific rather than redundant. The structure with 'Best for:', 'Returns:', and 'Does NOT' makes it easy to parse.

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 relatively simple read-only tool, the description covers purpose, usage scenarios, return format, and alternatives. Combined with the comprehensive schema and annotations, the agent has all necessary context. No output schema exists, but the description explicitly states what the return text looks like, filling that gap.

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% with clear descriptions for all three parameters. The tool description adds only a minor clarification that passing a ref inspects a specific branch, but does not elaborate on max_count or repo_path. The schema already carries the parameter semantics adequately, so a baseline 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 clearly states the tool's function: 'Show the reflog for a ref (default HEAD), recording every local HEAD movement even after branch deletions or resets.' It includes the specific resource (reflog for a ref) and distinguishes from siblings by explicitly stating 'Does NOT show regular commit history — use git_log for that; pair with git_reset to restore a commit found here.'

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?

Usage context is explicit: 'Use this to recover lost commits after a reset or branch delete, and to answer "where was HEAD before?"' The exclusion is also clear: 'Does NOT show regular commit history — use git_log for that; pair with git_reset to restore a commit found here.' This provides both when-to-use and when-not-to-use guidance with a named alternative.

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 annotations (destructiveHint=true), the description details return formats ('one 'name -> url' line per remote', 'operation confirmation', 'No remotes configured.'), prerequisites ('add needs both name and url', 'remove/rename operate on existing remotes'), and explicitly states it does not transfer data. This significantly enriches behavioral context beyond the annotation flags.

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?

All sentences are information-dense and front-loaded with the primary purpose. The description is structured logically: purpose, use cases, return details, exclusions, and comparative advantage. No filler or repetition.

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 no output schema, the description fully explains return values and edge cases ('No remotes configured.'). It covers prerequisites, exclusions, and comparisons to alternative tools, making it complete for a moderate-complexity management tool.

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% with parameter descriptions, so baseline is 3. The description adds relationships between parameters (add needs both name and url; remove/rename operate on existing remotes), providing meaning beyond the individual schema fields.

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 'Manage remotes: list, add, remove or rename them', which is a specific verb+resource. It also distinguishes from siblings by explicitly contrasting with git_fetch, git_pull, and git_push, making its scope unambiguous.

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 use cases ('where does this repo sync to?', 'configure a new upstream', 'fix a remote URL') and exclusions ('Does NOT transfer data') with named alternatives. This fully guides when to use the tool vs siblings.

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 goes well beyond the destructiveHint annotation by explaining the safety mechanisms: requires confirmed=True to execute, run preview=True first to see discarded changes, and details how soft mode only moves HEAD without touching working tree or index. It also discloses return values and preview behavior. No contradictions with annotations.

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 well-structured with a clear opening, usage line, safety warning, alternatives, and return behavior. Every sentence contributes value, though it is slightly longer than necessary and could be tightened. It is front-loaded and organized logically.

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 fully covers a complex, destructive tool: it explains purpose, when to use, safety protocol, mode-specific effects, alternatives, and return format. Since there is no output schema, the description compensates by describing both success and preview returns. This is complete for an agent to use the tool effectively.

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 descriptions already cover all 5 parameters (100% coverage), so baseline is 3. The description adds extra meaning by explaining when confirmed and preview are needed, clarifying mode semantics (soft/mixed/hard effects), and noting the default repo_path. This goes beyond the schema, justifying a 4.

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 resets the repository to a target commit in soft, mixed, or hard mode, with examples of use cases (undo commits, unstage changes, discard working tree changes). It also distinguishes itself from git_revert and git_stash, making it unique among siblings.

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?

Explicit guidance is provided: 'Use this to undo commits, unstage changes, or discard working tree changes.' It also explicitly mentions alternatives: 'use git_revert to undo a published commit safely, or git_stash to keep changes before resetting.' This covers when-to-use and when-not-to-use with clear alternatives.

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 adds meaningful context beyond the annotations: it clarifies that this operation does NOT move HEAD backwards or discard history, and explains the no_commit behavior. While destructiveHint=true is present, the description aligns with it by noting the safe nature (new commit) and explicitly what it doesn't do. It does not disclose conflict potential or prerequisites, but given annotations heavily cover the safety profile, this is credible.

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 front-loaded with the core purpose, followed by usage guidance, alternatives, best-for, and return value, all in five concise sentences. No redundant or filler language; each sentence contributes value.

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 tool of moderate complexity with no output schema, the description covers what, when, and the return value. It does not mention potential issues like merge conflicts or working tree states, but it includes enough context for an agent to select and invoke the tool correctly, especially with sibling alternatives clearly distinguished.

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 already has 100% coverage with descriptive parameter descriptions, so the baseline is 3. The description adds a small amount of context by referring to no_commit=True in context, but it does not enrich the parameter meanings beyond what the schema provides.

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 'Revert a commit by creating a new commit that undoes it,' which precisely states the tool's function and unique mechanism. It also explicitly contrasts with git_reset and git_cherry_pick, clearly distinguishing it from sibling tools.

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 provides explicit guidance: 'Use this to safely undo a published commit without rewriting history, when other people may already have the commit.' It also states when NOT to use it, naming alternatives ('use git_reset for that; use git_cherry_pick to re-apply a commit instead of undoing it'), fulfilling the highest bar for usage 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?

The description claims 'stat defaults to True' while the input schema states stat has a default of false. This is a direct contradiction with the structured schema and misrepresents the tool's actual default behavior. Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered, but the inaccurate statement about stat undermines behavioral transparency.

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 well-structured with distinct sections: purpose, use case, returns, and exclusions. It is appropriately sized and front-loaded with the primary purpose. Minor redundancy exists ('inspect exactly what a specific commit changed' appears twice), but overall every sentence contributes value. Score 4, not 5, due to the redundancy and the contradictory stat default.

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 covers purpose, usage, return format, and exclusions, and names sibling alternatives. However, the contradiction about stat's default (saying True vs schema's false) creates incomplete and misleading context. With no output schema, the description must be accurate, and this error prevents it from being fully complete.

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 baseline is 3, but the description introduces a factual error: 'stat defaults to True' contradicts the schema's default of false. While it adds useful context for the object parameter (defaults to HEAD, omit to see latest change), the incorrect stat default is misleading and reduces the reliability of parameter understanding.

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 verb ('Render a commit's metadata and patch') and resource (specific commit, defaulting to HEAD). It distinguishes itself from siblings by explicitly noting it does NOT list history (use git_log) and does NOT compare working tree changes (use git_diff). This is a specific and unambiguous purpose.

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 when-to-use guidance: 'Use this to inspect exactly what a specific commit changed' and 'Best for: inspecting what a specific commit changed.' It also provides explicit when-not-to-use with alternatives: 'Does NOT list history — use git_log to find commits; does NOT compare working tree changes — use git_diff for that.' This is exactly what the dimension asks for.

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 destructiveHint annotation, the description discloses that only drop removes a stash and requires confirmed=True, push preserves changes and needs modified tracked files, and pop restores work. This clarifies exactly which operations are destructive and what conditions apply.

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 front-loaded with the core purpose and operation list. It is slightly redundant ('Best for' repeats the earlier use case), but each sentence contributes useful information about behavior, prerequisites, returns, and related tools, making it tight overall.

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?

Without an output schema, the description still communicates the return type ('stash listing, or git stash output'), all supported operations, prerequisites for each, and related tool usage. It provides sufficient context for an agent to safely and correctly invoke the tool across its operations.

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 already covers all 5 parameters with descriptions, so the baseline is 3. The description adds extra operational constraints not present in the schema, such as drop requiring confirmed=True and push needing modified tracked files, which enriches parameter understanding.

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 specifies it manages stashes with operations list, push, pop, and drop, which is a concrete verb+resource. It also distinguishes from related tools by explicitly referencing git_checkout and git_reset for switching branches or discarding changes, avoiding confusion with siblings.

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 explicitly says 'Use this to set aside uncommitted work before switching branches, or to restore previously stashed work.' It further provides alternatives: 'Use git_checkout after stashing to switch branches; use git_reset to discard changes instead of preserving them,' giving clear when-to-use and when-not-to-use 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?

Annotations already mark this as readOnly/idempotent/non-destructive. The description adds substantial behavioral detail: the exact return format with first line and sections, the 10-file cap with ', and N more', and the effects of short and include_untracked flags. This goes well beyond the annotation safety profile.

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 well-organized and front-loaded. It opens with the core purpose, then usage, then return format, then exclusions, and a final comparison to raw git status. Every sentence contributes value, and it is appropriately sized for the tool's complexity.

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 three optional parameters and no output schema, the description fills gaps by specifying the return format, parameter effects, and explicitly contrasting with sibling tools. The combination of annotations, schema, and description fully equips the agent to select and invoke the tool 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?

The schema already describes all parameters, so baseline is 3. However, the description adds meaningful semantics: 'short=True gives compact "--short --branch" output' and 'include_untracked=False omits untracked files', which explains how these flags alter the return shape.

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 and resource: 'Show the repository's working tree state: current branch, staged, modified and untracked files.' It also explicitly distinguishes from siblings by stating what it does NOT do ('Does NOT show file contents or diffs — use git_diff; does NOT list commit history — use git_log').

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 usage context: 'Use this at the start of any edit task to answer "what changed?", and before committing to verify what will be staged.' It also names alternatives for non-covered cases, fulfilling the when/when-not/alternatives criterion.

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 annotations provide minimal safety information (not read-only, not idempotent, not destructive), so the description adds valuable behavioral context. It explains that 'update fetches and inits all submodules,' describes the return output including the 'No submodules found.' case, and notes that 'add needs both url and path.' This goes beyond the annotations without contradicting them.

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 four sentences, front-loaded with the core purpose, and every sentence adds value: usage, return info, parameter constraints, and an explicit alternative. No wasted words.

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 tool with no output schema and minimal annotations, the description covers purpose, usage scenarios, return values, parameter requirements, and a key limitation. It thoroughly equips an agent to select and invoke the tool 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?

The input schema already includes descriptions for all four parameters (100% coverage), so baseline is 3. The description adds extra meaning by specifying that 'add needs both url and path' and that 'update fetches and inits all submodules,' which clarifies parameter relationships and operation behavior beyond 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?

The description clearly states the tool manages submodules with specific operations: 'show status, add a new one, or update all of them.' It distinguishes itself from sibling tools like git_clone and git_status by focusing on submodule-specific actions and explicitly noting it does not clone the superproject.

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: 'Use this when a repository embeds external repositories, to check whether embedded repos are in sync, or to add a new dependency as a submodule.' Also names an alternative: 'Does NOT clone the superproject — use git_clone for that.'

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 destructiveHint annotation, the description adds important behavioral context: delete requires confirmed=True, annotated=True needs a message, and the return values differ by operation. This helps the agent understand side effects and prerequisites.

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 front-loaded with the core capability and then adds essential details. It is somewhat verbose with the 'Best for' line repeating earlier usage guidance, but every sentence adds useful information.

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 6 parameters and no output schema, the description covers all operations, key parameter constraints, and return value expectations. It does not explicitly describe repo_path, but that is adequately covered in the input schema.

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%, but the description adds relationships between parameters (e.g., 'delete requires confirmed=True', 'annotated=True needs a message') and clarifies expected outputs per operation, providing value beyond the schema definitions.

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 manages tags with a specific set of operations: list, create, delete. It explicitly differentiates from sibling tools by stating 'Does NOT branch or switch' and points to git_branch and git_checkout as alternatives.

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 provides explicit when-to-use guidance ('mark release points in history', 'list existing releases') and clear exclusions/alternatives: 'use git_branch for branches and git_checkout to switch to a tag'.

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 annotations (destructiveHint=true), the description discloses specific behavioral traits: it does not switch the main working tree, removal requires confirmed=True, and add refuses non-empty paths. These are critical for safe operation and are not present in the schema or annotations.

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 compact yet information-dense, with clear front-loading of purpose and structured labels for 'Best for' and 'Returns.' Every sentence earns its place without repetition or fluff.

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 multiple operations, no output schema, and destructive behavior, the description covers return values, operation-specific quirks, and prerequisites. It provides a complete mental model for an agent to invoke the tool 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%, so the baseline is 3, but the description adds meaningful parameter semantics: 'remove requires confirmed=True' clarifies the confirmed parameter, and 'add refuses non-empty paths' explains worktree_path behavior. This adds value beyond 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?

The description opens with 'Manage linked worktrees: list, add, or remove them,' a specific verb+resource combination. It clearly distinguishes from siblings by stating 'Does NOT switch the main working tree — use git_checkout for that; use git_branch to see which branches can be added.'

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 states when to use the tool ('check out multiple branches simultaneously,' 'work on a second branch without stashing') and names alternatives (git_checkout, git_branch). This goes beyond implied context to give actionable guidance.

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