codebahn

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

Annotations declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, and the description adds a genuinely useful behavioral nuance about compare direction. But for a mixed read/write tool it never splits safe reads (list/get/compare) from destructive ones (delete/delete_protection), and it says nothing about irreversibility or permission 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?

Three sentences, front-loaded with the capability summary followed by compare semantics and protection scope. No filler, though the action-level mapping that would help most is omitted rather than the text being bloated.

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 9-action, 32-parameter, destructive tool with no output schema, the description gives a reasonable capability map but no per-action guidance, no indication of which actions mutate state, and no sense of return shape. It is the minimum viable overview rather than a complete one.

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

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

Schema description coverage is 100% and every parameter already carries an 'For <action>' tag, so the schema does the heavy lifting. The description adds the head/base direction semantics that the schema wording ('Base ref. For compare') does not convey, but that covers only 2 of 32 parameters.

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

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

States a specific verb set and resource ('Manage branches, compare refs, configure branch protection rules'), which lets an agent distinguish branch operations from sibling tools like commits or repos. However, the nine concrete actions (list/create/delete/protection CRUD) are only implied by the schema enum, not named in the description.

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 points at one action explicitly ('Use \'compare\' to see commits reachable from head but not base') and groups the protection actions, so usage is partly implied. It never states when-not to use this tool or routes between overlapping actions (e.g. list vs list_protections, create_protection vs update_protection).

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

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

Annotations declare destructiveHint=true and readOnlyHint=false, and the description's 'cancel' to 'abort a running build' is consistent with that, so there is no contradiction. However the annotations apply uniformly to a mixed tool whose list_runs/get_run/get_logs actions are clearly read-only, and the description does not clarify that distinction, nor does it mention permissions, auth, or rate limits.

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 compact sentences: the first front-loads the purpose, the second is a dense action-to-meaning map with zero filler. Every clause 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 15 parameters fully documented in the schema, defined annotations, and no output schema, the description covers the essentials and even notes that get_logs output is grouped by step. It omits only secondary context like pagination behavior and auth requirements.

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 each parameter already documents its action scoping ('For get_logs', 'For dispatch') and the required run_id/workflow_id relationships. The description adds the action vocabulary but no format or syntax detail beyond what the schema provides, making the baseline of 3 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 concrete verb+resource ('Trigger and monitor CI workflows') and then enumerates all five actions with their individual meanings, so an agent understands exactly what this tool covers. It is clearly distinguishable from siblings like ci_config, branches, or webhooks.

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?

Each action is mapped to an intent ('dispatch' to start a run, 'cancel' to abort, 'list_runs' for history, 'get_run' for details, 'get_logs' for job output), which is strong when-to-use guidance within the tool. It stops short of naming when NOT to use this tool or pointing to alternatives such as ci_config for configuration.

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?

Adds real behavioral context beyond the annotations: secrets are encrypted and write-only and cannot be read back, and 'set' is an upsert. The annotations already flag destructiveHint=true and non-read-only, so the write-only secret behavior is the key value-add here. It stops short of describing delete behavior or auth requirements.

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

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

Three tight sentences, front-loaded with the resource and scope, then the variable-vs-secret distinction, then action semantics. No filler; every sentence carries distinct 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?

For a 9-parameter multi-action tool with no output schema, it covers the important conceptual distinctions (variable vs secret, scope, action semantics) adequately, and pagination params are documented in the schema. Minor gaps remain around delete semantics and permission requirements.

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 already documents every parameter, including the write-only note on 'value' and the variables-only note on 'get'. The description reinforces the variable/secret and upsert distinctions but adds little that is not already in the schema, so the baseline 3 applies.

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

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

States a specific verb ('Manage') and resource ('Actions variables and secrets') and clearly distinguishes the two config subtypes and their scopes. It does not name any sibling tool, but the resource is specific enough to separate it from the generic neighbors like ci or repos.

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 operational context ('get' is variables-only, 'set' is an upsert) that helps select the right action, but never says when to reach for this tool over sibling tools or states prerequisites such as required permissions. Usage is implied rather than spelled out.

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

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

Annotations already declare destructiveHint=true, non-idempotent and non-readOnly, so the safety profile is partly covered. The description adds the cross-entity behavioral fact (comments shared between issues/PRs), but does not say which action (delete) is destructive or that edits overwrite existing body text.

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

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

Two short sentences, front-loaded with the core purpose followed by the key shared-index caveat. No filler 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?

With 100% schema coverage and no output schema, the structured fields carry most of the load, so the description is adequate. However, for a five-action tool it should at least map the actions at a high level or flag the destructive delete, which it omits.

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% (all eight params documented, including per-action requirements and the action enum), so the baseline is 3. The description adds a little meaning by clarifying that index refers to an issue or PR interchangeably, but not enough to 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 names the resource (comments) and its scope (on issues and pull requests), and the 'Manage' verb correctly signals a multi-action tool. It is distinguishable from siblings like issues and pull_requests, though the verb itself is generic rather than 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?

