Server Quality Checklist

Tool Scores

• list_pull_requestsB
  3.1/5.0
  Behavior3/5

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

  Annotations already establish readOnlyHint=true and destructiveHint=false, so the description does not need to restate safety. It does add the 'open' filter and an attempted pipeline-ref/index relationship, which is behavioral context, though its ambiguity limits the value.

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

  Conciseness3/5

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

  The description is short and front-loaded with the main purpose. However, the second half is malformed ('with the index a pipeline ref...') and would likely confuse an agent, so the sentence does not fully earn its place in its current form.

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

  Completeness3/5

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

  With an output schema, strong annotations, and fully documented parameters, the description does not need to explain return values or permission details. Still, the key extra context about how PR indices relate to pipeline refs is delivered unclearly, and no usage boundaries are stated.

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

  Parameters3/5

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

  All three parameters are already described in the schema, so the 100% schema coverage sets a baseline of 3. The description does not add parameter-level detail; pagination and repo_id resolution are handled by the schema's own descriptions.

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

  Purpose4/5

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

  The opening clause names a specific action and resource: 'Lists the open pull requests of a repository,' which clearly separates it from repository and pipeline list tools. However, the appended clause about 'the index a pipeline ref ... refers to' is grammatically tangled and leaves the reader uncertain about what exactly is being indexed.

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

  Usage Guidelines2/5

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

  No guidance is given on when to choose this over alternatives such as list_pipelines, get_pipeline, or list_repository_branches. There are no exclusions or explicit use cases; the only context is that the tool lists open pull requests, making usage inferable but not explicit.

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

• delete_secretA
  3.6/5.0
  Behavior4/5

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

  Annotations already mark the tool as destructive and idempotent, but the description adds meaningful consequences: pipelines may fail or keep running with an empty value, and a two-step confirmation flow is required. This goes beyond the structured hints without contradicting them.

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

  Conciseness5/5

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

  Three short sentences deliver the action, the impact, and the process clue with no unnecessary words. The most important information is front-loaded.

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

  Completeness4/5

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

  For a destructive two-step tool, the description covers the key behavioral consequences and signals the confirmation workflow. Combined with complete schema documentation and annotations, the agent has enough context to invoke it correctly, though the exact first-and-second-call sequence is left implicit.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the parameters are already well documented. The description's 'Two-step' hint reinforces the purpose of confirm_token but does not add new semantic detail beyond what the schema provides.

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

  Purpose4/5

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

  States a specific verb and resource ('Deletes a secret') and clearly conveys the destructive effect on pipelines. The operation is unambiguous, though it does not explicitly contrast with sibling tools like update_secret or create_secret.

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

  Usage Guidelines2/5

  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 such as get_secret, create_secret, or update_secret. The 'Two-step' note is about the calling procedure, not about selecting the right tool for a situation.

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

• create_cronA
  3.8/5.0
  Behavior4/5

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

  With all annotation hints false, the description carries the transparency burden. It adds a genuinely non-obvious behavior: cron pipelines run with event 'cron' so event-restricted steps/secrets don't apply, illustrated by a push-only cron job doing nothing. It stops short of naming permissions or duplicate-name behavior, but the disclosed event semantics are substantial.

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

  Conciseness5/5

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

  Two sentences, first is front-loaded with purpose and second packs a valuable caveat with a concrete example. No filler or repetition of schema content.

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

  Completeness4/5

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

  With a full output schema and 100% parameter coverage, the description only needs to supply behavioral context, and it does. The main omissions are usage routing to sibling cron tools and permission requirements, which are not covered elsewhere.

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

  Parameters3/5

  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 syntax or format details. The cron-event note gives context for how schedule interacts with pipeline events, but the schema already documents each parameter thoroughly.

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

  Purpose4/5

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

  The opening 'Schedules a pipeline run' gives a concrete verb and resource, and the 'event "cron"' clarification distinguishes it from manual pipeline triggers. It relies on the title/name to make clear this creates a persistent cron job rather than triggering one immediately, so it stops short of full sibling differentiation.

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

  Usage Guidelines3/5

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

  The description implies the use case: recurring scheduled pipeline runs via cron event. However, it never states when to prefer create_cron over update_cron, run_cron, delete_cron, or trigger_pipeline, and gives no explicit exclusions or alternatives.

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

• list_registriesA
  3.8/5.0
  Behavior4/5

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

  Annotations already establish the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), and the description adds value beyond them with 'Passwords are never returned' — a key behavioral guarantee that prevents an agent from expecting usable secrets in the response. No contradiction with annotations; the read-only hint aligns with 'Lists.'

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

  Conciseness5/5

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

  Three short sentences, each earning its place: the action and scope, the purpose context, and the behavioral guarantee. The core action is front-loaded and nothing repeats the title or the schema content.

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

  Completeness4/5

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

  Given a full output schema, 100% parameter coverage, and safety annotations, the description covers the remaining essentials: what the resource is, that it operates at one level, and that passwords are excluded. The only notable gap is not steering the agent to get_registry for a single credential, but call behavior is otherwise fully specified.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the baseline of 3 applies even without parameter info in the description. The phrase 'at one level' lightly echoes the scope semantics, but the schema already fully explains the repository/organization/global hierarchy and which IDs each requires, so the description adds little new parameter meaning.

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

  Purpose4/5

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

  The description gives a specific verb and resource: 'Lists the container registry credentials at one level.' The 'at one level' qualifier is meaningful and maps to the scope parameter. It is clearly the collection counterpart to get_registry among siblings, though it does not name that alternative explicitly.

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

  Usage Guidelines3/5

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

  Usage is implied rather than stated: 'These are what let a pipeline pull private images' tells the agent these credentials are relevant to pipeline image pulls, suggesting this tool is for inspecting available credentials. However, there is no explicit when-to-use guidance, no mention of get_registry for single credential lookups, and the level-selection logic lives entirely in the schema's scope parameter rather than the description.

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

• update_forgeA
  3.8/5.0
  Behavior4/5

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

  Beyond the annotations, the description discloses an admin requirement, a two-step invocation flow, and the destructive consequence of a bad value ('locks everyone out of the instance'). It also notes that the forge is a shared dependency for logins and repository reads. It doesn't detail the exact token handshake, but this is substantial context not present in annotations.

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

  Conciseness5/5

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

  Two sentences, front-loaded with the action and then the critical risk. The lockout warning is earned and vivid without being verbose, and every sentence adds decision-relevant information.

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

  Completeness4/5

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

  For a destructive, admin-gated mutation, the description covers authorization, risk, and dependency criticality. It stops short of spelling out the two-step sequence explicitly (e.g., first call returns a token, second call applies it), but the schema's confirm_token description and the presence of an output schema partially fill that gap.

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

  Parameters2/5

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

  The description contains no per-parameter guidance; all meaning must come from the schema, which itself leaves client, skip_verify, and oauth_client_secret undocumented at 63% coverage. The only hint related to confirm_token is the phrase 'two-step', which is not parameter-level semantics. The schema and output schema carry the burden.

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

  Purpose4/5

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

  The description opens with 'Changes a forge configuration' — a concrete verb and object that clearly maps to the update-forge operation and separates it from get_forge, create_forge, and delete_forge. It doesn't enumerate what configuration fields can change, but the resource and action are unambiguous.

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

  Usage Guidelines4/5

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

  The description gives clear operational context: 'Admin only' sets the authorization bar, 'two-step' flags the invocation process, and the lockout warning explains the high blast radius. It doesn't name sibling alternatives or state when not to use the tool, but for a config-update tool the usage context is enough to route an agent.

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

• get_cronA
  3.9/5.0
  Behavior3/5

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

  Annotations already establish readOnly, idempotent, and non-destructive behavior, so the description need not restate safety. It adds a small behavioral detail (variables are included) but does not address error behavior or the shape of the returned object; the output schema likely covers that.

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

  Conciseness5/5

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

  A single sentence that front-loads the primary purpose and adds only one meaningful qualifier. Every word earns its place.

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

  Completeness5/5

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

  For a simple read-only getter with two fully documented parameters and an output schema, the description plus structured metadata is complete. An agent has enough to select and invoke the tool correctly.

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

  Parameters3/5

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

  Schema description coverage is 100% and both cron_id and repo_id have descriptive text, so the description adds no param-level value. Baseline 3 is appropriate.

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

  Purpose5/5

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

  Description states a specific verb ('Returns') and resource ('one cron job'), and explicitly calls out the distinguishing detail that the variables the job passes are included. This makes it clear against siblings like list_crons or run_cron.

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

  Usage Guidelines3/5

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

  The description implies use when a single cron job is needed and gives a hint of when the variables matter, but it does not explicitly contrast with list_crons or state when to prefer this over bulk listing. No alternatives or exclusions are named.

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

• get_forgeA
  3.9/5.0
  Behavior4/5

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

  Annotations already communicate readOnlyHint, idempotentHint, and non-destructiveness, so the description does not need to restate those. It adds valuable behavioral context beyond the annotations: access is restricted to admins, and the OAuth client secret is deliberately excluded from the read model and never returned. These disclosures help an agent set permissions expectations and avoid assuming sensitive data is present.

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

  Conciseness5/5

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

  The description is compact and effective: the first sentence states the core purpose, and the second supplies the admin access constraint plus an important privacy caveat. There is no filler or redundant restating of the tool name.

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

  Completeness5/5

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

  Given the tool has only one parameter, a full input schema, strong annotations, and an output schema, the description provides all necessary additional context. It covers access control and a critical data-exclusion behavior, leaving no obvious gap for a caller to invoke the tool correctly.

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

  Parameters3/5

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

  The input schema fully documents forge_id as a required integer with a numeric range and description. Since schema description coverage is 100%, the description does not need to add much. The tool description's focus on 'one forge configuration' reinforces the parameter's role but adds no new meaning beyond the schema.

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

  Purpose4/5

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

  The description clearly states the action with a specific verb and resource: 'Returns one forge configuration.' The singular 'one' and 'configuration' distinguish it from administrative write operations, though it does not explicitly name sibling tools like list_forges or update_forge, so it stops short of a 5.

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

  Usage Guidelines3/5

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

  The description implies the use case: retrieving a single forge configuration by id. It also gives an important access prerequisite with 'Admin only.' However, it does not explicitly say when not to use it, such as pointing to list_forges for multiple forges or update_forge for modifications.

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

• get_organizationA
  3.9/5.0
  Behavior3/5

  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. The description adds the concrete behavioral detail that exactly one organization is returned and that the lookup key is a numeric ID, which is modest context beyond the annotations, though it omits error behavior or not-found handling.

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

  Conciseness5/5

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

  A single, front-loaded sentence with no filler. It communicates the essential behavior and key distinguishing detail (numeric ID) in minimal words.

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

  Completeness5/5

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

  This is a simple read-only, single-ID lookup with one parameter, a fully documented input schema, complete annotations, and an output schema. The one-sentence description is sufficient for an agent to select and invoke it correctly; no important context is missing.

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

  Parameters3/5

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

  Schema description coverage is 100%, and the org_id parameter is already documented with type, range, and provenance ('as returned by list_organizations or lookup_organization'). The description merely restates the parameter's role without adding further semantic meaning, so the baseline of 3 applies.

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

  Purpose5/5

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

  The description states a specific verb ('Returns'), resource ('organization'), and retrieval method ('by its numeric id'). This clarity differentiates the tool from sibling lookup_organization, which likely uses a name or slug, and from list_organizations, which returns multiple records.

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

  Usage Guidelines3/5

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

  The 'by its numeric id' phrasing implicitly signals that this tool is appropriate when an organization ID is already available, but the description gives no explicit when-to-use or alternative-routing guidance. It does not mention preferring lookup_organization for non-ID lookups or list_organizations for enumeration, leaving the agent to infer the intended context.

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

• list_cronsA
  3.9/5.0
  Behavior3/5

  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 only the 'next execution time' output detail; it does not disclose pagination behavior, ordering, or any other runtime behavior, but it also does not contradict 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.

  Conciseness5/5

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

  A single sentence that front-loads the verb and resource, states the scope, and includes the key output detail without any filler or repetition.

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

  Completeness5/5

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

  For a simple list operation, the description plus the fully documented input schema, the read-only/idempotent annotations, and the presence of an output schema cover everything an agent needs to select and invoke the tool correctly.

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

  Parameters3/5

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

  Schema coverage is 100%, and the schema already documents all three parameters, including repo_id lookup, page bounds, and per_page clamping behavior. The description adds no parameter-level meaning beyond connecting 'of a repository' to repo_id.

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

  Purpose5/5

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

  The description uses a specific verb ('Lists') and a specific resource ('scheduled pipeline runs of a repository'), and adds a concrete output detail ('next execution time of each'). This clearly distinguishes list_crons from sibling tools like get_cron or list_pipelines.

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

  Usage Guidelines3/5

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

  The intended use is implied: call this when you need scheduled pipeline runs for a repository. However, the description gives no explicit guidance about alternatives, such as using get_cron for a single cron job or run_cron to trigger one.

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

