BunkerWeb MCP

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

With readOnlyHint=false the agent might assume a mutation, but the description usefully clarifies that no configuration changes occur; that is real context beyond the annotations. However, it says nothing about credential requirements, token lifetime, or rate limits, and it does not explain why a 'read-like' operation is flagged as non-read-only.

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; the token-returning behavior leads and the safety note follows. It is efficient, though the extreme brevity leaves obvious questions unaddressed.

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?

No output schema, three parameters, and no annotation detail about token semantics. An agent is not told where the returned token is used, its validity duration, or that credentials are mandatory despite zero required parameters.

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

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

Schema description coverage is 100% and each of the three parameters (payload, password, username) is documented in the schema, so the baseline of 3 applies. The description adds no extra meaning about how credentials are supplied or what payload does.

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 a new BunkerWeb API token.' No sibling tool competes for the authentication role, so the purpose is unambiguous, though it never names the credentials required to obtain the token.

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 no when-to-use context: it does not say the token is a prerequisite for the other API tools, nor when to re-authenticate versus reuse an existing token. The only guidance-adjacent statement is the negative claim about configuration.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false, so the description must carry most of the behavioral load. 'Acts on the instances immediately' usefully discloses timing/effect, but it does not say whether the ban persists across restarts or config reloads, what happens to already-established connections, or what the result looks like. Useful context, but significant gaps remain for a mutating 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, front-loaded with the action and scope, followed by the alternative and the effect. No wasted words or hedging.

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 required parameter whose nested fields are fully documented in the schema and with no output schema, the description covers action, scope, duration, and the inverse tool. The main omission is persistence/lifecycle behavior, which matters for a security-sensitive mutation.

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

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

Schema description coverage is 100%, so every parameter including exp, reason, and service is already documented in the schema; the description's 'for exp seconds (0 = permanent)' and 'globally or per service' largely restate that. It does confirm that 'one or more IPs' maps to the bans array, but adds no syntax or format detail 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?

States a specific verb and resource ('Ban one or more IPs'), plus the scope dimension ('globally or per service') and duration semantics. It is clearly distinguishable from the sibling unban_ip, which it names, and from list_bans.

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?

Names the inverse operation ('Use unban_ip to lift a ban') so the agent knows which sibling selects the opposite action, and 'Acts on the instances immediately' implies this is a live runtime action rather than a config edit. No explicit when-not guidance (e.g., checking list_bans first, or persistence vs. restart) is given.

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 destructiveHint annotation already declares the safety profile, yet the description adds two facts the annotations cannot: the work is queued for the scheduler and the tool cannot confirm execution. That async, fire-and-forget trait is critical for a destructive op. It stops short of stating permission prerequisites or whether a delete can be undone, keeping it below a 5.

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 padding, with the action front-loaded and the caveat and alternative packed into the remainder. 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 destructive, asynchronous bulk tool with fully described parameters and no output schema, the description covers the action, the sibling alternative, the regeneration path, and the inability to confirm success. Nothing an agent needs to call it correctly is missing.

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

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

The single top-level parameter is fully documented in the schema (coverage 100%), including nested keys cross-referenced to cache_list. The description adds no syntax or format detail beyond that, so the schema carries the load and baseline 3 applies.

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

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

States a specific verb and resource with explicit cardinality: 'Delete several job cache files.' It immediately distinguishes itself from the singular sibling by naming cache_delete_file, so an agent can pick between them without opening either schema.

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 routes single-file deletion to cache_delete_file and explains the recovery path ('jobs_run regenerates them'), which is exactly the context needed before invoking a destructive bulk operation. No ambiguity about when this tool versus its alternative applies.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description is not the sole carrier of the safety profile. It nonetheless adds information annotations cannot express: the deletion is queued for the scheduler and the tool cannot confirm execution, which changes how an agent should verify results. It stops short of stating permissions or whether a queued delete can be cancelled.

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

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

Three short sentences, front-loaded with the action, then the alternative, then the async caveat. No filler and every clause carries decision-relevant 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 4-parameter destructive tool with full schema coverage, no output schema, and existing destructive annotations, the description covers the remaining gaps an agent needs: sibling routing, regeneration semantics, and the fire-and-forget execution model.

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%, including per-field guidance pointing back to cache_list and the note that 'service' can be omitted for global. The description adds nothing about parameters beyond the schema, so baseline 3 is appropriate.

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

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

States a specific verb+resource with explicit cardinality: 'Delete one job cache file.' The word 'one' plus the sibling reference 'cache_delete_bulk' lets an agent distinguish this from the bulk variant without opening either schema.

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?

Directly names the alternative and the condition that selects it ('Use cache_delete_bulk for several'), and adds a decision-relevant fact ('jobs_run regenerates it') that tells the agent the deletion is not catastrophic. Both when-to-use and when-to-use-something-else are covered.

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?

readOnlyHint=true already covers the safety profile, and the description adds real behavioral detail beyond it: the return is printable text by default or base64 bytes when download=true. It does not cover error cases (missing file, permission) but adds substantive context.

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

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

Three short sentences, front-loaded with the action and the key semantics, with zero 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?

Read-only, no output schema, so the description carrying the return-value distinction (text vs base64) is exactly what's needed. Minor gaps around file-not-found behavior keep it from a 5.

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

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

Schema coverage is 100%, so baseline is 3, and the description reinforces the download flag's effect on return type beyond the schema wording. The plugin/service/job_name/file_name keying is only restated, so it doesn't lift this to 5.

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 ('Read one job cache file') and immediately scopes it against the listing sibling. An agent can distinguish it from cache_list and cache_delete_file from the description alone.

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 routes the agent to cache_list to discover file keys, which is the required prerequisite for all three required params. It does not spell out when-not to use it (e.g., it is not for jobs/configs), but the 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?

readOnlyHint=true already declares the safety profile, so the description only needs to add context. It does clarify these are job-run cache artifacts fetched by file, but it says nothing about result volume, ordering, or how with_data affects response size — the schema carries that instead.

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, purpose first and the sibling hand-off second. Nothing is redundant with the schema or the title, 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?

A read-only listing tool with full schema documentation and no output schema needs mainly to state scope and the read-a-file alternative, both of which are present. The remaining gap is how listing relates to deletion siblings and what a cached file represents across job runs.

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 both the filter semantics (including the 'global' nuance for service) and with_data are already documented. The description restates the filter axes (service, plugin, job) without adding format or interaction details, so baseline 3 applies.

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

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

