gitwhy-mcp

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

The description uses read-oriented language ('Retrieve', 'Returns') implying a safe read operation, but the annotations declare readOnlyHint=false and destructiveHint=true. This creates a dangerous contradiction where the agent expects a non-destructive fetch but the tool actually performs destructive operations.

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 efficiently structured with three sentences: first stating the action, second specifying usage conditions, and third providing the CLI alternative. No words are wasted and the most critical information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description explains return values (helpful since there's no output schema), but fails to disclose critical behavioral traits revealed in annotations—specifically that this is a destructive, non-idempotent operation. Given the destructive annotation, the description should warn about what gets destroyed or modified.

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?

While the schema has 100% coverage for the single 'id' parameter, the description adds valuable semantic context by specifying where the ID comes from ('e.g., from gitwhy_search or gitwhy_list results'), clarifying the relationship between this tool and its siblings.

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 retrieves a saved context by ID and specifies what it returns (full markdown content including metadata, reasoning, and file changes). It effectively distinguishes this from sibling tools gitwhy_search and gitwhy_list by referencing them as sources for obtaining the ID.

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 clear guidance on when to use the tool ('when you know the exact context ID') and implies the workflow (use search/list first to find IDs). It also includes a CLI alternative for context. However, it lacks explicit '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?

Serious contradiction: Description frames tool as 'Browse' and 'discover' (read operations), but annotations declare readOnlyHint=false and destructiveHint=true. An agent reading 'Browse' would assume safe reading, but annotations indicate this performs destructive mutations. Description fails to disclose the actual destructive behavior suggested by 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?

Perfectly structured with zero waste: front-loaded purpose, followed by usage patterns, then optional CLI context. Four sentences that each earn their place. Appropriate length 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?

Without output schema, description adequately explains the domain/topic hierarchy concept, but fails to address the discrepancy with destructive annotations. For a tool claiming to browse but annotated as destructive, the description is incomplete regarding actual side effects and return structure.

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?

Adds valuable usage context beyond the 100% schema coverage: explains 'no args' behavior, 'drill down' patterns, and validates the domain/topic relationship. Schema tells what parameters exist; description tells how to use them effectively.

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?

Excellent specificity with 'Browse saved contexts and the domain/topic tree structure'—clear verb, resource, and scope. Effectively distinguishes from sibling tools like gitwhy_get (retrieve specific) and gitwhy_save (write) by emphasizing discovery and tree hierarchy exploration.

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 concrete usage patterns: 'Call with no args to see the domain/topic hierarchy' and 'Add filters to drill down.' Mentions CLI alternatives for context. Lacks explicit 'when not to use' relative to gitwhy_search or gitwhy_get, but strong positive 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 adds critical workflow context (must publish first) and clarifies the side effect (PR comment with summary). It aligns with annotations (destructive mutation, not idempotent) by mentioning 'Post or update'. It could explicitly state that repeated calls may create duplicate comments or overwrite, but the 'update' keyword hints at the 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?

Three sentences deliver: (1) core function, (2) usage trigger, (3) prerequisite and CLI alternative. Zero redundancy, front-loaded with the action, and every sentence provides distinct value not found in structured fields.

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, the description adequately covers the workflow dependency (publish first) and intended audience (reviewers). Given the 3 optional parameters and clear side effects, it provides sufficient context for invocation, though it could briefly note the auto-detection behavior when pr_number is omitted.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema description coverage, the schema carries the parameter documentation burden. The description references 'context-id' in the CLI example which loosely maps to the 'ids' parameter, but doesn't add semantic detail beyond the schema. Baseline 3 is appropriate given comprehensive 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 specific action ('Post or update') and resource ('GitHub PR comment'), along with the content ('development context for linked commits'). It effectively distinguishes this from sibling tools like gitwhy_publish by focusing on the PR commenting workflow.

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 ('when the developer wants reviewers to see the why'), names the prerequisite sibling tool ('Contexts must be published first via gitwhy_publish'), and provides a CLI alternative for context. This creates a clear decision framework for the agent.

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?

Adds valuable behavioral context beyond annotations: specifically discloses the auto-sync side effect ('Auto-syncs to cloud if not already synced') and maps to CLI equivalent, though could elaborate on visibility scope or permissions.

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 tightly constructed sentences front-loaded with purpose, followed by side effects, usage conditions, and CLI mapping. No redundant or filler content; every clause delivers actionable 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?

Comprehensive for a single-parameter mutation tool: covers purpose, behavioral side effects, usage timing, and CLI parity. Lacks only error handling specifics (e.g., invalid IDs, already-shared contexts) which would elevate it to 5.

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 clear parameter description ('JSON array string of context IDs'). The description implies the inputs are contexts but does not add syntax, format details, or examples beyond what the schema already provides, meeting baseline expectations.

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 specific action ('Make synced contexts visible') and target resource (shared team contexts), clearly distinguishing from siblings like gitwhy_save or gitwhy_sync by emphasizing team visibility/sharing aspect.

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 ('when the developer wants teammates to see their context') and provides concrete scenarios ('typically after a PR is merged or a milestone is reached'), effectively differentiating from private sync operations.

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 cover safety profile (destructiveHint=true, readOnlyHint=false). Description adds valuable behavioral context not in annotations: auto-population of 'Context ID, repository, branch, date, and commits', and that repo_root updates persist for subsequent calls. Does not explicitly address non-idempotent behavior (multiple saves create multiple entries), though annotation covers this.

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?

Lengthy but justified by complexity of required XML format. Well-structured with purpose front-loaded, followed by usage timing, then detailed formatting guide. The CLI alternative section at the end provides useful escape hatches without cluttering primary usage instructions. Every section serves a distinct purpose.

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?

Comprehensive coverage for a 5-parameter tool with complex structured input requirements. Describes input format exhaustively (XML structure), documents auto-population behavior, and provides CLI alternatives. No output schema exists, and description correctly focuses on input requirements rather than return values.

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?

Despite 100% schema coverage (baseline 3), description adds substantial value: detailed XML schema for the 'markdown' parameter with required/optional tags, explanation that 'commits' auto-detects from git history when omitted, and crucial note that 'repo_root' affects subsequent tool calls. Elevates beyond 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?

Description opens with specific verb 'Save' and clear resource 'development context (reasoning, decisions, trade-offs)'. The scope 'for the current coding session' and extensive XML format details clearly distinguish this write-operation tool from siblings like gitwhy_get and gitwhy_search.

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 timing guidance ('Use after completing a meaningful unit of work') and detailed format instructions. However, it does not explicitly differentiate when to use this versus siblings like gitwhy_publish or gitwhy_post_pr in a workflow context.

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

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

Annotations declare readOnlyHint=false and destructiveHint=true, but description doesn't explain why a search operation is destructive or non-idempotent. Adds valuable context about search scope (titles, reasoning, code snippets), result ranking, and authentication requirements for cloud workspaces.

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?

Efficiently structured with core action first, followed by search scope, result composition, usage guidance, and CLI alternative. No redundant sentences; every clause adds distinct 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?

Comprehensive coverage of search behavior, result types (local vs. cloud), and follow-up actions. No output schema exists, but description clarifies that results are 'summaries' requiring gitwhy_get for full content, adequately compensating for missing return type documentation.

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 applies. Description mentions 'natural language or specific terms' which aligns with query parameter, but doesn't add syntax constraints or validation rules beyond the schema documentation.

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 specific action ('Search saved contexts') with clear mechanism ('hybrid keyword + semantic search') and distinguishes from sibling gitwhy_get by specifying when to use each ('Use gitwhy_get...to read the full context' vs search for finding).

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 lists use cases ('finding past decisions, understanding why code was written'), provides clear alternative tool for full content retrieval (gitwhy_get), and mentions CLI equivalent for context.

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 annotations indicate destructiveHint=true and readOnlyHint=false, the description adds crucial behavioral context: the repo auto-detection may incorrectly resolve to the home directory (requiring correction), and it notes the side effect that passing repo_root updates context for subsequent calls. CLI alternatives add further 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?

Four sentences with zero redundancy. Front-loaded with core functionality, followed by usage scenarios, then an IMPORTANT alert about response handling, and finally CLI references. Every sentence earns its place; the capitalization of 'IMPORTANT' effectively prioritizes the critical repo_root behavioral note.

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 lacking an output schema, the description references specific response fields ('repo_root field in the response') and enumerates the three status components returned. It adequately covers the destructive/side-effect behavior hinted by annotations. Could slightly improve by hinting at the format of 'pending commits' (count vs list), but overall complete for a status 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%, establishing a baseline of 3. The description adds significant value by specifying WHEN to use the parameter (when response shows home directory) and WHY (to correct detection), transforming a simple path parameter into actionable troubleshooting guidance.

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 ('Check') and clearly enumerates the three specific resources inspected: 'GitWhy setup state, pending commits, and sync status.' This effectively distinguishes it from action-oriented siblings like gitwhy_save or gitwhy_sync by emphasizing diagnostic/status-checking functionality.

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 three concrete usage scenarios: determining whether to suggest saving context, checking authentication for cloud features, and verifying initialization. Also offers CLI alternatives for user comparison. Lacks explicit 'when not to use' exclusions, but the specific positive guidance and sibling context provide strong implicit direction.

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 and openWorldHint=true; the description adds valuable behavioral context about deduplication logic ('skip all dedup checks') via the force parameter explanation and clarifies privacy semantics ('not shared with team'). Could explicitly acknowledge the destructive overwrite behavior, but the dedup context provides meaningful behavioral transparency beyond 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?

Three efficiently structured sentences: first establishes action and privacy status, second provides workflow timing, third offers CLI alternative. Every sentence contributes distinct value (purpose, prerequisites, alternative interface) with zero 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?

Comprehensive coverage for a sync tool: explains privacy implications, workflow integration with gitwhy_save and gitwhy_publish, CLI parity, and deduplication behavior. Lacks explicit description of return values (no output schema), but annotations and parameter coverage provide sufficient operational context for agent decision-making.

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%, establishing baseline 3. The description adds CLI syntax context ('git why push <context-id>') demonstrating parameter usage patterns and elaborates on deduplication behavior for the force parameter, providing usage context 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?

Specific verb 'Upload' with clear resource (local contexts to GitWhy cloud) and scope (private/not shared with team). Explicitly distinguishes from sibling gitwhy_publish by stating contexts 'remain private until explicitly published with gitwhy_publish', clarifying the privacy boundary.

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 workflow guidance ('Use after saving contexts locally') and clear sequencing for backup purposes. Names the specific sibling tool (gitwhy_publish) as the alternative for making contexts public, establishing clear when-to-use vs when-not-to-use boundaries.

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