• list_organizationsA
  3.9/5.0
  Behavior4/5

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

  Annotations already declare the tool read-only, idempotent, and non-destructive, so the description doesn't need to restate that. It adds genuinely useful behavioral context beyond the annotations: the warning that is_user=true entries are personal accounts rather than real organizations, and that Woodpecker treats org-level secrets for both. This clarifies data semantics in a way annotations cannot.

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

  Conciseness5/5

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

  Three short sentences, each earning its place: the core purpose, the admin restriction, and a critical data-modeling caveat. The most important operational constraint (admin only) is front-loaded, and there is no filler.

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

  Completeness5/5

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

  For a simple paginated list tool with read-only/idempotent annotations, a 100%-covered parameter schema, and an output schema, the description covers everything an agent needs: what it lists, who may call it, and how to interpret the returned entries. The is_user warning is especially valuable for correctly consuming the output.

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

  Parameters3/5

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

  With 100% schema description coverage, both page and per_page are already fully documented in the input schema, including the clamping behavior of per_page. The description adds no parameter-level information, which is acceptable given the schema coverage, so the baseline score of 3 applies.

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

  Purpose4/5

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

  The description clearly identifies the action ('Lists'), the resource ('organizations known to this Woodpecker instance'), and the admin-only scope. It does not explicitly contrast itself with sibling tools like lookup_organization or get_organization, so it stops short of full sibling differentiation.

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

  Usage Guidelines3/5

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

  The description states 'Admin only,' which is a clear access condition, and the plural 'Lists' implies this is the tool for enumerating all organizations. However, it gives no explicit guidance on when to prefer this over lookup_organization or get_organization, and no when-not-to-use information.

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

• move_repositoryA
  3.9/5.0
  Behavior1/5

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

  The description provides excellent behavioral detail about the HTTP 500 bug, the fact that the move still happens, and the no-retry instruction. However, it directly contradicts the idempotentHint=true annotation: it says retrying would move the repository a second time and that duplicate calls fail, which means the operation is not idempotent as annotated. Per the rubric, a contradiction with annotations forces a score of 1.

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

  Conciseness5/5

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

  Every sentence earns its place. The description front-loads the core purpose, then covers the most important safety warning, version-specific behavior, the alternative webhook path, and a concrete follow-up action. The length is justified by the dangerous failure mode.

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

  Completeness5/5

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

  The description is complete for a tool with a tricky failure mode: it covers prerequisites, the two-step workflow, when the tool should not be used, version-specific exceptions, retry guidance, and how to verify success. An output schema exists, so return-value details are not required from the description.

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

  Parameters3/5

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

  The input schema has 100% description coverage, with clear explanations for repo_id, to, and confirm_token. The description does not add parameter-level semantics, but it does not need to because the schema already documents the parameters well. Baseline 3 is appropriate.

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

  Purpose5/5

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

  The description states a specific verb and resource ('Tells Woodpecker that a repository moved') and immediately distinguishes the tool by clarifying it does NOT move anything in the forge. This removes ambiguity and clearly separates it from forge-side move operations and from sibling tools like get_repository or update_repository.

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

  Usage Guidelines5/5

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

  The description gives explicit when-to-use guidance ('do that first, then call this'), explicit when-not-needed guidance ('forges that send webhooks report a rename and Woodpecker follows by itself'), and warns that calling afterwards fails. It also recommends reading the repository back with get_repository before deciding anything, which is actionable usage direction.

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

• update_secretA
  3.9/5.0
  Behavior4/5

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

  The description adds meaningful behavioral detail beyond the annotations: partial updates, wholesale replacement of events and images, and rotation semantics for value. These are non-obvious mutation behaviors that the agent needs to know, and they align with destructiveHint=true and idempotentHint=true.

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

  Conciseness5/5

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

  The description is only two sentences, front-loads the core behavior, and every sentence carries critical information. There is no filler or repetition of schema details.

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

  Completeness4/5

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

  For a mutating tool with 9 parameters, the description plus the fully documented schema covers the important semantics: partial updates, replace-not-merge behavior, rotation, and scope requirements. An output schema exists, so return-value explanation is unnecessary. Missing explicit routing guidance is the main gap.

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

  Parameters4/5

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

  Schema description coverage is 100%, so the baseline is 3. The description adds extra semantics for value (rotates the secret) and for events/images (replaced wholesale, pass complete lists), which goes beyond the schema's field-level wording without duplicating it.

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

  Purpose4/5

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

  The description clearly states the verb and resource: it changes an existing secret. It is unambiguous as an update operation and is distinguishable from siblings like create_secret and delete_secret, though it does not explicitly name those alternatives.

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

  Usage Guidelines3/5

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

  The description implies when to use it: when you need to modify an existing secret while leaving unspecified fields intact. However, it gives no explicit guidance about when to use create_secret instead, when a secret should be deleted, or when get_secret should be called first.

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

• get_registryA
  4/5.0
  Behavior4/5

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

  Annotations already mark this read-only, idempotent, and non-destructive. The description adds valuable behavior beyond that: the password is stripped by Woodpecker (Registry.Copy) and will never appear in the response, which is exactly the kind of unexpected absence an agent should know about.

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

  Conciseness5/5

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

  Two sentences, no filler. The first sentence states the action and result fields; the second provides a high-value behavioral guarantee (password stripped). Front-loaded and every sentence earns its place.

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

  Completeness4/5

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

  For a parametrized read tool, the description plus fully documented schema and output schema give an agent what it needs to call correctly. The only minor gap is explicit routing versus list_registries, though the singular wording mostly covers that; not-found behavior is not stated but is not essential.

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

  Parameters3/5

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

  Schema description coverage is 100%, with each of the four parameters documented including the scope-dependency of repo_id/org_id. The description adds no parameter-level detail beyond noting the address and username are in the result, so the baseline of 3 applies.

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

  Purpose5/5

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

  The description opens with 'Returns one registry entry', a specific verb and object, and clarifies the returned fields (address and username). The singular 'one' distinguishes it from the sibling list_registries, and the read-only wording distinguishes it from create/update/delete registry tools.

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

  Usage Guidelines3/5

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

  It does not name alternatives or state when to choose get_registry over list_registries. The singular return and address-scope parameters imply the intended use case, but no explicit when/when-not guidance is provided.

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

• get_repositoryA
  4/5.0
  Behavior3/5

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

  Annotations already establish the tool as read-only, idempotent, and non-destructive, so the description doesn't need to restate that. It adds useful context about the scope (one repository) and the configuration fields returned. It omits error or auth details, but annotation coverage keeps this at an acceptable level.

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

  Conciseness5/5

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

  A single front-loaded sentence states the action and object, followed by a compact, useful enumeration of returned configuration fields. No wasted words.

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

  Completeness4/5

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

  For a simple one-parameter read tool with a rich schema, an output schema, and safety annotations, the description covers the core purpose well. It would benefit from explicit alternative routing or error behavior, but these are largely covered by the schema and sibling list.

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

  Parameters3/5

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

  Schema coverage is 100%, and the repo_id parameter's description already explains how to obtain an ID via lookup_repository and list_repositories. The tool description itself doesn't add parameter-level detail, so the baseline of 3 applies.

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

  Purpose5/5

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

  The description uses a specific verb ('Returns') and resource ('full Woodpecker configuration of one repository'), then enumerates concrete fields. This clearly distinguishes it from sibling tools like get_repository_permissions or list_repositories.

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

  Usage Guidelines4/5

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

  The intended context is clear: use this tool when you need the complete configuration for a single repository. It doesn't explicitly contrast with sibling tools or state when not to use it, but the schema's repo_id description does point to lookup_repository and list_repositories for finding IDs.

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

• get_step_logsA
  4/5.0
  Behavior5/5

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

  Beyond the annotations (read-only, idempotent, non-destructive), the description discloses meaningful behavior: logs are returned newest-end-first by default, lines are base64-encoded by Woodpecker and the tool decodes/reassembles them, and the step id comes from get_pipeline. This gives the agent important runtime knowledge that annotations alone do not convey.

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

  Conciseness5/5

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

  Three sentences, each earning its place: first the core result and ordering, then why the tail default is useful, then where the step id comes from and how encoding is handled. It is front-loaded with the most important information and contains no filler.

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

  Completeness4/5

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

  The description is largely complete for a read-only log-fetching tool: output format, ordering, failure-oriented use, step id provenance, and decoding behavior are all covered, and the output schema handles return-value details. However, the internal inconsistency about where the step id comes from, plus a lack of any note about when logs become available, prevents it from being fully reliable.

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

  Parameters2/5

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

  Schema coverage is 100%, so the baseline is 3, and the schema already documents all five parameters well. The description adds one useful provenance note about the step id, but it contradicts the parameter schema: it says workflows[].steps[].id whereas the schema for step_id says workflows[].children[]. This inconsistency can actively mislead an agent into reading the wrong field of get_pipeline results.

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

  Purpose4/5

  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 the output of one pipeline step as text. It clearly separates this from pipeline-level tooling by emphasizing 'one pipeline step' and even references get_pipeline as the source of the step id. However, it does not explicitly differentiate from sibling tools such as delete_step_logs or get_pipeline itself, so it falls just short of the strongest purpose-clarity standard.

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

  Usage Guidelines4/5

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

  The description gives practical usage context: a failing step almost always explains itself in its last lines, which tells the agent when to use the default tail behavior. It also tells the agent where to obtain the step id. It does not explicitly state when not to use this tool or name alternatives, but the failure-debugging framing is clear enough.

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

• resume_queueA
  4/5.0
  Behavior4/5

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

  Beyond the annotations, the description adds meaningful behavioral context: the operation is admin-only, enqueued pipelines start immediately, and the user should expect a burst of activity. This complements the idempotentHint and destructiveHint without contradicting them.

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

  Conciseness5/5

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

  Two short sentences carry all the essential information with no filler. The key action and immediate consequence are front-loaded, and every clause earns its place.

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

  Completeness5/5

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

  For a zero-parameter tool with an output schema, the description covers the purpose, the authorization requirement, and the operational consequence. Nothing critical is missing for an agent to decide whether and how to invoke it.

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

  Parameters4/5

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

  The tool has zero parameters and the schema coverage is effectively 100%, so there is no parameter information the description needs to add. The baseline of 4 for a parameterless tool is appropriate.

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

  Purpose4/5

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

  The description states a specific action: the server resumes handing work to agents, meaning queued pipelines will be processed. It clearly identifies the resource (the build queue) and the effect, though it doesn't explicitly contrast itself with the sibling pause_queue.

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

  Usage Guidelines3/5

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

  It provides an important usage restriction ('Admin only') and describes the immediate effect ('Queued pipelines start at once, so expect a burst'). However, it does not explicitly say when to use this tool versus alternatives like pause_queue or trigger_pipeline, leaving some inference to the agent.

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

• create_agentA
  4.1/5.0
  Behavior5/5

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

  The description discloses that the response contains a credential token that can attach a machine, receive workloads, and read all pipeline secrets — behavior that is not inferable from the annotations or schema. It also emphasizes that the token is only available in this response, which is a critical operational constraint. This goes well beyond the structured metadata.

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

  Conciseness4/5

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

  The description is only two sentences and front-loads the core purpose before the high-value security warning. The phrase 'It is part of this answer because it is the only way to get it' is slightly awkward and partially redundant with the surrounding token warning, but every sentence still contributes useful information. A little polish would make it fully crisp.

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

  Completeness4/5

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

  For a mutating create tool, the description covers the most important non-obvious aspect (token security and uniqueness), while the schema covers all parameters and the output schema covers return values. Permission prerequisites and lifecycle details are not mentioned, but the annotations and schemas carry enough of the remaining burden. The definition is complete for practical agent use.

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

  Parameters3/5

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

  The input schema has 100% coverage and detailed descriptions for all four parameters, including org_id, no_schedule, and custom_labels. The tool description adds no parameter-level meaning beyond what the schema already provides. Therefore the baseline score of 3 is appropriate.

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

  Purpose5/5

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

  The description begins with a specific verb ('Registers') and a specific resource ('a new build agent'), and it adds the distinctive outcome 'returns its token.' This makes it unambiguous and easily distinguishable from sibling list/get/update/delete agent tools. There is no tautology or ambiguity.

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

  Usage Guidelines3/5

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

  The description implies this tool is for creating new agents rather than managing existing ones, but it never names an alternative such as update_agent or states when not to use it. The only usage guidance is about token handling after creation, not about tool selection. This is acceptable but leaves selection mostly implicit.

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