States a specific verb and resource ('List files that scheduler jobs cached') plus the filter axes, so an agent knows exactly what it returns. It also names the sibling cache_fetch_file as the tool for reading a single file, cleanly separating the two.

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 routes content retrieval to cache_fetch_file ('use cache_fetch_file to read one file'), which is the main ambiguity for a listing tool. It gives no guidance on the other cache siblings (cache_delete_file, cache_delete_bulk) or on when the listing is empty versus erroring, so it falls short of full when/when-not coverage.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the mutation profile is known. The description adds genuinely non-obvious behavior: the snippet is only persisted and the scheduler applies it later, so the tool cannot confirm it is live — a critical expectation-setting detail for an async write. It does not cover permissions or duplicate-name handling, keeping it below 5.

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

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

Three short sentences, front-loaded with the core action, then the alternative, then the async caveat. No padding or restated name/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?

With a fully documented schema, annotations, and no output schema, the description covers the essential gaps: persistence vs. live application and the single-vs-bulk split. Minor omissions remain (duplicate name behavior, whether the return is the created snippet), but nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so all five parameters (including the service/global choice and is_draft) are already documented with formats and defaults. The description's 'from text' hints that data is inline content rather than a file path, but adds nothing about the individual parameters. Baseline 3 applies.

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

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

States a specific verb and resource with scope ('Create one custom config snippet from text') and immediately distinguishes it from the bulk sibling configs_upload. An agent can tell exactly which operation this performs without opening the schema.

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

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

Explicitly routes multi-file work to configs_upload ('Use configs_upload for several files'), giving a clear when-to-use-this-instead signal. It stops short of distinguishing create from the update siblings (config_update, config_upload_update), so the selection context is not fully closed.

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

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

Annotations already declare destructiveHint=true, but the description adds critical behavior the annotations cannot express: the deletion is persisted to the database and applied asynchronously by the scheduler, and the call cannot confirm liveness. That timing caveat materially changes how an agent should report results to a user.

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 action, the alternative routing, and the async caveat. Front-loaded with the core action and 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 destructive single-item mutation with no output schema, the description covers the essential concerns: specificity, the bulk alternative, and the deferred-application semantics. What remains unsaid (permission requirements, behavior on a non-existent snippet, error modes) is minor but not trivial.

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% – all three parameters carry their own descriptions including name format rules and the global-service convention. The description adds no parameter-level semantics beyond what the schema states, so the baseline 3 applies.

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

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

The description uses a specific verb and resource ('Delete one custom config snippet') and immediately scopes the cardinality to a single item, which distinguishes it from configs_delete_bulk. An agent can select it without opening the schema.

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

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

It names the explicit alternative for the multi-item case ('Use configs_delete_bulk for several'), giving clear routing guidance. It stops short of stating prerequisites or when-not conditions beyond the bulk case, so it is not a full 5.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds real context beyond that by stating the call returns the snippet's content (not just metadata), which is exactly what distinguishes it from the list sibling.

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 waste, with the core action and keying front-loaded and the alternative pointer trailing. Nothing to trim.

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 single-resource getter with fully documented params and annotations covering safety, the only real gap is not-found/error behavior. Since no output schema exists, the brief mention that content is returned is sufficient for an agent to call 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?

Schema description coverage is 100% — type enumerations, name format and the 'global' service convention are all documented in the schema itself. The description only restates the keying fields, adding no syntax or default behavior of its own.

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

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

Specific verb+resource: 'Read one custom config snippet with its content' keyed by service, type and name. It implicitly separates itself from global_config_read by saying 'custom config snippet', though it doesn't name that sibling explicitly.

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 routes discovery to configs_list ('Use configs_list to find snippets'), giving the agent a clear alternative for lookup vs. direct read. No explicit when-not conditions, but the intended workflow 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?

Goes beyond the annotations by disclosing that the delete is persisted to the database and only applied later by the scheduler, and that the tool cannot confirm the change is live. This is exactly the asynchronous caveat an agent needs before reporting success. It stops short of saying whether deletion is reversible or what happens if a listed snippet does not exist.

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 waste, with the scope stated first and the caveat last. Every sentence carries distinct information.

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

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

No output schema exists, so the description correctly signals that no liveness confirmation is returned, which is the key completeness concern for a destructive bulk call. What remains unaddressed is partial-failure semantics for a batch delete, a meaningful gap for an array-input destructive 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 coverage is 100% and the nested ConfigKeyParams fields (name, type, service) are fully documented inline, so the description adds little parameter detail. It frames the input as a list of snippets keyed by service/type/name, but does not state behavior for duplicate or unknown entries. Baseline 3 is appropriate when the schema does the heavy lifting.

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 with an explicit bulk scope ('Delete several custom config snippets in one call'), which distinguishes it from the singular sibling config_delete by name. An agent can tell exactly what it does without opening the schema.

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

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

Explicitly routes the agent: bulk use here, single deletion via config_delete. The alternative and the condition that selects it are both named, leaving nothing to inference.

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 readOnlyHint annotation already establishes that this is a safe read operation. The description adds that content can optionally be included, but it does not disclose further behavioral context such as default draft inclusion or pagination/return 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?

The description is two tight sentences with zero waste. It front-loads the listing purpose and immediately follows with the key alternative.

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 list tool with fully described parameters, the description is largely complete. It explains the return shape at a high level and when to prefer config_get, though it does not mention the with_drafts behavior that may matter to callers.

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 four parameters are already documented in the schema. The description mentions service, type, and optional content, but adds no syntax, defaults, or filtering details 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?

The description states a specific verb and resource: list custom config snippets. It names the relevant dimensions (service, type, name) and explicitly distinguishes the tool from config_get for full single-snippet reads.

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 a clear usage cue by directing users to config_get when reading one snippet in full, implying configs_list is for listing or metadata retrieval. It does not explicitly state when not to use the tool or mention other sibling alternatives, but the 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 declare destructiveHint=true and readOnlyHint=false, but the description adds genuinely new behavior: writes go to the database, the scheduler applies them later, and the tool cannot confirm the config is live. That deferred-application caveat is exactly the kind of context an agent needs. It stops short of stating what gets overwritten on a name collision, which matters given destructiveHint=true.

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 clauses with zero filler, and the core action plus the count/naming rule are front-loaded ahead of the alternative and the caveat. Every sentence carries distinct information.

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

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

