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

No annotations provided, so the description carries the full burden. It doesn't disclose that this is a mutation, any auth requirements, or what the response contains. The terse description lacks behavioral transparency.

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

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

Two short, direct sentences. No fluff. Each sentence contributes meaning.

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 mutation, the description is minimal but does not address the existence of add_pr_comment, leaving confusion about when to use which. The output schema exists, so return details are not needed, but usage guidance 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?

Schema covers all three parameters with descriptions. The description adds that the 'number' can refer to either an issue or PR number, giving context beyond the schema's generic 'Issue number.' This extra semantic info justifies a score above baseline.

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

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

The description clearly states the tool adds a comment to an issue with a specific verb and resource. It also mentions PR support, which adds context. However, it does not explicitly differentiate from the sibling add_pr_comment, causing slight ambiguity.

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 vs add_pr_comment or other alternatives. The note about PRs might imply it's also for PR comments, but there is a dedicated sibling, so the description leaves the decision unclear.

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 burden of behavioral disclosure. It adds the useful nuance that comments are general conversation rather than code review, and the verb 'comment' implies a write operation. However, it omits any mention of permissions, side effects, or return behavior, which prevents a higher score.

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 wasted words. Every part contributes to the purpose, and the parenthetical adds a valuable distinction without bloat.

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 tool with fully documented parameters and an output schema, the description covers the essential purpose and a key behavioral nuance. It is complete enough for an agent to invoke the tool correctly, though it lacks deeper usage guidance that would push it to a 5.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds no additional parameter semantics beyond what the schema already provides for repo, number, and body, so it does not exceed the 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 clearly states the action ('Comment on a pull request') with a specific resource, and adds a distinguishing note ('general conversation, not a code review') that separates it from review comment tools. This makes the purpose immediately identifiable and differentiates it from siblings like add_issue_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 provides clear context that this is for PR comments and explicitly excludes code reviews, which serves as a when-not guidance. However, it does not name alternative tools (e.g., add_issue_comment) or state explicit conditions for when to use this tool, so it earns a 4 rather than a 5.

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 says 'Create an issue.' It does not mention that this is a mutating operation, what permissions are needed, what the API return value is, or any side effects beyond the obvious creation.

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, minimal sentence that is front-loaded with the verb 'Create.' It is concise and avoids unnecessary words, though it is too sparse to be considered excellent.

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

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

Despite having a structured output schema and rich parameter descriptions, the description lacks broader context. It does not explain the operation's workflow, any required preconditions, or how it fits among sibling tools, making it insufficient for a 5-parameter 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?

The input schema has 100% description coverage, with each parameter (repo, title, body, labels, assignees) already explained. The description adds no parameter-level meaning, so the baseline of 3 is appropriate since 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 'Create an issue' clearly states the action (create) and resource (issue), which is a specific verb+resource pairing. It distinguishes itself from sibling tools like update_issue and create_pull_request, though it lacks extra scope or detail that would make it exceptional.

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 no guidance on when to use this tool versus alternatives. It does not mention when to prefer create_issue over update_issue or create_pull_request, nor does it state any prerequisites or exclusions.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It only says 'Create a pull request' and gives no insight into side effects, required permissions, or what happens on failure. It is not misleading but is extremely sparse.

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 but is under-specified rather than concise. It adds no value beyond the tool's name and fails to earn its place by providing useful 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?

For a 6-parameter mutation tool with no annotations, this description is inadequate. It does not explain the workflow, any constraints, or expected outcomes. The output schema exists, but the description still needs to provide context that the structured fields cannot.

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

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

Schema description coverage is 100%, so the schema already documents all parameters with meaningful descriptions. The tool description adds no parameter information, but the baseline of 3 is appropriate since the schema handles the heavy lifting.

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

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

The description clearly states the action (create) and the resource (pull request), which is specific. However, it does not distinguish from sibling tools like list_pull_requests or get_pull_request, nor does it mention any scope or constraints, so it falls short of a 5.

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 is provided on when to use this tool versus alternatives. The description does not mention context, prerequisites, or any exclusions, leaving the agent without direction.

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

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

