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

No annotations are supplied, so the description carries the full behavioral burden, yet it says nothing about side effects: whether it writes to a config file, whether IDs must be unique, what happens on duplicate IDs, or that optional SSH/transport/token fields are stored. For a mutation tool with 10 parameters this is a significant disclosure gap.

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?

It is a single front-loaded sentence with no wasted words or filler. It is efficient, though its brevity borders on under-specification rather than true conciseness.

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 10 parameters, no annotations, and no output schema, the description should explain persistence, validation, and error behavior. As written, an agent knows only that something is added and nothing about consequences or return value, which is insufficient for a config-mutating 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 description coverage is 100%, so every parameter including id, key, alias, transport, and signing_key is already documented in the schema. The description adds no meaning beyond that (e.g., how alias relates to key or host), so the baseline of 3 applies.

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 gives a specific verb and resource ('Add a new Git profile'), which is unambiguous about what the tool creates. It does not, however, distinguish this from sibling tools such as gitchanger_switch or gitchanger_set_default, which a user might confuse with profile creation/setup.

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?

There is no guidance on when to use this versus alternatives: nothing about whether the profile must not already exist, what to do for an existing profile, or which sibling handles switching/defaults afterward. The sentence simply restates the operation with no exclusions or prerequisites.

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?

With no annotations, the description carries the full burden of behavioral disclosure. It identifies the tool as destructive but does not state that deletion is irreversible, what related data is removed, or that an SSH Host entry may be affected unless keep_ssh is true.

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 concise sentence with no wasted wording and the action is front-loaded. It is appropriately sized, though its brevity contributes to the missing behavioral and usage context.

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

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

The tool is structurally simple with two well-described parameters and no output schema, but the absence of annotations makes the missing destructive-behavior details more important. A complete definition should explicitly note irreversibility and the SSH config side effect.

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 both the required profile ID and the optional keep_ssh flag are already documented in the input schema. The description adds no further meaning or constraints beyond those schema descriptions, which fits the baseline of 3.

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 a specific verb and resource: delete a Git profile from GitChanger. It distinguishes the operation from siblings like list, switch, or add by naming the deletion action, though it does not explicitly compare against 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?

There is no guidance on when to use this deletion tool versus alternatives, no prerequisites, and no warning about conditions such as whether the profile must exist or be unused. Usage is only implied by the verb 'delete'.

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?

No annotations are supplied, so the description carries the full burden. 'List' implies read-only behavior and no mutation, but the description does not explicitly confirm that it is non-destructive, what permissions are needed, or what the returned details contain.

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 front-loaded sentence with no filler. Every part earns its place by naming the action, the resource, and the scope.

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 simple listing tool this is mostly adequate, but without an output schema the description does not clarify the default return shape or how the 'verbose' flag changes the details. It leaves some ambiguity about what 'configured profiles with their details' includes by default.

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 fully documents the sole optional 'verbose' parameter at 100% coverage. The description adds no additional meaning about how verbose changes the output, so the schema 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 uses a specific verb and resource: 'List all configured Git profiles in GitChanger'. It is clear this is a read/list operation, though it does not explicitly distinguish itself from nearby discovery tools such as gitchanger_status or gitchanger_mcp_get.

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?

There is no explicit when-to-use guidance, prerequisites, or comparison against alternatives. The use case is only implied by 'List all configured Git profiles'.

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?