For a batch upload tool with no output schema, it covers the essential gaps: multi-file semantics, naming, the text alternative, and the fact that success does not mean the config is live. Absent details about overwrite behavior and draft handling are the remaining minor holes.

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 schema already documents filename, content_base64, service, is_draft, and config_type. The description only reinforces the file-to-snippet naming relationship and the base64 requirement, adding little beyond the structured fields and never mentioning config_type or service scoping.

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+resource ('Create snippets from base64 files') plus the cardinality and naming rule ('one per file, named after the file'), and explicitly contrasts with the sibling config_create for text input. An agent can distinguish it from config_create, config_update, and config_upload_update without opening any schema.

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 routes text content to config_create, which is the most likely confusion point among siblings. It does not, however, address when to prefer config_upload_update or how this differs from config_update, so the guidance is clear but not exhaustive.

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 (readOnlyHint=false, destructiveHint=true), the description discloses the crucial asynchronous behavior: the change is saved to the database and the scheduler applies it later, so the tool cannot confirm the change is live. That is real value an agent cannot infer from the structured fields. It stops short of stating reversibility or permission requirements.

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

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

Two tight sentences with zero waste: operation and merge semantics first, sibling routing second. The important asynchronous caveat is packed into the same space without padding.

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 a fully described 8-parameter schema, no output schema, and destructive annotations, the description supplies exactly the missing pieces: the patch contract, the sibling alternative, and the eventual-consistency caveat. Nothing an agent needs to call this correctly is absent.

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

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

Schema description coverage is 100%, so every one of the 8 parameters is already documented, including the per-param 'omit to keep' note. The description's merge-semantics sentence restates that contract rather than adding new 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?

States a specific verb set (edit, rename, move) against a specific resource (one snippet, inline text) and explicitly separates itself from the file-based sibling config_upload_update. An agent can identify the operation and its scope without opening the schema.

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

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

Names the alternative for file uploads ('Use config_upload_update to send a file') and states the patch-style contract that omitted fields keep their value. It does not distinguish config_update from config_create or state any precondition around draft vs. live snippets, but the key sibling routing is explicit.

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

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

Annotations declare destructiveHint=true, and the description backs that up with the specific destructive side effect most agents would miss: omitting new_name silently renames the snippet from the file stem. It also discloses the persistence model (database write, scheduler applies later) and an explicit limitation (cannot confirm it is live), which no annotation conveys.

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 clauses, front-loaded with the action and the base64 requirement, followed by the alternative and then the persistence caveat. Telegraphic but every clause carries a distinct, load-bearing fact.

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 an eight-parameter destructive mutation with no output schema, the description covers the surprising side effect, the alternative tool, and the deferred-application model, which is what an agent most needs. It stops short of stating that the prior content is lost or whether type/service must match the existing snippet, leaving a small gap.

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

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

Schema description coverage is 100%, so all eight parameters, including the new_name rename behavior and the service/global default, are already documented in the schema. The description echoes the new_name trap for emphasis but adds no syntax or constraint beyond the structured fields, 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?