No annotations are provided, so the description carries the transparency burden. It discloses a significant behavioral trait: files larger than 100,000 characters are refused to protect the context window. This is valuable beyond basic operation, although it does not mention error handling or authentication, which are less critical for this simple fetch.

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 only two sentences long, front-loads the core purpose, and adds one critical behavioral note. Every sentence earns its place with no redundancy or fluff.

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

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

Given the tool's simple function, the description is nearly complete: it states what is fetched, highlights a key constraint, and suggests a workaround. An output schema exists, so return-value details are not needed. Minor gaps like binary-file handling are not critical for this low-complexity 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 the baseline is 3. The description itself adds little parameter-specific meaning beyond the schema, though 'fetch a narrower path' hints at how to use the path parameter to avoid size limits. The schema already documents each parameter adequately.

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 begins with a specific verb 'Get' and resource 'raw text contents of a file in a repository,' clearly distinguishing this from sibling tools that handle issues, PRs, or repository metadata. It unambiguously states what the tool does.

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

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

The description provides clear context for when this tool is appropriate—fetching file contents. It does not explicitly name alternative tools, but the size-limit advice ('fetch a narrower path instead') implies a usage adjustment. With no sibling tool performing the same function, the context is sufficient.

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 description carries full burden. It states the return includes body and optionally comments, but does not explicitly state read-only nature, error behavior, or other side effects. The verb 'get' suggests non-destructive intent, but this is not made explicit.

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?

Single sentence that is front-loaded and contains no extraneous words. Efficiently conveys the core functionality.

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

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

Given there is an output schema and comprehensive parameter descriptions, the description is sufficient for this simple get operation. It would be improved by mentioning the repo and number identifiers, but those are already in the 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?

All three parameters are fully documented in the input schema with 100% coverage, so the description doesn't need to add parameter details. Description adds no new semantic information about parameters, meeting 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?

Description uses specific verb 'Get' and resource 'single issue', clearly distinguishing from list_issues and search_issues. Mentions body and comments, which adds specificity beyond a bare 'get 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?

Description implies this tool is for retrieving one specific issue, contrasting with list_issues for multiple. However, it does not explicitly name alternatives or exclusion criteria, so it falls short of a 5.

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 transparency burden. It discloses that the operation targets the authenticated user (implying auth context) and specifies return fields. It does not mention error conditions or edge cases, but for a zero-parameter read-only tool this is adequate.

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 that conveys the essential purpose without wasted words. Ideal conciseness for a simple 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?

Given zero parameters and an existing output schema, the description sufficiently covers the tool's purpose and key return values. It could mention authentication requirements or error behavior, but these are secondary for a simple get 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?

The tool has zero parameters, so the description need not add parameter details. The baseline for 0 params is 4, and no additional parameter semantics are required.

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 ('Get'), a clear resource ('the authenticated GitHub user'), and explicitly lists the returned fields (login, name, profile URL). It is distinct from sibling tools like get_pull_request or get_repo.

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 when-to-use vs. alternatives is provided. However, the purpose is so specific that usage is implied: use this when you need the current authenticated user's profile. It lacks an explicit exclusion statement or reference to related 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 provided, the description carries the full burden of behavioral disclosure. It adds valuable context about the file cap (first 100) and the files_truncated flag, as well as summarizing what checks represent (GitHub Actions on head commit). This goes beyond a simple 'get' and helps set expectations.

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 three sentences, front-loaded with the core purpose, followed by two concise behavioral clarifications. Every sentence earns its place with no fluff or redundancy.

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

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

The tool has an output schema, so return values are covered elsewhere. The description adequately covers key edge-case behavior (file truncation) and the nature of the checks. It is complete for a GET-style tool with modest 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%, with both repo and number having clear descriptions ('Repository as "owner/repo"' and 'Pull request number'). The tool description adds no additional parameter semantics, so baseline 3 is appropriate.

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

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

