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

With no annotations, the description carries the transparency burden. It clearly indicates an additive mutation ('add') and the target resource, but it does not disclose whether label names must already exist, whether duplicates are ignored, or what error conditions occur.

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 sentence carries all the essential information with no filler, and the core action is front-loaded. Every word 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?

The presence of an output schema covers return-value expectations, and the description covers the core operation. However, it lacks guidance on label-management behaviors such as whether labels are created automatically, which is a meaningful gap for a mutation tool with no annotations.

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 0%, so the description must compensate for all four parameters. It adds meaning for 'labels' (one or more) and clarifies issue_number applies to issues or pull requests, but owner and repo are left entirely to their self-evident names without additional context.

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 (add), a resource (labels), and a target (issue or pull request), making it immediately clear what the tool does and distinguishing it from sibling tools like post_comment or assign_issue. It also correctly implies that issue_number may refer to a pull request.

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 action is self-contained: if the goal is to attach labels to an issue or pull request, this is the obvious tool. No sibling tool handles labels, so there is no ambiguity, though the description does not explicitly state when not to use it.

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 present, so the description carries the behavioral burden. It usefully discloses that assignees are verified first and unverifiable users are rejected rather than guessed. However, it does not state whether assignment replaces existing assignees, what permissions are required, or how partial failures are handled.

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

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

Two concise sentences with no filler. The core action is front-loaded, and the important verification behavior is stated immediately after, earning 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?

The description covers the core purpose and a key validation behavior, and an output schema exists to document return values. Still, for a mutating operation with no annotations, it omits important context such as whether existing assignees are replaced or appended, permission prerequisites, and partial-failure behavior.

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 0%, so the description must compensate. It adds meaning for assignees by specifying 'one or more' and describing verification behavior, but it does not explain owner, repo, or issue_number. Those parameters are self-explanatory in a GitHub context, so the gap is moderate.

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 action ('assign') and object ('one or more GitHub users'), which clearly distinguishes it from sibling tools that get, search, label, comment on, close, or reopen issues. The target issue is implied by the tool name and the required issue_number parameter, so meaning is 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?

No explicit guidance about when to use this tool instead of siblings such as add_labels or post_comment, and no exclusions or alternative conditions. The usage context is only implied by the tool name and the action itself.

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 of behavioral disclosure. It clearly warns that the tool is DESTRUCTIVE, that the first call is a no-op, and that confirm=true is required for the actual close. This is highly transparent for a mutation tool.

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

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

The description is concise, front-loaded with the core action, and wastes no words. Every sentence adds meaningful operational 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 destructive nature and human-approval flow are well covered, but the tool has six parameters, no annotations, and no parameter descriptions. The description does not explain required inputs like reason or the optional state_reason default. The output schema helps, but parameter semantics remain a notable gap for a destructive operation.

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 0%, and the description only adds meaning for confirm by explaining when it should be true. The other parameters—owner, repo, issue_number, reason, and state_reason—are left with only their bare schema titles. Since coverage is low, the description needed to compensate but did not.

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 the action clearly: 'Close an issue.' It also adds the critical distinction that the first call only proposes an action and does not actually close anything. It does not explicitly differentiate from sibling tools like reopen_issue or get_issue, so it falls short of full sibling differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear usage context by explaining the two-step confirmation flow: the first call is only a proposal, and the second call with confirm=true should only happen after human approval. It does not explicitly say when to use close_issue versus reopen_issue, but the confirmation protocol is strong 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?

