SpinupWP MCP by usefulapi

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

Goes well beyond the annotations: it discloses the async execution model, the return value (event_id), and the latency caveat ('can take a while on big sites'), which lets the agent plan around polling spinupwp_get_event. It also spells out exactly what gets mutated (permissions and ownership), consistent with 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?

Front-loads the WRITE marker and the core action, then layers the caveat and async contract in two tight sentences. The trailing REST path (POST /sites/{id}/file-permissions/correct) is somewhat redundant for an agent but is short and does not bloat the 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?

With no output schema, the description correctly compensates by stating that an event_id is returned. Combined with the async note, latency warning, and mutation scope, an agent has everything needed to invoke and follow up on this 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?

Only one parameter (site_id) and schema description coverage is 100%, so the schema already documents it fully. The description adds no syntax, format, or constraint detail beyond what the schema provides, making 3 the appropriate 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 ('reset a site's files and folders to the permissions and ownership SpinupWP recommends') and leads with a WRITE marker. No sibling tool touches file permissions, so it is trivially distinguishable from deploy/restart/purge siblings.

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

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

Gives a concrete trigger condition ('usually after a manual upload as the wrong user'), which tells the agent when this tool is the right call. It stops short of naming an alternative or stating when not to use it, so it is clear context rather than full routing 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?

Goes well beyond the annotations by disclosing that live site files change, that build/migration commands may run, the git-connected precondition for failure, and the asynchronous event_id return contract. This is exactly the extra context an agent needs for a destructive, non-idempotent write that annotations alone only flag as dangerous.

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, front-loaded with the 'WRITE:' marker and the mutation warning, followed by the failure condition, async contract, and endpoint. 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?

With only one parameter at full schema coverage and no output schema, the description supplies everything else the agent needs: destructiveness, side effects, failure precondition, and the event_id return that pairs with spinupwp_get_event. 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% and the single site_id parameter is fully documented in the schema, so the baseline is 3. The description adds only the qualifier that the site must have git connected, which is useful but marginal beyond the schema text.

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: pull the site's connected git branch and run its deploy script on the server. No sibling tool performs a git deploy, and the 'WRITE:' prefix plus the endpoint make the operation unambiguous 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 precondition for invocation — the site must have git connected, otherwise it fails — which tells the agent when this call is viable. It does not name an explicit alternative or when-not-to-use case, but no sibling tool offers a comparable deploy action, so the gap is minor.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, openWorld), so the bar is lower; the description adds real value by disclosing the async polling pattern – that this endpoint is how you resolve a write tool's returned event_id and that output includes command output as well as status.

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

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

Two compact sentences, front-loaded with what the tool returns and then the usage motivation, ending with the literal endpoint for orientation. 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?

With no output schema, the description carries the return-value burden and does name the key fields (status, command output). It does not enumerate possible status values or note whether results are retained/expire, which is a minor gap for a polling 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 single event_id parameter is already documented with its origin ('the event_id a write tool returned'). The description adds no format or constraint detail beyond that, 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 ('One event by id') plus what is returned ('status and command output'), which cleanly separates it from spinupwp_list_events without the agent needing to open 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?

Gives a concrete when-to-use scenario: checking whether a purge, restart or deploy has finished or failed, and notes that those write tools return an event_id. It stops short of stating when to prefer spinupwp_list_events (browsing/history) instead.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false, so the safety profile is covered. The description adds that reboot/upgrade-required flags and install notes are part of the payload, useful extra context, but nothing about auth, rate limits, or error 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?

Two compact fragments, resource first then endpoint, with zero filler. The most decision-relevant information leads.

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

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

For a one-parameter read tool with annotations covering safety and no output schema, the description tells the agent what it gets back and where the id comes from. The explicit surfacing of returned fields partly compensates for the absent output schema; only the return shape's detail is thin.

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 is fully documented in the schema, including the cross-reference to spinupwp_list_servers. The description adds no format or validation 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 (get) and resource (one server) and enumerates the fields returned, which helps distinguish it from spinupwp_list_servers. It does not explicitly name the sibling alternative, so it stops short of a 5.

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

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

The id's provenance is given ('from spinupwp_list_servers'), which implies the correct workflow, but there is no explicit when-to-use statement versus spinupwp_list_servers or a note that this is the single-resource counterpart to the list call.

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 a safe read, so the description's value-add is the payload disclosure and the explicit note that the git deploy-trigger URL is hidden — a non-obvious truncation an agent would otherwise assume was present. It does not cover auth requirements or failure behavior (e.g. unknown id), keeping it 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?

Front-loaded with the core action and the return-shape summary, then the endpoint, with no filler sentences. The field enumeration is long but earns its place as the substitute for a missing output schema.

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

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

With no output schema, the description carries the full burden of describing the return value, and it does so field by field while flagging the one field that is omitted. For a single-record read tool with one required parameter, nothing an agent needs in order 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%, and the single site_id parameter is already documented with its provenance in the schema, so the baseline is 3. The description adds no format or constraint detail beyond what the schema states.

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 — fetch one site by id — and immediately scopes it as the single-record counterpart to the list tool by enumerating the full settings payload. An agent can distinguish it from spinupwp_list_sites or spinupwp_get_server 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?

Usage is implied (call this when you need the detail record for a known site id) but the description never states when to use it versus spinupwp_list_sites or the narrower list_site_domains/list_site_path_redirects siblings. No prerequisites or exclusions are given; the only routing hint, the id source, lives in the schema, not the description.

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, destructiveHint=false and openWorldHint=true, so the description's lower bar is met and exceeded by adding two behaviors not in the structured data: long command output is truncated, and a full detail read lives elsewhere. It also enumerates the status lifecycle, useful for interpreting results.

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 plus the endpoint path, with the resource, payload fields and truncation caveat all front-loaded. No filler or repetition of the title.

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

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

With no output schema, the description carries the return-shape burden and does so adequately by naming the fields returned (actor, status, timestamps) and the truncation behavior; pagination is covered by the schema. Only minor gaps remain, such as ordering or default recency window.

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

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

Schema description coverage is 100% and both parameters (page, limit) are fully documented in the schema, including the 'Pass the previous reply's next_page' guidance. The description adds no parameter-level detail, so the baseline of 3 applies.

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

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

Specific verb+resource with the content spelled out: 'List recent events (the activity log: provisioning, restarts, deploys, cache purges)'. It distinguishes itself from the sibling spinupwp_get_event by noting that detailed output belongs there.

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?

'read one event for its full output' explicitly routes the agent to spinupwp_get_event when full command output is needed, which is the key alternative. No explicit when-not conditions or other exclusions are given, but the primary disambiguation is present.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuine value beyond that by naming the endpoint (GET /servers) and disclosing the return payload, including actionable state flags such as reboot/upgrade required and connection status.

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 covering scope, fields and endpoint, with no wasted prose. The long field enumeration is dense but each item is informative, so it 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?

There is no output schema, so the description carries the burden of describing return values — and it does so by enumerating the server attributes. Pagination behavior is left entirely to the schema, which handles it well, so nothing critical is missing for a simple read-only list tool.

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

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

Schema description coverage is 100%, so both pagination parameters (page, limit) are fully documented in the schema with defaults and ranges. The description adds nothing beyond that, which is the expected baseline when the schema does the work.

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 ('List') and resource ('servers in your SpinupWP team'), and enumerates the returned fields, which cleanly separates it from spinupwp_get_server (single server) and spinupwp_list_sites. An agent can identify the tool's 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?

Usage is implied by the scope — it is the bulk-listing counterpart to get_server — but the description never states when to prefer this tool over get_server or list_sites, nor any prerequisite. Adequate but implicit only.

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, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds value by enumerating the returned redirect settings and giving the underlying REST endpoint, but says nothing about pagination behavior, ordering, or whether the primary domain is included. Adequate, not rich, given the annotations already carry the safety burden.

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, front-loaded sentences with zero filler: the resource and its payload come first, the endpoint trails as a compact identifier. Nothing could be removed without losing 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 read-only list tool with full schema coverage and no output schema, the description compensates by naming the fields returned (enabled, type, destination), which the agent would otherwise have to discover at runtime. It omits edge cases such as empty results or whether redirects apply to the primary domain, 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% – site_id, page and limit are each documented in the schema, including the 'pass the previous reply's next_page' chaining hint. The description adds no parameter-level detail, so the baseline of 3 is correct.

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

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

States a specific resource (the additional domains of a site) and discloses what each entry carries (redirect settings: enabled, type, destination). The word 'additional' usefully distinguishes the scope from a site's primary domain. It does not explicitly name or contrast with the close sibling spinupwp_list_site_path_redirects, so it falls short of a 5.

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

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

The description explains what will be returned but gives no when-to-use guidance, no exclusions, and does not point to spinupwp_list_site_path_redirects or spinupwp_get_site as alternatives. The agent must infer the use case purely from the name.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered by structured data. The description adds the concrete GET endpoint and the shape of returned items, which is useful, but says nothing about pagination behavior even though page/limit parameters 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?

Two short sentences with the resource and its fields front-loaded and no filler. Efficient, though the parenthetical overlaps with information better suited to, and indeed present in, the schema.

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

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

With no output schema, the description partially compensates by naming the fields returned, and the annotations carry the safety profile while the schema carries pagination. A brief note on pagination ordering or result count 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%, so site_id, page, and limit are all documented in the schema itself, making this the baseline 3. The description's field list (from, to, type) refers to returned data rather than adding meaning to the input parameters.

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

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

The description names the specific resource (path redirects configured on a site) and even enumerates the distinguishing fields (from, to, type permanent/redirect). No sibling tool covers redirects, so differentiation is easy, but the description itself uses a noun phrase rather than an explicit verb (the 'list' action lives only in the name).

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?

There is no guidance on when to use this tool versus alternatives, no prerequisites, and no mention of the site_id requirement context. The endpoint path implies a read of a sub-resource, but usage conditions are left entirely 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 already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real value beyond that by disclosing that 'Deploy-trigger URLs are hidden' – a concrete note about what the response omits – which is non-obvious behavioral context.

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

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

Two compact sentences with the scope statement front-loaded. The field enumeration is long but earns its place since there is no output schema to convey the return shape.

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

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

With no output schema, the description usefully lists returned fields and notes the hidden deploy-trigger URLs, and the schema fully covers pagination and filtering. It is complete enough for an agent to call correctly, with only pagination behavior (beyond the schema) left implicit.

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

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

Schema description coverage is 100%, so all three parameters (page, limit, server_id) are already fully documented in the schema. The description only loosely gestures at server scoping and adds no syntax or default details 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 and resource ('List sites') and immediately clarifies scope ('across your servers (or one server)'), which distinguishes it from the singular spinupwp_get_site sibling. It also enumerates the fields returned, so an agent knows exactly what it gets.

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

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

The parenthetical '(or one server)' implies the server_id filtering case, giving implied usage guidance. However, it never states when to use this tool versus spinupwp_get_site (single site) or spinupwp_list_site_domains, and there are no explicit exclusions.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the underlying endpoint (GET /storage-providers) and the returned fields (id, service, name), which is useful but limited context. Pagination behavior, which matters for a list tool, is not mentioned here.

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 plus the endpoint path. Very tight with no waste, though the trailing 'GET /storage-providers' is mildly redundant for an agent that cannot call the raw endpoint.

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

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

There is no output schema, so the description's enumeration of returned fields (id, service, name) usefully fills that gap. Pagination is fully specified in the schema, so a simple read-only list tool is adequately covered, though the connection between paging and the response could be clearer.

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 page and limit are fully documented in the schema; baseline 3 applies. The description adds nothing about the parameters, and the '(id, service, name)' list refers to response fields rather than inputs.

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

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

The description names the specific resource ('backup storage providers connected to the team'), and combined with the tool name/title the list action is unambiguous. It is clearly distinguishable from all siblings, none of which touch storage providers, though the verb 'list' itself lives in the name/title rather than the description text.

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?

There is no when-to-use guidance and no alternatives or exclusions mentioned. The agent must infer usage purely from the resource name.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered by structured data. The description adds that only public keys are returned and the underlying endpoint, but doesn't cover pagination behavior for this list.

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 terse clauses front-load the resource and its returned fields, then add the public-key constraint and endpoint with zero waste.

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?

Complete for a paginated read-only list whose safety annotations and schema cover most needs. It could note pagination behavior, but the schema's next_page hint already handles that.

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?

Both parameters (page, limit) are fully documented in the schema, including defaults, ranges, and the next_page chaining hint. The description adds nothing beyond what the schema already provides, 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 (List) and resource (team SSH keys), and enumerates the returned fields (id, name, fingerprint, public key). No sibling tool lists SSH keys, so differentiation is inherent.

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 implied by the read-only list nature and the field list, but there is no explicit when-to-use or exclusion guidance. The 'Public keys only' note gives a light boundary on what data this covers.

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

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

Annotations already cover safety (readOnlyHint=false, destructiveHint=false, idempotentHint=true), but the description adds real value beyond them: the operation is asynchronous and returns an event_id, and 'the cache refills on demand' explains why the flush is non-destructive and effectively idempotent. It stops short of saying how to retrieve the returned event, which the sibling spinupwp_get_event would handle.

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

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

Three tight sentences: operation class and scope first, then the behavioral consequence, then the async return, closing with the endpoint. No filler and the most important constraint (write + precondition) is front-loaded.

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

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

There is no output schema, and the description compensates by naming the return value (event_id). The precondition and non-destructiveness are stated, so an agent can invoke it correctly. The only gap is not pointing at spinupwp_get_event for polling the async result, which would have made it self-sufficient end to end.

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 description coverage, the schema fully documents site_id ('SpinupWP site id.'), so the description carries no additional parameter burden. It adds nothing about site_id format or sourcing, which is the expected baseline at this coverage level.

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 ('flush') and precise resource ('Redis object cache of one site'), and the 'WRITE:' prefix flags the operation class immediately. The phrase 'object cache' also implicitly separates it from the sibling spinupwp_purge_page_cache, so an agent can distinguish the two 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 one useful precondition ('the site must have object caching'), which is genuine when-to-use context. However, it never contrasts with the adjacent spinupwp_purge_page_cache or explains when a purge is warranted versus not, so the alternative-selection guidance is only implied.

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 substantial value beyond the annotations: pages rebuild on next visit with transient slowness, 'nothing is lost' (reassuring on destructiveness), and it is asynchronous, returning an event_id. This is exactly the kind of consequence and return-shape disclosure the annotations cannot carry.

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

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

Three tight clauses plus the endpoint, front-loaded with the write indicator and verb. No sentence is wasted and the endpoint is a useful trailing detail.

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

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

Given a single-parameter mutation with no output schema, the description covers side effects, reversibility, async behavior, and the HTTP endpoint. An agent has everything needed to call and reason about the result.

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 well-described site_id parameter, so the schema does the heavy lifting. The description adds no syntax or format detail beyond what the schema already provides, 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 (purge) and resource (nginx page cache of one site), and the 'WRITE:' prefix immediately signals the operation class. It distinguishes itself from the sibling spinupwp_purge_object_cache by naming the page cache specifically.

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

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

The 'WRITE:' prefix and the scoping to 'one site' imply context, but there is no explicit when-to-use or when-not-to-use guidance, and it does not point to the object-cache sibling as an alternative. Usage is inferable but not 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 destructive=true, idempotent=false and readOnly=false, but the description adds operational context annotations cannot: all sites go offline for the duration (a minute or two), the call is asynchronous and returns an event_id, and the underlying endpoint. That is genuine added behavioral value beyond 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?

Front-loaded with the WRITE marker, then blast radius, then trigger condition, then async return and endpoint. Four tight clauses, no filler, 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?

No output schema exists, and the description compensates by disclosing the async event_id return. Downtime impact, trigger, idempotency and destructive nature are all covered, so an agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100% (server_id is documented as the SpinupWP server id), so the schema does the heavy lifting. The description adds no parameter-level detail such as accepted id ranges or sourcing the id from list_servers, 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 (reboot) and resource (a whole server) and scope ('whole server') that cleanly separates it from the sibling restart_nginx/restart_php/restart_mysql tools, which operate on individual services. An agent can tell exactly what this 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?

Gives an explicit trigger: use when spinupwp_get_server shows reboot_required, routing the agent to the sibling that produces the precondition. It stops short of naming when-not-to-use (e.g. prefer the service restart tools for service-level issues), but the 'whole server' scope carries that distinction implicitly.

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 destructive/non-idempotent/open-world, but the description adds concrete consequences: all sites on the server lose database access, running queries are interrupted, and the call is asynchronous returning an event_id. The event_id detail is especially valuable given there is no output 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?

Three tight sentences plus the endpoint; the write marker, effect, and async contract are all front-loaded 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?

For a single-parameter mutation with no output schema, the description supplies everything needed: the blast radius, the interruption of in-flight queries, the asynchronous event_id return, and the underlying endpoint.

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

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

Schema coverage is 100% and the schema documents server_id (positive integer), so baseline is 3. The phrase 'on one server' corroborates the single-server scoping 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+resource+scope: 'restart MySQL (database) on one server'. The 'WRITE:' prefix and the MySQL qualifier clearly separate it from sibling restart tools (restart_nginx, restart_php, restart_redis) without needing their schemas.

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

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

The description establishes the operational context (one server, brief DB outage) which implies a service is unhealthy, but it never states when to choose this over alternatives such as reboot_server or when DB access loss is unacceptable. Usage is implied rather than spelled out, and no exclusions are 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?

Annotations already declare destructive=true, idempotent=false, openWorld=true, so the safety profile is covered. The description adds value beyond them by disclosing the visitor-visible service interruption and the asynchronous contract (returns an event_id), which is exactly the kind of detail an agent needs before invoking a non-idempotent write.

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 WRITE designation and the core action, followed by impact and return behavior. No filler or restatement of the title.

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

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

For a single-parameter mutation with no output schema, the description covers the essential: what changes, side effects, and the async return. It omits any permission/auth prerequisite, a small gap given the destructive annotation, but nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100% and server_id is documented as a positive integer SpinupWP server id, so the schema carries the semantics. The description's path template reinforces which server is targeted but adds no new format or constraint detail.

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 (restart) and resource (nginx web server) scoped to one server, and the 'WRITE:' prefix plus the endpoint make the operation unambiguous. An agent can distinguish it from spinupwp_restart_mysql, spinupwp_restart_php, and spinupwp_restart_redis 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?

Usage is implied by the nature of the operation, and the 'on one server' scoping constrains it, but the description never says when to restart nginx versus rebooting the server (spinupwp_reboot_server) or correcting other service states. The interruption warning gives a reason to be cautious but not explicit 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 already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description still adds real value beyond them: it warns that in-flight PHP requests can fail or be cut off, and that the call is asynchronous returning an event_id. It stops short of stating permission/auth requirements.

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

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

Three tight sentences with zero filler: the WRITE marker and action are front-loaded, the risk note follows, and the async/endpoint detail closes. Every clause carries information an agent can act on.

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

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

There is no output schema, and the description compensates by explaining that the call returns an event_id, plus the HTTP endpoint used. For a one-parameter async mutation, nothing needed to invoke or follow up on it 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 server_id parameter is already documented as the SpinupWP server id in the schema. The description adds no additional parameter semantics such as id format or source, 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 (restart) plus resource (PHP-FPM) and scope (every PHP version, one server), which cleanly separates it from the sibling restart_nginx, restart_mysql, and restart_redis tools 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?

The 'WRITE:' marker and the async note imply when this is appropriate (a mutating, fire-and-forget operation), but there is no explicit when-to-use caveat, prerequisite, or guidance on choosing between this and related maintenance tools. Usage is inferable rather than stated.

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

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

Annotations already flag destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so safety is covered. The description adds genuinely new context: cached objects are lost and rebuilt on demand, and the call is asynchronous, returning an event_id rather than completing inline. That is valuable disclosure beyond the annotations.

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

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

Four short clauses, all front-loaded: write classification, action and scope, consequence, async return, and endpoint. No sentence is filler and nothing important is buried.

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 mutation with no output schema, the description covers the write nature, the side effect, the asynchronous return value (event_id), and the endpoint. An agent has everything needed to invoke it and handle the response.

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?

There is a single parameter with 100% schema description coverage, so the schema already documents server_id fully. The description only reinforces that the action targets one server and adds no format or constraint detail 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 (restart) and resource (Redis / object cache) scoped to one server, and the REST endpoint confirms the exact target. It is trivially distinguishable from sibling restart_mysql, restart_nginx, and restart_php tools.

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

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

The description implies the use case (cached objects are lost and rebuilt on demand), but never says when to prefer this over spinupwp_purge_object_cache or when a restart is actually warranted. Usage is inferable but not stated.

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