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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered, but the description adds non-obvious behavior: long files are cut and flagged `truncated`, which tells the agent results may be incomplete. It does not state what happens with binary/non-text files or whether private repos require additional auth, leaving some behavioral ground uncovered.

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 short sentences with zero filler; the core action comes first, followed by the truncation caveat and the alternative-tool routing. Every sentence 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?

An output schema exists so return values needn't be explained, and the description usefully covers the truncation flag that appears in output. The only gap is handling of non-text or very large/binary files, which the tool name's scope implies but does not state outright.

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 67%, with both non-obvious parameters (ref, repo) already documented in the schema including their defaults. The description adds no parameter-level meaning, so the schema does the heavy lifting and 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?

States a specific verb and resource ("Read a text file") and explicitly demarcates the boundary against a sibling: "For a directory use github_list_directory." An agent can distinguish this from the list/get siblings without opening any schema.

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?

Names the alternative tool and the condition that selects it (directories → github_list_directory), which covers the most likely confusion case. It does not address other conditions such as binary files or when to prefer listing pull request files instead, but the key routing decision is 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds that mergeability and review metadata are included, hinting at extra server-side computation, but says nothing about errors for missing PRs or permission requirements. With annotations doing the heavy lifting, this is an adequate-but-thin addition.

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 enumeration of returned fields is mildly redundant given an output schema exists, but it still conveys scope efficiently.

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?

An output schema covers return values and annotations cover safety, so the description only needs to fill parameter and usage gaps — which it largely does not. For a simple two-parameter read tool it is minimally sufficient, but the undocumented required number parameter and lack of sibling routing leave 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 only 50%: repo documents its 'owner/name' format and GITHUB_MCP_DEFAULT_REPO fallback, but the required number parameter has no description anywhere. The description mentions no parameters at all, so it does not compensate for the gap.

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 and resource ("Get one pull request") and enumerates the detail fields returned, which implicitly separates it from the sibling github_list_pull_requests. It does not explicitly name that sibling, so differentiation is left to the reader.

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 statement of when to use this versus github_list_pull_requests or github_get_pull_request_files, and no prerequisites (e.g., needing a PR number, whether closed PRs are visible). Usage is only inferable from the name.

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 this as a read-only, non-destructive, open-world operation. The description adds genuinely useful context beyond them: long diffs are truncated and this is signaled via the `patch_truncated` field, which an agent would otherwise miss.

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 the truncation caveat in a parenthetical. Nothing is wasted and the key behaviors come first.

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?

An output schema exists, so return values need not be explained, and the truncation note is a valuable addition. However, with three parameters and low schema coverage, the definition leaves required-vs-optional and limit behavior unaddressed.

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 only 33%: `repo` is documented but `limit` and `number` are not. The description says nothing about any parameter, so it fails to compensate for the undocumented required `number` and the default-limited `limit`.

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 and resource: list the files a pull request changes, along with their diffs. This clearly separates it from sibling tools like github_get_pull_request (PR metadata) and github_get_file.

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: call this when you need the file-level changes of a specific PR. There is no explicit statement of when to prefer this over github_get_pull_request or when it is inappropriate, and no prerequisites are mentioned.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered. The description adds the content scope ('basic info, including default branch'), but says nothing about behavior on missing/inaccessible repos, rate limits, or auth requirements.

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 sentence, front-loaded with the verb and resource, with no filler. Everything in it contributes to identifying the tool's output.

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?

A simple read-only tool with a fully documented single parameter, annotations, and an output schema, so little needs to be explained. The only gap is that 'basic info' is not enumerated (name, description, stars, visibility), leaving the exact field set to the output 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 description coverage is 100% and the single 'repo' parameter is fully documented in-schema, including the owner/name format and the GITHUB_MCP_DEFAULT_REPO fallback. The description adds nothing beyond that, so the baseline 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?

