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

Annotations already signal a non-read-only, non-idempotent operation. The description goes further by disclosing the required write:issue scope, attribution to the token's owner, and the fact that comments cannot be deleted through this tool. This gives an agent realistic expectations beyond what annotations and schema provide.

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 brief and front-loaded: main action first, then a compact parameter summary, return shape, and the key permission/behavior caveat. Every sentence contributes useful information without 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?

For a write operation with five parameters and no output schema, the description covers the returned fields, the required scope, and the attribution/non-deletion caveat. Together with the fully described schema, an agent has enough information 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?

Schema description coverage is 100%, so each parameter is already well documented with types, defaults, constraints, and descriptions. The description's parameter list only restates names and requiredness without adding new field-level meaning, so it does not exceed the schema 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 opening sentence names a specific action and resource: adds a comment to an issue or pull request, and clarifies the shared numbering. This distinguishes it clearly from siblings like forgejo_create_issue and forgejo_update_issue, which modify issues rather than add comments.

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 states the intended context (commenting on issues/PRs), the required write:issue scope, and that the comment is attributed to the token's owner. It does not explicitly name alternative tools or when-not-to-use conditions, but the use case is unambiguous given the sibling tool 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?

Beyond the annotations, the description discloses important behaviors: the scope requirement, that unknown labels are silently skipped and reported, that the issue is attributed to the token owner, and the exact return shape. This gives the agent meaningful expectations about side effects and output without contradicting any annotation.

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 well-structured with a clear opening, a concise parameter list, a return summary, and a helpful attribution note. Every sentence adds information; there is no fluff or repetition of schema content. The most critical context (write operation and scope) is front-loaded.

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 output schema, the description supplies the return fields, which is essential. It also covers scope requirements, label handling, and token attribution. The only omission is how response_format affects the output, but that's documented in the schema, so the context is complete for an agent to call 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 input schema already covers all parameters with descriptions (100% coverage), so the baseline is 3. The description adds value by explaining the behavior of labels (unknown names are skipped and reported) and by reminding that owner/repo may be optional when default are configured, which supplements the schema's default 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 opens with a concrete action, 'Opens a new issue,' clearly identifying the verb and resource. The title and sibling context (forgejo_get_issue, forgejo_update_issue, forgejo_comment_issue) make the creation purpose unambiguous and distinguishable from related tools.

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 clearly that this is a write operation requiring the 'write:issue' scope, which helps the agent determine whether it is the right tool given permissions. It also notes that the issue is attributed to the token owner and suggests checking forgejo_whoami if uncertain, giving practical context on when to use supporting tools. It doesn't mention explicit alternatives or exclusions, but the creation role is clear enough.

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?

Beyond the annotations, the description discloses required permissions, the server-side prerequisite for the head branch, and specific error codes (409, 404, 422) with their meanings. It also states the return object shape, which is valuable since no output schema exists. There is no contradiction with the annotations.

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

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

The description is well-organized with clear sections: summary, parameters, return value, prerequisite, and errors. It is front-loaded with the core action and permission requirement, and every sentence earns its place without redundant 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?

For a write operation with no output schema, the description covers everything an agent needs: required parameters, optional parameters, authentication scope, preconditions, return format, and expected failure modes. This is a complete and self-sufficient definition.

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 input schema already documents each parameter thoroughly. The description adds minimal new parameter semantics beyond restating that head is source, base is target, and owner/repo are optional when defaults are configured, which the schema already expresses via default values.

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 opens with a specific verb and resource: 'Opens a pull request between two branches of the repository.' This clearly differentiates it from siblings like forgejo_create_issue or forgejo_get_pull_request, so an agent can select it unambiguously.

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 clear operational conditions: it is a write operation requiring 'write:repository' scope, and the head branch must be pushed before calling. It does not explicitly name alternatives or when not to use it, but the context is strong enough for a single-purpose creation tool.

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

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

The annotations already declare readOnly/idempotent behavior, and the description adds significant value beyond them: binary files are not decoded, contents are truncated with the cut reported, and exact return shapes are given for both files and directories. This fully discloses behavioral edge cases.

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

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

