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

With no annotations, the description carries full responsibility for disclosing behavior. It only says 'Create a new issue', implying mutation but not mentioning permissions, rate limits, return value, or side effects such as whether the issue is immediately visible or if duplicate titles are allowed.

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, nine words, front-loaded with the verb and object. No wasted content.

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

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

The tool is simple and all parameters are documented, but absent annotations or an output schema, the description lacks details on return behavior or potential errors, leaving the agent with some uncertainty about what to expect after invoking it.

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

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

Schema has 100% coverage of all six parameters with clear descriptions, so the description need not add parameter details. It adds no extra semantics beyond what the schema already provides.

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 action ('Create') and object ('a new issue') with a location ('in a repository'), distinguishing it from sibling tools like github_update_issue, github_list_issues, and github_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?

No guidance on when to use this tool versus alternatives like github_create_pull_request or github_update_issue, nor any prerequisites or conditions such as repository existence or permissions.

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, and the description does not disclose any behavioral traits such as authentication requirements, side effects, or the fact that it performs a write operation. The description adds no transparency beyond the tool name.

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 zero redundancy, but it is too terse to provide meaningful value beyond the tool name. It lacks any elaboration that would make the brevity appropriate for a 7-parameter 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?

With no annotations, no output schema, and a minimal description, the tool is under-documented. The schema covers parameters, but the description does not provide enough context for an agent to understand the operation's implications, such as what the response contains or whether it requires special permissions.

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% coverage with descriptions for all 7 parameters, so the baseline is 3. The description itself does not add any extra parameter semantics, but the schema already provides sufficient detail.

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 a new pull request' clearly states the specific action (create) and resource (pull request), distinguishing it from sibling tools such as github_get_pull_request and github_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?

No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, conditions, or scenarios for using this tool, leaving the agent without contextual decision support.

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 states the action without detailing side effects, required permissions, rate limits, or result format. For a mutation operation, this leaves significant behavioral uncertainty.

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, direct sentence that front-loads the verb and resource. It is appropriately concise with no redundant or filler content.

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

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

Despite a complete parameter schema, the lack of annotations and output schema leaves gaps. The description does not mention what the tool returns, potential errors, or any other behavioral context. For a creation tool, this is insufficient for full contextual completeness.

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 tool description does not add extra parameter context; it only echoes the action. Since parameters are well-documented in schema, this is acceptable.

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 a new repository') and specifies the scope ('for the authenticated user'), distinguishing it from sibling tools that list, get, or update repositories. It directly maps to the tool name and 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?

The description implies usage context by specifying 'authenticated user', indicating this is for creating a repository on behalf of the user. However, it does not mention alternatives or when explicitly not to use this tool, so guidance is only implicit.

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 for behavioral disclosure. It only says 'Get the contents of a file' and does not mention key behaviors such as response format (e.g., raw vs base64), error handling for missing files, authentication requirements, or rate limits. This is a minimal disclosure with significant gaps for a GitHub API 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, direct sentence with no redundant words. It front-loads the core purpose effectively. Every word contributes to meaning, making it highly concise and well-structured.

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 no output schema and no annotations, yet the description does not explain the response structure, potential variations (e.g., raw vs encoded content), or error scenarios. Given the tool's 4 parameters and the complexity of GitHub's contents API, the description is too sparse to fully guide an agent in understanding what the tool returns and how to handle edge cases.

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 provides clear descriptions for all four parameters (owner, repo, path, ref), and the description adds no additional parameter-level information. Since schema description coverage is 100%, the baseline is 3, and the description neither enhances nor detracts from parameter understanding.

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 ('Get') and the resource ('contents of a file in a repository'), making the primary purpose obvious. However, it does not explicitly differentiate itself from sibling tools, though it is distinct in name and function. It is clear but lacks explicit sibling differentiation, so it does not earn 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 about when to use this tool versus alternatives, such as when a repository listing or commit history is needed. There is no mention of prerequisites or exclusionary conditions. The description simply states what it does without any usage context.

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

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

With no annotations, the description carries the full burden for behavioral disclosure. It only says 'Get details' and does not state authentication requirements, rate limits, response format, or any side effects. As a read operation, more transparency about what 'details' are included would be helpful.

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 short sentence that communicates the purpose efficiently. It is appropriately terse for a simple retrieval tool with no extra required 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 simple GET operation with fully documented parameters, the description is minimally viable. However, it does not mention what data is returned, whether any authentication is required, or how it relates to sibling tools like github_list_issues. Given the lack of annotations and output schema, a bit more detail would improve completeness.

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 coverage is 100% and each parameter has a clear description (owner, repo, issue_number). The tool description adds no additional parameter context, but the schema already provides sufficient meaning, so a baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Get') and resource ('details of a specific issue'), clearly distinguishing it from sibling tools like github_list_issues or github_update_issue. It is instantly clear 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 such as github_list_issues. The context is obvious from the name but the description does not explicitly say 'use this to fetch one issue' or mention 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 present, the description carries the full burden of behavioral disclosure. It only states 'Get details', which implies a safe read operation, but does not mention authentication requirements, rate limits, error behavior, or the structure of the response. This is minimal and leaves important questions unanswered.

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 redundant words. It efficiently conveys the tool's purpose without unnecessary 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 GET operation with fully described parameters, the description is minimally adequate. However, there is no output schema and no mention of what 'details' are included, so an agent might not know exactly what fields to expect in the response. This is a clear gap but not fatal given the straightforward nature of the 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?