No annotations are supplied, so the description carries the full behavioral burden, yet it discloses almost nothing: it never says the token is masked by default (that fact lives only in the schema's unmask field), that the operation is side-effect-free, or that a credential/secret is being returned. For a tool that surfaces authentication material, this is a notable gap, though 'Retrieve' does correctly signal a read rather than a mutation.

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?

A single front-loaded sentence with no filler, which is appropriate for a two-parameter lookup tool. It loses a point only because the trailing clause about 'active MCP client configuration' is vague rather than 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?

For a simple zero-required-parameter read tool with fully documented schema, this covers the essentials, and the absence of an output schema is partly mitigated by naming the returned artifact (the token). It would be stronger if it clarified the masked-by-default return shape and what happens when no token is configured for the profile.

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%, and both parameters already document their semantics ('Return full unmasked token', 'Profile ID (uses active profile if omitted)'), so the baseline of 3 applies. The description's phrase 'for a profile or active MCP client configuration' loosely corroborates the fallback behavior but adds no format or precedence detail 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 gives a specific verb ('Retrieve') and resource ('configured GitHub MCP token'), which distinguishes it from siblings like gitchanger_mcp_set, gitchanger_mcp_status, and gitchanger_mcp_sync. The scope phrase 'for a profile or active MCP client configuration' adds a second dimension, though 'MCP client configuration' is never explained and remains ambiguous.

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?

There is no explicit guidance on when to use this instead of gitchanger_mcp_status or gitchanger_mcp_test, nor when to set unmask. The reader must infer that this is the read counterpart to gitchanger_mcp_set from the name alone. No prerequisites or cautions are stated.

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?

With no annotations, the description carries the full behavioral burden for a destructive mutation. It does not say whether removal is reversible, whether confirmation is required, what happens if both arguments are omitted, or which config files/'detected MCP client configuration files' are touched. The only behavioral hint is that removal may target multiple destinations.

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?

A single front-loaded sentence with no filler; the scope ('from a profile and/or MCP client configs') follows immediately after the verb. Brevity is appropriate, though it leaves little room for the behavioral detail a destructive tool needs.

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 destructive tool with zero annotation coverage, no output schema, and zero required parameters, the description is too thin. It never states the result of the operation or the no-argument behavior, both of which an agent needs before invoking it.

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 both parameters are already documented and the baseline is 3. The word 'and/or' in the description usefully signals that the two targets are independent and optional, but adds nothing about defaults or precedence when both are supplied.

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 ('Remove GitHub MCP token') and scopes it to 'a profile and/or MCP client configs', which separates it from siblings like gitchanger_mcp_set or gitchanger_mcp_sync. It stops short of explaining how it relates to the broader profile lifecycle (gitchanger_delete), so it is clear but not maximally differentiated.

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?

There is no explicit when-to-use or when-not-to-use guidance and no mention of alternatives such as gitchanger_mcp_sync or gitchanger_mcp_set. The agent must infer that this is the inverse of gitchanger_mcp_set purely from the names.

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?

No annotations are supplied, so the description carries the full behavioral burden for a tool that writes a credential. It does not disclose whether an existing token is overwritten, where the token is persisted, whether the token is validated before storage, or any security/permission implications of storing a plaintext PAT.

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?

A single compact sentence with the key resource front-loaded and no filler. It is arguably too terse for a credential-writing tool, but nothing in it is wasted.

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 five parameters, no annotations, and no output schema, the definition is minimally adequate: the agent knows the intent but not the side effects on existing configuration or the overwrite semantics. For a mutation tool touching credentials, that leaves meaningful 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 all five parameters are already documented in the schema. The description adds a little meaning by mapping profile vs. direct to two distinct outcomes, which helps the agent understand they are mutually exclusive paths, but it adds no detail on token format, the 'file' override, or sync interaction 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?

States a specific verb (Set) and resource (GitHub MCP Personal Access Token) and names the two target modes: a profile or directly into MCP client configs. This clearly separates it from siblings like gitchanger_mcp_get or gitchanger_mcp_remove, though it does not explicitly contrast with gitchanger_mcp_sync, which also writes tokens to client configs.

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 two modes (profile-scoped vs. direct) are implied by the phrase 'for a profile or directly into MCP client configs,' but the agent gets no explicit guidance on when to use each, whether a profile must already exist, or when to prefer gitchanger_mcp_sync afterward.

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?

With no annotations, the description carries the full behavioral burden. The verb "Show" implies a read-only operation and the description usefully discloses that status is gathered across profiles and detected AI client configurations, but it does not explicitly state that nothing is modified or mention any permission considerations.

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 definition is a single front-loaded sentence with no redundant wording. The parenthetical list of detected AI clients is compact and directly relevant to the tool's scope.

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 low-complexity status tool with one optional parameter and no output schema, the description is largely complete: it identifies the resource, the scope, and the client configurations covered. The remaining gap is the lack of explicit read-only/side-effect language, which matters because no annotations are provided.

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 optional cwd parameter is already documented in the schema. The description adds no additional meaning about how cwd affects status detection, which is acceptable given the high schema coverage 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 states a specific verb, "Show," and a precise resource, "GitHub MCP token status," with scope across profiles and detected AI client configurations. It clearly distinguishes this as a status-viewing tool, though it does not explicitly contrast it with sibling tools such as gitchanger_mcp_get or gitchanger_mcp_test.

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 implies a diagnostic use case by saying it shows token status, but it gives no explicit guidance on when to use this tool versus alternatives. It does not mention when not to use it, prerequisites, or how it relates to sibling tools like gitchanger_mcp_get or gitchanger_mcp_test.

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?

No annotations are supplied, so the description carries the full behavioral burden and falls short. It does not state whether existing tokens in config files are overwritten, whether backups are made, what permissions are required, or how partial failures are reported — all critical for a tool that rewrites config files.

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?

A single front-loaded sentence with no filler; the scope qualifier 'all detected' is placed where it matters.

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

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

For a zero-annotation config-mutating tool with no output schema, the definition omits far too much: overwrite semantics, failure behavior, and target resolution are all unstated. An agent could invoke it correctly but cannot predict its side effects.

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 both parameters are already documented, and the description only adds the phrase 'all detected MCP client configuration files'. It does not explain how the optional file parameter interacts with that 'all detected' scope, which is the main semantic ambiguity.

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 (sync) and a specific resource (a profile's GitHub token into MCP client config files). It is distinguishable from siblings such as gitchanger_mcp_set or gitchanger_mcp_remove, though it never names them explicitly.

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 is only implied: 'all detected MCP client configuration files' suggests a bulk operation versus a single-target one, and the file param hints at a custom target. There is no explicit when-to-use/when-not guidance or reference to alternatives like gitchanger_mcp_set.

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?

No annotations are supplied, so the description carries the full behavioral burden. It usefully discloses that the check goes out to the GitHub API (an external authenticated call) and that it only verifies rather than modifies, but it says nothing about rate limiting, network failure behavior, or what happens when the token is invalid or expired.

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?

A single front-loaded sentence with no filler; the checked attributes are listed compactly. It is efficient, though the enumeration could have been split so the target (GitHub API) leads rather than trails.

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 simple, zero-required-parameter read-only diagnostic with no output schema, the description covers what the tool inspects (validity, username, scopes), which effectively conveys what the caller gets back. The remaining gap is failure/edge-case behavior, which is minor at this complexity.

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%, and the two parameters (token, profile) are already fully documented in the schema, including the fallback to the active token. The description adds no additional meaning about precedence between the two or formatting of the token, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb+resource pair ('Test and verify GitHub token validity, account username, and OAuth scopes against GitHub API') and enumerates exactly what is checked, so an agent knows it is a credential diagnostic rather than a credential-mutating tool. It does not explicitly name the closest sibling, gitchanger_test_ssh, which handles the analogous SSH case.

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?

There is no explicit when-to-use or when-not-to-use guidance; the diagnostic intent is only implied by the verbs 'test and verify'. Nothing routes the agent away from gitchanger_test_ssh or gitchanger_status, both of which sit adjacent in the sibling list and could plausibly be confused with a credential check.

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?

No annotations are provided, so the description carries the full behavioral burden; it does disclose the exact locations read, which is meaningful. It does not state that the operation is read-only/non-destructive, whether private key material is read or exposed, or what the scan produces, leaving real gaps for a filesystem-touching 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?

A single tight sentence with the resources front-loaded and no filler. It could be slightly stronger by leading with the action's purpose rather than only listing paths, but nothing is wasted.

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 no annotations and no output schema, the description should say something about what a scan returns or what the agent should do with it. It names the inputs well but leaves the result shape and safety profile for the agent to discover.

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 has zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; the description correctly implies the tool runs without any user-supplied scope.

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 gives a specific verb ("Scan") plus three concrete resources it inspects: the ~/.ssh directory, SSH config, and MCP client configurations. That is far more informative than the bare name 'gitchanger_scan', though it never explicitly distinguishes itself from siblings like gitchanger_status or gitchanger_mcp_status that could plausibly surface overlapping information.

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?

There is no guidance on when to run this versus gitchanger_list, gitchanger_status, or gitchanger_mcp_get. Use is only implied by the word 'scan', and with fourteen sibling tools in the namespace an agent gets no routing signal here.

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?

No annotations are provided, so the description carries the full burden and largely fails it. It says nothing about whether the change is persistent, whether it affects the currently active profile, whether it overwrites an existing default, or whether errors occur for unknown profile IDs — all relevant for a configuration mutation.

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?

One short front-loaded sentence with no filler or repetition. It is efficient, though the brevity reflects under-specification rather than tight compression of rich content.

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 one-parameter tool with full schema coverage and no output schema, the definition is minimally adequate. The gaps are the unannotated mutation semantics and the unresolved default-versus-switch distinction, which matter given the dense sibling set.

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% and the single parameter is documented as "Profile ID to set as default," so the baseline is 3. The description adds no format hints, no indication of what a valid ID looks like, and no note on whether an ID or profile name is accepted.

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?

"Set a profile as the default GitChanger profile" names a specific verb and resource, so the basic action is unambiguous. However, it never distinguishes "default" from the sibling gitchanger_switch, so an agent cannot tell from the description whether setting a default also activates the profile or how it relates to switching.

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?

There is no guidance on when to use this versus gitchanger_switch, gitchanger_add, or gitchanger_list, and no stated prerequisites such as the profile having to exist first. The agent must infer the choice entirely from sibling names.

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?

No annotations are supplied, so the description carries the full burden. 'Show' correctly signals a non-mutating read, and the enumerated fields tell the agent what information comes back. However, it does not disclose failure behavior outside a Git repository, whether the global environment is reported alongside or instead of the repository, or whether any config is read from disk.

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?

A single front-loaded sentence with no filler or repetition, and the resource list is ordered from most to least expected. It is slightly dense as a comma-separated enumeration, but every element names a distinct reported value, so nothing is wasted.

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 two-optional-parameter, read-only status tool with no output schema, the description is largely sufficient because it enumerates the returned fields in place of a schema. The remaining gap is the absence of any note on behavior when cwd is omitted or points outside a repository. A simple status tool does not need much more than this.

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 both optional parameters (cwd, verbose) are already documented with adequate detail in the schema. The description adds only a light hint that the target scope can be repository-level or global, without mapping that to the cwd parameter or explaining what verbose diagnostics change. Baseline 3 applies when the schema 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 opens with a specific verb ('Show') and enumerates the exact resources reported: Git identity, matching GitChanger profile, remote URLs, and GitHub MCP token status. This is far more concrete than a tautology. It stops short of 5 because it never distinguishes itself from the closely named sibling gitchanger_mcp_status, which plausibly reports an overlapping token-status slice.

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?

Scope is implied ('for the repository or global environment'), which hints that this is the diagnostic entry point before switching identities, but no explicit when-to-use or when-not-to-use rule is given. The agent must infer whether to call this versus gitchanger_list or gitchanger_mcp_status. No prerequisites (e.g., must be inside a Git repo) are stated.

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?

With no annotations provided, the description carries the full burden, and it does substantial work: it discloses the write side effects (rewriting git user.name/email, SSH host alias and keys, ssh-agent insertion, and syncing the GitHub MCP token to AI clients). It still omits failure handling, whether remote URL rewrites occur by default (only visible via the schema's no_remote_update flag), and whether prior config is recoverable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, both load-bearing, with the core action and scope front-loaded before the list of automated side effects. Nothing is redundant or padding.

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 7-parameter mutating tool with no annotations and no output schema, the description covers the action, scopes, and the major side effects an agent must be aware of before invoking it. Remaining gaps are outcome reporting and failure/reversibility behavior, which are modest for this complexity.

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 earns a bump by explaining the automatic behaviors that the opt-out flags (no_ssh_agent, no_mcp) exist to suppress, giving those booleans practical meaning. It adds little for cwd, global, or test beyond what the schema already says.

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 gives a specific verb ('Switch') plus resource ('active Git profile') and states the two scopes it operates on ('current repository or globally'), which separates it from siblings like gitchanger_status or gitchanger_list. It does not explicitly distinguish itself from gitchanger_set_default or gitchanger_add, so the differentiation is implied rather than stated.

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 is only implied: the agent can infer it should call this when it wants a profile applied to a repo or globally. There is no explicit guidance about when to prefer gitchanger_set_default, gitchanger_add, or gitchanger_test_ssh, and no stated prerequisites such as the profile already existing in the configured list.

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?

No annotations are supplied, so the description carries the full burden, and it discloses almost nothing: it doesn't say whether the test is non-destructive, whether it performs a real network handshake (with timeout or host-key prompt implications), or what happens on failure. For a connectivity tool with zero annotation coverage, that is a substantial gap.

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?

One short, front-loaded sentence with no filler or redundancy. It is efficient, though the brevity comes at the cost of the behavioral and usage detail noted elsewhere.

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 (one required parameter), but there is no output schema and no annotations, so the description should at least indicate what a result looks like (boolean, message, latency, error text). An agent cannot predict the return shape or failure mode from this definition.

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

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

Schema description coverage is 100% and the single parameter 'profile' is documented as the profile ID to test. The description adds only the adjective 'Git', which is marginal value beyond the schema; the baseline of 3 applies when the schema 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 gives a specific verb and resource: it tests an SSH connection for a Git profile, which is meaningfully distinct from the mcp_test and mcp_status siblings. It stops short of naming which sibling to use for non-SSH checks, so the differentiation is implicit rather than stated.

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?

There is no guidance on when to call this tool: not before switching profiles, not after adding or scanning, and no mention of prerequisites such as the profile existing or keys being configured. The agent must infer all usage context from the one-line purpose statement.

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