The description is well-structured with a summary first, followed by parameters, return shapes, and edge cases. Each section earns its place; the only minor cost is a parameter list that partially duplicates schema fields, though it adds practical usage details.

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 output schema, the description takes on the burden of explaining return values and does so thoroughly: file objects, directory entry objects, binary-file behavior, truncation reporting, and revision defaults. For a tool of this complexity, nothing an agent needs to invoke 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?

Schema coverage is 100%, so baseline is 3, but the description enriches parameters meaningfully: path semantics ('', '.', repository-root-relative examples), ref types and default branch, response_format intent, and optionality of owner/repo under configured 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 opens with a specific action and resource: 'Reads a text file's contents, or lists a directory, at a given revision.' It clearly distinguishes this tool from the sibling issue/pr/repo/branch tools and even covers both file and directory behavior in one sentence.

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?

Clear selection context is provided: it targets repository file/directory contents, accepts a revision via ref, and notes owner/repo are optional when defaults are configured. No explicit exclusions are given, but none are needed since no sibling tool covers file access.

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 readOnly, idempotent, non-destructive, so safety is covered. The description adds useful behavior: comments are fetched by default, issues and PRs share numbering, and a 404 is returned for missing numbers. This gives clear expectations about non-schema behaviors.

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?

Four short, front-loaded sentences: core purpose, return contract, shared-numbering special case, and error condition. There is no filler and each sentence carries needed 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?

Even without an output schema, the description specifies the exact return object shape, default behavior, error semantics, and a non-obvious quirk (PRs and issues share numbering). With read-only annotations and only one required parameter, an agent has enough to call and interpret 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?

Schema covers 100% of parameters, so baseline is 3. The description adds meaning beyond the schema by explaining that 'include_comments' is an on-request behavior and that 'number' can also be a PR number due to shared numbering. It also documents the return shape, which helps interpret response_format.

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

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

States a specific action ('Returns a full issue') and resource, and enumerates the data included (description, metadata, comments). The 'Also works with a pull request number' clause clarifies its broader scope, distinguishing it from pure issue or PR-specific siblings.

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 clear context: use this tool when you need full issue detail and optionally its comments. It also notes the tool can work for pull request numbers, which helps an agent decide between this and forgejo_get_pull_request, though it does not explicitly name alternatives 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?

Beyond the readOnly/idempotent annotations, the description discloses a valuable behavioral detail: the diff is truncated past the context limit and the truncation is explicitly reported. It also warns that include_diff can be large, which helps agents anticipate cost.

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 compact and front-loaded with the core action, followed by parameter/return summaries and a practical tip. Every sentence contributes information; there is no filler or redundant restatement of 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?

With no output schema, the description compensates by listing the exact return fields and noting the optional diff plus its truncation behavior. Combined with the fully documented input schema and annotations, an agent has everything needed to call and interpret 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic value by explaining the include_diff tradeoff and the diff truncation behavior. It contextualizes when to use the boolean parameter without merely repeating the schema.

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: 'Returns a pull request' with a detailed field list covering description, merge state, statistics, and optional diff. This clearly distinguishes it from sibling tools like forgejo_list_pull_requests and forgejo_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 tip about leaving include_diff=false for status checks provides concrete context-saving guidance, and the return-field list makes the intended use case clear. It does not explicitly name sibling alternatives or state when not to use it, but the tool's purpose is unambiguous enough.

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 state readOnlyHint, idempotentHint, openWorldHint, and non-destructive behavior. The description adds value by disclosing the exact return shape and that branches include protection status, commit SHA, and commit message. It does not contradict 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 compact and front-loaded with the core purpose, followed by a terse parameter list, a precise return contract, and a practical usage hint. Every sentence adds useful information without 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 no required parameters, rich annotations, and a fully documented input schema. The description covers the output shape and a concrete workflow context, so an agent has everything needed to invoke the tool and interpret results 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?