• get_organization_permissionsA
  4.1/5.0
  Behavior3/5

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

  Annotations already declare this as read-only, idempotent, and non-destructive. The description adds that the result is limited to member/admin status and that admin is required for org-level secrets and agents, but it does not go deep into behavioral details like response shape or edge cases. This is adequate but not exceptional.

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

  Conciseness5/5

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

  The description is a single well-structured sentence that immediately states the tool's purpose and adds a relevant practical note. There is no redundancy or wasted wording.

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

  Completeness5/5

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

  For a simple read-only tool with one fully documented parameter, rich annotations, and an output schema, the description is complete. It tells the agent what the tool does, what distinction matters, and where this permission level applies.

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

  Parameters3/5

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

  The schema description coverage is 100%, so the single org_id parameter is fully documented in the schema. The description adds no additional parameter-level meaning, so the baseline score of 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states what the tool returns: the permissions of the authenticated account within an organization, specifically 'member and admin'. This distinguishes it from repository-level permission tools like get_repository_permissions by making the organization scope explicit.

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

  Usage Guidelines4/5

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

  The description gives practical context by noting that 'Org-level secrets and agents need admin here', which tells an agent when this permission check matters. It does not explicitly name alternatives or exclusions, but the clear org-level scope provides enough guidance for typical selection.

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

• lookup_organizationA
  4.1/5.0
  Behavior3/5

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

  Annotations already declare readOnly, idempotent, non-destructive behavior, so the description does not need to repeat those. It adds context that the returned id is a prerequisite for other org-level calls. However, it does not describe resolution behavior for missing or ambiguous names, which would add value beyond the schema.

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

  Conciseness5/5

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

  The description is a single, front-loaded sentence with no filler. Every clause earns its place by establishing the action, the result, and why the result matters.

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

  Completeness5/5

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

  For a single-parameter lookup tool with a full output schema, strong annotations, and a clear use case, the description covers everything essential. The agent knows what to pass, what it gets back, and why it is needed.

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

  Parameters3/5

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

  Schema description coverage is 100%, and the name parameter already has a clear description including the 'as it is spelled' qualifier. The tool description contributes little semantic detail beyond the schema, so the baseline score of 3 is appropriate.

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

  Purpose5/5

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

  The description uses the specific verb 'resolves' and states the exact resource ('an organization name') and outcome ('to its id'). It clearly distinguishes the tool from siblings like get_organization by focusing on the name-to-id lookup responsibility.

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

  Usage Guidelines4/5

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

  The description provides the contextual trigger: use this when an org-level call needs the organization id. It explicitly mentions org-scoped secrets and registries as consumers. It does not name alternatives or state when not to use it, but the context is clear enough to guide the agent.

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

• update_agentA
  4.1/5.0
  Behavior4/5

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

  Annotations already mark the tool as non-read-only, destructive, and idempotent. The description adds useful behavioral context beyond annotations by explaining that no_schedule=true drains the agent, allowing it to finish current work and accept nothing new. It also surfaces the admin-only requirement, which is not present in 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.

  Conciseness5/5

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

  The description is two short sentences, front-loaded with the primary action and immediately covering the most behaviorally important detail. Every sentence earns its place, and there is no filler or repetition of schema content.

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

  Completeness5/5

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

  Given the full parameter schema coverage and the presence of an output schema, the description covers the critical non-obvious context: admin-only access and the meaning of no_schedule as a drain switch. It is sufficiently complete for an agent to select and safely invoke this tool correctly.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the schema documents every parameter. The description adds a useful clarification for no_schedule with the drain-switch explanation, but it largely repeats the schema's own parameter description. It does not describe name, org_id, or custom_labels beyond what the schema already provides.

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

  Purpose4/5

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

  The description states a clear verb and resource: 'Changes an agent.' It also includes the notable 'Admin only' restriction. It does not enumerate what can be changed, but the title and input schema cover that, and the resource clearly differentiates it from sibling update_* tools like update_user or update_secret.

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

  Usage Guidelines4/5

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

  The description gives a clear usage context: this is for changing an agent and is restricted to admins. It also explains a specific scenario for no_schedule=true, which is the drain switch. It does not explicitly mention when not to use it or discuss alternatives, but for an update operation on a specific resource this is adequate.

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

• update_userA
  4.1/5.0
  Behavior5/5

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

  Beyond the annotations, the description discloses that granting admin grants full instance control including every repository secret, and that omitted fields are preserved. This is exactly the kind of side-effect context an agent needs before invoking a destructive, admin-only mutation.

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

  Conciseness5/5

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

  Three short sentences with the core action first, followed by a prerequisite and the two most important behavioral notes. No fluff or repetition.

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

  Completeness4/5

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

  For a 5-parameter mutation tool with an output schema and annotations, the description covers the action, restrictions, and critical risk. The confirm_token requirement and parameter meanings are already in the schema, so the context is nearly complete, though it could have listed the updatable fields for even faster agent comprehension.

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

  Parameters4/5

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

  Schema coverage is 80%, so the schema carries most parameter documentation. The description adds value by highlighting 'admin' as the critical parameter and by stating the partial-update semantics ('Fields you do not pass are preserved'), which is not inferable from the schema alone.

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

  Purpose4/5

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

  The description states a clear action ('Changes an account') on a user resource, which aligns with the tool name and title. It does not explicitly differentiate from sibling update tools like update_forge or update_agent, so it misses the top score.

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

  Usage Guidelines3/5

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

  It gives a prerequisite ('Admin only') and implies partial-update usage via 'Fields you do not pass are preserved,' but it never states when to choose this tool over create_user/get_user/delete_user or other update tools. Usage context is implied rather than explicit.

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

• create_registryA
  4.2/5.0
  Behavior3/5

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

  Annotations already mark it as a non-read-only, non-idempotent mutation; the description adds that it stores credentials and that address identity is significant. However, it doesn't disclose what happens if the same address is used again or how this interacts with update_registry, leaving a behavioral gap for a write operation.

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

  Conciseness5/5

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

  Two sentences with no filler: the first establishes purpose and the second adds a critical parameter nuance. It is front-loaded and every clause earns its place.

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

  Completeness4/5

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

  Given the comprehensive schema and an output schema, the description is largely sufficient for invoking the tool. The remaining gap is the lack of explicit guidance on create-versus-update behavior, which matters because update_registry exists as a sibling.

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

  Parameters4/5

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

  Schema coverage is 100%, so parameters are already documented. The description adds value by explaining the address is the identifier with no separate name and that similar-looking addresses are treated as distinct entries, which is not fully explicit in the schema.

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

  Purpose5/5

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

  The description uses a specific verb and resource ('Stores credentials for a container registry') and connects it to a concrete goal ('so pipelines can pull private images from it'). It also clarifies the unique addressing model, which helps distinguish it from registry-related siblings.

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

  Usage Guidelines4/5

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

  It provides a clear use context: when credentials need to be stored for a registry so pipelines can access private images. It doesn't explicitly list alternatives or exclusions such as 'use update_registry to modify an existing address,' so it falls short of a 5.

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

• decline_pipelineA
  4.2/5.0
  Behavior4/5

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

  The description adds useful behavior beyond the annotations: the pipeline ends as declined, never runs, and the pipeline entry and metadata are preserved. This clarifies the state transition and reassures about non-destructiveness, complementing the destructiveHint and idempotentHint annotations.

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

  Conciseness5/5

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

  Two short sentences, no filler, and the primary action is stated first. The description earns its length with concrete outcome information.

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

  Completeness4/5

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

  For a two-parameter tool with a complete input schema and an output schema present, the description covers the required state, the effect, and the preservation behavior. It is slightly lean on edge cases such as what happens if the pipeline is not waiting for approval, but it is adequate for correct invocation.

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

  Parameters3/5

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

  Schema description coverage is 100%, and both parameters are already well documented with descriptions referencing repo_id and pipeline number. The tool description adds no parameter-level meaning, 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.

  Purpose5/5

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

  The description uses a specific verb and resource: it refuses a pipeline that is waiting for approval. It clearly distinguishes this from sibling tools like approve_pipeline, cancel_pipeline, and delete_pipeline by stating the target state and the terminal outcome.

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

  Usage Guidelines4/5

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

  The description clearly indicates when to use the tool: when a pipeline is waiting for approval and should be refused. It does not explicitly name alternatives or exclusion conditions, but the intended context is unambiguous.

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

• delete_pipeline_logsA
  4.2/5.0
  Behavior4/5

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

  Annotations already mark this as destructive and idempotent, so the description adds value by clarifying exactly what is and is not destroyed: logs go away, but pipeline and step results remain, preserving failure indication. The 'Two-step' note also discloses an additional confirmation behavior not visible in 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.

  Conciseness5/5

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

  Three short sentences, no fluff, and the core behavior is front-loaded. Every sentence adds meaningful information: what is deleted, what remains, and that a two-step confirmation is involved.

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

  Completeness4/5

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

  For a destructive tool, the description covers the effect on logs, the preservation of pipeline results, and the two-step nature. Combined with full schema descriptions and an output schema, this is nearly complete; a slightly more explicit mention of the confirm_token requirement would make it fully self-contained.

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

  Parameters3/5

  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 repo_id, number, and confirm_token thoroughly. The description does not add parameter-level detail beyond what the schema provides, which meets the baseline for fully covered schemas.

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

  Purpose5/5

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

  The description uses a specific verb—'Deletes'—and names the exact resource: 'the stored output of every step of a pipeline.' It clearly distinguishes itself from sibling delete_step_logs by covering all steps, not a single step.

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

  Usage Guidelines4/5

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

  The description clearly implies this tool is for clearing all step log output while preserving pipeline structure and step results. It mentions 'Two-step,' which signals a confirmation workflow, though it does not explicitly contrast with delete_step_logs or state when to prefer one over the other.

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

• update_registryA
  4.2/5.0
  Behavior4/5

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

  Annotations already flag readOnlyHint=false, destructiveHint=true, and idempotentHint=true, so the safety profile is covered. The description adds a valuable behavioral constraint beyond those: the address is immutable and acts as the identifier, so updating it requires a different workflow. 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.

  Conciseness5/5

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

  Two tight sentences with no filler. The first states the core operation, and the second delivers the critical exception and alternative in exactly the right place.

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

  Completeness4/5

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

  For a 7-parameter mutation tool, the description plus a fully covered input schema is largely complete: scope selection, address immutability, credential fields, and confirm_token are all documented. It could theoretically say more about prerequisites or side effects, but annotations and schema already carry most of that burden.

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

  Parameters3/5

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

  Schema description coverage is 100%, and the schema thoroughly documents all parameters, including the conditional confirm_token requirement and scope-specific IDs. The description adds no parameter-level semantics beyond what the schema already provides, so the baseline 3 is appropriate.

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

  Purpose5/5

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

  The description states a specific action ('Changes the username or password') on a specific resource ('a registry entry'), and explicitly distinguishes itself from delete/re-create by noting that the address is the identifier and cannot be changed. This makes it clearly separable from sibling tools like create_registry and delete_registry.

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

  Usage Guidelines4/5

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

  It gives clear context for when to use this tool: when updating credentials. It also gives an explicit when-not and alternative: if the address needs to change, delete and re-create instead. It does not enumerate all sibling tools, but the credential-update intent is unambiguous.

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

• update_repositoryA
  4.2/5.0
  Behavior4/5

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

  Annotations already convey read-only=false, idempotent=true, and destructive=true. The description adds useful behavioral context beyond those flags: partial-update patch semantics and the security consequence of the 'trusted' flag (elevated container privileges, administrator-only change). 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.

  Conciseness5/5

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

  Two sentences with no filler. The first sentence states the action and the patch behavior; the second highlights the most important security caveat. Everything earns its place.

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

  Completeness4/5

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

  Despite 12 parameters, the schema provides detailed descriptions for every parameter and an output schema exists, so the description does not need to repeat them. The description covers the general behavior and the main sensitive flag. It could mention confirm_token requirements or asynchronous effects, but these are already documented in the schema. Overall adequate.

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

  Parameters4/5

  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 adds cross-cutting meaning beyond the schema: that only passed fields are changed, and that the trusted flags share an elevated-privilege security implication. This helps the agent apply consistent semantics across all parameters.

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

  Purpose5/5

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

  The description states a specific action ('Changes Woodpecker settings of a repository') with a clear resource, and the partial-update note ('Only the fields you pass are touched') adds precision. It is clearly differentiated from sibling tools like get_repository, delete_repository, activate_repository, and repair_repository.

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

  Usage Guidelines3/5

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

  The purpose implies when to use it — when repository settings must be modified. However, there is no explicit guidance about when not to use it or how it compares to alternatives such as activate_repository or repair_repository. Usage must be inferred rather than stated.

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

• chown_repositoryA
  4.3/5.0
  Behavior4/5

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

  Discloses a human-confirmation requirement ('Asks a person first') and a two-step token flow, which are not captured in the annotations. It also explains the operational consequence of ownership (forge token used for reads/build status), adding meaningful context beyond the idempotent and destructive hints.

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

  Conciseness5/5

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

  Three sentences, each earning its place: action, rationale, and procedural caveat. The core verb and resource are front-loaded, and there is no redundant wording.

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

  Completeness5/5

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

  For a two-parameter mutation with an output schema and safety annotations, the description covers the essential edge cases: why ownership matters, when to run it, and how to handle the confirmation dialog. 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.

  Parameters3/5

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

  The schema already documents both parameters at 100% coverage, including confirm_token's origin as a token from a previous call. The description's mention of the two-call flow reinforces confirm_token's purpose but adds no new parameter-level meaning, 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.

  Purpose5/5

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

  The description opens with a concrete outcome: 'Makes the authenticated account the repository's owner in Woodpecker.' It also gives the trigger scenario ('fix when the previous owner left'), which clearly separates it from other repository tools like move_repository or delete_repository.

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

  Usage Guidelines4/5

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

  Explicitly identifies the intended use case ('this is the fix when the previous owner left') and gives a conditional procedure for non-dialog clients ('call once to receive a token and again with it'). It doesn't name sibling alternatives or state when not to use, but the contextual trigger is strong enough for an agent to select it.

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