"Replace one snippet's content from a base64 file" gives a specific verb (replace), a scoped resource (one snippet's content), and the input medium (base64 file). The singular "one snippet" implicitly separates it from the bulk sibling configs_upload, and the next clause explicitly separates it from config_update.

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?

"Use config_update for text" names the primary alternative and the condition that selects it, which is exactly the routing decision an agent faces. It does not address when to prefer configs_upload (bulk) or config_create instead, so the alternative map is clear but not complete.

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

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

Beyond the annotations, the description discloses critical behavior: the change is saved to the database, applied asynchronously by the scheduler, and the tool cannot confirm the service is live. That async caveat is exactly the kind of context an agent needs for a mutation whose effect is delayed.

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

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

Three short sentences, front-loaded with the core action and followed by the deletion alternative and the async behavior caveat. Every sentence adds useful information with no 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 two-parameter mutation with no output schema, the description covers the essential semantics and the delayed-application caveat. Minor gaps remain, such as error behavior or permission requirements, but the core context needed to invoke it correctly is present.

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, but the description adds meaningful domain context by naming the two target states, online and draft, which the schema does not specify via enum or description. This helps the agent infer valid convert_to values.

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

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

The description uses a precise verb and resource: 'Switch a service between online and draft.' It also explicitly distinguishes the operation from deletion by naming delete_service, so an agent can tell this is a state-change tool, not a removal tool.

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 a clear when-to-use versus delete_service: use this to change state without deleting. However, it does not address update_service, another sibling that could plausibly overlap with changing service state, so the alternative guidance is incomplete.

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 a non-read-only, non-destructive write. The description adds genuinely useful behavior beyond that: the change is persisted to the database, the scheduler applies it asynchronously, and the tool cannot confirm the service is live. It doesn't mention validation of names, uniqueness, or what is returned, but the eventual-consistency caveat is the important disclosure an agent needs.

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 compact clauses, front-loaded with the action and followed by the alternative and the behavioral caveat. No sentence is redundant with another, and nothing is padded.

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 three-parameter create tool with annotations and no output schema, the description covers the action, the alternative, and the async persistence caveat. It leaves the return value (e.g., whether a created service identifier is returned) unstated, which is the only meaningful gap.

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

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

Schema description coverage is 100%, so all three parameters (including is_draft and variables) are already documented. The description only restates SERVER_NAME and refers vaguely to "optional settings" without adding semantics such as draft behavior or how variables are substituted. Baseline 3 is appropriate when the schema carries the parameter burden.

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

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

States a specific verb and resource ("Create a service") plus the key input (SERVER_NAME) and the optional-settings dimension. It also names the sibling that handles the mutation case, so the agent can separate create_service from update_service without inspecting either schema.

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?

"Use update_service to change one" gives an explicit alternative and the condition that selects it, which is the main routing ambiguity in this sibling cluster. It stops short of covering edge cases like when to use convert_service or is_draft instead, so it is clear context rather than exhaustive 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 destructiveHint=true, but the description adds genuinely new context: deletion wipes settings as well as the service, it is irreversible, the change is persisted and applied asynchronously by the scheduler, and the tool cannot confirm the outcome. The async/no-liveness-confirmation disclosure is the kind of trait annotations cannot 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 short clauses, zero filler, front-loaded with the action and its irreversibility before the alternative and the async caveat. Every sentence carries decision-relevant 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 one-param mutation with no output schema, the description covers danger, alternative, and execution model — nearly everything needed. The only small gap is return/error behavior (what happens if the service does not exist), which 'cannot confirm it is live' only partially implies.

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 a single parameter at 100% schema coverage, the schema already documents 'service' as the identifier to delete. The description adds nothing about format or resolution (name vs UUID) beyond the schema, so this sits at the baseline.

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

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

States a specific verb and resource ('Delete a service') and immediately scopes it ('and all its settings'), which distinguishes it from narrower siblings like instance_delete and plugin_delete. The contrast with convert_service makes the boundary 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?

Explicitly routes the agent to the alternative ('Use convert_service to take it offline') and encodes the when-not condition via 'not reversible' — an agent wanting a reversible takedown is steered away. This is exactly the when-to-use-vs-alternative guidance the dimension rewards.

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's 'read-only' claim is consistent with readOnlyHint=true and it enumerates what is inspected, which is useful. It does not disclose cost, latency, permission requirements, or what a failed vs. partially-failed check looks like, so it adds modest value over the annotation.

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

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

One front-loaded sentence with a compact enumeration of checks; nothing is wasted, though the trailing 'and optionally who owns a service's settings' is slightly buried for the only parameter-dependent behavior.

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

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

No output schema exists, so the description must imply the return shape, and it only lists topics checked rather than describing the report structure or what happens on partial failures. Adequate but not complete for a diagnostic entry point.

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 single optional 'service' parameter is fully documented there, so the schema carries the load. The description only hints at the extra behavior ('who owns a service's settings'), adding marginal detail 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?

States a specific verb (read-only check) and resource (connected BunkerWeb) and enumerates the dimensions checked: reachability, authentication, version, MULTISITE, instances, and service ownership. An agent understands the scope immediately, though it never distinguishes itself from siblings like health or ping.

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?

Usage is only implied — the breadth of checks suggests a first-line triage tool, but there is no explicit 'use this when X, use health/ping instead when Y' routing despite several overlapping diagnostic siblings (health, ping, instance_get).

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, so safety is covered. The description adds meaningful behavior beyond that with 'Cached up to 5 min', telling the agent results may be stale. It doesn't discuss auth requirements or error cases, but for a read-only lookup the cache disclosure is the key trait.

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 zero waste: core behavior first, then caching caveat, then sibling routing. Everything is front-loaded and each 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 read-only getter with no output schema and full schema documentation, the description supplies what structured fields cannot: sibling routing, the meaning of the full flag, and cache staleness. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, with all four parameters documented including the full/methods/with_drafts defaults, so the schema carries the semantics. The description restates only the full flag and adds no format details for the service identifier or methods/with_drafts beyond the schema. 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?

Names a specific verb and resource ('read one service's settings by ID') plus the scope modifier (full=true adds defaults), so an agent knows exactly what the tool returns. It is immediately distinguishable from list_services and global_config_read, which it names.

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 routes the agent: use list_services to find IDs and global_config_read for global settings. It also states the condition under which the full flag matters, leaving no alternatives to inference.

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

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

Annotations only declare readOnlyHint=true, so the description's added caveat that results may be cached up to 10 minutes is genuinely new and operationally important for a read tool — it tells the agent the data may be stale. It does not disclose anything about permissions or the shape of the returned settings, so it stops short of a 5.

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 compact clauses, front-loaded with the core action, then the caching caveat, then the alternative routing. Every sentence earns its place 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?

For a two-boolean read-only tool this covers the essentials: what it returns conceptually (global settings plus optional defaults), staleness (10-minute cache), and where to go for the narrower case. It does not describe the response structure, and with no output schema present that leaves a small gap, but not one that would cause a mis-call.

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 both parameters are already documented. The description restates full=true as adding defaults, which marginally reinforces the schema rather than adding new semantics, and it never mentions the methods parameter at all. Baseline 3 is appropriate.

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

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

States a specific verb and resource ("Read global settings") and immediately differentiates from the sibling get_service by naming it for the per-service case. An agent can pick between the two without opening either schema.

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 routes the agent to get_service when only one service's settings are needed, which is the primary confusion risk here. It stops short of stating when-not to use this tool (e.g., prefer config_get for individual config entries), so it is clear context rather than full when/when-not guidance.

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

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

Annotations only say readOnlyHint=false and destructiveHint=true; the description goes further by disclosing that other settings are preserved (merge, not replace), that changes persist to the database, and that the scheduler applies them later so liveness cannot be confirmed. That async caveat is exactly the kind of trait annotations cannot convey. Not a 5 because prerequisite permissions/validation behavior remain unstated.

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 compact clauses: what it does, which sibling to prefer, and the persistence/async caveat. 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 destructive, async-applied config mutation with no output schema, the description covers scope, merge behavior, persistence, and the delayed-application limitation. Minor gap: no statement about permissions or validation failures on bad keys.

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 single 'config' parameter is documented as flexible key-value pairs, so the schema already carries the weight. The description adds merge semantics ('other settings are kept'), which is genuinely useful, but adds no key naming or value-format guidance.

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 ('Set global settings from key-value pairs') and immediately distinguishes scope from the sibling 'update_service for one service'. An agent can pick between the two without opening either schema.

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 routes the agent to update_service when the change is scoped to a single service, which is the most likely confusion point among the large sibling set. It lacks an explicit 'when not to use' clause beyond that, 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 only declare readOnlyHint=true, so the description earns credit for disclosing that the probe 'does not contact instances' — a genuinely useful scope boundary that prevents misreading an all-healthy response as instance health. It stops short of describing what the response contains or failure semantics, which keeps it below 5.

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: the capability first, then the routing to alternatives. Zero filler and no repetition of the name or endpoint twice.

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 no-arg, read-only liveness probe with rich annotation and full schema coverage, the description covers purpose, scope, and sibling routing. The only gap is the shape of the result (e.g. status payload or degraded state), which there is no output schema to cover.

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 there is no parameter semantics to convey; the baseline for a no-param tool applies. Nothing in the description is needed to disambiguate arguments.

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 ('Read the API's own liveness probe') and anchors it to a concrete endpoint (GET /health). The scope qualifier 'its own' plus the sibling callouts make it unambiguously distinct from instances_ping_all and ping.

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 routes the agent: use instances_ping_all for instance reachability and diagnose for auth/version checks. Both alternatives are named with the condition that selects them, leaving nothing to inference.

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

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

Annotations only say readOnlyHint=false and destructiveHint=false. The description adds genuinely new behavioral context: the record is persisted to the database, the scheduler applies it asynchronously later, and the call cannot confirm the instance is live. That async/eventual-consistency caveat is exactly the kind of information an agent cannot get from structured fields.

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

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

Three short sentences, no filler: purpose first, alternative second, behavioral caveat last. Each sentence carries distinct information.

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

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

For a 7-parameter creation tool with no output schema, the description covers what is created, what happens to it, and the key limitation on confirmation. It does not indicate what the call returns (e.g. an id or the created record), which would help close the loop on a create operation.

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 seven parameters (hostname, port, server_name, listen_https, etc.) are already documented. The description adds no parameter-level meaning beyond the schema, which is acceptable at full coverage but merits only the baseline.

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

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

States a specific verb and resource ("Register a new instance for the scheduler to manage") and immediately differentiates it from instance_update. An agent can tell which sibling to pick without opening any schema.

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 routes modification cases to instance_update ("Use instance_update to change one"), giving a clear alternative for the adjacent operation. It stops short of stating preconditions or when-not-to-use cases (e.g. duplicate hostnames), so not a full 5.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is known; the description still adds real value by disclosing the asynchronous model ("Saved to the database; the scheduler applies it later") and its key limitation ("cannot confirm it is live"). It doesn't state any auth/permission requirements or what an error response looks like for a non-existent hostname, which keeps it below a 5 for a destructive mutation.

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 compact clauses, each load-bearing: what it does, how to handle multiples, and the async caveat. The primary effect and the host-keeps-running reassurance are front-loaded ahead of the routing hint.

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 destructive tool with no output schema, the description covers the essentials: effect scope, alternative for bulk, deferred application, and inability to verify liveness. The only meaningful gap is that the deferred-application warning doesn't say how to check whether the deletion actually took effect (e.g., via instance_get).

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% with a single required hostname already documented as "Instance hostname", so the schema carries the parameter burden. The description only indirectly enriches the parameter by implying the hostname must refer to a UI/API-registered instance rather than a file-declared one — a useful but thin addition over 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?

States a specific verb and resource ("Unregister one UI/API-registered instance") and immediately scopes the effect ("the host keeps running"), which separates it from instance_stop and instance_delete-adjacent siblings. The restriction to UI/API-registered instances further pins down which entities are eligible.

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 routes multi-delete traffic to instances_delete_bulk ("Use instances_delete_bulk for several"), giving a named alternative plus the condition that selects it. The "UI/API-registered" qualifier also implicitly excludes config-file-declared instances, so the agent knows the boundary of applicability.

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 this as a read-only operation. The description adds a useful behavioral detail not present in annotations: results may be cached for up to 60 seconds, which can affect freshness expectations.

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 three short sentences, front-loads the core action, then adds caching and sibling-usage guidance. There is no wasted text.

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 operation with readOnlyHint and full schema coverage, the description is nearly complete. It could say a little more about the fetched instance shape, but the core behavior and freshness caveat are covered.

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% for the single hostname parameter, so the schema already carries the parameter documentation. The description reinforces the hostname-based lookup but does not add syntax or format details 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: fetch one registered instance by hostname. It also names related tools, which helps distinguish this operation from listing instances or pinging reachability.

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 tells the agent how to obtain a hostname via list_instances and directs reachability testing to instance_ping. This gives clear routing guidance against the most relevant sibling 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 declare readOnlyHint=true, and the description adds the key behavioral distinction that this performs a live probe rather than reading cached state, which matters for latency and failure modes. It stops short of saying what a failed ping looks like or whether it can time out.

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, zero filler, with the primary action front-loaded and the disambiguation following. Every clause carries routing or scope 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 single-parameter read-only probe, the description covers what it does, how it differs from neighbors, and that the result is live. What a ping result contains (latency, success/failure) is left implicit since there is no output schema to lean on.

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?

One required parameter at 100% schema coverage, so the schema already defines hostname as 'Instance hostname'. The description's 'by hostname' restates the same idea and adds no format or resolution detail beyond the schema, making the baseline 3 appropriate.

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

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

States a specific verb ('ping'), scope ('one instance') and mode ('live by hostname'), which immediately separates it from the bulk and read-only siblings. An agent can pick this without opening any schema.

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 names two alternatives and the condition selecting each: instances_ping_all for every instance, instance_get for the stored record without pinging. The remaining case (live single-instance probe) is the implied default and 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?

Goes well beyond the destructiveHint=true annotation: it clarifies the hosts are NOT stopped, that the change is persisted to the database and applied asynchronously by the scheduler, and that the tool cannot confirm liveness. These are exactly the caveats an agent needs before calling a destructive bulk 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?

Three compact clauses, zero filler, with the destructive scope and the sibling alternative front-loaded before the caveats. Every sentence carries distinct information.

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

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

For a one-parameter destructive tool with no output schema, it covers effect (unregister), non-effect (hosts keep running), persistence/async semantics, verification limits, and the single-vs-bulk alternative. Nothing material 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% for the single `instances` array parameter, so the schema already documents it as hostnames to delete. The description adds only the quantifier "several" and the notion that entries are UI/API-registered, which is marginal beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ("Unregister several UI/API-registered instances") plus the crucial scope qualifier that the hosts keep running. This is immediately distinguishable from instance_delete and instance_stop, which are named or implied in the sibling 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?

Explicitly routes the agent: "Use instance_delete for one," which names the alternative and the condition that selects it. Combined with "several" in the opening clause, the bulk-vs-single decision is fully determined.

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 the description is consistent with that while adding real information: the ping is live (actual contact with hosts) rather than reading stored registration data. It does not cover latency, timeouts, or what an unreachable instance yields, which keeps it below a 5.

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, zero waste, with the core action front-loaded and the sibling disambiguation following. 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 zero-argument read-only tool with no output schema, 'report which answer' adequately signals the per-instance answer mapping. It stops short of describing timeout or partial-failure reporting, which is the only remaining gap.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to compensate for. No misleading parameter language is present.

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 (ping) and resource (every registered instance) plus the output intent (report which answer). It also distinguishes itself from two named siblings, so an agent can select it without opening any schema.

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 routes alternatives: instance_ping for a single host, list_instances for registration data without pinging. Both the when-to-use and the when-not-to-use conditions are stated.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is known; the description adds genuinely new consequence information (traffic stops until instances restart) and timing (acts immediately). It stops short of stating auth requirements, whether it fails partially, or how recovery is triggered beyond the word "restart."

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 clauses, zero filler, with the blast radius and the outage consequence front-loaded before the alternative-tool pointer. 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?

With no parameters and no output schema, and annotations covering the safety profile, the description supplies what an agent actually needs: scope, consequence, and the sibling alternative. Slightly thin only on partial-failure behavior and how instances are restarted.

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 there is no parameter meaning to convey and the baseline applies. The description correctly implies a global scope with no filtering options.

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 with an explicit scope qualifier ("Stop every registered instance") and immediately contrasts it with the single-host sibling. An agent can distinguish this from instance_stop without opening any schema.

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?

Names the alternative explicitly ("Use instance_stop for one host") and pairs it with the condition that selects it. That is the only realistic branching decision for this tool family, and it is stated outright.

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 is not read-only and is destructive, and the description adds useful behavioral context: the instance serves no traffic until restarted and the action is immediate. It does not describe confirmation, error behavior, or side effects beyond traffic loss, but it meaningfully improves on the annotations.

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

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

The description is compact and front-loaded: the main action and scope come first, followed by the sibling alternative and the immediate effect. 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 single-parameter destructive tool with annotations covering safety and a fully described schema, the description is largely complete: it names the impact and immediate behavior. It does not mention failure handling or restart expectations beyond traffic loss, but no major invocation gap remains.

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 hostname parameter is already documented. The description reinforces that the tool targets one instance by hostname but adds no format, validation, or example 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 states a specific verb and resource: stop one instance, scoped by hostname. It also explicitly distinguishes the single-instance action from the bulk sibling instances_stop_all, so an agent can select it without opening the schema.

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

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

It gives a clear usage condition by specifying one instance versus all instances and naming instances_stop_all for the bulk case. It does not discuss other nearby alternatives such as deletion or reload, but the primary routing guidance 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?

Adds real behavior beyond the annotations: the write is persisted to the database yet only applied later by the scheduler, and the tool cannot confirm the change is live. That async propagation caveat is exactly the kind of context annotations cannot express. It stops short of 5 because destructiveHint=true is left unqualified – no word on whether re-pointing ports/server_name breaks a running instance or whether the change is reversible.

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 waste, ordered by importance: what it does, the alternative, then the operational caveat. 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 7-parameter mutation with no output schema, the description covers the essentials an agent needs to call it safely: partial-update semantics and the fact that success is not immediately verifiable. Missing only permission/error expectations and any hint that the instance must already be registered, which the hostname description partially covers.

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 each property already carries an "omit to keep" description, so the description's patch-semantics line mostly restates what the schema documents. It adds no field-level meaning (e.g. what hostname keys on, or how port vs https_port interact), so baseline 3 applies.

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

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

States a specific verb and resource ("Change a registered instance") and immediately distinguishes it from the sibling creator ("Use instance_create for a new host"). An agent can tell update apart from create/delete/get without opening any schema.

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 routes new-host work to instance_create, and the patch semantics ("omitted fields keep their value") tell the agent it may send a partial payload. It gives no when-not guidance (e.g. use instance_get first to inspect current values, or that hostname must already exist), keeping it 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?

readOnlyHint=true already tells the agent this is a safe read, so the description's burden is lighter. It adds real context beyond the annotation: the listing includes run history and cache metadata, and that triggering jobs is a separate, write-gated action. It does not cover pagination or result volume, which keeps it below a 5.

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, zero filler, with the core purpose front-loaded and the sibling routing as follow-up. Every clause carries 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 zero-parameter read tool with no output schema, the description covers what the tool does, what comes back at a high level, and where to go for related operations. Only minor gaps remain, such as ordering or volume of the returned job 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?

The tool takes no parameters and the schema is empty, so there is nothing for the description to disambiguate. Baseline 4 applies; no parameter semantics are missing.

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 ("List scheduler jobs") and adds the payload scope ("with their run history and cache metadata"). It also names the sibling tools that cover adjacent tasks, so an agent can distinguish it from cache_list and jobs_run without opening any schema.

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 routes two common follow-on intents: use cache_list for the files the jobs wrote, and use jobs_run to trigger jobs (only when writes are enabled). That is clear positive guidance with a stated precondition, though there is no explicit statement of when not to use jobs_list.

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

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

Adds the single most important behavioral fact, which no annotation conveys: the trigger is queued for the scheduler and 'this tool cannot confirm it ran.' That tells the agent to poll jobs_list rather than treat a success response as execution. With readOnlyHint=false and destructiveHint=false, the safety profile is already covered by annotations, so this is pure added 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?

Three short sentences, zero waste, and the action is front-loaded before the alternative tool and the async caveat. Every sentence carries distinct information.

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

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

For a one-parameter async trigger tool with no output schema, the description covers what it does, when to call it, that it is fire-and-forget, and where to look for outcomes. Nothing an agent needs in order 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% and the single parameter (an array of JobDescriptor with plugin and informational name) is fully documented in the schema. The description only paraphrases it with 'one or more plugins', adding no format or cardinality detail beyond what the schema already states. Baseline 3 applies.

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

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

States a specific verb and resource: 'Trigger the jobs of one or more plugins.' It also names the sibling tool jobs_list for result checking and gives a concrete motivating example (cache_delete_file), so an agent can tell it apart from jobs_list without opening either schema.

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 a concrete usage cue ('e.g. after cache_delete_file') and explicitly routes result-checking to jobs_list. What is missing is any when-not guidance or prerequisite note (e.g. whether the plugin must already exist or be enabled).

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 readOnlyHint annotation already signals a safe read operation. The description adds useful behavioral context by disclosing that results may be cached up to 30 s and by explaining that the output contains exact IPs and services for unban_ip.

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 wasted text. The core purpose is front-loaded, followed by the cache caveat and the unban_ip connection.

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 with no parameters and no output schema, the description is complete enough: it covers scope, per-instance reporting, cache behavior, and the practical use of the returned IP/service data.

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 there are no parameter semantics to clarify. Per the baseline for a 0-parameter tool, this dimension scores 4.

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 ("List active IP bans") and adds scope ("as reported by each instance"). It also names the sibling tool unban_ip, which helps distinguish its role from related ban-management 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 usage context: the output provides the exact IPs and services needed for unban_ip when writes are enabled. It does not state explicit exclusions or when-not conditions, but the intended use case 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 declare readOnlyHint=true, so safety is covered by structured data. The description adds genuinely useful behavioral context with the 'cached up to 60 s' staleness window, which affects whether the agent can trust status freshness. It doesn't say whether auth is required or whether the list is paginated, so it is above baseline but not rich.

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 waste, with the core action front-loaded and the caveat and routing following in priority order.

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?

No output schema exists, yet the description discloses the key returned field (status) and the freshness caveat, which is sufficient for a zero-param list tool. Only the auth/permission expectation 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?

Zero parameters, so the baseline applies. The description still clarifies scope by saying 'every' instance, signaling there is no filtering or pagination knob to reach for.

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 ('List every registered BunkerWeb instance') plus the payload detail that matters ('with its status'). This is clearly distinguishable from instance_get and instances_ping_all, which it names.

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 routes the agent: 'Use instance_get for one host, instances_ping_all for live reachability.' Both the when-to-use and the alternatives are stated, leaving nothing to inference.

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 readOnlyHint annotation already declares this is a safe read, and the description adds a genuinely non-obvious behavioral trait: results may be cached for up to 5 minutes, which matters for freshness expectations. It stops short of describing ordering, size limits, or pagination of the result set.

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

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

Three short sentences with zero filler; the core purpose leads, the caching caveat and the sibling pointer follow in priority order.

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 annotation coverage and no output schema, the definition covers purpose, freshness, and the key alternative. A brief note on result shape or scale (how many services, whether unpaginated) would close the remaining gap.

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

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

Schema description coverage is 100% and the single boolean with_drafts is fully documented in the schema, so baseline 3 applies. The description adds no extra meaning about the parameter, such as whether drafts are excluded by default in downstream behavior.

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 ('List services') plus what is returned ('configuration and dates'), and explicitly contrasts with the sibling get_service for single-service detail. An agent can distinguish this from get_service without opening either schema.

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 routes the agent to get_service when one service's full detail is needed, which is a clear usage split. It does not state when to use list vs. other list siblings (e.g. configs_list) or how with_drafts should factor into the decision, so it falls just short of full when/when-not coverage.

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, so the safety profile is covered. The description adds useful scope information beyond that: it discloses that this call checks reachability only and does not verify authentication, version, or instances, which prevents an agent from over-reading a successful pong. A minimal note on timeout/error behavior would earn a 5.

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

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

Two short sentences, front-loaded with the action and endpoint, then the routing guidance. Every clause carries information; nothing is padding.

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

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

For a zero-parameter liveness probe, the description covers what it does, what response to expect, what it does not verify, and which sibling to use instead. No output schema exists, but the return value (pong) is stated inline, so nothing an agent needs is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. No misleading parameter claims are made.

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 ('Check that the BunkerWeb API answers'), names the exact endpoint (GET /ping), and gives the expected response (pong). An agent can distinguish it from diagnose without reading any schema.

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 says to use it as the fastest liveness probe and names the alternative, diagnose, together with what extra checks that alternative adds (authentication, version, instances). Both the when and the when-else are stated.

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

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

Annotations already declare destructiveHint=true, so the description does not waste words on that; instead it adds non-obvious behavior - the delete is persisted to the database and applied later by the scheduler, and the tool cannot confirm the plugin is actually stopped. This deferred/asynchronous consequence is exactly what annotations cannot 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 short clauses, front-loaded with the action and scope, then the lookup helper, then the behavioral caveat. No filler and no 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 single-parameter destructive tool with annotations covering the safety profile and no output schema, the description supplies everything needed: how to obtain the ID, what gets rejected, and the fact that success is not immediately verifiable.

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 single parameter already documents 'ID of a UI plugin, as returned by plugins_list type=ui'. The description largely restates that constraint, adding no syntax, format, or edge-case detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Uninstall one UI-installed plugin by ID') plus a scope restriction ('other plugins are refused'), which immediately separates it from plugins_upload and plugins_list. No ambiguity about what the tool does.

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

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

Explicitly names the prerequisite/alternative: 'Use plugins_list with type=ui to find IDs.' It also states an exclusion ('other plugins are refused'), so the agent knows both when to use it and when it will fail.

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?

readOnlyHint=true already declares the safety profile, so the description's burden is lighter. It adds a useful conditional note that the ui listing only maps to deletable IDs "when writes are enabled", but says nothing about the with_data payload cost or result size, which matters for a listing call that can embed archive data.

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?

One front-loaded sentence with no filler; the filter semantics come first and the cross-references follow. The trailing "use jobs_list for jobs" clause is slightly tangential but earns its place as disambiguation.

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, fully documented, read-only list tool with no output schema, this covers what an agent needs to invoke it correctly. Minor gaps remain around the shape/cost of results when with_data is true, but the schema carries the parameter meaning.

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 goes slightly beyond by giving type=ui a downstream meaning (IDs accepted by plugin_delete) rather than just an enum label. The with_data parameter is left entirely to the schema, which is acceptable given full coverage.

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

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

Specific verb+resource ("List installed plugins") plus the filter dimension (all, external, ui, pro). It also names the sibling it is not ("use jobs_list for jobs") and cross-references plugin_delete, so an agent can place it in the toolset without opening the schema.

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

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

Gives a concrete selection rule for the type parameter (type=ui → IDs accepted by plugin_delete when writes are enabled) and redirects to jobs_list for jobs. It lacks an explicit statement of when not to call it, but the routing context is clear enough to act on.

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

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

Annotations already declare destructiveHint=true, but the description adds critical context the annotations can't: the refusal on existing IDs, the asynchronous scheduler-based apply, and that the tool cannot confirm liveness. This is exactly the kind of operational nuance an agent needs beyond the safety 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 compact sentences, front-loaded with the action and the refusal behavior before the replacement guidance and async caveat. No filler or repetition.

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

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

For a write tool with no output schema, the description covers what gets written (database), when it takes effect (scheduler later), what it cannot confirm (liveness), and the replacement workflow. Nothing an agent needs to avoid a bad call 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% and both parameters (files, method) are fully documented in the schema, so the description correctly defers to it. It adds no parameter-level detail itself, which is acceptable at this coverage level, but it doesn't earn extra credit.

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 ('Install UI plugins from base64 archives') and immediately names a key constraint ('an existing plugin ID is refused'). An agent can distinguish this from plugins_list and plugin_delete without opening the schema.

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

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

Explicitly names the alternative path for replacement ('Use plugin_delete first to replace a UI plugin') and the condition that triggers it (existing plugin ID). It also notes the failure mode when the ID exists, so the agent knows when not to call it directly.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the risk profile is known. The description adds that the action 'acts on the instances immediately', implying no confirmation or undo step, but says nothing about service interruption, rollback on failure, or what changes if the test rejects the config.

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, front-loaded sentences with no filler, and the alternative is named before the caveat. Minor flaw: 'Acts on the instances immediately' uses a plural noun for a single-instance tool, which slightly muddies the scope it just established.

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 single-instance mutation with no output schema, the definition covers what it does and the sibling choice, but leaves out operational consequences an agent should weigh: service disruption during reload, what happens when the config test fails, and whether the previous config is retained.

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 'test' parameter already documents the non-dry-run semantics in detail. The description only echoes the default ('testing it first by default') and adds no syntax, format, or hostname-selection guidance beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('Reload configuration on one instance') plus the default behavior (test first), and explicitly contrasts with the sibling 'reload_instances'. An agent can pick between the singular and bulk tools without opening either schema.

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?

'Use reload_instances for all' names the alternative and the condition that selects it, giving clear scope guidance. It stops short of stating when a reload should be avoided (e.g. healthy instances or maintenance windows), so there is no explicit when-not.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is known. 'Acts on the instances immediately' adds useful context that there is no confirmation or preview step, but the description says nothing about rolling vs parallel execution, partial failure handling, or whether a failed reload leaves instances in a bad state — material for a destructive bulk 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?

Three short sentences with zero filler; scope, alternative, and immediacy are all front-loaded. Nothing is repeated or padded.

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 tool with no output schema and annotations covering destructiveness, the description covers scope, targeting, default behavior, and immediacy. The only gap is what happens on partial failure across many instances, which is secondary.

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 single test parameter is already fully documented, including the important 'not a dry run' caveat. The description only echoes the default, so baseline 3 applies.

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

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

States a specific verb (reload) and resource scope (every instance) and immediately distinguishes itself from the single-host sibling reload_instance. An agent can tell the two apart without opening either schema.

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?

'Use reload_instance for one host' names the alternative and the condition that selects it, giving a clear fan-out vs single-target rule. The default test-first behavior is also surfaced so the agent knows what happens without parameters.

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?

readOnlyHint=true already covers the safety profile, and the description adds that the search is remote/semantic and what each result contains (title, URL, category, relevance). However, an output schema exists, so the return-shape detail is largely redundant, and it says nothing about latency, result volume, or behavior when nothing matches (that tuning hint lives only in 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, purpose front-loaded, then return shape, then the routing rule. No filler and every clause carries 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?

With 5 params at full schema coverage, a readOnly annotation and an output schema, the description covers everything an agent still needs: what the search is, what it returns, and when to prefer the live-state API tools.

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%, including the purpose of query, limit, category, min_score and max_content_length, so the schema does the heavy lifting. The description adds no parameter-level guidance beyond implying natural-language queries and a category-ish result field.

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 ("Search the official BunkerWeb documentation") plus the mechanism (semantic / meaning-based, remote) and the unit of return (one titled section per document). It also explicitly distinguishes itself from the API tools that read live state, so an agent can separate documentation lookup from live-state calls at a glance.

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 a clear routing rule: how-to and setting questions go here, live-state questions go to the API tools. It stops short of naming which specific sibling to use for a given live-state need, but the boundary is unambiguous.

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

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

Annotations already flag this as a destructive, non-read-only mutation; the description adds the non-obvious behavioral fact that it 'Acts on the instances immediately', warning the agent that there is no staging or confirmation step. It leaves out error behavior for unknown or non-banned IPs and permission requirements, keeping it out of the top band.

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

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

Three short sentences, front-loaded with the action and scope, then the prerequisite, then the behavioral warning. Nothing is redundant and every sentence adds 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 destructive mutation with no output schema, the description covers what it does, what to do first, and that the effect is immediate. It could still say what happens on partial failures across the bans array or whether unbanning an already-unbanned IP is a no-op, but nothing essential is absent.

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 nested UnbanPayload already documents ip and service. The description only hints at semantics by saying 'globally or per service', loosely implying that omitting service means a global unban, but it never states that mapping explicitly. Baseline 3 applies when the schema carries the parameter burden.

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

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

States a specific verb and resource ('Lift bans for ... IPs') plus its scope ('globally or per service'), which clearly separates it from sibling tools like ban_ip and list_bans. It stops short of naming the inverse operation explicitly, but the resource-level precision is enough for an agent to pick it correctly.

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

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

'Use list_bans first to find them' gives an explicit prerequisite and points at the sibling that produces valid inputs. It does not state exclusions (e.g., when to use ban_ip instead), so it falls short of a full when/when-not statement.

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 this as a mutating, destructive tool, but the description adds genuinely non-obvious context: unknown or externally owned keys are skipped rather than erroring, the result is read back, and the write is persisted for a later scheduler pass without confirming it is live. The main omission is what happens when the service is missing and whether omitted fields are left untouched.

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 clauses with no filler; the skip behavior and the async-application caveat are both front-loaded where the agent will read them.

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?

No output schema exists, and the description tells the agent the result is read back after applying skips, which is the key return-value fact. Together with the destructive annotation, that covers nearly everything needed to call it correctly, missing only failure behavior for an invalid service.

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 each parameter is documented, including the skip-and-report semantics of 'variables'. The description mirrors rather than extends that, so it earns the baseline rather than more.

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 ('Change a service's settings') and immediately scopes it against a named sibling ('Use global_config_update for global settings'). An agent can distinguish this from global_config_update and config_update without opening a schema.

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 an explicit alternative for the adjacent case (global settings) and implies the per-service scope. It does not cover when-not-to-use cases such as a nonexistent service or what happens if the caller wants immediate effect, but the routing guidance is clear.

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