The schema already describes all three parameters (owner, repo, pull_number) with 100% coverage, so the baseline is 3. The description adds no additional semantic meaning beyond the schema, but it does not need to; the parameter names and descriptions are self-explanatory.

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 ('Get') and resource ('details of a specific pull request'), clearly indicating a singular retrieval operation. This distinguishes it from sibling tools like github_list_pull_requests (listing) and github_create_pull_request (creation).

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. It does not mention cases like 'use when you have a pull request number' or 'for listing use github_list_pull_requests instead', leaving the agent to infer usage from the name alone.

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 must disclose behavioral traits. It only states 'Get details' without mentioning authentication requirements, rate limits, error behavior for nonexistent repos, or the response structure. The read-only nature is implied but not explicitly stated.

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 that clearly communicates the tool's purpose. It is appropriately sized for a simple getter, though it lacks some helpful detail without becoming verbose.

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 absence of an output schema, the description should explain what 'details' means or what the response includes. It does not, leaving the agent to infer the return format. For a simple tool, this is a significant 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?

The schema descriptions cover 100% of parameters ('Repository name' and 'Repository owner username'), so the baseline is 3. The description adds no additional semantics beyond what the schema already provides, but it does not need to compensate.

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

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

The description clearly states a specific verb ('Get') and resource ('details of a specific repository'), which distinguishes it from sibling tools like github_list_repos or github_search_repos. However, it lacks explicit differentiation from similar getter tools (e.g., github_get_issue, github_get_file_content), though the repo focus is evident.

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. There is no mention of using github_list_repos for listing multiple repositories or github_search_repos for finding repositories, leaving the agent without context for selection.

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 says only 'List branches' and does not mention pagination, return format, permissions, or whether this is a read-only operation. This is a significant gap for a tool with pagination parameters.

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 unnecessary words. It is front-loaded and to the point.

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 no output schema and no annotations, and the description is minimal. It does not explain what is returned (list of branch names? metadata?), pagination behavior, or any edge cases. This is insufficient for a tool with 4 parameters.

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 parameters (owner, repo, page, per_page) have descriptions in the schema, so schema coverage is 100%. The description adds no additional parameter semantics beyond what the schema already provides, warranting the baseline score of 3.

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

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

The description 'List branches in a repository' clearly identifies the action (list) and resource (branches), making it distinct from sibling tools like list_commits or list_issues. It is unambiguous and specific.

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 gives no explicit guidance on when to use this tool versus alternatives. However, the name and description make the use case obvious (listing branches), so usage is implied rather than stated.

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

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

With no annotations provided, the description carries full responsibility for disclosing behavior. It only states the core function, omitting details about pagination, default ordering, response format, or rate limits that would be valuable for a list 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 sentence that directly states the tool's purpose with no unnecessary words. It is front-loaded and immediately understandable.

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 7 parameters and no output schema or annotations, yet the description provides no context about expected input, output shape, or operational constraints. It is minimal but leaves significant gaps for an agent to safely use the 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 even though the description adds no parameter information. The description does not clarify parameter usage beyond what the schema already provides, but it also does not need to due to complete schema coverage.

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

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

The description states a specific verb ('List') and resource ('commits in a repository'), clearly distinguishing it from sibling tools like github_list_issues or github_list_branches. It unambiguously identifies the action and target.

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 offers no guidance on when to use this tool versus alternatives or how it fits into a workflow. There is no mention of filtering, pagination, or contextual cues to help an agent decide to invoke 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?

With no annotations, the description must disclose behavior fully. It only says 'List issues,' which is read-only, but does not mention pagination, default state, authentication needs, or the absence of side effects. No additional behavioral context is offered.

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. It efficiently communicates the core purpose without unnecessary 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?

The tool has 6 parameters, no output schema, and no annotations. The description is too thin: it does not explain what is returned (e.g., an array of issues), default filter behavior, or how pagination and filtering options work. The schema lists parameters but the description fails to synthesize them into actionable 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?

The input schema provides descriptions for all 6 parameters (100% coverage), so the diagram's parameter semantics are already documented. The description adds no extra meaning beyond the schema, such as how parameters interact or defaults.

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 is specific with a clear verb ('List') and resource ('issues for a repository'), distinguishing it from sibling tools like github_list_commits and github_list_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?

No guidance is provided on when to use this tool versus alternatives such as github_get_issue for a single issue or github_create_issue for creating. The description states only the action, leaving usage context implied with no 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?