• get_pipelineA
  4.3/5.0
  Behavior4/5

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

  The annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is established. The description adds valuable behavioral context by revealing that the result includes workflows, steps, step ids, state, and exit_code, and that these guide next actions. 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.

  Conciseness5/5

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

  Two densely informative sentences with no wasted words. The core purpose is front-loaded, and the practical hint about step state/exit_code follows naturally.

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

  Completeness5/5

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

  Given the output schema exists and the two parameters are fully documented, the description covers the remaining operational knowledge: what is returned and how it feeds into get_step_logs. For a read-only, idempotent lookup, this is sufficient.

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

  Parameters3/5

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

  Schema coverage is 100% and both parameters already have rich descriptions (repo_id explained via lookup_repository; number explained as per-repository counter vs global id). The description does not add parameter-level meaning, so the baseline of 3 applies.

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

  Purpose5/5

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

  The description uses a specific verb and resource ('Returns one pipeline with its workflows and steps'), and goes beyond the title by naming the key output (step id) and its downstream consumer (get_step_logs). This makes it easy to distinguish from siblings like list_pipelines, get_pipeline_config, and get_pipeline_metadata.

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

  Usage Guidelines4/5

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

  It provides clear context on when to use this tool: you need a step id for get_step_logs, and step state/exit_code tell you which step to inspect. It does not explicitly say when not to use it or name alternatives like get_pipeline_config, so it stops short of a fully explicit routing guide.

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

• get_pipeline_configA
  4.3/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds meaningful behavioral context by emphasizing the historical snapshot nature of the returned YAML and the distinction from the live branch config, which is useful beyond what annotations convey.

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

  Conciseness5/5

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

  Two sentences, no filler. The primary behavior is stated first, and the clarifying contrast with the current branch follows immediately. Every word earns its place.

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

  Completeness5/5

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

  With an output schema present, the description need not explain return values. The parameter schemas are fully documented, annotations cover safety and idempotency, and the description supplies the essential historical-config context. Nothing critical is missing for an agent to select and call this tool correctly.

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

  Parameters3/5

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

  Schema description coverage is 100%, and both parameters already have detailed descriptions: 'number' is clarified as the per-repository counter rather than the global pipeline id, and 'repo_id' explains how to obtain it. The tool description adds no parameter-specific meaning beyond the schema, so the baseline score of 3 is appropriate.

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

  Purpose5/5

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

  The description names a specific verb ('Returns'), a specific resource ('pipeline YAML files this run was built from'), and adds the key historical qualifier 'as they were at that commit.' It clearly distinguishes the tool from any current-branch config getter and from sibling tools like get_pipeline or get_pipeline_metadata.

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

  Usage Guidelines4/5

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

  The description gives clear context: this tool returns the config that actually ran for a pipeline run, not the current branch config. This implies when to use it, but it does not explicitly name an alternative sibling or state a direct 'when-not-to-use' rule beyond the branch distinction.

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

• get_pipeline_metadataA
  4.3/5.0
  Behavior4/5

  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 meaningful behavioral context by explaining what metadata is returned—the CI_* environment visible to a step and the previous pipeline of the same workflow—which goes beyond the annotations and clarifies the tool's semantics.

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

  Conciseness5/5

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

  The description is two sentences with no filler. The first sentence front-loads the core purpose, and the second provides a practical use case. Every sentence earns its place, and the structure is easy to parse quickly.

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

  Completeness5/5

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

  For a read-only metadata tool with only two fully-described parameters, an output schema, and complete annotations, the description is adequate on its own. It explains what the tool returns, identifies the practical scenario for using it, and leaves no critical ambiguity for an agent deciding whether to invoke it.

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

  Parameters3/5

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

  Schema description coverage is 100%, and both parameters (repo_id and number) are already well-documented in the schema. The description does not add parameter-level detail, but the schema fully carries that burden, so the baseline score of 3 is appropriate.

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

  Purpose5/5

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

  States a specific verb and resource: "Returns the metadata Woodpecker exposes to the pipeline itself — the CI_* environment a step sees, plus the previous pipeline of the same workflow." This clearly distinguishes it from sibling tools like get_pipeline or get_pipeline_config by focusing on metadata exposed to the pipeline rather than pipeline status or configuration.

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

  Usage Guidelines4/5

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

  The description provides clear context for when this tool is valuable: "Useful when a step behaves differently than its config suggests." It does not explicitly name alternatives or exclusions, but the use case is specific enough for an agent to infer when to choose it over related pipeline tools.

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

• get_repository_permissionsA
  4.3/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so no safety burden remains. The description adds meaningful behavioral context: Woodpecker inherits permissions from the forge, and the result reflects what the authenticated account may do. This helps the agent interpret the value rather than assuming repository owner semantics.

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

  Conciseness5/5

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

  Two sentences with no filler. The first sentence immediately states the action and output fields, and the second explains the practical diagnostic value. Every clause contributes meaning.

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

  Completeness5/5

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

  For a single-parameter read-only tool with a rich parameter schema and an output schema present, the description covers purpose, semantic meaning, and a practical use case. Nothing material is missing for correct invocation and interpretation.

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

  Parameters3/5

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

  Schema description coverage is 100%, and the repo_id parameter already has a clear description plus guidance for looking up a repository from an owner/name pair. The tool description adds no parameter-specific details, but it does not need to because the schema fully documents the single required parameter.

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

  Purpose5/5

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

  The description states a specific action (get), resource (repository permissions), and enumerates the three permission types returned (pull, push, admin). It also gives a concrete diagnostic purpose, explaining why an agent would call this tool rather than guessing about a 403.

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

  Usage Guidelines4/5

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

  The phrase 'so this answers "why was that 403" without guessing' clearly communicates a primary use case. It implies troubleshooting permission issues for the authenticated account, but it does not explicitly contrast with alternatives like get_organization_permissions or get_repository.

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

• list_agentsA
  4.3/5.0
  Behavior4/5

  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 bar for the description is lower. It adds valuable context beyond the annotations: the administrative auth requirement for instance-wide lists and the disclosure that agent tokens are redacted. These are exactly the auth-needs and response-content disclosures the rubric rewards; 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.

  Conciseness5/5

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

  Three tightly-scoped sentences (~50 words) with zero waste. The purpose and returned fields are front-loaded first, followed by scope/auth, then token redaction. Each sentence carries distinct, necessary information and earns its place.

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

  Completeness5/5

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

  For a read-only list tool, nothing critical is missing: purpose, returned fields, scope behavior, auth requirement, token redaction, fully documented parameters, and an output schema that covers return values. The description is complete enough for an agent to select and invoke it correctly without consulting anything else.

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

  Parameters3/5

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

  Schema coverage is 100% and every parameter already has a solid description (page range, org_id scoping, per_page clamping behavior), so the baseline is 3. The description adds one meaningful insight beyond the schema — that omitting org_id yields an instance-wide list requiring admin — which informs invocation choice but does not substantially expand the schema's parameter documentation.

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

  Purpose5/5

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

  States a specific verb ('Lists') with a specific resource ('build agents') and explicitly enumerates the returned fields (platform, capacity, version, last contact). The diagnostic hook 'why is nothing being built' further distinguishes it from siblings like get_agent (single agent), list_agent_tasks (tasks), and create/update/delete_agent (mutations).

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

  Usage Guidelines4/5

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

  Provides clear usage context: it is the diagnostic call for stalled builds, and the org_id vs instance-wide distinction with its admin requirement tells the agent how scope changes invocation. It lacks explicit exclusions or named alternatives (e.g., 'use get_agent for a single agent'), so it stops short of a 5.

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

• list_agent_tasksA
  4.3/5.0
  Behavior4/5

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

  Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds the 'Admin only' authorization requirement and the 'currently running' temporal scope, both of which go beyond structured annotations. There is no contradiction between description and annotations.

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

  Conciseness5/5

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

  Three short, purposeful sentences. The core behavior is front-loaded, followed by permission and practical use case. There is no filler or repetition of schema content.

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

  Completeness5/5

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

  For a one-parameter, read-only listing tool with an output schema, this description is complete: it states what is listed, the admin-only restriction, and how to interpret the results. Nothing essential is missing.

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

  Parameters3/5

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

  The single agent_id parameter is fully documented by the schema with 100% coverage, so the description does not need to add much. The phrase 'an agent's tasks' reinforces that agent_id selects the target agent, but no new parameter-level detail is provided.

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

  Purpose5/5

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

  The description clearly identifies the resource as an agent's currently running work, states the admin-only access, and adds an operational purpose: discovering which pipeline to cancel. This distinguishes it from sibling tools like list_pipelines and get_agent.

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

  Usage Guidelines4/5

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

  It explicitly frames when to use the tool: when an agent is busy and you need to know what is occupying it and which pipeline to cancel. It does not list alternatives or exclusion conditions, but the usage context is clear enough for an agent to select it.

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

• list_forgesA
  4.3/5.0
  Behavior4/5

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

  Annotations already cover readOnly, idempotent, and non-destructive behavior. The description adds valuable behavioral context beyond that: the operation requires admin privileges, and the returned forge_id is a dependency for other tools. No contradiction with annotations exists.

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

  Conciseness5/5

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

  Three short sentences, each earning its place: purpose, access requirement, and downstream usability. The most important information is front-loaded, with no redundant filler.

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

  Completeness5/5

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

  For a straightforward paginated list operation, the description covers authorization, purpose, and how the result is used by sibling tools. The output schema and annotations handle the remaining structural and safety details, leaving no critical gap for an agent to infer.

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

  Parameters3/5

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

  Schema coverage is 100%, so the parameters are fully documented in the input schema. The description does not add any parameter-level detail beyond the schema, which meets the baseline but does not exceed it.

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

  Purpose5/5

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

  The description states a specific action ('Lists') and resource ('the forges this Woodpecker authenticates against'), plus a clear access scope ('Admin only'). It also signals the output's downstream use, making it distinct from get_forge, create_forge, update_forge, and delete_forge.

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

  Usage Guidelines4/5

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

  It provides clear context: admin-only access and a concrete use case (obtaining forge_id for get_user and delete_user). It does not explicitly contrast with get_forge or state when not to use it, but the listing role is strongly implied by the name and wording.

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

• list_pipelinesA
  4.3/5.0
  Behavior5/5

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

  Beyond annotations, the description adds meaningful behavioral detail: newest-first ordering, summarized output, server-side filtering, and the critical cross-tool distinction between pipeline 'number' and id. These are genuinely useful for an agent deciding how to interpret results and chain calls.

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

  Conciseness5/5

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

  Three concise sentences, each adding distinct value: the main action, the server-side filtering behavior, and the essential identifier warning. No filler or repetition of schema content.

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

  Completeness5/5

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

  The tool has rich schema coverage, an output schema, and annotations declaring read-only/idempotent behavior. The description fills the remaining gaps: ordering, response summary intent, and the number-vs-id convention. Nothing an agent needs to call correctly and interpret results is missing.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds no new parameter-specific detail; its 'number' note concerns output semantics and downstream tools rather than this tool's input parameters.

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

  Purpose4/5

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

  The description clearly identifies the tool as listing a repository's pipelines, with ordering ('newest first') and a summarized shape, so an agent can distinguish it from detail or mutation tools. It does not explicitly name sibling alternatives like list_queued_pipelines or get_pipeline_feed, but the repository-scoped framing provides enough clarity.

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

  Usage Guidelines4/5

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

  The description gives practical context: it tells the agent that filters are handled server-side and that the returned 'number' field is what other pipeline tools expect, which helps route follow-up calls. It does not explicitly state when to prefer this over sibling tools, but the usage context is clear enough.

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

• list_repository_branchesA
  4.3/5.0
  Behavior4/5

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

  Annotations already declare readOnly/idempotent and non-destructive behavior; the description adds the forge-sourced view and the practical warning about trigger_pipeline behavior. It does not disclose response shape or edge cases, but the output schema and schema-level notes cover some of that.

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

  Conciseness5/5

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

  Two sentences, zero filler, with the core action and its most relevant operational consequence front-loaded. Every sentence earns its place.

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

  Completeness5/5

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

  For a read-only list tool with a detailed input schema and output schema, the description is complete: it states what is listed, from whose perspective, and why to call it. No missing information blocks correct invocation.

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

  Parameters3/5

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

  Schema description coverage is 100%, with page, repo_id, and per_page each documented in the input schema. The tool description itself adds no parameter details, but it doesn't need to because the schema carries the burden.

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

  Purpose5/5

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

  The description names a specific verb and resource, 'Lists the branches of a repository,' and clarifies the view is 'as Woodpecker sees them in the forge.' This distinguishes it clearly from repository, pipeline, and pull-request oriented sibling tools.

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

  Usage Guidelines4/5

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

  It gives a concrete use case: check branches before trigger_pipeline, which 'fails with a bare 400 on a branch that does not exist.' It doesn't state when-not-to-use or mention alternative tools, but none is needed for a simple list operation.

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