It gives one useful usage hint — that comments are shared between issues and PRs so the same index works for either — but never states when to use this tool versus siblings or how to choose among its five actions. Usage is only implied via the action enum in the schema.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds only the action semantics already implied by the enum, saying nothing extra about pagination behavior, result size, or rate limits. With annotations doing the heavy lifting, this is adequate but not additive.

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

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

Two sentences, no filler, with the overall purpose front-loaded and the two actions enumerated immediately after. Every clause earns its place by mapping an action to its behavior.

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

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

For a read-only two-mode tool with a fully documented schema and annotations covering safety, the description is nearly sufficient: an agent knows both modes and the path filter. It would be complete with a brief note that 'diff' requires a sha and that results are paginated via page/limit, but nothing critical is missing.

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

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

Schema coverage is 100%, so every parameter (sha, path, page, limit, owner, repo) is already documented in the schema with per-action applicability notes. The description only restates the path filter for 'list', adding no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

The description gives a clear verb+resource ('Browse commit history and view diffs') and enumerates the two concrete actions, so an agent immediately knows the tool's scope. It does not compare itself to any sibling tool, but overlap with siblings like 'branches' or 'files' is low enough that differentiation is not a gap.

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 states the selection rule between the two modes: 'list' for listing commits (optionally path-filtered) and 'diff' for a single commit's unified diff. No explicit exclusions or prerequisites are given (e.g., that a sha is needed for diff), but the action routing is unambiguous.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered. The description adds real value beyond them by disclosing the side effect that 'Write actions (create, update, delete) each produce a commit' and that with_metadata is required to obtain the SHA used by update/delete. It omits permissions/auth requirements and rate-limit 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?

Three dense sentences, front-loaded with the overall capability, then the write side effect, then action-routing rules. No filler or repetition.

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 16-parameter, no-output-schema tool, the description covers action routing and the key write side effect, and the schema fully documents parameters. It does not mention pagination (page/limit for tree), return shape for read/list, or auth needs, which would be needed for 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 baseline is 3. The description goes beyond the schema by explaining the cross-parameter dependency chain: with_metadata=true on read yields the SHA that update/delete require, and it groups ref vs branch_name vs sha by action. This is useful semantics the schema only states piecemeal.

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

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

States a specific verb set (read/list/write) and resource (files in a repository), and enumerates the six actions so the agent knows the tool's full scope without opening the schema. It is clearly distinguishable from siblings like commits, branches, and repos, which handle 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?

Gives explicit action-selection guidance: 'read' for content, 'list' for one directory level, 'tree' for a recursive listing, and notes with_metadata=true when the SHA is needed. It does not state when *not* to use this tool versus a sibling (e.g. commits for history), so it stops short of a full 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?

Annotations already declare readOnlyHint=false and idempotentHint=false, so the bar is lower, yet the description adds almost no behavioral context. It never says which actions mutate, whether closing an issue is reversible, what permissions are needed, or that create/update/set_state have side effects while list/get do not.

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 tight sentences with the domain stated first and the two action hints following, no filler or repetition. It is efficient and front-loaded, though the extreme brevity is part of what leaves the tool under-explained.

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-action, 14-parameter mutation tool with no output schema and only coarse annotations, the description covers two actions and omits the rest. An agent gets no sense of what list returns, what create requires, or how get/update differ, which is a substantial shortfall given the complexity.

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

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

Schema description coverage is 100% and each parameter already documents its action scope (e.g., 'state ... For list: filter ... For set_state: required'), so the schema does the heavy lifting. The description adds no parameter detail beyond what the schema states, making the baseline 3 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 resource is clear ('issues and milestones') and it names two of the six available actions (set_state, list_milestones), which separates it from siblings like pull_requests or comments. However, the umbrella verb 'manage' is generic and the description never reveals that the tool can list, get, create, or update issues, leaving most of its actual capability hidden in the action enum.

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 concrete when-to-use guidance for two actions ('set_state' to open/close, 'list_milestones' to see milestones for filtering or assignment), which is more than nothing. But there is no guidance for selecting among list/get/create/update, no prerequisites, and no comparison against sibling tools such as labels or comments.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered. The description adds org-level scope behavior but does not disclose what gets destroyed by delete, auth requirements, or other execution traits.

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 waste. The core resource and scope are front-loaded, and the scope-condition sentence follows directly.

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 combination of rich schema descriptions and destructive annotations means most invocation details are covered. The description handles the org-vs-repo scope distinction, though it could say more about the multi-action nature and return behavior for list operations.

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 all 13 parameters are already documented in the schema. The description's scope note about repo duplicates the schema's own repo description and adds no meaning beyond it, making the baseline 3 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 ('Manage labels') and covers both repository/organization scope and issue-label assignment. It clearly distinguishes the tool from siblings, which are other resources like issues, repos, and commits.

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 an explicit scope rule: omit repo to operate on org-level labels. It does not state when not to use the tool or name alternatives, but no direct sibling alternative exists for label management.

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

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

