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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.