• list_usersA
  4.3/5.0
  Behavior4/5

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

  The description adds value beyond annotations that already mark this as read-only, idempotent, and non-destructive. It discloses the admin-only requirement and the important behavioral fact that accounts are created automatically on first login, so the set is all historical users. This gives the agent a clear mental model of the returned data.

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

  Conciseness5/5

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

  Three short sentences, all essential. The action and resource lead, the admin restriction follows immediately, and the semantic clarification earns its place by preventing a common misinterpretation.

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

  Completeness5/5

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

  For a simple list operation with an output schema, complete pagination documentation in the schema, and annotations covering safety semantics, the description gives everything an agent needs. No critical gaps remain.

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

  Parameters3/5

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

  The input schema already documents both parameters fully, including page starting at 1 and per_page range with Woodpecker's clamping behavior. The description does not add parameter-specific meaning, so the baseline score of 3 applies.

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

  Purpose5/5

  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 'Lists the accounts known to this Woodpecker instance.' It also differentiates this from a managed roster and from single-user operations like get_user by clarifying the list is auto-populated by login history.

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

  Usage Guidelines4/5

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

  The description clearly specifies an access prerequisite ('Admin only') and gives useful contextual guidance about what the list contains versus what it is not ('not a managed roster'). It does not explicitly name sibling alternatives, but the list-vs-get distinction is strongly implied by the wording.

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

• approve_pipelineA
  4.4/5.0
  Behavior5/5

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

  Annotations already flag destructiveHint=true, and the description adds a concrete, security-critical behavioral detail: approving runs code from a fork with the repository's secrets. This goes well beyond what the annotation alone conveys and helps the agent understand the real consequence of the action.

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

  Conciseness5/5

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

  Two sentences, zero fluff. The first sentence states the action and condition; the second delivers a crucial warning. Well front-loaded and easy to scan.

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

  Completeness4/5

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

  The description, annotations, and schema together cover purpose, risk, and all parameters. An output schema exists, so return-value explanation is not required. The only notable gap is that the description doesn't mention the confirm_token flow, which might make the multi-step approval behavior less discoverable, but the schema does at least acknowledge it.

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

  Parameters3/5

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

  Schema description coverage is 100%, so all parameters are already documented and the description doesn't need to repeat them. The description adds no param-specific meaning beyond the schema, which is acceptable given the full schema coverage. The confirm_token workflow is hinted at in the schema but not elaborated in the description.

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

  Purpose5/5

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

  The description uses a specific verb ('Releases') and resource ('a pipeline that is waiting for approval'), and names the exact status ('blocked'). This clearly distinguishes it from sibling tools like decline_pipeline or cancel_pipeline without needing to inspect their schemas.

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

  Usage Guidelines4/5

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

  It gives clear context for when the tool applies: pipelines waiting for approval, usually from forks. It also advises reading what you approve first. However, it doesn't explicitly mention when not to use it or point to an alternative such as decline_pipeline, so it stops short of full exclusion guidance.

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

• create_forgeA
  4.4/5.0
  Behavior4/5

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

  Annotations already indicate this is not read-only and not idempotent, so the mutation behavior is expected. The description adds useful behavioral context by disclosing the admin-only restriction and the external prerequisite about the OAuth application, which are not visible in the schema or annotations. This goes beyond what the structured fields provide.

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

  Conciseness5/5

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

  Two short sentences with no filler. The core purpose is front-loaded, and the additional admin/prerequisite guidance is compact and relevant. Every word earns its place.

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

  Completeness4/5

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

  Given the fully documented schema, output schema, and annotations, the description is largely complete for a create operation. It covers authorization and the key prerequisite. A minor gap is that it does not explicitly mention that this operation will not overwrite an existing forge, but the word 'additional' implies it sufficiently.

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

  Parameters4/5

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

  The input schema has 100% description coverage for parameters, so the baseline is 3. The description adds extra meaning by explaining the relationship between the OAuth parameters and the forge-side setup: the OAuth application must exist first and use this Woodpecker instance as the callback. This helps an agent understand why client/oauth_client_secret/oauth_host are needed, adding value beyond the schema.

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

  Purpose5/5

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

  The description uses a specific verb ('Registers') with a clear resource ('an additional forge'), which unambiguously identifies this as the create-type operation. It is easily distinguished from siblings like update_forge, delete_forge, and list_forges, and the title 'Add a forge' reinforces the intent.

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

  Usage Guidelines4/5

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

  The description gives clear context: this is for registering a new forge and is admin-only. It also states a prerequisite (the OAuth application must already exist on the forge side with Woodpecker as the callback), which tells an agent when it is appropriate to call this tool. It does not explicitly contrast with update_forge or delete_forge, but the create-oriented wording makes the intended use clear.

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

• delete_pipelineA
  4.4/5.0
  Behavior5/5

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

  Annotations already mark the tool destructive and non-read-only, and the description adds meaningful behavioral context: it destroys logs and attached data, cannot target running pipelines, and requires a two-step flow. This goes beyond the annotations by specifying exactly what gets removed and the precondition.

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

  Conciseness5/5

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

  Three short sentences, each earning its place: the destructive scope, the running-pipeline constraint, and the two-step nature. It is front-loaded with the action and consequence, with no filler.

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

  Completeness4/5

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

  Given the output schema and full parameter schema, the description provides enough context for selection and invocation. The only minor gap is that 'Two-step' is not fully elaborated, though the confirm_token parameter description and schema make the flow recoverable.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the schema fully documents repo_id, number, and confirm_token. The description's 'Two-step' hint adds some process context around confirm_token, but it does not materially enrich parameter understanding beyond the schema.

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

  Purpose5/5

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

  The description states a specific verb and resource: 'Removes a pipeline and everything attached to it, including its logs.' This clearly distinguishes it from log-only tools like delete_pipeline_logs and from cancel_pipeline, while the destructive scope is explicit.

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

  Usage Guidelines4/5

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

  It gives explicit guidance for a key edge case: 'A running pipeline cannot be deleted — cancel it first,' which points the agent toward the cancel_pipeline sibling. It does not enumerate other alternatives like delete_pipeline_logs for log-only removal, but the core usage context is clear.

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

• delete_registryA
  4.4/5.0
  Behavior4/5

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

  Beyond the annotations (destructiveHint=true, readOnlyHint=false, idempotentHint=true), the description adds genuinely useful behavioral context: the specific downstream effect of deletion is pipeline failures at the image pull step, and the operation requires a two-step confirmation flow. These traits are not enumerable from annotations alone and materially shape how an agent should reason about calling the tool.

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

  Conciseness5/5

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

  Three short sentences, zero filler, with the core purpose front-loaded before the consequence and workflow notes. Every sentence earns its place: what it removes, what breaks afterward, and how the process works.

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

  Completeness4/5

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

  The schema fully documents all five parameters (including conditional requirements and scope precedence), annotations cover the safety profile, and an output schema exists, so the description need not repeat structured information. The description supplies the missing operational context (impact on pipelines, two-step flow). A minor gap is that the mechanics of the two steps are not spelled out, but they are inferable from the confirm_token schema description.

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

  Parameters4/5

  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 with the schema doing the heavy lifting. The description's "Two-step" disclosure adds real value beyond the schema by explaining why confirm_token exists (it comes from a prior call to the same tool), which the schema states but does not motivate. This workflow context meaningfully enriches parameter understanding.

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

  Purpose5/5

  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 — "Removes stored credentials for a registry" — which precisely states what the tool does and differentiates it from siblings like get_registry, create_registry, and update_registry. The title, description, and annotations (destructiveHint=true) align consistently. It also adds operational detail (pull-step failures) that makes the purpose unmistakable.

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

  Usage Guidelines4/5

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

  The consequence warning — "Pipelines that pull private images from it start failing at the pull step" — gives an agent clear decision-relevant context about the impact of using the tool, and "Two-step" conveys the confirmation workflow required for correct invocation. It does not explicitly name alternatives such as update_registry for credential rotation, so it stops short of full exclusion guidance.

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

• repair_repositoryA
  4.4/5.0
  Behavior4/5

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

  The description discloses a mutating repair operation that is consistent with the annotations (readOnly=false, destructive=false, idempotent=true). It adds useful behavioral context for instance scope: it affects every repository and hits the forge API once per repository. It does not fully explain the confirmation flow, but the schema's confirm_token field covers that.

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

  Conciseness5/5

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

  Three compact sentences: first states the core action, second gives the practical use case, third adds the scope caveat with cost implications. No filler, repetition, or irrelevant details.

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

  Completeness4/5

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

  The description is sufficient for an agent to understand when and why to invoke the tool, and the schema fills in parameter specifics (confirm_token, repo_id, admin-only). An output schema exists, so return values need not be described. The only minor ambiguity is the exact two-step flow, but confirm_token's schema description clarifies it.

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

  Parameters4/5

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

  Schema coverage is 100%, so the baseline is 3. The description adds extra semantic meaning for the scope parameter by describing the instance-wide effect ('every repository on the server... hits the forge API once per repository'), which goes beyond the schema's terse 'repairs all of them (admin only).'

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

  Purpose5/5

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

  The description opens with a specific verb-resource pair: 'Re-installs the forge webhook and refreshes the stored repository data.' It then names the exact problem it fixes ('pushes no longer start a pipeline' after a rename or URL change), which clearly distinguishes it from siblings like update_repository or activate_repository.

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

  Usage Guidelines4/5

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

  The description explicitly states when to use the tool: 'This is the fix for "pushes no longer start a pipeline" after a repository was renamed or the Woodpecker URL changed.' It doesn't name alternatives or exclusions, but the triggering condition is unambiguous and enough for an agent to select it.

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

• run_cronA
  4.4/5.0
  Behavior5/5

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

  Annotations declare readOnlyHint=false, idempotentHint=false, and destructiveHint=true, yet the description still adds substantial behavioral value: the schedule stays unchanged, the run counts as a cron event, and — going beyond the idempotentHint flag — 'a retry after a timeout starts a second one.' This gives the agent concrete, actionable understanding of the side effects it cannot infer from the annotations alone.

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

  Conciseness5/5

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

  Three sentences, each earning its place: the core action is front-loaded in sentence one, the use case and cron-event accounting anchor sentence two, and the retry consequence lands in sentence three. There is no filler or restatement of the title.

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

  Completeness4/5

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

  For a two-parameter mutation with a full output schema, the description covers the critical behavioral surface: what starts, what stays unchanged, what side effects occur, and what retry means. The only minor gap is the absence of failure conditions (e.g., whether the cron must exist or be active), but the output schema and schema parameter docs cover the remainder.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the baseline of 3 applies even though the tool description adds no parameter-level guidance. The schema itself documents cron_id and repo_id adequately (including a lookup hint for repo_id), but the description contributes nothing about how the parameters interact with the run behavior.

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

  Purpose5/5

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

  The description opens with a specific verb+resource statement: 'Starts the cron job's pipeline immediately, without waiting for its schedule.' The phrase 'without waiting for its schedule' clearly separates on-demand execution from every sibling that manages or inspects cron definitions (create_cron, update_cron, delete_cron, get_cron) and from direct pipeline triggers (trigger_pipeline, restart_pipeline).

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

  Usage Guidelines4/5

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

  The description gives an explicit scenario: 'this is how you test that a nightly job works before waiting a night for it.' It also clarifies constraints around use ('every call is another run'). However, it never names alternative tools or states when not to use it, e.g., a direct one-off pipeline that should go through trigger_pipeline instead.

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

• update_cronA
  4.4/5.0
  Behavior4/5

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

  Annotations already signal idempotent and destructive behavior, and the description adds meaningful context beyond them by disclosing that updates are partial — untouched fields are not modified. It also explains the 'enabled' field's role in pausing instead of deleting. It does not contradict 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.

  Conciseness5/5

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

  Two sentences with no filler. The action is stated first, then the most important behavioral nuance follows immediately. Every part of the description earns its place.

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

  Completeness4/5

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

  Given the strong schema, annotations, and output schema, the description covers the essential behavioral contract. It could go slightly further by explicitly noting this applies to an existing cron job, but the name, required cron_id parameter, and sibling context make that reasonably inferable.

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

  Parameters4/5

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

  Schema description coverage is 100%, and parameter descriptions are already rich. The description's key added value is the cross-parameter semantic that only passed fields are touched, which clarifies that omitted optional parameters retain their current values. This goes beyond the individual property descriptions.

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

  Purpose5/5

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

  States a specific action and resource: 'Changes a cron job.' The added detail about partial updates and pausing via 'enabled' distinguishes it from sibling tools like delete_cron and create_cron, so an agent can immediately understand what this tool does and what it is not for.

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

  Usage Guidelines4/5

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

  The description gives clear usage context: pass only the fields to change, and disable a schedule with 'enabled' rather than losing it by deleting. It does not explicitly enumerate alternatives such as create_cron or run_cron, but the guidance is clear enough for practical selection among the cron siblings.

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

