Oxyforge WordPress

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

With no annotations, the description carries the full disclosure burden. It usefully adds a rate limit ('one every few minutes per site') and a synchronous-sounding 'now', but says nothing about what is captured (files, database, config), where it is stored, whether it is retained or restorable, or what it costs. The auth nuance is delegated entirely to 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?

A single sentence is appropriately short and front-loads the verb. However the parenthesis 'account agent key that may make changes' is grammatically tangled and forces the reader to reparse it rather than reading cleanly as a rationale plus a rate limit.

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 no annotations, so the description should say something about the result of the backup (an identifier, a timestamp, a completion state) and about prerequisites. It covers the when and the throttling but leaves the return value and restore path unaddressed.

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 the site name and token parameters are already documented, including the oxa_ prefix and the fallback to an account agent key. The description adds only the vague parenthetical about the agent key and no format or sourcing 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: 'Take a backup of one of the account's sites now'. The action is unmistakable and clearly distinct from siblings like delete_site or create_site. The trailing parenthetical is muddled and slightly muddies an otherwise crisp statement.

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?

'before a risky change' gives a concrete trigger condition, and 'one every few minutes per site' gives an operational constraint that shapes how an agent should schedule calls. It doesn't name when not to use it or any alternative, but no sibling offers an equivalent capability.

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?

No annotations are provided, so the description must carry the full behavioral burden. It names the cache types but does not disclose side effects, scope of cache invalidation, reversibility, return behavior, or whether the operation affects other users or sites.

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

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

The description is a single efficient sentence with the action and trigger front-loaded. No words are wasted.

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 two-parameter tool with full schema documentation, the description is largely complete. It provides the when and what, though it could say more about the effect of clearing caches given that no annotations or output schema are 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?

Schema description coverage is 100%, with both parameters documented. The description adds no parameter-level meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb and resource: clear the page and object cache. It also adds a triggering condition ('if a change does not show'), which makes the tool's purpose immediately distinguishable from sibling site 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 clearly indicates when to use the tool: when a change does not appear. However, it gives no explicit exclusions or alternative remedies, so it falls short of the highest clarity for usage 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?

With no annotations, the description carries the full load and does well: it discloses that the site is temporary, that no account is required, and critically that the returned token is shown only once and must be saved. Missing are the site's lifetime before expiry and whether creation is rate-limited or quota-bound, which matter for a "temporary" resource.

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

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

Two tight sentences with no filler; the core capability and the security caveat about the one-time token are both front-loaded where an agent will see 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?

Because there is no output schema, the description's enumeration of return values (site name, token, visitor login, admin login, claim link) is genuinely load-bearing and it delivers it. The remaining gap is the unspecified lifetime of a "temporary" site, which an agent would need before advising a user.

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

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

Schema description coverage is 100%, so the schema already explains ref, name, title, and site_password in detail. The description adds only an indirect nod to the password ("password-protected") and does not elaborate on any parameter beyond that. 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 ("Create a new ... WordPress site") plus two distinguishing qualifiers: temporary and password-protected. It is unmistakable against siblings like get_site, list_sites, and delete_site.

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

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

"No account needed" gives useful context about prerequisites, but the description never states when to choose this over alternatives or what happens afterward (e.g. that delete_site or get_site would be the follow-up tools). Usage is implied by the unambiguous create verb 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?

destructiveHint=true already flags the safety profile, so the bar is lower. The description does add a useful constraint beyond annotations — the operation is limited to three wp-content subdirectories — but it omits whether deleting a folder is recursive, whether deletion is reversible/backed up, and whether permissions are required.

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 scope restriction is stated immediately. It is arguably too terse for a destructive tool rather than too long, but structurally sound.

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, no-output-schema tool with an undocumented path parameter, the description leaves out recursion behavior, irreversibility, error cases, and format of path. What exists is accurate but insufficient to safely invoke the tool on the first try.

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 67%: site and token are documented in the schema, but the critical 'path' parameter has no description anywhere. The description mentions directory scope but does not say whether path is relative to the site root, absolute, or what format it takes, so it fails to fill the gap.

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

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

States a specific verb (delete) and resource (file or folder) plus the allowed scope under wp-content/themes, plugins or uploads. That scope sentence separates it from write_file/read_files siblings, though it never names those alternatives 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?