States a specific verb and resource ('Get a repository's basic info') and adds a concrete content hint ('including its default branch'), so an agent knows this returns repo metadata rather than file or branch data. It doesn't explicitly distinguish itself from siblings like github_list_branches, which also surface default branch info.

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 statement of when to call this versus alternatives, no prerequisites (auth, repo access), and no exclusions. Usage is only inferable from the tool name and the generic 'basic info' phrasing.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds that the call is pollable and names the salient returned fields, but says nothing about polling cost, rate limits, or eventual consistency — the traits that matter most for a polling tool. An output schema exists, so return-value detail is not required.

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 short sentences, zero filler, with the identification of the resource front-loaded ahead of the polling hint. Nothing could be removed without losing 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?

Annotations and an output schema carry much of the burden, and the description covers what the call returns. The remaining gaps — how to obtain run_id and how aggressively to poll — are the ones an agent actually needs for a single-run lookup 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 only 50%: repo is documented in the schema as 'owner/name' with a default, but run_id is a bare integer with no description anywhere. The description does not explain where a run_id comes from (e.g., github_list_workflow_runs), so it fails to compensate for the coverage gap.

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 and resource ("Get one workflow run") plus the returned attributes ("status and conclusion"), which separates it from the list-style sibling github_list_workflow_runs. It never names that sibling explicitly, so differentiation is implied by "one" 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?

"Poll this to follow a run" gives a real operational cue about repeated invocation, which is useful. However, there is no when-not guidance and no explicit routing to github_list_workflow_runs when the run id is unknown, leaving selection to inference.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered structurally. The description adds only a return-value summary (head commit sha) that output_schema already provides, and says nothing about pagination behavior via 'limit', rate limits, or error cases.

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 zero filler. It is efficient, though so short that it reads as a title restatement rather than a purposeful briefing.

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 list tool with an optional repo default and an undocumented 'limit' parameter, the description omits the default-repo fallback, pagination/capping semantics, and ordering of results. Since output_schema exists, repeating the return field is redundant while real gaps remain unaddressed.

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 50%: 'repo' is documented (owner/name plus default fallback) but 'limit' has no description anywhere. The description never mentions 'limit' or that it caps the number of branches returned, leaving the one undocumented parameter unexplained in both places.

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 and resource ('List branches') plus the key returned field (head commit sha), so the agent knows exactly what it retrieves. It doesn't explicitly contrast with siblings, but the resource is distinct from github_list_tags and github_list_pull_requests, making intent 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?

There is no guidance on when to call this versus alternatives, no mention of prerequisites (e.g., needing an authenticated repo context), and no note that omitting 'repo' falls back to a default. The agent must infer everything about usage from the name.

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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds only the root-path convention and says nothing about pagination, recursive vs non-recursive listing, or large-directory behavior, leaving behavioral gaps beyond the 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?

A single short sentence with no wasted wording, front-loading the core action. It errs toward under-specification rather than verbosity.

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 read-only directory listing with an output schema and annotations, the essentials are present, but the description omits whether listing is one level deep and how large directories are handled. These are meaningful gaps for correct invocation.

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

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

Schema coverage is 67%; ref and repo are documented inline, but path has no schema description. The description compensates by defining path's empty-string meaning as the repo root, but it does not explain path formatting or whether nested paths are supported.

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

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

The description states a specific verb and resource ("List a directory") and clarifies the root-path convention. It is clear what the tool does, but it does not differentiate itself from siblings such as github_get_file or explain depth (single-level vs recursive).

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 versus github_get_file or the other listing tools, and no exclusions or prerequisites. The intended use is only inferable from the tool name.

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, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds two genuinely non-obvious behaviors: results are sorted newest first, and requesting state='closed' returns merged PRs which surface as state='merged'. It says nothing about pagination behavior or what the default limit of 20 does when more PRs exist.

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 short sentences with no filler, and the ordering guarantee is front-loaded before the state caveat. Appropriately sized for the small amount of information conveyed.

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?

An output schema exists, so return shape need not be explained. However, for a list tool with four parameters and 25% schema coverage, the description leaves `limit` truncation behavior and the meaning of the `base` filter entirely undocumented in any structured or unstructured source.

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 only 25% (only `repo` is documented), so the description must compensate. It does valuable work on the highest-risk parameter by explaining that `state='closed'` conflates closed and merged, which the enum alone cannot convey, but `base` and `limit` receive no semantics in either place.

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 and resource ('List pull requests') plus an ordering guarantee ('newest first'), so the operation itself is unambiguous. It does not distinguish itself from the sibling github_get_pull_request, which an agent could reasonably confuse when it wants a single PR.

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 by the word 'List'; there is no explicit when-to-use or when-not-to-use, and no pointer to github_get_pull_request as the alternative for single-PR retrieval. The one piece of routing guidance present is indirect: the note about the closed state tells the agent how to enumerate merged PRs rather than using some other tool.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the meaningful behavioral detail of ordering (newest first) and that each tag is paired with its commit, but says nothing about pagination or truncation behavior beyond the implicit limit.

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 zero filler; ordering and returned data are packed into the fewest words possible.

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 read-only list tool with annotations and an output schema, this is nearly complete. The only real gap is the undocumented limit parameter behavior, which neither the schema nor description explains.

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 50%: repo is fully documented in the schema with its default-repo fallback, while limit has only a default of 30 and no explanation of maximum or meaning. The description's 'newest first' hints at what limit truncates but adds no parameter-specific 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?

Specific verb (list) and resource (tags) plus two useful qualifiers: ordering (newest first) and payload content (the commit each points to). It does not distinguish itself from siblings, but the sibling list contains nothing tag-related, so confusion risk is low.

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?

No guidance on when to use this versus alternatives such as github_list_branches or github_get_repo, and no stated prerequisites or exclusions. The agent must infer usage entirely from the name and one sentence.

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, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds the useful ordering trait (newest first) but says nothing about pagination, what `limit` truncates, or whether results are cached/filtered — and no output explanation is needed since an output schema exists.

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, no filler, with the core action and ordering front-loaded before the parameter clarification. Every clause carries 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?

The output schema removes the need to describe return values, and the workflow identifier format is covered. Still, for a 4-parameter listing tool with 25% schema coverage, the description leaves `branch` filtering and `limit` semantics entirely unexplained, which an agent must guess at.

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 only 25% (just `repo` is documented), so the description is doing real work by explaining that `workflow` accepts a name, a file name like 'ci.yml', or an id — a genuinely non-obvious detail. However, `limit` (default 10) and `branch` remain undocumented in both places, so it only partly compensates for the coverage gap.

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 and resource ('List runs of a workflow') plus an ordering guarantee ('newest first'), which is enough to separate it from github_get_workflow_run (single run) and github_list_workflows (the definitions, not the runs). It never names those siblings explicitly, so the differentiation is inferred 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?

The second sentence is parameter guidance, not usage guidance; there is no statement of when to reach for this versus github_get_workflow_run or github_list_workflows. The purpose is self-evident enough that the right tool is implied, but nothing is explicit.

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, openWorldHint=true and destructiveHint=false, so safety is covered. The description adds only the returned fields, and since an output schema exists that detail is largely redundant, so it contributes little 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?

A single front-loaded sentence with zero filler; the resource and return fields are stated immediately.

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 single-parameter list tool with annotations and an output schema, the description covers purpose and return shape adequately. It could note pagination or that results are scoped to one repo, but nothing critical is missing.

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

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

One optional parameter with 100% schema description coverage that explains the 'owner/name' format and the GITHUB_MCP_DEFAULT_REPO fallback. The description adds nothing on parameters, which is acceptable at full 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?

States a specific verb and resource ('List GitHub Actions workflows') plus what each item carries ('id and file name'). It is clearly distinct from github_list_workflow_runs and github_get_workflow_run, though it never explicitly contrasts itself with them.

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 listing intent is implied by the verb and resource, so an agent can infer it discovers workflows before calling github_get_workflow_run. There is no explicit when-to-use/when-not guidance or named alternative.

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