• cancel_pipelineA
  4.5/5.0
  Behavior5/5

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

  The description goes beyond the annotations by disclosing that steps are killed in place and half-written artifacts remain half-written, and that the operation is reversible via restart. This gives the agent a realistic model of non-atomic cancellation behavior.

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

  Conciseness5/5

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

  Three short sentences with each earning its place: the action, the side-effect, and the recovery option. The main behavior is front-loaded, and there is no tautology or filler.

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

  Completeness5/5

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

  With a full output schema, complete parameter documentation, and annotations already declaring idempotency and non-destructiveness, the description is sufficient for an agent to select and invoke the tool correctly. Nothing essential is missing.

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

  Parameters3/5

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

  Schema description coverage is 100%, and the schema already explains that number is the per-repository pipeline counter and repo_id is numeric with lookup/list guidance. The tool description adds no parameter-specific detail, so the baseline 3 applies.

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

  Purpose5/5

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

  Description opens with a specific verb and target—'Stops a pipeline that is pending or running'—and the closing 'can be restarted afterwards' separates cancellation from a permanent delete. It clearly identifies the resource and state to which it applies.

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

  Usage Guidelines4/5

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

  The 'pending or running' qualifier gives a clear state-based condition for use, and 'can be restarted afterwards' implies cancellation is preferable when the pipeline is not to be permanently removed. It does not explicitly name alternative tools like delete_pipeline, so it misses the top bar for explicit routing.

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

• create_secretA
  4.5/5.0
  Behavior5/5

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

  It goes well beyond the annotations by disclosing that the value is write-only and never readable again through the API, recommending external storage, and warning that events have no defaults and pull_request must be explicitly included. These are critical behavioral details not captured by the raw annotation flags.

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

  Conciseness5/5

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

  Three short sentences, each earning its place: the purpose, the write-only warning, and the events/pull_request gotcha. The most important constraints are front-loaded and there is no filler.

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

  Completeness5/5

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

  For a complex 8-parameter create operation with an output schema, the description covers the non-obvious pitfalls that could cause data loss or invisible secrets. The remaining parameter details are fully covered by the 100%-documented schema, so 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.

  Parameters3/5

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

  Schema description coverage is 100%, so the baseline is 3. The description reinforces the meaning of scope, value, and events, but mostly restates what the schema already documents. It adds no new per-parameter syntax beyond the schema's own rich descriptions.

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

  Purpose5/5

  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, 'Creates a secret,' and adds the scoping notion 'at the chosen level.' This clearly distinguishes it from sibling tools like get_secret, update_secret, and delete_secret.

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

  Usage Guidelines4/5

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

  The description makes the tool's context clear: use it to create a secret, with important warnings about write-only values and required events. It does not explicitly name alternatives such as update_secret or delete_secret for subsequent changes, but the create verb makes the primary use case unambiguous.

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

• create_userA
  4.5/5.0
  Behavior5/5

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

  With no meaningful annotation coverage beyond non-read-only flags, the description carries the behavioral burden well. It discloses the side-effect boundary—pre-creating only a Woodpecker record, not granting forge access—and the confirmation behavior for admin=true ('asks a person first').

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

  Conciseness5/5

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

  Three sentences with the core purpose front-loaded, followed by important scope caveats and the admin confirmation behavior. Every sentence adds useful information without filler.

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

  Completeness5/5

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

  The output schema exists and all parameters are documented in the schema. The description supplies the missing contextual pieces: permission level, timing, side-effect scope, and admin confirmation, making it sufficiently complete for correct invocation.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the baseline is 3. The description adds no new parameter-level meaning beyond what the schema already documents; the 'asks a person first' note repeats the admin parameter's schema description.

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

  Purpose5/5

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

  The description states a specific verb and resource: 'Registers an account ahead of its first login.' It further clarifies this is not a forge-level creation and only 'pre-creates the Woodpecker record,' which clearly distinguishes it from sibling create_* tools like create_agent, create_forge, or create_secret.

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

  Usage Guidelines4/5

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

  The description gives clear conditions: use it before first login and it is admin-only. It also states a when-not by explaining that 'this does not create anything in the forge and grants no access there,' but it does not name any alternative sibling tool explicitly.

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

• delete_forgeA
  4.5/5.0
  Behavior5/5

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

  Annotations already indicate destructive and non-readonly behavior, and the description adds meaningful specifics: access loss for users, repositories no longer readable, and a two-step confirmation process. This goes well beyond the structured hints.

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

  Conciseness5/5

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

  Three short sentences, each earning its place: what the tool does, who can use it, and the critical consequences/process. No filler or redundant restatement of the title.

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

  Completeness5/5

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

  For a destructive, two-step admin tool with full schema documentation and an output schema, the description covers the essential context: admin restriction, destructive impact, and confirmation workflow. Nothing critical is missing.

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

  Parameters3/5

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

  Schema coverage is 100%, so the parameters are already fully documented. The description adds only a general 'two-step' hint that echoes the confirm_token schema text; it doesn't need to add more since the schema carries the load.

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

  Purpose5/5

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

  Description uses the specific verb 'Removes' with the resource 'forge from Woodpecker', clearly distinguishing it from sibling tools like delete_repository and update_forge. It goes beyond a tautology by adding consequences and administrative scope.

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

  Usage Guidelines4/5

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

  Explicitly states this is 'Admin only' and notes the two-step nature, giving an agent enough context about prerequisites and process. It does not explicitly name alternatives or exclusions, but the resource and behavior are clear enough to route correctly.

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

• delete_organizationA
  4.5/5.0
  Behavior5/5

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

  The annotations already mark the tool as destructive and non-read-only, and the description adds valuable behavior beyond that: it names the affected org-level resources, notes downstream breakage for anything relying on org-level secrets, states the admin requirement, and reveals the two-step confirmation flow. No contradiction with annotations exists.

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

  Conciseness5/5

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

  The description is compact and well-structured: main effect first, then prerequisites, then exclusions and consequences, then the two-step note. Every sentence carries useful information and no filler is present.

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

  Completeness5/5

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

  For a destructive org-level operation with a two-step confirmation, the description plus annotations and complete schema coverage give an agent everything needed to call the tool correctly: what is deleted, who may call it, the confirmation flow, and what remains untouched.

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

  Parameters3/5

  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 both org_id and confirm_token thoroughly. The description's 'Two-step' hint marginally reinforces the confirm_token purpose, but does not add meaningful parameter semantics beyond the schema.

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

  Purpose5/5

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

  The description uses a specific verb ('Removes') and a clear resource ('an organization from Woodpecker'), and lists exactly what is removed along with it: org-level secrets, registries, and agents. This clearly distinguishes the tool from sibling delete_repository, delete_secret, and delete_registry tools.

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

  Usage Guidelines4/5

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

  It gives clear context: admin-only, two-step, and what it does not do (does not touch the forge or delete repositories). It does not explicitly name an alternative tool, but the scoping language makes the appropriate use obvious relative to the sibling delete_* tools.

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

• delete_repositoryA
  4.5/5.0
  Behavior5/5

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

  The description goes well beyond the destructiveHint annotation by detailing exactly what will be deleted and what will not. It also discloses the two-step process, giving the agent an accurate model of the tool's behavior before invoking it.

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

  Conciseness5/5

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

  The description is tight and efficient: three short sentences that enumerate the deletion scope, state the key exception, and flag the two-step flow. Every sentence adds necessary information without repetition or filler.

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

  Completeness5/5

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

  For a destructive, high-stakes operation, the description covers the scope of destruction, the non-destructive boundary, and the two-step confirmation mechanism. The output schema and rich input schema fill any remaining gaps, so the description is complete for correct invocation.

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

  Parameters3/5

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

  Schema description coverage is 100%, and the schema already explains repo_id and confirm_token well, including how to resolve a repo_id from an owner/name pair. The description's 'Two-step' note adds some context for confirm_token, but the parameter knowledge is largely carried by the schema, so a baseline score is appropriate.

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

  Purpose5/5

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

  The description clearly states the tool removes a repository from Woodpecker and specifies exactly which related resources are removed (webhook, pipelines, logs, secrets, registries, cron jobs). It also notes the forge repository itself is untouched, distinguishing it from broader deletion or forge-level operations.

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

  Usage Guidelines4/5

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

  The description makes the tool's use case clear: full removal of a repository from Woodpecker. The explicit list of all sub-resources deleted and the note that the forge repository is untouched provide good contextual guidance, though it does not name an alternative like delete_pipeline for single-pipeline deletion.

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

• delete_step_logsA
  4.5/5.0
  Behavior5/5

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

  Beyond the destructiveHint and idempotentHint annotations, the description explains the two-step confirmation behavior, clarifies that only logs are deleted, and warns that deleting a log does not undo the exposure. This is valuable behavioral context for a destructive operation.

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

  Conciseness5/5

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

  The description is short, front-loaded, and every sentence earns its place: core action, scope clarification, usage context, and safety warning. There is no redundant phrasing or filler.

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

  Completeness5/5

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

  The combination of full schema coverage, the two-step confirmation flow hinted in the description, existing annotations, and an output schema leaves no critical gap. The credential-rotation warning makes this particularly complete for a destructive log-clearing tool.

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

  Parameters3/5

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

  Schema description coverage is 100%, and the schema already explains repo_id, number, step_is and confirm_token, including where the identifiers come from. The description adds no parameter-level detail, 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.

  Purpose5/5

  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 ('Deletes the stored output of a single step') and clarifies that the step and pipeline remain while logs are removed. This clearly distinguishes it from pipeline-level deletion tools like delete_pipeline_logs.

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

  Usage Guidelines4/5

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

  The description gives a concrete trigger condition ('This is what you use when a step printed a secret') and adds necessary follow-up guidance to rotate the credential. However, it does not name an alternative tool or explicitly state when not to use it.

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

• get_agentA
  4.5/5.0
  Behavior5/5

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

  Annotations already mark the operation as read-only, idempotent, and non-destructive. The description adds meaningful context beyond those: admin-only access, the fact that the token is redacted, and the consequence for token recovery. This is exactly the kind of behavioral disclosure that helps an agent avoid misuse.

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

  Conciseness5/5

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

  Very concise: two short sentences front-load the core action, access restriction, and the critical redaction behavior. Every clause earns its place and no filler is present.

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

  Completeness5/5

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

  For a simple single-object get operation with one fully documented parameter and an output schema, the description fully covers authorization, redaction behavior, and the relevant recovery path. Nothing essential is missing for an agent to select and invoke it correctly.

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

  Parameters3/5

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

  With schema description coverage at 100% and a single parameter already described as 'Numeric agent id,' the description does not need to add parameter details. It adds no redundant semantics, which is appropriate here.

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

  Purpose5/5

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

  States a specific verb and resource: 'Returns one agent.' The singular scope distinguishes it from list_agents, and the additional admin-only and token redaction details clarify what this operation actually does.

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

  Usage Guidelines4/5

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

  The description provides practical when-not-to-use guidance: because the token is redacted, an agent that lost its token must be recreated via delete_agent and create_agent. It does not explicitly contrast with list_agents, but the single-agent scope and the recovery path give strong contextual direction.

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

• get_current_userA
  4.5/5.0
  Behavior4/5

  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 covered. The description adds useful context beyond annotations: token ownership, the admin boolean, and the diagnostic 403 workflow.

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

  Conciseness5/5

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

  Two tight sentences with no filler. The primary result is stated first, followed by an immediately actionable usage tip, making the description both compact and well-structured.

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

  Completeness5/5

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

  With an empty input schema, an output schema present, and annotations covering safety, the description includes all essential context: what is returned and when to call the tool. Nothing critical is missing.

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

  Parameters4/5

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

  The tool has zero parameters and schema description coverage is 100% by default, so the baseline is 4. There is no parameter meaning for the description to add.

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

  Purpose5/5

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

  States precisely what it returns: the account associated with WOODPECKER_TOKEN, plus admin status. This clearly distinguishes it from sibling tools like get_user or list_users, which operate on other users.

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

  Usage Guidelines4/5

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

  Gives explicit when-to-use guidance: call this first when a tool returns 403, because admin-only tools require admin=true. It doesn't explicitly name alternatives or exclusions, but the 'current account' scope makes the intended context clear.

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