The description starts with a clear verb 'Get' and identifies the specific resource ('a pull request') and its scoping ('with its changed files and CI check summary'). This clearly distinguishes the tool from siblings like list_pull_requests or get_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 description implies usage when a specific pull request's details are needed, especially with files and checks. However, it does not explicitly state when to prefer this over alternatives like list_pull_requests or search_issues, nor any exclusions.

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

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

No annotations are provided, so the description carries the full burden. It reveals the tool returns a summary card with specific metadata, implying a lightweight read operation. However, it does not disclose error handling, rate limits, or authentication needs. For a simple read tool, this is adequate but not thorough.

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 two sentences, front-loaded with the action and resource, and includes a usage tip. Every word contributes value; there is no redundant information.

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

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

The tool is simple with one well-documented parameter and an output schema. The description covers what it returns, and the suggested use case with search_repositories adds valuable context. It feels complete for the tool's 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?

The sole parameter 'repo' is fully documented in the schema with format 'owner/repo'. The description does not add additional parameter semantics, but since schema coverage is 100%, the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Get a repository's summary card' with specific fields (stars, forks, language, topics). This distinguishes it from sibling tools like get_pull_request or get_me, which target different resources.

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 an explicit usage context: 'Use with search_repositories to evaluate repos found by popularity.' This tells the agent when to use this tool, though it does not explicitly state when not to use it or mention alternatives.

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

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

With no annotations, the description must disclose behavior; it only says 'List issues in a repository' and omits pagination, default state, or filtering capabilities, which are key for a listing tool. This is a significant gap in behavioral transparency.

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

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

The description is a single, concise sentence without fluff, making it easy to parse. However, it's so brief that it under-specifies the tool's capabilities, though this is more a completeness issue than 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?

Given the straightforward nature and complete schema, the description is minimally adequate. It lacks explicit mention of filtering (state/labels) and pagination options, and does not clarify how it relates to search_issues, leaving some gaps in context.

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

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

Schema coverage is 100% with detailed descriptions for all params (repo, state, labels, page, per_page), so the description need not elaborate. It adds no extra meaning beyond the schema, matching the baseline for high coverage.

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

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

The description uses the specific verb 'List' with resource 'issues' and scope 'in a repository,' clearly distinguishing it from get_issue (single issue) and search_issues (search across). It precisely states what the tool does.

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

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

No guidance is provided on when to use this tool versus alternatives like search_issues or get_issue. The description only states the function without any contextual distinctions, leaving the agent to infer usage.

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 states 'List' without explaining pagination, default state filtering, or that this is a read-only operation. It adds no context beyond the basic action, failing to disclose non-obvious behavior like default state='open' or max per_page.

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 words. It is appropriately sized for a simple list operation and is front-loaded with the verb and resource.

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 list tool, the description is adequate but has gaps. It does not mention the state parameter, pagination, or how it fits with siblings. The output schema exists, so return values are covered, but the description alone would not fully inform an agent about the tool's capabilities without reading the 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%: each parameter (repo, page, state, per_page) has a clear description and default. The tool description itself adds no parameter information, but the baseline of 3 is appropriate since the schema fully documents parameter semantics.

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

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

The description clearly states the action 'List' and the resource 'pull requests in a repository'. It distinguishes from sibling tools like get_pull_request (single) and create_pull_request (creation). The scope is explicit, leaving no ambiguity about what the tool does.

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

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

The description provides no guidance on when to use this tool versus alternatives such as list_issues or search_issues. It does not mention state filtering, pagination, or any context for selection. The agent is left to infer usage from the schema and 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 provided, so the description carries the full burden of behavioral disclosure. It only states the action and query syntax, but does not mention that this is a read-only operation, any authentication requirements, rate limits, or limitations like searching only public repositories or the default branch. This is insufficient for a tool with no annotations.

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

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

The description is a single sentence, 'Search code with GitHub code search syntax,' which is concise and free of unnecessary words. It is appropriately sized for the tool's simplicity and meets the standard for front-loaded clarity.

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

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