Annotations declare readOnlyHint=false and idempotentHint=false, so the agent already knows this is a non-idempotent mutation surface. The description adds nothing about merge irreversibility, the effect of delete_branch_after_merge/force_merge, or auth/rate-limit constraints, so it goes only marginally beyond the structured fields.

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, zero filler. The purpose statement is front-loaded and the action-routing hints follow, so a skimming agent gets the tool's identity first and the disambiguation second.

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 21-parameter, eight-action dispatcher with no output schema, the description covers identity and partial action routing but omits how actions map to required inputs (index for everything but list/create), pagination behavior on list, and the difference between this tool and reviews/comments. The complete schema prevents this from being worse, but the description alone is thin 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?

Schema description coverage is 100% across all 21 parameters, including per-action annotations ('Required for create', 'For merge', 'For list'), so the schema carries the parameter burden. The description adds no syntax, format, or default-value detail beyond it, making 3 the correct 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?

States a specific resource (pull requests) and enumerates the operation set (create, update, merge, inspect), and the second sentence disambiguates three of the eight actions. It does not distinguish this tool from siblings like reviews, comments, or commits, which an agent could reasonably confuse with PR-related operations.

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 routes the agent among internal actions ('diff' for unified diff, 'list_files' for changed paths, 'list_commits' for commits), which is genuine guidance, but it never says when to pick pull_requests over the sibling reviews/comments tools, nor does it surface prerequisites beyond what the schema already encodes.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, readOnlyHint=false, covering the safety profile. The description adds no behavioral context beyond that: it never says which specific actions (delete, delete_tag, delete_attachment) are destructive, nor mentions auth, permissions, or rate limits. With annotations doing the safety work, a bare description earns a low score for adding nothing.

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

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

Three short sentences with zero filler, and the broad purpose is front-loaded ahead of the action-routing detail. Efficient for the amount of information conveyed, though it stops short of the most valuable per-action 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 12-action tool with 15 parameters and no output schema, the description covers the tag-vs-release distinction but leaves most actions and their required parameter combinations unexplained. An agent must fall back entirely on the schema and the coarse tool-level annotations to know which actions are destructive, so it is minimally adequate rather than 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 100%, so every parameter already carries a description, including action-scoping hints ('For get/update/delete/list_attachments'). The description's action-routing sentences add marginal cross-parameter context but no syntax or format detail beyond the schema, so the 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?

States specific verbs and resources ('Manage releases, git tags, and release attachments') and explicitly separates tag actions from release actions, which is genuinely useful for a 12-action tool. It does not differentiate itself from sibling tools like branches or commits, but the resource scope is clear enough for an agent to pick it correctly.

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 routes the agent for two actions ('get_latest' for most recent, 'get_by_tag' for lookup by tag) and clarifies that tag actions are independent of releases. However, 9 of the 12 actions (create, update, delete, list_attachments, delete_attachment, etc.) get no when-to-use guidance, and there is no when-not or alternative-tool 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?

Annotations only supply readOnlyHint=false and idempotentHint=false; the description must carry the rest and does not. It never warns that 'update' can archive a repo or flip visibility (irreversible-ish, non-idempotent in effect), never mentions permission/owner requirements for org creation, and says nothing about rate limits. Naming visibility and merge options as updatable is the only behavioral signal.

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

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

Three short sentences, front-loaded with the resource and the valid verbs, then the per-action routing. No filler, no restatement of the title, and each sentence carries distinct 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?