• get_log_levelA
  4.5/5.0
  Behavior4/5

  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 context by noting the 'Admin only' access restriction, which is beyond the annotations and important for invocation.

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

  Conciseness5/5

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

  The description is a single concise sentence that communicates the operation, scope, and access restriction without any redundant wording.

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

  Completeness5/5

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

  For a simple zero-parameter read-only tool with a rich output schema, the description fully covers what an agent needs: what it returns, for which server, and who is allowed to call it. Nothing important is missing.

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

  Parameters4/5

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

  The tool has zero parameters and schema description coverage is 100%, so there is nothing for the description to add about parameters. The baseline of 4 for zero-parameter tools is appropriate.

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

  Purpose5/5

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

  The description clearly states the specific verb 'Returns' and the resource 'current log level of the Woodpecker server'. It is easily distinguished from the sibling set_log_level because it is explicitly a read operation.

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

  Usage Guidelines4/5

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

  The description conveys clear usage context: it returns the current log level. It does not explicitly mention alternatives or state 'use set_log_level to change the level', but the get/set distinction is obvious from the sibling list and the verb used.

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

• get_queue_infoA
  4.5/5.0
  Behavior4/5

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

  Annotations already convey read-only, idempotent, non-destructive behavior. The description adds meaningful context beyond annotations: the admin-only authorization requirement and the specific scope of queue state. This is valuable behavioral disclosure without contradicting 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.

  Conciseness5/5

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

  Two concise sentences deliver the core scope, the admin restriction, and the primary use case. Every clause earns its place, and the most important information is front-loaded.

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

  Completeness5/5

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

  With no parameters, annotations covering safety, and an output schema present, the description is complete for correct invocation. It adds the auth requirement and the diagnostic use case, so an agent has everything needed to choose and call the tool.

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

  Parameters4/5

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

  The tool has zero parameters, so parameter semantics are trivially complete. The description correctly avoids inventing parameter details and focuses on what the tool returns, which matches the 100% schema coverage baseline for zero-parameter tools.

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

  Purpose5/5

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

  The description clearly identifies the resource (server-side build queue) and the specific information returned (pending, running, waiting on an agent, agent statistics). It also positions itself relative to list_queued_pipelines, making its role distinct enough for an agent to understand what this tool covers.

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

  Usage Guidelines4/5

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

  The description gives clear usage context: it is admin-only and is part of answering 'why is my build not starting', explicitly paired with list_queued_pipelines. It does not enumerate exclusion conditions or alternative selection rules, but the guidance is sufficient for typical invocation decisions.

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