There are no annotations, and the description offers no behavioral details beyond the basic function. It does not disclose default state filtering (open/closed/all), pagination behavior, rate limits, or what happens with empty results, so the agent is left without critical 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 clear and concise sentence that conveys the essential purpose without any filler or redundancy. 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?

With 7 parameters, no output schema, and no annotations, the description is too minimal to be contextually complete. It omits details on default behavior, pagination, sorting, and edge cases, making it inadequate for an agent to fully anticipate the tool's 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?

The input schema has 100% coverage with descriptive text for every parameter, so the baseline is 3. The tool description itself does not add any extra semantics or constraints beyond what the schema already provides.

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 for a repository'), which is specific and distinguishes it from sibling tools that list other resources like commits, issues, repositories, or branches.

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. It does not mention filters, defaults, or contrast with analogous tools such as github_get_pull_request or github_list_issues, leaving the agent without decision support.

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 must disclose behavioral traits. It only states 'List', which implies read-only, and 'for the authenticated user', which implies authentication and scoping, but it doesn't mention pagination behavior, response format, or that the list can be filtered by the 'type' parameter. Important details like rate limits or that only repos the user has access to are returned are absent.

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 that conveys the essential purpose without extraneous words. It is front-loaded and every word contributes value, making it highly concise and appropriately structured.

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

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

With 4 optional parameters and no output schema, the description should provide more context about expected return values and behavioral nuances. It doesn't mention that results are paginated, that the 'type' parameter controls which repos are listed, or how the listing differs from searching, leaving an agent under-informed for proper usage.

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 for all four parameters (page, sort, type, per_page), so the baseline is 3. The description adds no additional parameter semantics, such as the effect of 'type' on the repo list or pagination defaults, but the schema already covers them 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 uses a specific verb 'List' with resource 'repositories' and scope 'for the authenticated user', making the core function clear. It doesn't explicitly differentiate from sibling tools like github_search_repos, though the word 'authenticated' implies it lists the user's own accessible repositories, distinguishing it from global search.

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

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

The description provides no guidance on when to use this tool versus alternatives such as github_search_repos or github_get_repo. There are no exclusions, prerequisites, or contextual hints beyond the phrase 'for the authenticated user', which indirectly suggests authentication but doesn't specify use cases or trade-offs.

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, yet it only states a generic search action. It does not mention pagination, sorting, default result counts, or whether authentication is required, so the agent lacks insight into how the tool behaves.

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 clear sentence that is efficient and front-loaded with the core purpose. While it is brief, it does not waste words, though it could be expanded with 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?

Given the tool's complexity (5 parameters, no output schema), the description is minimal and incomplete. It does not explain return values, pagination behavior, or how to construct queries, leaving significant 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?

The input schema covers 100% of the parameters with descriptions, so the baseline is 3. The tool description adds no parameter details beyond the schema, but the schema already provides sufficient semantics for query, page, sort, order, and per_page.

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 'Search' and resource 'code across GitHub repositories', clearly indicating this tool is for code search. However, it does not distinguish itself from the sibling tool github_search_repos, which also searches GitHub, so it lacks explicit 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 no guidance on when to use this tool versus alternatives. It does not mention github_search_repos or any other tool, leaving the agent without context for choosing between code search and repo search.

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 says 'Search for repositories on GitHub' and gives no information about pagination, rate limits, or what the response contains. The read-only nature of search is implied but not stated.

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 zero waste, making it concise and front-loaded. However, it is so sparse that it borders on under-specification, lacking any additional context or structure that would make it truly effective.

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 5 parameters and no output schema, but the rich schema descriptions cover parameter semantics. However, the description gives no indication of return values or broader usage context. It is adequate for a simple tool but leaves gaps for an agent expecting more behavioral or result information.

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 for its 5 parameters, including query format and enum values for sort/order. The description adds no additional meaning beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: 'Search for repositories on GitHub.' It clearly indicates what the tool does. However, it doesn't explicitly distinguish from sibling tool github_search_code, relying on the name to convey the focus on repositories rather than code.

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, what scenarios it's best for, or when to use alternatives. It simply states the action, leaving the agent to infer usage without any exclusions or contextual hints.

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 'Update' which implies modification, but does not explain whether it performs a partial update, whether changes are reversible, what happens to unspecified fields, or any authentication/authorization 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?

The description is a single short sentence, but it is under-specified to the point of being redundant with the tool name. It lacks any substantive structure or additional context, making it more under-specification than effective 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 tool's moderate complexity (7 parameters, 3 required) and absence of an output schema, the description should clarify update semantics, return values, or side effects. It does none of this, so the description is inadequate for an agent to understand how to invoke the tool correctly.

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 parameters (e.g., body, state, title, labels). The description adds no additional meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly identifies the action ('Update') and the resource ('an existing issue'), distinguishing it from sibling tools like create_issue and get_issue. However, it lacks specificity about what aspects of the issue can be updated (e.g., title, body, state), making it slightly less informative than ideal.

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

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

There is no guidance on when to use this tool versus alternatives, such as create_issue for new issues or get_issue for viewing. No prerequisites or contextual hints are provided.

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