Given the tool's simplicity, the complete input schema, and the presence of an output schema, the description is adequate but minimal. It lacks usage guidelines and behavioral context such as when to use it or what results to expect, but the structured fields cover the core details. It is not as rich as the HIGH calibration example.

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 100% coverage with descriptions for all three parameters, including an example for the query. The description's mention of 'GitHub code search syntax' is consistent with the schema but does not add new meaning beyond it. Thus, a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Search code with GitHub code search syntax.' It uses a specific verb ('search') and resource ('code'), and the mention of 'GitHub code search syntax' distinguishes it from sibling tools like search_issues and search_repositories.

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 no guidance on when to use this tool versus alternatives. It does not mention how it differs from search_issues or search_repositories, nor does it offer any context about appropriate use cases. There are no exclusions or recommendations.

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 burden of behavioral disclosure. 'Search' implies a read-only operation, but the description does not mention rate limits, authentication, pagination behavior, or any additional caveats. It is minimal but not misleading; a 3 is appropriate given the low risk of a search operation.

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 conveys the purpose and key differentiator ('GitHub search syntax') without any redundant fluff. 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 tool is a simple search with a high-quality schema, output schema, and a direct description. The description is sufficient for an agent to know when to invoke it and what it does. It could benefit from a note on read-only behavior since annotations are absent, but overall it is complete for this low-complexity tool.

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

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

Schema coverage is 100%, so the schema fully documents all three parameters (query, repo, per_page). The description adds a small bit of context by mentioning 'GitHub search syntax', which relates to the query parameter, but does not add significant meaning beyond the schema's existing examples and descriptions.

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

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

The description clearly states the tool's purpose: searching issues and pull requests, and explicitly mentions 'GitHub search syntax' which differentiates it from sibling tools like list_issues and get_issue that likely don't support search qualifiers. The verb 'search' is specific to the resource.

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 usage: use when you need to search with GitHub search syntax. However, it does not explicitly contrast with alternatives like list_issues or search_repositories, nor does it provide guidance on when not to use this tool. The context is clear but lacks explicit exclusions.

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

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

With no annotations provided, the description carries the full burden. It discloses the sort order (by stars descending), which is a key behavioral trait. However, it does not mention pagination behavior, authentication needs, or any side effects. For a read-only search tool, this is minimal but acceptable, hence a 3.

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 two sentences: the first states the core function and sorting, the second provides a concrete example. Every word earns its place, with no redundancy or filler.

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

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

Given that the schema covers all parameters and an output schema exists, the description is largely complete. It explains the purpose, sorting, and typical usage. It does not explicitly mention pagination, but the schema parameters (page, per_page) imply it. Adequate for the tool's simplicity.

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 provides 100% parameter description coverage, so the description does not need to explain individual parameters. The description aligns with the min_stars parameter context but adds no new parameter-level meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states 'Search repositories' with the specific sorting behavior ('sorted by popularity (stars) descending'), which distinguishes it from sibling tools like search_code and search_issues. The verb and resource are explicit and 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?

The description provides useful usage context: 'Use this to explore existing repos and projects, e.g. find the most starred implementations of a tool or library.' This implies when to use it, but it does not explicitly mention alternatives or when not to use it. A clear context without exclusions merits a 4.

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 discloses the critical behavior that title and body are replaced in full, which is valuable. Yet it omits other behavioral details such as permissions, reversibility, or effects on unspecified fields, making it adequate but not rich.

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 two short sentences, front-loaded with the action and followed by the key behavioral note. Every word earns its place with no redundancy.

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

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

Given the schema covers all parameters and an output schema exists, the description does not need to explain return values. It supplies the essential scope and the most important behavioral caveat. A small gap is the lack of explicit contextual guidance like 'use for existing issues only,' but overall it is complete for a straightforward update 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%—all five parameters have clear descriptions. The tool description only reiterates the replacement behavior already present in the schema, adding no new semantic information, so a baseline score 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?

Description clearly states the tool updates an issue's title, body, or state with the specific verb 'update' and identifies the resource. It also adds a key behavioral nuance ('Title/body replace in full') and is easily distinguished from siblings like get_issue and create_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?

Usage context is implied: it is for modifying existing issues. However, there is no explicit guidance on when to use this tool versus alternatives (e.g., create_issue for new issues) or any exclusions, so it stays at the 'implied usage' level.

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