No guidance on when to delete vs. overwrite with write_file, no mention of prerequisites, confirmation steps, or what to do if the path is a theme/plugin root. The agent must infer all usage context from the one scope sentence.

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 irreversibility is partly covered; the description reinforces it with 'Cannot be undone' and adds genuinely new behavioral context in the form of the unclaimed-site precondition, which will cause the call to fail if violated. It stops short of stating the failure mode, required permissions, or the role of the token parameter.

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 applicability constraint front-loaded ahead of the irreversibility warning. Nothing here could be cut without losing meaning.

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

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

For a two-parameter destructive tool with full schema coverage, an explicit destructive annotation, and no output schema, the description covers the essentials: what it removes, the precondition, and irreversibility. Only the failure behavior and auth/permission expectations are 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% – both site and token are documented in the schema, including where the value comes from and the account-agent-key case. The description adds no parameter-level information 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 (delete) and resource (site) with an added scope constraint: only sites nobody has claimed yet. Clear enough to distinguish from delete_file in the sibling list, though it does not name or contrast any 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?

The phrase 'nobody has claimed yet' implies a precondition and thus implicitly tells the agent when this tool is applicable. However, it offers no guidance on what to do for claimed sites (get_site? another tool?) and no alternatives are mentioned.

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 this as a safe read operation. The description adds useful context by naming the specific fields returned, but it does not mention error behavior, authentication needs, or whether all fields are always returned.

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

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

The description is a single, dense sentence fragment that efficiently enumerates the returned information. It is appropriately sized and front-loads the most important status fields, though the lack of a verb makes it slightly less structured.

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

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

For a simple read-only tool with fully described parameters and no output schema, the description is nearly complete because it lists the returned fields. It only lacks explicit usage guidance and error behavior, which are minor gaps for this straightforward status 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 the site and token parameters are fully documented in the schema. The description adds no parameter-level detail beyond what the schema provides, which is the expected baseline when schema coverage is complete.

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

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

The description clearly identifies the resource as a single site and enumerates the status/details it returns (state, address, logins, claim link, clocks). It does not include an explicit verb or distinguish itself from siblings such as list_sites, but the singular 'of a site' and detailed fields make the intent clear.

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 explicit guidance on when to use this tool versus list_sites or create_site. The schema mentions that the site name comes from create_site or list_sites, but the description itself provides no usage context or alternatives.

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

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

Annotations already declare readOnlyHint=true, and the description is consistent with that. It adds real value beyond the annotations by disclosing the auth path for obtaining the key and warning that the response states whether the key may make changes, which signals permission scoping in the result.

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

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

Two short sentences with no filler, and the auth requirement is parenthetically tucked in without derailing the main scope statement. The awkward inline URL and the noun-fragment opening keep it from being a 5.

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 full schema coverage and no output schema, the description covers scope, auth requirements, and what the response conveys about key permissions. 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 token parameter is well documented in the schema itself, including when to omit it. The description adds no further meaning about the token, 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?

The description identifies the resource (sites) and constrains scope to 'the Oxyforge account this connection belongs to', which separates it from the singular get_site. It lacks an explicit verb and never names get_site as the narrower alternative, so sibling differentiation is implied by scope rather than stated.

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

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

It gives an authentication prerequisite ('needs an account agent key, made in the members area under Connect MCP') but never says when to call this versus get_site or the other site-scoped siblings. The usage context is implied by the listing nature of the tool rather than spelled out.

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

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

With no annotations, the description does real work: it discloses single-use semantics, a five-minute expiry, and that the browser additionally demands the visitor login first — the three traits that matter most for a credential-minting tool. Still missing is whether any specific role/permission is needed to mint the link and precisely what the caller receives back.

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 core behavior and the lifetime, then the authentication caveat. No filler, nothing repeated from 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?

For a two-parameter tool with full schema coverage and no annotations this is adequate, but the description never says what actually comes back (a URL string? a link object?) and there is no output schema to fall back on, so the return shape is left to inference.

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

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

Schema coverage is 100% and the schema already explains both `site` (from create_site or list_sites) and `token` (oxa_..., omit when connected via account agent key). The description adds nothing about either parameter, 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?