Input schema coverage is 100%, so the schema fully documents all five parameters with defaults, constraints, and descriptions. The description only lists parameter names and the return structure, adding no new semantic meaning 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 states a specific action and resource: 'Lists the repository's branches with their latest commit and protection status.' It clearly differentiates from sibling tools like forgejo_list_commits and forgejo_list_pull_requests by naming the branch resource and the exact data returned.

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 an explicit use case: 'Use it to confirm a branch exists before opening a pull request with forgejo_create_pull_request.' It does not discuss when not to use it or compare against alternatives, but the stated context is clear enough for an agent to select it appropriately.

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. The description adds useful behavioral context beyond this: commits are returned newest first, pagination is exposed via has_more, and response_format controls markdown vs json output. This goes beyond the safety profile already covered by 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 well-structured and front-loaded: a one-sentence purpose, a compact parameter list, a return shape, and two practical examples. Every section earns its place without unnecessary verbosity.

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

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

The tool has six optional parameters, a complete schema, and rich annotations. The description compensates for the missing output schema by specifying the exact return object shape including commits fields. Examples cover both simple and branch-specific usage, making the tool fully callable without additional inference.

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 input schema already documents every parameter. The description restates parameters and adds a couple of illustrative examples, but it does not substantially enrich meaning beyond the schema, 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 states a specific verb and resource: 'Lists a branch's commits, newest first.' This clearly identifies the operation and distinguishes it from sibling tools like forgejo_list_branches, which lists branches rather than 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?

The description includes clear usage examples such as 'what changed recently' and 'history of the migration branch', which indicate when to call the tool. It does not explicitly state when not to use it or mention alternatives, but the context is clear enough for an agent to select it appropriately.

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 flag read-only, idempotent, non-destructive behavior. The description adds value beyond annotations by describing the exact return shape, pagination fields, and the fact that pull requests are excluded. It does not contradict annotations and adds meaningful behavioral context.

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 well-structured: a front-loaded purpose sentence, a compact parameter summary, a return-shape example, and illustrative use cases. Every line earns its place with no redundant 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?

The tool has 8 parameters and no output schema, so the description appropriately documents all parameters, return fields, pagination behavior, and response formats. The presence of examples closes remaining ambiguity about how to interpret user requests. Nothing needed for tool selection or invocation 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 of parameters is 100%, but the description adds semantics beyond the schema: it clarifies that all listed labels are required, interprets default owner/repo configuration, and provides concrete examples mapping user intent to state and labels. This goes beyond simply repeating schema descriptions.

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

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

The description explicitly states that the tool lists a repository's issues and immediately excludes pull requests, clearly distinguishing it from forgejo_list_pull_requests. The verb-resource pairing is specific 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 tells the agent to use forgejo_list_pull_requests for pull requests, provides example natural-language mappings, and explains filter semantics like default state and required labels. This is explicit guidance for tool selection and invocation.

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?

Beyond the readOnly/idempotent annotations, the description discloses a genuinely subtle behavioral detail: both merged PRs and closed-without-merge PRs show state='closed', so the caller must rely on the 'merged' field. It also states the exact return shape, which is valuable since no output schema exists.

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

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

The description is compact, front-loaded with the core action, and structured into parameters, return values, and a critical note. Every sentence adds value, and no redundant or promotional wording appears.

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 output schema, the description compensates by giving a precise returns contract. All six parameters are covered (albeit summarized), the state ambiguity is resolved, and the tool's behavior in a paginated listing context is fully understandable for an agent.

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 every parameter. The description's parameter list mostly restates the schema's enum values and defaults rather than adding new meaning, though it does helpfully surface them in one place. This fits the baseline for high 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 opens with a specific verb and resource: 'Lists a repository's pull requests.' This is clear and distinct from sibling tools like get_pull_request (single PR) and list_issues (issues rather than PRs), and the title is expanded with sufficient specificity.

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 context makes clear this is the list-all-PRs operation, and the default state='open' plus available state filter gives practical usage guidance. It does not explicitly name alternative tools such as get_pull_request for a single PR, but the intended use is nonetheless obvious and 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?