• get_secretA
  4.5/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds a non-obvious behavioral guarantee: the secret value is stripped from every response, even immediately after creation. This is exactly the kind of insight an agent cannot derive from annotations or the schema.

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

  Conciseness5/5

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

  Two sentences with no waste: the first defines the purpose and output fields, the second prevents a critical misuse by stating that the value is never returned. The key caveat is front-loaded and clearly separated.

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

  Completeness5/5

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

  For a single-item read tool with a rich output schema, 100% parameter schema coverage, and safety annotations, the description supplies the one essential missing expectation—the value is never exposed—making the tool fully and safely invocable.

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

  Parameters3/5

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

  Schema description coverage is 100%, with each parameter (name, scope, org_id, repo_id) already containing detailed descriptions including case-sensitivity and scope-dependent requirements. The tool description adds no parameter-specific meaning, so the baseline of 3 applies.

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

  Purpose5/5

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

  The description states a specific verb ('Returns'), a clearly bounded resource ('one secret's metadata'), and exactly which fields are returned (events, images, note). It also explicitly distinguishes this from value retrieval, making it easy to tell apart from list_secrets, create_secret, update_secret, and delete_secret.

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

  Usage Guidelines4/5

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

  The description gives clear context: this tool returns metadata only, and the secret value is never included, so an agent knows not to call it when the value is needed. It does not explicitly name sibling alternatives, but the 'one secret' phrasing and the value-stripping caveat provide practical selection guidance.

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

• get_userA
  4.5/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the admin-only authorization requirement and notes that forge_id is needed by the API, which are behavioral details not present in 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.

  Conciseness5/5

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

  Two sentences, no filler. The core purpose is front-loaded, and the admin restriction and forge_id note are placed right after it. Every clause earns its place.

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

  Completeness5/5

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

  For a simple read-only getter with a full output schema, 100% parameter schema coverage, and rich annotations, this description is complete. It tells the agent everything needed to call it correctly: the access level, the identifying parameters, and where to get the required forge_id.

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

  Parameters4/5

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

  Schema coverage is 100%, giving the baseline of 3. The description adds value by clarifying that forge_id is required by the API and that list_users is the source for its value, which helps an agent understand the relationship between parameters beyond the schema.

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

  Purpose5/5

  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 one account by its login' — and distinguishes itself from siblings by contrasting with list_users ('see list_users'). It makes the tool's scope immediately clear: fetch a single account, not a list.

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

  Usage Guidelines4/5

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

  The description gives clear usage context: 'Admin only' signals the permission boundary, and 'forge_id is required — see list_users for the value' tells the agent where to obtain a needed parameter. It doesn't explicitly state when to prefer this over get_current_user or list_users, but the singular-account framing makes the intended use unambiguous.

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

• list_queued_pipelinesA
  4.5/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds meaningful context by explaining what the list actually represents ('what is stuck, and behind what') and that it spans all repositories, going beyond 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.

  Conciseness5/5

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

  Two sentences with no filler. The first sentence front-loads the action, resource, and scope; the second delivers the key differentiation against get_queue_info. Every word earns its place.

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

  Completeness5/5

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

  For a simple parameterless read-only list with an output schema and full annotation coverage, this description is complete. It tells the agent what the tool returns conceptually, its scope, and how it relates to the closest sibling. Nothing needed 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.

  Parameters4/5

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

  The tool has zero parameters, so there is nothing to document. The baseline of 4 for parameterless tools applies, and the description correctly avoids inventing parameter-related instructions.

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

  Purpose5/5

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

  The description states a specific verb ('Lists'), a precise resource ('pipelines waiting in the server queue'), and an explicit scope ('across all repositories'). It also distinguishes itself from get_queue_info by framing this as the instance-wide view, so an agent can tell them apart.

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

  Usage Guidelines4/5

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

  The description gives clear context: this is the instance-wide queue view, while get_queue_info covers the agent-side picture. It names the relevant alternative and implies the selection condition, though it does not explicitly enumerate when-not-to-use scenarios beyond that one sibling.

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

• list_secretsA
  4.5/5.0
  Behavior5/5

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

  Annotations already mark the operation as read-only, idempotent, and non-destructive; the description adds important behavior beyond that: values are never returned, the response contains only names/events/image restrictions, and a missing secret may still exist at a higher level. This sets correct expectations for response contents and hierarchical lookup without contradicting 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.

  Conciseness5/5

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

  Three short sentences with no filler: the core listing behavior is front-loaded, followed by the critical caveat about values, and then the hierarchical nuance. Every sentence contributes distinct, useful information.

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

  Completeness5/5

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

  The description is complete for a list operation: it specifies the scoping dimension, describes the response shape, and warns about hierarchy behavior. Pagination and ID requirements are already fully handlded by the schema and output schema, so nothing needed for correct invocation is missing.

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

  Parameters3/5

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

  With 100% schema description coverage, the baseline is 3 even when the description adds no parameter-specific details. The description's mention of repository/organization/instance-wide mirrors the scope enum, while the schema already documents required IDs, admin-only global scope, pagination, and clamping behavior.

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

  Purpose5/5

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

  The description states a specific verb ('Lists'), a clear resource ('secrets'), and the scoping levels ('repository, organization or instance-wide'). It also distinguishes the list operation from get by explicitly noting that values are never returned and that the response contains names, events, and image restrictions.

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

  Usage Guidelines4/5

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

  The description clearly frames this as a one-level listing tool and states that values are not available even here, which signals that it is not the tool for retrieving secret values. The note that a pipeline sees all three levels provides practical context for interpreting results, though it does not explicitly name get_secret as the alternative.

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

• pause_queueA
  4.5/5.0
  Behavior5/5

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

  The description adds meaningful behavior beyond the annotations: running pipelines finish, all other work queues up, the pause is instance-wide, it persists until resume_queue is called, and the operation requires a two-step confirmation flow. These details disclose impact and persistence far beyond the structured hints.

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

  Conciseness5/5

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

  The description is compact: three sentences that front-load the core action, then give consequences, scope, permissions, and process. Every sentence contributes useful information with no filler or redundancy.

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

  Completeness5/5

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

  For a globally destructive-ish admin action, the description covers the key operational facts: what stops, what continues, who can call it, how wide the impact is, how long it lasts, and that a second step is required. The output schema exists and can carry return-value details, so nothing essential is missing for an agent to invoke this correctly.

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

  Parameters3/5

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

  Schema coverage is 100%: the confirm_token property is already described as a token from a previous call. The description adds the 'Two-step' workflow hint, which mildly reinforces but does not substantially extend what the schema already says. With full schema coverage, baseline 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states the action: 'Stops the server from handing new work to agents.' It names the specific resource (the build queue) and distinguishes itself from siblings like resume_queue and cancel_pipeline by emphasizing instance-wide behavior. The verb is specific and the scope is immediately understandable.

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

  Usage Guidelines4/5

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

  The description gives clear context: admin-only, instance-wide, stops CI for everybody, and stays paused until resume_queue is called. It explicitly names resume_queue as the counterpart for undoing the action. However, it does not explicitly contrast with alternatives like cancel_pipeline for stopping a single pipeline, so exclusions are mainly implied rather than fully stated.

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

• restart_pipelineA
  4.5/5.0
  Behavior5/5

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

  The description adds meaningful behavioral detail beyond the annotations: the re-run gets a new number, the original run is kept, and every call creates another run with no idempotency protection. This directly expands on destructiveHint=true and idempotentHint=false.

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

  Conciseness5/5

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

  Three concise sentences with no filler. The first sentence states the purpose, the second clarifies the outcome, and the third warns about idempotency. Every sentence earns its place and the key behavior is front-loaded.

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

  Completeness5/5

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

  Given rich annotations, a complete input schema, and an output schema, the description covers the critical behavioral facts: same commit/config, new run number, original preserved, and no idempotency key. Nothing needed for correct selection or invocation is missing.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the schema already documents all four parameters well. The description does not add parameter-specific detail, but that is acceptable given the full schema coverage; baseline 3 is appropriate.

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

  Purpose5/5

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

  The description states a specific verb ('Runs') and resource ('an existing pipeline'), and adds precise scope: same commit, same config. This clearly distinguishes restart_pipeline from siblings like trigger_pipeline, cancel_pipeline, and delete_pipeline.

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

  Usage Guidelines4/5

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

  The description gives clear context for when to use the tool: re-running an existing pipeline with its original commit and config. It also provides an important caution about retries causing additional runs, though it does not explicitly name alternative tools or state when not to use it.

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

• trigger_pipelineA
  4.5/5.0
  Behavior5/5

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

  Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds real context on top: the exact failure mode (bare 400 for nonexistent branch), the concrete retry hazard (a retry starts a second pipeline because Woodpecker has no idempotency key), and the event='manual' semantics. No contradictions 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.

  Conciseness5/5

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

  Four sentences, each carrying distinct information: core action, failure mode with mitigation, idempotency limitation, and post-call verification. The most decision-relevant fact (what it does and scope) is front-loaded, and there is zero redundancy or filler.

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

  Completeness5/5

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

  Given that an output schema exists (so return values need no explanation) and annotations cover the safety profile, the description covers everything an agent needs: exact behavior, failure behavior, idempotency consequences, and both pre- and post-call checks referenced to sibling tools. Nothing material is missing for correct invocation.

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

  Parameters3/5

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

  Schema description coverage is 100%, so all four parameters (branch, message, repo_id, variables) are already fully documented, including the flat string-to-string constraint on variables. The description adds one useful bit of parameter-related context—that an invalid branch yields a bare 400—but otherwise adds no per-parameter meaning beyond the schema. Baseline 3 is appropriate.

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

  Purpose5/5

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

  The description states a specific verb and resource ('Starts a pipeline manually on a branch') and adds a distinguishing detail: the config runs as it exists in that branch right now with event 'manual'. This clearly separates it from siblings like restart_pipeline (existing pipeline), run_cron (scheduled), and cancel_pipeline (opposite action).

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

  Usage Guidelines4/5

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

  The description gives explicit operational guidance: check list_repository_branches before calling to avoid the bare-400 failure, and read list_pipelines before retrying to avoid duplicate runs. It names concrete sibling tools for pre- and post-call validation. It falls just short of 5 because it never explicitly contrasts with restart_pipeline or run_cron as alternatives for different scenarios, leaving some sibling differentiation to the agent.

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

• activate_repositoryA
  4.6/5.0
  Behavior4/5

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

  Annotations already indicate the operation is non-read-only, idempotent, and non-destructive. The description adds meaningful behavioral context by disclosing that activation installs a webhook and enables pipeline runs, which are important side effects. It also signals the precondition that the repository must already exist in the forge.

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

  Conciseness5/5

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

  The description is two sentences with no filler: the first sentence conveys the core action and consequence, and the second handles parameter disambiguation and retrieval guidance. It is front-loaded and every sentence adds value beyond the structured fields.

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

  Completeness5/5

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

  For a single-parameter tool with an output schema and full annotations, the description covers purpose, effects, preconditions, and parameter sourcing. The idempotent annotation already addresses the behavior for already-active repositories, so nothing essential is missing.

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

  Parameters5/5

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

  Although the schema already describes forge_remote_id, the tool description goes further by explicitly ruling out owner/name pairs and Woodpecker IDs, and by providing a concrete lookup path through list_repositories. This eliminates a common point of confusion and materially helps the agent supply the correct value.

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

  Purpose5/5

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

  The description states a specific action ('Turns on Woodpecker'), the target resource (a repository that exists in the forge), and the concrete effects (installs the webhook and makes pipelines run). It clearly differentiates activation from repository creation and from sibling tools by focusing on the enablement action.

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

  Usage Guidelines4/5

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

  The description gives clear context: use this when you need to enable Woodpecker for an existing forge repository. It also provides important usage guidance by explaining how to obtain the correct identifier via list_repositories with include_inactive=true. It does not explicitly discuss alternatives or exclusions, but the activation use case is distinct and unambiguous enough that no additional exclusions are strictly necessary.

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

• delete_agentA
  4.7/5.0
  Behavior5/5

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

  Even though destructiveHint=true covers the broad safety class, the description goes further by disclosing token invalidation, loss of in-flight work, and the two-step nature of the operation. This meaningfully enriches the annotation and helps the agent understand consequences beyond 'destructive'.

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

  Conciseness5/5

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

  The description is concise: two sentences that front-load the core action, then add the most important consequence and prerequisite. Every sentence adds necessary information without redundancy.

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

  Completeness5/5

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

  Given the rich input schema, output schema, and annotations, the description covers all essential operational context: what is destroyed, why caution is needed, and how to sequence the deletion. No critical behavioral gap remains for a tool of this complexity.

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

  Parameters3/5

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

  The input schema already has 100% description coverage for all three parameters, including a clear description of confirm_token as 'Token from a previous call'. The tool description does not add parameter-level meaning beyond that, so a baseline score of 3 is appropriate.

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

  Purpose5/5

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

  The description uses a strong verb ('Removes') with a specific resource ('an agent') and adds concrete scope ('invalidates its token'). It clearly distinguishes this from sibling tools like update_agent by framing the two-step relationship.

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

  Usage Guidelines5/5

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

  The description gives explicit usage guidance: drain the agent first with update_agent no_schedule=true, and warns that running work is lost and must be restarted. This tells the agent exactly when deletion is appropriate and what prerequisite step to take.

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

• delete_cronA
  4.7/5.0
  Behavior5/5

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

  Annotations already mark this as destructive and not read-only, but the description adds the crucial 'Two-step' behavior, indicating a confirmation token is required and this is not a single-call operation. It further contrasts with the non-destructive update_cron path, adding context beyond the structured hints.

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

  Conciseness5/5

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

  Three short sentences convey the primary action, the key alternative, and a critical workflow detail. The main action is front-loaded, and every clause earns its place without redundancy.

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

  Completeness5/5

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

  For a destructive, two-step cron deletion tool, the description plus annotations and fully-covered schema provide everything needed: what it does, when to use it, the alternative, and the token-based confirmation flow. The output schema covers return values, so no further description is needed.

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

  Parameters3/5

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

  Schema coverage is 100%, so the baseline is 3. The description does not explain repo_id or cron_id beyond the schema, and the 'Two-step' note is behavioral rather than parameter-specific. The confirm_token parameter is already well described in the schema as a token from a previous call, so the description adds little param-level meaning.

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

  Purpose5/5

  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 ('Removes a scheduled run') that exactly matches the tool title. It also distinguishes itself from update_cron by explicitly framing deletion versus temporary disabling.

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

  Usage Guidelines5/5

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

  It gives an explicit alternative: if you only want to stop the run for now, use update_cron with enabled=false. The condition (permanent removal vs. temporary stop) is clearly stated, leaving no ambiguity about when this tool should be chosen.

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

• delete_userA
  4.7/5.0
  Behavior5/5

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

  Beyond annotations, the description discloses critical behavioral consequences: repositories keep running on a nonexistent token and pipelines later stop starting. It also reveals the two-step deletion flow and the admin permission requirement. This does not contradict the destructiveHint and adds valuable operational context beyond what the annotations already convey.

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

  Conciseness5/5

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

  Every sentence earns its place: purpose, permission, consequence, prerequisite action, and flow are all packed into two concise sentences. No filler or repetition of schema content. The key instruction about chowning first is front-loaded after the core purpose.

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

  Completeness5/5

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

  For a destructive admin tool with an output schema and full parameter documentation, the description covers the essential context: what is removed, who may do it, the prerequisite ownership transfer, and the two-step confirmation flow. The agent has everything needed to decide when and how to invoke it safely.

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

  Parameters3/5

  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 login, forge_id, and confirm_token thoroughly. The description's 'Two-step' hint loosely relates to confirm_token but does not add meaning beyond the schema's 'Token from a previous call of this tool.' Baseline 3 is appropriate since the structured fields carry the parameter semantics.

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

  Purpose5/5

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

  States a specific verb and resource: 'Removes an account from Woodpecker.' It immediately signals scope with 'Admin only' and clearly distinguishes this from sibling tools like delete_repository or delete_agent by naming the account-level operation. The title 'Delete a user' is expanded into meaningful, non-tautological language.

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

  Usage Guidelines5/5

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

  Explicitly tells the agent when to call this tool and what to do first: 'chown_repository moves ownership to someone else, and doing that first is the point.' It also names the alternative tool and warns about the consequence of deleting without it, plus the 'Admin only' restriction. This is strong when-to-use guidance with a clear exclusion.

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

• get_pipeline_feedA
  4.7/5.0
  Behavior4/5

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

  Annotations already indicate the operation is read-only, idempotent, and non-destructive. The description adds meaningful context beyond those annotations by specifying authentication scope, repository visibility, ordering ('newest first'), and that it returns only the latest pipeline per repository.

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

  Conciseness5/5

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

  Two sentences deliver the full meaning without wasted words. The key scoping factors — account feed, visible repositories, latest pipeline, newest first, and the one-request advantage over list_pipelines — are all front-loaded and succinct.

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

  Completeness5/5

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

  With no parameters and a present output schema, the description covers everything an agent needs to know: what the feed contains, its scope, its ordering, and how it compares to the related list_pipelines tool. The annotations complete the safety picture.

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

  Parameters4/5

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

  The tool takes zero parameters, so the description has no parameter burden to carry. The baseline of 4 applies here, and the description does not conflict with the empty schema.

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

  Purpose5/5

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

  The description clearly identifies the resource (the activity feed of the authenticated account) and the action (returns the latest pipeline of every visible repository, newest first). It also distinguishes itself from list_pipelines by presenting this as the 'state of everything' call, making its purpose unmistakable.

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

  Usage Guidelines5/5

  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 this tool: when it wants the overall state of all repositories in a single request. It also names the alternative (list_pipelines per repository) and explains that this tool replaces that multi-call pattern, giving clear selection guidance.

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

• list_repositoriesA
  4.7/5.0
  Behavior5/5

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

  Annotations already mark the operation as read-only, idempotent, and non-destructive; the description adds meaningful behavioral detail beyond that, including the default visibility boundary, the admin requirement for instance scope, the performance cost of include_inactive, and the relationship between inactive repositories and forge_remote_id. 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.

  Conciseness5/5

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

  Three focused sentences deliver the core behavior, the key parameter distinctions, the admin caveat, and a cross-tool hint without wasted words. The most important default behavior is front-loaded.

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

  Completeness5/5

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

  The description is complete for a listing tool: it explains all meaningful mode switches, the admin constraint, the performance tradeoff, and the connection to activate_repository. The output schema and fully documented parameters cover return shape and pagination, so no critical operational context is missing.

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

  Parameters4/5

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

  Schema coverage is 100%, so the baseline is 3; the description adds extra value by explaining that include_inactive is only meaningful for account scope, that it is noticeably slower, and that the returned forge_remote_id is intended for activate_repository. This supplements rather than merely repeats the schema parameter descriptions.

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

  Purpose5/5

  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 repositories') and then clarifies the scope variants: authenticated account view, inactive forge repos, and instance-wide view. It also ties one variant to the forge_remote_id needed by activate_repository, which helps distinguish this listing tool from nearby repository-related siblings.

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

  Usage Guidelines4/5

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

  The description gives clear conditions for each mode: default account-scope listing, include_inactive for never-activated forge repositories, and scope="instance" for admin-only server-wide listing. It does not explicitly say 'use X instead when Y,' but it names activate_repository as the consumer of the forge_remote_id, giving practical routing context.

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

• lookup_repositoryA
  4.7/5.0
  Behavior5/5

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

  Annotations already indicate this is read-only, idempotent, and non-destructive. The description adds meaningful behavioral context beyond that: it warns that repositories existing in the forge but not activated in Woodpecker return a 404, and it clarifies the tool's role as the id-resolution step. This is valuable edge-case disclosure.

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

  Conciseness5/5

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

  Three compact sentences, each earning its place. The core purpose is front-loaded, the relationship to sibling tools is stated next, and the failure mode with alternative is given last. No filler or redundancy.

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

  Completeness5/5

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

  For a single-parameter lookup tool with complete schema coverage, full annotations, and an output schema, the description is complete. It covers the tool's purpose, the 404 edge case, and how to recover, leaving no significant gap for an agent to call it incorrectly.

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

  Parameters3/5

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

  The input schema already fully documents full_name with its format, pattern, and description. The description's mention of an 'owner/name pair' reinforces the schema but does not add substantial 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.

  Purpose5/5

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

  The description states a specific verb ('Resolves') and a precise resource ('owner/name pair to a repository id'). It clearly distinguishes itself from related tools by explaining that every other repository tool takes the numeric id and this is how you obtain it.

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

  Usage Guidelines5/5

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

  The description explicitly explains when to use this tool: any time you need the numeric repository id for other repository tools. It also provides an actionable alternative for the failure case, directing users to list_repositories with include_inactive when the repository is not activated in Woodpecker.

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

• set_log_levelA
  4.7/5.0
  Behavior5/5

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

  Goes well beyond the annotations: discloses the live no-restart effect, the admin authorization requirement, that debug/trace are noisy and should be reverted, and that trace logs request bodies (a real privacy consideration). The idempotentHint=true and destructiveHint=false annotations are consistent with the described behavior, and the description materially enriches what the annotations alone convey.

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

  Conciseness5/5

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

  Three short sentences earn their place: the core action, the access precondition, and the operational warning. The most decision-relevant information (what it changes, that no restart is needed) is front-loaded, with zero filler.

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

  Completeness5/5

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

  For a two-parameter tool with 100% schema coverage, an output schema, and safety-relevant annotations, nothing essential is missing. The description covers access control, live behavior, and operational risks; return-value details are covered by the output schema, and the confirm_token mechanism is documented in the schema.

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

  Parameters4/5

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

  Schema coverage is 100% and both parameters already have rich descriptions, so the baseline is 3. The description adds value by characterizing specific enum values ('debug' and 'trace' are loud; trace logs request bodies), which reinforces the playbook for the level parameter without duplicating the schema's content.

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

  Purpose5/5

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

  States a specific verb and resource ('Changes the log level of the running Woodpecker server') and adds a scope-defining detail ('without a restart') that separates it from config-file-based alternatives. It reads clearly as the mutating counterpart to the sibling get_log_level, so an agent can distinguish it from the 60+ siblings without opening the schema.

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

  Usage Guidelines4/5

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

  Gives clear operational context: use this for live changes that take effect without a restart, and it flags the admin-only precondition. It also cautions to revert debug/trace after use, which is actionable guidance. However, it does not name an explicit alternative or state a when-not-to-use condition, so it falls just short of a 5.

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

• get_server_infoA
  4.9/5.0
  Behavior5/5

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

  Annotations already cover read-only and idempotent behavior, so the bar is lower. The description adds valuable context by disclosing that no token is required, and explains what a successful response means for diagnosing WOODPECKER_URL versus WOODPECKER_TOKEN issues. This goes beyond the structured annotations without contradicting them.

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

  Conciseness5/5

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

  Two sentences carry all necessary information with no waste. The result payload is stated first, followed by the most important behavioral trait (no token required) and a compact diagnostic rule. Every sentence earns its place.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  The tool has no parameters and a provided output schema, so only usage context and behavioral traits need description. The description fully covers why and when to call it, including the anonymous-access detail and the diagnostic meaning of a successful response. Nothing important is missing.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  This tool has zero parameters, and the schema confirms that. No parameter explanation is needed, and the description appropriately focuses on the response and usage rather than inventing unnecessary parameter semantics.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description states a specific verb ('Returns') and precise resource ('Woodpecker version and whether the server reports itself healthy'). It clearly distinguishes this from the many sibling tools by naming exactly what information it provides.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  It explicitly identifies when to use this tool: 'Works without a token, which makes it the call to use when nothing else does.' It also explains the diagnostic interpretation of the result, giving an agent actionable guidance for choosing this tool in a troubleshooting workflow.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.