It states specifically that the tool mints a one-use link into wp-admin, with a five-minute lifetime, which no sibling tool does. It's a noun phrase rather than a verb ('generate a login link'), but the resource and scope are unmistakable and clearly distinct from get_site/list_sites/run_wp_cli.

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 purpose implies when to use it (you need browser admin access to a site), but there is no explicit when-to-use, no exclusion, and no pointer to an alternative such as run_wp_cli for scripted admin work. 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?

readOnlyHint=true already tells the agent this is a safe read, and the description usefully adds the directory-scope constraint (themes, plugins, uploads). It does not disclose truncation/size limits for large files, recursion behavior for listings, or error behavior on a missing path — meaningful gaps for a file reader.

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 zero waste; the mode-selection rule is embedded where it is most needed, at the point the path is described.

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 3-parameter read tool with no output schema, the core is covered, but the description says nothing about what a listing returns or how file contents are returned/limited. The dual-mode nature of the tool warrants at least one sentence on output shape or truncation.

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 beyond the schema examples by explaining that a folder path lacks a file extension while a file path has one, which clarifies how the 'path' parameter drives tool mode rather than just duplicating the example strings.

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 two specific verbs (list, read) on a specific resource (files/folders) and explicitly restricts the scope to wp-content/themes, plugins or uploads. The sibling names (write_file, delete_file) are not referenced, so differentiation is by implication rather than statement.

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 '(a path without a file extension)' gives a usable rule for choosing between the list and read modes, which is the main ambiguity. It never says when to use this over read-alternatives or when-not to use it, and no prerequisites (e.g. site/token pairing) are mentioned.

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

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

With no annotations, the description must carry the behavioral burden; it does disclose that several subcommands are unavailable and how stdin is consumed. It does not state that commands can mutate or destroy site data, whether output is returned raw or truncated, or how errors/exit codes are surfaced — significant gaps for an arbitrary command-execution 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 core action and immediately followed by the format example and the stdin tip. The prohibited-command caveat could arguably come earlier, but 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 tool with no output schema and no annotations, the description should explain what comes back (raw stdout? porcelain output? error shape) and any safety expectations. It covers input format well but leaves the agent guessing about return values and failure behavior on a powerful execution 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%, so baseline would be 3, but the description adds real value: a full example command line demonstrating the expected string format and an explicit note that stdin is used for long content with "-" as the file argument. That meaningfully supplements the terse schema descriptions.

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

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

States a specific verb and resource (run one WP-CLI command on the site) and clarifies the argument format with a concrete example. It is clearly distinguishable from siblings like write_file, read_files, or get_site, which operate on files or site metadata rather than arbitrary CLI commands.

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 useful invocation guidance (omit the leading "wp", put long content in stdin and use "-") and rules out eval, shell, and db import/export. However, it gives no guidance on when to prefer this over siblings such as write_file/read_files for content changes, nor any caution about command scope or irreversibility.

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

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

With no annotations, the description carries the full burden and does disclose key traits: the operation overwrites ('replace'), intermediate folders are created implicitly, and there is a 25 MB payload ceiling. It does not mention permission requirements, whether a prior file version is recoverable, or what is returned after a successful 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 sentences, front-loaded with verb, resource and allowed roots, then the example, then the payload rules. No filler and no 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?

For a mutating file-write tool with no annotations and no output schema, the description covers scope, path rules, payload formats and limits. The remaining gap is the post-write contract — what the tool returns or how to verify the result — which an agent would otherwise have to discover.

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 60% and the two undocumented parameters (content, content_base64) are precisely the ones the description explains, including mutual exclusivity of text vs binary and the size limit. It adds little for site/token, but those are already described in the schema.

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

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

States a concrete verb pair ('Create or replace') plus the resource ('a file') and bounds the write to three top-level directories, with a concrete example path. This is unmistakably distinct from siblings like read_files and delete_file without needing to name them.

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 clear operative guidance on which parameter to use (content for text, content_base64 for binary) and the 25 MB cap, plus the note that folders are auto-created. It stops short of explicit exclusions or naming an alternative tool (e.g., when to prefer run_wp_cli for file changes).

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