For a 29-parameter, mixed read/write tool with no output schema and thin annotations, the description is minimally viable: it routes the actions and names update categories, while the schema documents per-action parameter requirements. It omits return shape, pagination behavior, and any error/permission context, so an agent still infers a fair amount.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by explaining the semantics of the required action enum (poorly served by the schema's 'Operation to perform') and grouping which field families apply to update. Minor ding: it cites 'visibility', a parameter that does not exist in the schema (the actual property is 'private').

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 resource (repositories) and enumerates the three operations (list, create, update) with a one-clause gloss of each. It is trivially separable from siblings like branches, issues, or pull_requests, and internally the three actions are spelled out rather than lumped into 'manage'.

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?

Gives explicit action routing: 'list' for your repositories, 'create' for a new one (account or org), 'update' for settings changes. It covers the main selection question (which action), but offers no guidance on list filtering, pagination, or when to reach for a search tool 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?

Annotations already declare readOnlyHint=false and destructiveHint=true, so the safety profile is covered. The description adds verdict semantics and explains request/cancel_request, but is silent on the destructive 'delete' and 'dismiss' actions and whether those are reversible — a gap the annotations flag but do not explain.

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, front-loaded with the resource scope, no filler. Efficient and well-ordered, though it could consolidate the action list rather than covering only a subset.

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 13-parameter, nine-action tool with no output schema, the description covers only a few actions and omits the behavior of get/list/submit/dismiss/delete. Given the complexity, an agent must rely on the schema alone for most operations, which is adequate but not 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 100%, so all 13 parameters are already documented in the schema, including the enum action. The description's mention of verdict values (APPROVED, REQUEST_CHANGES, COMMENT) merely restates what the schema already provides, 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?

States specific resources (PR reviews, review comments, review requests) with concrete operations, and names verdict values. It doesn't distinguish itself from the sibling 'comments' or 'pull_requests' tools, leaving some ambiguity about which handles which comment type.

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 action-level guidance for 'request' (ask users/teams to review) and 'cancel_request' (withdraw), which is useful. But it gives no guidance on when to use this tool versus the sibling 'comments' or 'pull_requests' tools, and six of the nine actions (get, list, submit, dismiss, delete, list_comments) get no guidance at all.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint, so the safety profile is covered. The description adds genuinely new behavioral detail: the return shape differs by action ('all' returns aggregate hit counts, the others return paginated result sets), which tells the agent what to expect. It omits any note of rate limiting, which is common for search endpoints.

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 tight sentences with the general scope front-loaded and the action-dependent return behavior immediately after. No filler and nothing repeated from the schema.

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

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

For a 7-parameter read-only tool with full schema coverage, no output schema, and annotations covering safety, the description supplies the one thing the structured data does not: how results differ per action. The only shortfall is the mismatch between the advertised resource types and the available action values.

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

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

Schema description coverage is 100%, so every parameter including mode, filename, language, page, and limit is already documented with its applicable action. The description only alludes generically to 'type-specific filters' without adding syntax or constraint detail beyond the schema, so the 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?

States a specific verb (Search) and enumerates the resources it spans, which is much more informative than the bare name 'search'. However, it claims coverage of issues, users, and organizations while the action enum only exposes 'all', 'code', and 'repos', so the stated scope over-promises relative to what can actually be requested.

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 implicitly guides action selection by explaining that 'all' returns hit counts while 'code'/'repos' return paginated results, which implies 'all' is for discovery and the others for retrieval. It never mentions when to use this tool versus the sibling tools (repos, issues, files, commits), so the routing guidance stops short of explicit 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?

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds value by disclosing the shape of the payload (profile fields including permissions and account settings), which matters because no output schema exists to reveal it.

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 with the operation front-loaded and the returned content listed compactly. No filler, no restatement of the title or annotations.

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

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

For a zero-parameter, read-only tool with no output schema, the description supplies the essentials: who it operates on and what comes back. It stops short of noting auth prerequisites or whether the profile reflects the token's scopes, but nothing needed to call it correctly 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?

The tool takes zero parameters, so per the rubric the baseline is 4. The description correctly implies no inputs are needed by scoping to the authenticated user, and there are no parameters left 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?

Specific verb ('Get') plus resource ('authenticated user's profile') and an explicit enumeration of the fields returned (username, email, permissions, account settings). No sibling tool in the set covers the user profile, so the scope is unambiguous without needing an exclusion clause.

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 'authenticated user's' implies it operates on the caller's own identity and needs no arguments, but the description never states when to reach for this tool versus the many resource-oriented siblings (repos, issues, commits). Usage is inferable 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is known. The description adds one genuine behavioral rule (test is repo-only), but never says which action is destructive, that delete is irreversible, or what permissions are needed. With annotations carrying the safety burden, this is adequate but thin.

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

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

Three short sentences, front-loaded with the resource and scope model before the exception rule. Nothing is redundant with the schema and every sentence carries a constraint the agent needs.

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

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

For a 15-parameter, six-action mutation tool with no output schema, the description omits what each action returns, what create/update actually change, and that delete removes the hook permanently. The schema compensates for parameter detail, but the action-level behavior remains underspecified.

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 all 15 parameters are already documented in the schema, including action/scope enums and per-action requirements. The description only reinforces the scope enum semantics and the test restriction, adding marginal value beyond the structured fields. Baseline 3 applies.

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

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

States a concrete resource ('webhooks') and scoping model ('repository or organization scope'), which no sibling tool covers. It doesn't spell out the full action set in the prose, but the title-less definition is still immediately distinguishable from repos, issues, or ci.

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?

Offers real routing guidance between scope='repo' and scope='org', and explicitly warns that the 'test' action is unavailable for org webhooks. However, there is no sibling alternative to steer away from, so this is parameter-level guidance rather than true when-to-use guidance; an agent still infers that this is the only webhook tool.

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