With no annotations, the description carries the behavioral disclosure burden. It does convey that the operation is read-only ('Fetch') and what data will be returned (labels, assignees, comments). However, it does not mention authentication requirements, rate limits, or behavior for nonexistent issues, leaving some behavioral gaps.

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 word adds value by naming the resource and the specific metadata included, making it appropriately sized for a straightforward read tool.

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-value details are covered elsewhere. The main gaps are the lack of parameter descriptions and the absence of guidance on when to use this tool versus search_issues or get_repository_context. For a simple fetch tool, this is adequate but not comprehensive.

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 0%, and the description provides no additional meaning for owner, repo, or issue_number. The parameter names are somewhat self-explanatory, but the description does nothing to compensate for the missing schema descriptions, so parameter semantics are essentially undocumented.

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 ('Fetch') and a clear resource ('full issue metadata'), and explicitly lists the included elements: labels, assignees, and comments. This distinguishes it from siblings like search_issues (searching) and get_pull_request (PR-specific), and from mutation tools like add_labels and post_comment.

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 the tool is for retrieving complete issue details, but it does not explicitly state when to prefer it over search_issues or get_repository_context, nor does it name alternatives. There is no exclusions guidance, so the usage context is clear but not fully specified.

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. It goes beyond a bare fetch statement by disclosing the concrete data categories returned: changed files, commits, reviews, CI check status, and linked issues. This gives the agent a meaningful expectation of the tool's behavior, though it does not mention rate limits, authorization, or error behavior.

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

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

The description is a single, front-loaded sentence that states the action and the key returned data without unnecessary words. It is concise and structured effectively, earning its place entirely.

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 has an output schema, so return-value details do not need to be in the description. However, the description lacks explicit usage guidance and parameter clarification, and there are no annotations to cover safety or behavioral context. The core purpose is clear, but the overall definition is only minimally complete for a 3-parameter read 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 0%, and the description does not explain owner, repo, or pr_number. While these parameter names are somewhat self-explanatory in a GitHub context, the description provides no additional semantics or format guidance to compensate for the missing 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?

The description names a specific verb and resource: 'Fetch a pull request', and further specifies the content returned (changed files, commits, reviews, CI check status, linked issues). This clearly distinguishes it from sibling tools like get_issue, which target issues rather than pull requests.

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 implied by the resource: use this when you need pull request data, and get_issue for issue data. However, there is no explicit guidance on when to choose this over alternatives or any exclusions, such as when to use search_issues instead.

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, but it only restates the purpose and the default window (which is already in the schema). It does not mention pagination, sorting, whether closed issues are included, or other behavioral nuances.

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 sentence that is front-loaded with the action and resource, with the default window appended parenthetically. No filler or redundant detail.

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 an output schema, the description covers the basics. However, it omits usage guidance and potential edge cases (e.g., closed vs. open issues, pagination, sorting), making it minimally viable but not fully complete.

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

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

Schema description coverage is 0%, so the description must compensate. The parenthetical '(default: last 14 days)' adds semantic meaning to the days parameter, but owner and repo are left to inference from their names.

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 ('List') and resource ('recently updated issues/PRs') with a default time window, making its core function clear. It does not explicitly differentiate itself from sibling tools like search_issues or get_issue, but the action and scope are distinct enough.

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 no guidance on when to use this tool versus alternatives. The phrase 'recently updated' implies a recency-based use case, but there are no explicit exclusions, prerequisites, or alternative routing to sibling tools.

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

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

With no annotations, the description carries the full transparency burden. It clearly signals a read-only fetch and specifies the data items returned, but it does not disclose authentication needs, behavior when files are missing, or rate limits. For a simple read operation this is adequate but not richly transparent.

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 states the operation and then uses a colon-delimited list to enumerate the exact returned items. There is no filler, and the structure makes the scope instantly scannable.

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

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

The output schema covers return structure, and the description enumerates the response elements, making the data contract clear. The main gaps are explicit routing guidance and parameter elaboration, but for a low-complexity read tool these are partially mitigated by self-explanatory parameter names and sibling tool names.

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 0%, and the description does not elaborate on the owner and repo parameters. While these names are self-evident GitHub identifiers, the description provides no per-parameter meaning beyond what the schema title already implies, so it fails to compensate for the absent schema descriptions.

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

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