With annotations already declaring readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, the description adds meaningful behavioral context beyond those: result ordering, pagination fields, the ability to choose markdown or JSON output, and the specific 403 error condition for missing read:user scope. This fully discloses observable behavior 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 tightly organized: purpose first, then parameters, return shape, usage scenario, and error condition. Every section earns its place; the parameter list briefly restates schema names but does not bloat the entry. It is compact yet informative.

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?

There is no output schema, so the description compensates by providing a precise return structure with all key fields. It also includes error behavior, parameter names, and the intended discovery use case. For a simple, optional-parameter list tool, nothing essential 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 the input schema already defines page, limit, and response_format with defaults, ranges, and descriptions. The description merely lists the parameter names without adding extra syntactic or semantic detail. Baseline 3 is appropriate because the schema carries the parameter documentation burden.

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 ('Lists'), a clear resource ('repositories the token can reach'), and an ordering detail ('most recently updated first'). The stated purpose distinctly separates it from sibling tools like forgejo_list_issues, forgejo_list_branches, or forgejo_list_commits. The description even ties the tool to a concrete discovery role: finding owner/repo values for other tools.

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 use case: 'Use it to discover the owner/repo values to pass to the other tools when they are unknown.' This gives clear context for when to call the tool. It does not name specific alternatives or give explicit 'when not to use' guidance, so it misses the full exclusionary guidance needed for 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?

Beyond the annotations, it discloses key write behaviors: body overwrites rather than appends, labels and assignees are fully replaced, unknown labels are skipped and reported, and omitted fields remain unchanged. It also states the required write:issue scope. These details align with destructiveHint=true and add meaningful operational context.

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 well-structured: a clear lead sentence, parameter block, behavioral note, return fields, and examples. It is fairly long but justified for a 9-parameter tool. A small amount of parameter detail duplicates the schema, but the organization keeps it scannable.

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

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

Given the tool's complexity, 9 parameters, no output schema, and the write-side annotations, the description covers auth scope, overwrite semantics, required-field conditions, defaults, return value shape, and practical examples. Nothing essential for invoking 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?

Even though schema coverage is 100%, the description adds crucial semantics beyond the schema: 'replaces the current title', 'this overwrites, it does not append', 'replaces the full label set', and 'replaces the full assignee list'. The 'at least one changing field is required' rule is also a valuable addition.

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 first sentence names the verb ('Changes') and the resource ('an existing issue'), plus the exact mutable attributes: state, title, body, labels, or assignees. This clearly distinguishes it from siblings like forgejo_create_issue and forgejo_comment_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 clearly states that the target must be an existing issue, requires the issue number, and requires at least one changing field. It also says omitted fields are left untouched. It does not explicitly name alternatives or say 'use forgejo_create_issue for new issues', but the usage context 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 provide readOnlyHint, idempotentHint, and destructiveHint=false. The description adds useful behavioral context beyond annotations: return fields, 401/403 error conditions, and the fact that it reveals write-attribution identity. No contradiction with 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 tightly organized: purpose first, then parameters, return shape, usage rationale, and error codes. Every sentence contributes a distinct operational fact with no 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?

There is no output schema, so the description appropriately provides the return fields and error codes, which is enough for a trivial whoami call. The only notable gap is the 'No parameters' statement contradicting the schema's response_format parameter, but since the schema documents that parameter fully, the operational impact is limited.

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 fully documents response_format with enum and default, so the description did not need to repeat it. However, the description's claim 'No parameters' conflicts with the schema's single optional parameter, giving an agent contradictory guidance about whether a parameter can be supplied. This is a genuine correctness issue rather than merely a coverage gap.

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

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

The description states a specific verb and resource: it returns the Forgejo account associated with the token used for the call. This clearly identifies the tool as a token-identity/validation operation and distinguishes it from the sibling repo/issue/PR tools.

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 explicitly tells the agent when to use it: to confirm a token is valid and to know which identity writes will be attributed to, before creating an issue or pull request. It does not list when-not-to-use alternatives, but no close alternative exists among the siblings, so the guidance is clear enough.

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