The description names a specific verb ('Fetch') and a precise resource ('repository decision context') followed by an explicit enumeration of contents: description, topics, README, CONTRIBUTING.md, CODEOWNERS, and available labels. This clearly differentiates the tool from siblings focused on issues, pull requests, or recent activity.

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 use when repository-level context is needed, but it does not explicitly state when not to use this tool or mention any sibling alternatives. An agent has to infer routing from the listed contents rather than receiving direct 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?

With no annotations provided, the description carries the full burden of behavioral disclosure, but it only states the action without explaining side effects, permission requirements, or non-obvious API behavior. It does not mention that post_comment is a write operation with potential notification consequences, nor does it clarify behaviors like appending to an existing thread.

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, focused sentence with no filler. The key action and target are front-loaded, making it easy for an agent to quickly parse the tool's 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?

For a simple four-parameter write tool with an output schema, the description is minimally adequate: an agent can likely infer how to call it. However, it lacks usage guidance, behavioral caveats, and parameter clarifications, so it is not fully self-sufficient.

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 0% and the description adds no parameter-level meaning beyond the obvious names owner, repo, issue_number, and comment. The description does not clarify formats, required comment content, or that issue_number can also identify a pull request in GitHub's API.

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 names a specific verb ('Post') and a concrete resource ('a comment on an issue or pull request'). This clearly conveys what the tool does and distinguishes it from sibling issue operations like add_labels, assign_issue, close_issue, and reopen_issue.

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 intended use is implied by the verb and target: use this tool when you need to add a comment to an issue or pull request. However, the description gives no explicit guidance about when not to use it, nor does it mention any alternatives or prerequisites such as required permissions or issue state.

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 and does well: it flags the operation as DESTRUCTIVE and clearly requires confirm=true after explicit human approval. It does not detail side effects or permissions, but the core behavioral risk is disclosed.

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 with no filler. The destructive warning and confirmation requirement are front-loaded, and every sentence adds value.

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

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

Despite a clear purpose and strong behavioral warning, the tool has 5 parameters, no schema descriptions, and no annotations. The description does not explain the meaning or format of the required parameters, so an agent is left guessing about reason and the target identifiers.

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 0%, so the description must compensate. It adds meaning only for the confirm parameter ('requires confirm=true') and leaves owner, repo, issue_number, and reason completely unexplained.

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 verb and resource: 'Reopen a closed issue.' It doesn't explicitly differentiate from siblings like close_issue, but the action is unambiguous and easy to map to the tool name.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives context for when to use the tool (reopening a closed issue) and references the close_issue flow, but it does not explicitly state when not to use it or compare it directly to alternatives. The confirm requirement is useful guidance, but exclusions are missing.

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. It does disclose that the search is scoped to one repository and that it follows GitHub search syntax, which are useful behavioral constraints. It does not mention result limits, pagination, or whether the search is read-only, though 'Search' strongly implies non-mutating behavior.

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

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

The description is a single sentence with no filler: it leads with the action and resource, adds the key scoping and syntax detail in parentheses, and closes with the purpose. Every word contributes.

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 three-parameter search tool with an output schema, the description covers the essential what, where, and intended use, and the GitHub search syntax note is the non-obvious detail an agent needs. It is slightly incomplete only in not mentioning limitations like pagination or explicitly stating that it returns a list of matches, but the output schema mitigates the return-value gap.

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

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

Schema description coverage is 0%, so the description must compensate for the bare parameter names. It offers a hint that owner/repo scope the search and that query uses GitHub search syntax, but it never explicitly documents any parameter, expected format, or examples. This leaves significant inference to the agent.

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 clear verb ('Search'), resource ('issues/PRs'), and scope ('in one repository'), plus the intended purpose of finding related or duplicate reports. It is distinct from sibling tools like get_issue and get_pull_request, though it does not explicitly name 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 phrase 'to find related or duplicate reports' implies the use case, and 'Search issues/PRs in one repository' indicates discovery rather than retrieval of a known item. However, it never explicitly says when to prefer this over get_issue or get_pull_request, nor gives any exclusion criteria.

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