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

Annotations already cover the safety profile (readOnly=false, destructive=false, non-idempotent, open world), so the bar is lower. The description adds one real behavioral fact — posts/pages default to draft status — but omits permission requirements, whether the created resource is returned/identified, and failure 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 short sentences, front-loaded with purpose and followed by the one behavioral default. Nothing is redundant; the only weakness is that comparative brevity trades away detail an agent needs.

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 mutation tool with a nested free-form data object, no output schema, and an undocumented required resource parameter, the description covers the basics but leaves key gaps: valid resource identifiers, required vs optional fields, and any indication of what a successful call returns.

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 data are documented, while the required resource parameter has no description at all. The description partly compensates by listing plausible resource values (post/page, term, comment), but it does not say whether these are exact names or where to look them up, so the most important parameter remains ambiguous.

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 (Create) and enumerates resource families (post/page draft, term, comment), so an agent knows exactly what it produces. It also names the sibling it is not for (aism_media_upload for files), though the catch-all "another native resource" leaves the resource set partially open.

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

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

It provides one explicit routing rule — use aism_media_upload for files instead — which is genuinely useful. But it gives no guidance on choosing between create vs aism_content_update, or where valid resource names come from (aism_schema is only hinted at inside the data parameter description), leaving the primary selection decision 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?

Annotations already flag destructiveHint=true and idempotentHint=false, so the bar is lower; the description still adds real context beyond them — that deletion is a trash operation unless force=true, that some resource types require force, and that operator authorization is a precondition. It does not say whether trashed items are recoverable or what happens on failure.

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, front-loaded with the default trash behavior before the force override. Hedges like "when supported" and "generally" cost a little precision but no sentence is 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?

Adequate for a destructive 4-parameter tool whose annotations cover the safety profile, but an agent still lacks recoverability details, error behavior, and any indication of what the call returns, which matters for a delete 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 coverage is only 25%, but the description compensates for the most consequential parameter by explaining force=true's permanent-deletion effect and its resource-dependent requirement. The `id` and `resource` parameters receive no semantic explanation (e.g., valid resource names), leaving a 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 (trash/delete) with the key distinction between soft trash and permanent deletion via force. The resource is generic ("an object") and resolved only by the `resource` parameter, so the tool isn't sharply differentiated from aism_content_update without reading the schema, but the delete semantics are 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?

Gives useful conditional guidance (media and terms generally need force=true) and an authorization constraint, but never states when-not to use it or which sibling to prefer for retrieval/verification before deleting.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered. The description adds the useful context=edit distinction for raw vs. rendered fields, but says nothing about permissions, auth, or error behavior for cross-site reads.

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 action front-loaded and the context hint immediately after. 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?

There is no output schema, so the description could reasonably say more about what a returned object looks like or how the four resource types differ in shape. The nested query parameter also goes largely undescribed beyond 'raw fields'. Adequate but with real gaps for a 4-parameter 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 only 50%, but the description compensates partially: the resource list (content/media/term/comment) illustrates the values the undocumented 'resource' pattern accepts, and context=edit clarifies the nested query object. The 'id' and 'query' parameters remain largely unexplained 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 one') and enumerates the resource types it covers (content, media, term, comment), which distinguishes it from the list-oriented sibling aism_content_list. It stops short of naming that sibling or clarifying what 'resource' values are valid as strings.

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 context=edit for raw fields' gives one concrete usage condition, implying the default is a rendered/public view. However, there is no explicit guidance on when to use this versus aism_content_list or aism_schema, so selection still requires 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 readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds one genuinely useful behavioral fact ('Includes pagination headers'), but says nothing about pagination limits, default page size, or response shape.

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 core resource list front-loaded and no filler. The trailing 'Also supports types, taxonomies and statuses' is slightly vague but still informative.

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 rich annotations and no output schema, the description covers the resource universe and notes pagination headers. The main residual gap is that the free-form query object's supported keys and behaviors are left entirely to the schema.

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% and the required 'resource' parameter has no schema description, so the description's enumeration of resources is carrying real weight. However, the open-ended 'query' object (context, status, search, per_page, page, _fields) and the 'site' semantics get no elaboration 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 ('List/search') and enumerates exactly what resource values are accepted (posts, pages, media, terms, comments, custom). That makes it distinguishable from retrieval siblings like aism_content_get, though no sibling is named 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?

'List/search' implies the read-many use case, but there is no explicit guidance on when to use this versus aism_content_get, aism_discover, or aism_schema, and no stated prerequisites. Usage is inferable but not 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?

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, which is a large disclosure burden lifted off the description. The description's 'only supplied fields' line adds genuinely useful partial-mutation semantics, but it never mentions that unspecified fields are left intact versus overwritten-by-method, that changes are destructive, or anything about permissions or the POST/PUT/PATCH behavioral differences.

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 partial-update constraint is front-loaded ahead of the resource enumeration. Nothing redundant.

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, open-world, 5-parameter mutation tool with a nested free-form `data` object and no output schema, the description covers the resource surface but leaves the method choice, the meaning of destruction, and the required WordPress field set (deferred to aism_schema only via the schema, not the description) unaddressed. Adequate but with visible gaps.

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 40%, so the description should compensate more than it does. It does helpfully map the families accepted by the otherwise undescribed `resource` parameter (posts/pages, media, taxonomy, comments) and reinforces the partial `data` semantics that the schema already states, but `id`, `site`, and especially the `method` enum (POST default vs PUT vs PATCH) get no meaning from the description.

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

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

States a specific verb (update) plus the scope of editable resources (posts/pages, media alt text/caption, taxonomy relationships, comment moderation), so the agent can tell what class of operation this is. It does not explicitly differentiate itself from aism_content_create or aism_content_delete, but the verb-plus-resource phrasing is clear enough to avoid confusion.

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?

'Update only supplied fields' implies partial-update semantics and the resource list implies which resources are in scope, so usage is inferable. However there is no explicit when-to-use/when-not guidance, no pointer to aism_content_create for new content or aism_content_delete for removal, and no mention of when to prefer this over aism_schema for inspecting fields.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description's only added behavioral fact is the ordering requirement ("Call first"), which is useful but thin; it says nothing about auth requirements, whether the payload is cached, or how large it is.

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 sentence, no padding, and the actionable directive comes last in a natural reading order. It is efficient, though the compressed list of return categories verges on under-specification rather than crispness.

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 is the only place to explain the shape of a multi-part discovery payload (scopes/expiry, settings, limits), and it does so only as a bare list. For a "call first" orientation tool, an agent still lacks enough to interpret 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?

Schema coverage is 100% with a single optional parameter, so the schema fully documents `site` including omit-for-default semantics. The description adds nothing beyond it — "connected site" merely restates the concept, and it does not clarify whether the returned scopes/limits are site-specific.

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?

"Discover the connected site, key scopes/expiry, resources, approved settings and limits" names a resource and enumerates return categories, but the verb is generic and the listed items ("resources", "approved settings") are loose. It does not distinguish itself from the adjacent aism_sites or aism_guide, which likely overlap on site enumeration/introspection.

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?

"Call first" gives an explicit sequencing directive, which is real guidance. However, it does not say what to do with the result, when to skip it (e.g. if already discovered), or how it relates to aism_sites/aism_guide.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds only the word 'deployed', hinting the guide reflects the live site's state rather than generic docs—useful but thin; nothing about size, format, or whether the guide varies per site/version.

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 short sentence with no filler and the key information up front. It is efficient rather than padded; the only critique is that brevity here edges toward thinness.

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?

Low-complexity single-parameter read tool with no output schema, so the description needn't explain returns. However, it omits what the guide covers and whether output differs per site, leaving the agent with a minimal picture of what it will get back.

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 parameter is fully documented in the schema (name from aism_sites, omit for default). The description contributes nothing beyond that, which is acceptable at this coverage level but earns 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+resource: read the AI Site Manager usage guide for a deployed site. It is unambiguous and distinguishable from siblings like aism_schema (which presumably returns schema info) or aism_sites, though the description never names those alternatives to sharpen the distinction.

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 indication of when to reach for this tool versus aism_schema, aism_discover, or aism_sites. An agent must infer that a 'usage guide' is documentation-reading, and there is no guidance about prerequisites or typical triggering situations.

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 non-read-only, non-idempotent, non-destructive, open-world, so the safety profile is covered; the description adds genuinely new context by naming the required permission scope and pointing to host-enforced file-type/size rules. It still omits what the upload returns and what happens on success (attachment vs. library item).

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 the core action front-loaded and zero filler. Minor deduction: 'Host file-type/size rules' is terse enough to be ambiguous about what 'Host' refers to.

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 6-parameter mutation tool with low schema coverage and no output schema, the description covers the file-source and permission constraints but leaves parameter semantics and post-upload behavior undocumented. Adequate but with clear gaps an agent would hit when wiring up the 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 only 33% — post, title, caption, and alt_text have no descriptions anywhere. The description supplies no per-parameter meaning (e.g., that 'post' likely attaches the media to a content item, or what alt_text is used for), so it does not compensate for the coverage 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 and resource ('Upload a local file') and explicitly rules out the adjacent capability ('Does not download remote URLs'), which is the one real ambiguity an agent would have. It doesn't explicitly differentiate from the similarly named aism_plugin_upload / aism_theme_upload siblings, but 'media:write' signals the resource domain.

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?

Implies when to use it (you have a local file, not a URL) and names a prerequisite capability ('media:write apply'), but gives no explicit condition for choosing this over the other upload tools or guidance on when a media upload is the wrong approach.

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=true, openWorld=true, and idempotent=false, so the safety profile is covered. The description adds real value beyond that: it discloses what gets copied (dependencies), that IDs and URLs are remapped, and that re-copying updates prior copies. It stops short of warning about overwriting target content or what happens on a max_seconds timeout, which would be useful for a destructive 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?

Two dense sentences with no filler; the core action and its scope are front-loaded, and the re-copy behavior is appended efficiently. Nothing is 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 10-parameter, destructive, open-world migration tool with no output schema, the description covers what is copied but says nothing about what the call returns, how partial failures or timeouts are surfaced, or how it relates to aism_migration_status/rollback. It is adequate but leaves meaningful gaps for a complex 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 coverage is 90%, so nearly every parameter is already documented in the schema, making 3 the baseline. The description's mention of categories/tags, featured images, embedded media, and reusable blocks loosely corresponds to include_dependencies and the remapping behavior, but it adds no syntax or format detail beyond what the schema already 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 gives a precise verb and resource ('Copy selected posts/pages (any type) from one site to another') plus the full scope of what travels with them: terms, featured images, embedded media, reusable blocks, and ID/URL remapping. It is clearly distinguishable from siblings like aism_migration_export, aism_migration_plan, and aism_migration_run, which do not describe this copy-with-remap action.

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

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

The line 'Copying again updates the earlier copies' implies a re-run/iterative usage pattern, and the description gives a use case (moving content between sites). But it never says when to use this instead of aism_migration_plan, aism_migration_run, or aism_migration_transfer_package, so the agent must infer the routing from sibling names alone.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds that data is 'raw' (unprocessed export shape) and paginated ('one page'), but says nothing about rate limits, auth, or what a page contains. Adds some value beyond annotations, but not rich 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 sentences, front-loaded with the core action, and the parenthetical list earns its space by clarifying scope of the `posts` kind. No filler or restatement of the tool name.

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

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

There is no output schema, and the description does not describe the shape of a 'raw export page' or how pagination termination works, which are the main things an agent needs for a raw-paging inspection tool. Acceptable for routing, thin for correct invocation.

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

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

Schema description coverage is only 43%, and the schema itself documents only ids, site and modified_after. The description contributes real meaning for the `kind` enum (posts include attachments/menus/templates), but leaves page, per_page and post_type entirely unexplained, so it does not compensate for the coverage 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 and resource ('Read one raw export page from a site') and enumerates exactly what the four kinds cover, including that 'posts' spans attachments/menus/templates. It also names the siblings that do this automatically, so an agent can separate it from aism_migration_run/copy 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?

The phrase 'for inspection' plus the note that aism_migration_run and aism_migration_copy do this automatically makes the intended context clear: manual raw-data inspection, not bulk migration. It stops short of an explicit 'do not use this to migrate' exclusion, but the routing signal is strong.

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 read-only/idempotent/non-destructive profile, and the description adds two things they cannot: the required scope 'migration:read' and the companion version constraint (1.4.0+). Missing only notes on failure modes (e.g., unconfigured site) or whether it hits the remote site (relevant given openWorldHint=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?

One dense sentence that front-loads the action and the return payload, followed by a compact requirements clause. No filler, no restatement of the tool name.

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

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

With no output schema, the description usefully enumerates the manifest's fields so an agent knows what it gets back. Requirements (scope, companion version) are also covered. Slightly incomplete in that ordering/relationship to plan/export/run steps is left implicit.

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

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

Schema coverage is 100% and the single optional 'site' parameter is fully documented in the schema, including a reference to aism_sites and the default behavior when omitted. The description adds nothing parameter-specific, which is fine 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?

Specific verb + resource: 'Read a site's migration manifest', then enumerates exactly what the manifest contains (site UUID, URLs, versions, themes, plugins, content counts, capabilities, exclusions). This clearly distinguishes it from plan/status/export siblings by content. It stops short of naming a sibling explicitly, so a 4 rather than 5.

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

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

The description implies this is the inspection/introspection step of the migration workflow, but never says when to call it versus aism_migration_status or aism_migration_plan, nor any prerequisite ordering (e.g., run manifest before plan). 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, and the trailing 'Read-only' merely re-confirms them. The real added value is disclosing the scope of analysis the agent will receive — version comparison, dependency gaps, incompatible content types, prior-migration detection, and recommended steps — which tells the agent what a call actually yields. It stops short of covering cost, latency, or the fact that the target requires migration:write despite the read-only nature.

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: the action and scope come first, the enumerated checks follow, and the safety assertion closes it. Every clause carries information and there is no filler.

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

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

With no output schema, the description appropriately compensates by listing the categories of findings the agent will get back, including recommended steps, so the agent knows what to expect. It does not describe the report's shape or how findings are ordered, which is a minor residual gap for a discovery/reporting tool.

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

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

Schema description coverage is 100%, and the schema itself carries the important semantics: source vs target direction and the required scopes (migration:read for source, plus migration:write for target). The description adds no parameter-level detail beyond 'two configured sites'. Baseline 3 applies 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?

The description opens with a specific verb and object ('Compare two configured sites before migrating') and then enumerates exactly what dimensions are compared: versions, missing/outdated themes and plugins, unsupported post types and taxonomies, prior migration, and recommended steps. That is far more informative than a restated title. It does not, however, explicitly distinguish itself from close siblings like aism_migration_manifest or aism_migration_status, which is what keeps it from 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?

'before migrating' supplies a genuine timing cue that tells an agent when this tool belongs in a workflow. But no alternative tool is named and no exclusion is given — an agent still has to infer whether to call this versus aism_migration_manifest or aism_migration_status. Usage is implied rather than prescribed.

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 idempotentHint=false, yet the description adds real value: it names precisely what is destroyed, what is restored, that the ID map is forgotten, and what survives. It stops short of explaining failure/timeout behavior (max_seconds) or what happens if a rollback is interrupted.

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 dense sentences, front-loaded with the destructive action and its scope; the retention rule and permission requirement follow in priority order 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 destructive mutation with no output schema, the description covers the essential decision inputs: what gets deleted, what gets restored, what is preserved, and the required capability. The only gap, timeout semantics for max_seconds, is minor given 75% schema coverage.

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 75%, with source, target, and source_uuid documented in-schema; the description adds no parameter-level detail and never mentions max_seconds, which has no description at all. With the schema doing most of the work, 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 ('Undo a migration on the target') and enumerates the exact operations performed: deleting posts/media/terms/comments, restoring settings, forgetting the ID map. It is clearly the inverse of aism_migration_run, though no sibling is named 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 precondition ('Requires migration:delete on the target') and the retention rule ('Objects matched to pre-existing target content are kept') give useful context, but there is no explicit guidance on when to prefer this over alternatives (e.g. checking aism_migration_status first, or partial rollback limits).

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 and openWorld=true, yet the description adds real value beyond them: which state is overwritten (target settings and previously migrated objects), that re-runs update rather than duplicate, that ID remapping and URL rewriting occur in finalize, and that users are not created. The write profile is fully consistent with the destructive annotation; there is minor tension between 're-running updates instead of duplicating' and idempotentHint=false, but that reflects source drift rather than a real contradiction.

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 phase list, then the resumability contract, then the overwrite/incremental caveats. Sentences are long and packed with clauses, but every one carries operational meaning and nothing is redundant.

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 12-parameter, destructive, no-output-schema, open-world tool, the description covers the resume protocol, overwrite semantics, status handling implications, and author policy. It could go further by signaling failure recovery or pointing to aism_migration_rollback, but it is complete enough to call correctly.

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

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

Schema coverage is 100%, so the baseline is 3, and the description goes beyond it by explaining the cursor loop contract ('until done is true') and the incremental semantics of modified_after, neither of which is inferable from the schema alone since there is no output schema. The author matching fallback chain (login, then email, then default_author) is reinforced rather than merely repeated.

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 (migrate) plus a precisely enumerated resource scope: terms, media, content types, comments, site settings, and a finalize remap pass. It is clearly distinguishable from siblings like aism_migration_plan, aism_migration_copy and aism_migration_export because it describes a full-site, resumable run against a configured target.

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 concrete invocation guidance: call again with the returned cursor until done is true, and re-runs act as incremental sync when combined with modified_after. It does not explicitly route the agent between the sibling alternatives (plan vs copy vs run), but the runtime context it provides 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, idempotentHint, destructiveHint=false and openWorldHint, so 'Read-only' merely echoes structured data. The description does add genuine value by stating what the tool compares and that it surfaces finalize state, but says nothing about auth requirements for the two sites beyond what the schema states.

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 zero waste; the operation is stated first and the read-only safety note follows. 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 two-parameter read-only comparison tool, the description plus the 100%-documented schema and annotations give the agent enough to call it correctly. Without an output schema, more detail on the shape of the comparison report would have helped, but the essential behavior is 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%: both source and target are fully documented including naming pattern and required permissions. The description adds no additional meaning about the parameters, 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?

Names a specific operation: comparing source content counts against migrated content in the target and reporting finalize state. The verb+resource are clear enough to distinguish it from migration_run or migration_copy, though it does not explicitly position itself among the many migration 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?

Usage is only implied by the name and the 'report finalize state' phrasing – an agent can infer this is a verification check to run around migration, but there is no explicit statement of when to call it versus aism_migration_manifest or aism_migration_plan, and no 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?

Goes well beyond the annotations: names required permissions on both sides (migration:read on source, plugins:write/themes:write on target), discloses that installs land inactive unless activate=true, that parent themes are transferred first, and that older installed versions get updated from the source ZIP. 'Adds executable code' reinforces the destructiveHint. Not fully closed: nothing about partial-failure state or overwrite behavior when versions match.

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 action and the inactive-by-default caveat, and each subsequent sentence adds a distinct fact (file source, theme dependency, update behavior, permissions, code risk). Dense but no sentence is redundant; the final safety note is terse rather than integrated.

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, permission-gated migration write with no output schema, the description covers prerequisites, default state, dependency ordering, and risk. Only the return/outcome and retry semantics are absent, which are minor given the annotation coverage of destructiveness.

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 only 50%, and the description compensates for the most ambiguous field: the from enum's source-vs-wordpress.org semantics, which the schema leaves undocumented. It also explains activate's effect on the result. type and id are left to the schema, which describes id adequately.

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 a plugin or theme') with the exact scope ('from the source on the target'), which distinguishes it from the plain aism_plugin_install / aism_theme_install siblings. An agent can tell this is the cross-site migration installer 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?

Explains the key selection decision between from=source (exact installed files, custom/premium code) and from=wordpress.org (installs by slug), plus the activate flag default and that missing parent themes are pulled in first. It never explicitly says when to prefer this over the sibling install tools, so a small inference remains.

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 non-idempotent, but the description adds substantial context beyond them: the required capability for delete, the inactive-plugin precondition, the fact that updates pull the WordPress-advertised package, and the self-management and multisite exclusions. It stops short of saying whether a failed delete leaves state changed or what the failure surface looks like.

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 set, then constraints, then exclusions. Every sentence carries distinct information; nothing is repeated from annotations or 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 an unannotated-output mutation tool, the description covers permissions and preconditions well, but leaves the plugin identifier format undefined and gives no sense of the success/error outcome. That leaves an agent able to decide to call it but not necessarily to call it correctly 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 description coverage is only 33% — `site` is documented but `plugin` is a bare minLength-1 string with no hint of the expected format (slug, directory name, or plugin file path), which is the single most important thing to get right. The description adds no parameter-level meaning at all, so with low coverage it fails to compensate.

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

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

The description names a specific resource (installed plugin) and enumerates the four supported operations (activate/deactivate/update/delete), so the agent knows exactly what class of action this is. It does not, however, distinguish this tool's 'update' action from the sibling aism_plugin_update, leaving a real ambiguity among siblings.

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

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

It gives concrete preconditions: deletion needs the plugins:delete capability and the plugin must already be inactive, and it states that AI Site Manager cannot manage itself and multisite mutations are unavailable. What it lacks is routing guidance against aism_plugin_install/aism_plugin_update, so the agent must still guess which mutation tool to pick.

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 write, destructive, openWorld and non-idempotent, yet the description adds real value beyond them: the plugin is installed but left inactive, a capability/permission prerequisite, and a security warning that installation adds executable code. It does not say what happens if the plugin is already installed, which is the main remaining gap.

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 result state, then prerequisites, then risk. Every sentence carries distinct information with no repetition of schema or annotations.

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 rich annotations and no output schema, the description covers permission needs, the resulting state, and the risk. Only idempotency behavior in the already-installed case is left unstated.

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 50%: 'site' is documented in the schema while 'slug' is not. The description partially compensates by tying the slug to a WordPress.org plugin, implying a repo slug rather than an arbitrary path, but it adds no format or validation detail beyond that.

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 a WordPress.org plugin') plus an important result state ('inactive'), which distinguishes it from aism_plugin_upload and aism_plugin_update. It does not explicitly name those siblings, so differentiation is inferred 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?

The description gives a prerequisite ('Requires plugins:write and native install capability') but no guidance on when to choose this over aism_plugin_upload (arbitrary zip) or aism_plugin_update. Usage context is implied by 'WordPress.org' but never spelled out as an alternative-selection rule.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint, so safety is covered. The description adds that identifiers and status are returned, which is useful context, but it says nothing about network calls to the site, result size, or pagination.

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 boilerplate or repetition. It is efficient, though its terseness leaves little room for the guidance an agent might need.

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, annotated, read-only list tool with a fully documented single parameter and no output schema, this is close to complete. The description even notes the key return fields (identifiers/status); only pagination and site-resolution behavior are 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?

There is only one optional parameter, and schema coverage is 100%, so the schema already explains 'site' and its aism_sites reference. The description adds nothing to the parameter's meaning, which fits the baseline 3 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 and resource: 'List installed plugins and their identifiers/status.' That clearly separates it from siblings like aism_plugin_install, aism_plugin_update, and aism_plugin_action, but it never names an alternative or states the reverse distinction 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?

Use is implied — enumerate plugins before calling aism_plugin_update or aism_plugin_action — but no sentence says when to use this instead of aism_discover or aism_sites, and there are no prerequisites or 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?

Goes well past the destructiveHint/openWorldHint annotations by disclosing that ZIP replacement preserves activation, the required capabilities (plugins:write plus update/upload), the matching constraints (same plugin folder/main file, newer version, companion 1.2.0+), and the self-update/multisite limits. This is exactly the mutation-risk context an agent needs before a destructive 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?

Front-loaded with purpose and the file_path branch, then constraints. It is dense but every clause carries a constraint the agent would otherwise have to discover; the trade-off is a somewhat crammed run-on sentence of stacked caveats.

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 three-parameter mutation with no output schema, the description covers mode selection, capabilities, preconditions, and unsupported cases. It stops short of describing what a successful response contains or how version-mismatch failures surface, which would fully close the loop.

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, but the description adds real semantics: file_path is optional and selects the ZIP path, and the ZIP must contain the same plugin folder/main file at a newer version. It does not elaborate on the 'site' or 'plugin' parameters beyond the schema.

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

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

States a specific verb and resource ('Update an installed plugin') and immediately enumerates the two update modes: WordPress-advertised update vs. local ZIP replacement. This clearly separates it from aism_plugin_install, aism_plugin_upload, and aism_plugin_action without the agent needing to open 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?

Explicit routing rule: 'Omit file_path to use the WordPress-advertised update, or supply a local ZIP...'. It also names hard exclusions — AI Site Manager cannot update itself, and multisite mutations are unavailable — so the agent knows when not to call it.

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

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

Goes beyond the annotations by disclosing two important behaviors: the plugin is installed inactive, and it will not replace an existing plugin. It also flags the required permissions/capabilities. It leaves unexplained what 'native install/upload capabilities' concretely means and what happens on a name collision.

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, both front-loaded with the action and its key side-effect constraint, followed by the permission requirement. 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-parameter write tool with no output schema, the description covers action, side effects, overwrite behavior, and prerequisites. It stops short of describing failure modes or what is returned after a successful upload.

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 only 50% (file_path has no description beyond minLength), but the description compensates by indicating the expected input is a local plugin ZIP file path. The site parameter is fully documented in the schema, so no further description is needed.

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 gives a specific verb and resource ('Install a new local plugin ZIP') and adds scope qualifiers ('inactive', 'without replacing existing plugins'). It implicitly separates itself from aism_plugin_install by specifying a local ZIP source, though it never names the 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?

It supplies a precondition ('Requires plugins:write plus native install/upload capabilities') and the 'local plugin ZIP' framing hints at when to choose it over a slug/registry install. However, with aism_plugin_install and aism_theme_upload in the sibling list, no explicit when-to-use-this-vs-that guidance 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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false; the description's note that mutation is unavailable is consistent and reinforces them. It adds nothing about pagination of the revision list, ordering, or what a revision record contains.

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 the read scope front-loaded and the mutation limit trailing. The second sentence is terse to the point of being slightly cryptic about what 'mutation' covers.

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

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

The tool has 5 parameters including a free-form nested 'query' object and no output schema, so the description carries more burden than it does. It omits query argument behavior and return shape, though the read-only annotations and the explicit no-mutation note cover the main risk an agent faces.

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 40% across 5 parameters, so the description needs to compensate. It only hints at 'resource' values ('post/page') and implicitly at 'revision_id' for single fetches; it says nothing about the required 'id' pair, the 'site' selector, or how 'query' arguments (context, per_page, _fields) affect the result.

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') and resource ('post/page revision'), and clarifies the two modes (list vs. one revision). It does not name or differentiate itself from nearby siblings like aism_content_list or aism_content_get, which is the only gap.

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 sentence 'Revision mutation is unavailable' is a useful exclusion, telling the agent not to attempt writes here. However, there is no positive guidance on when to reach for this tool over aism_content_get or aism_content_list, leaving routing 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 description's 'read' matches readOnlyHint=true and is consistent with non-destructive/idempotent annotations, so no contradiction. However, it adds little behavioral context beyond the annotations — no mention of caching, freshness, or that results are site-scoped, which would matter for a schema introspection call.

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

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

A single front-loaded sentence with no filler. It is efficiently sized, though the brevity is partly what leaves gaps elsewhere.

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 must convey what comes back; 'schemas and endpoint arguments' gives a rough idea of the return payload but not its structure. Combined with the undocumented required resource parameter, an agent has enough to attempt a call but not to use the result confidently.

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 only 50%: the site parameter is documented, but the required 'resource' parameter has no description in either the schema or the tool description, despite accepting an anyOf of a free-form pattern and a plugins/themes enum. The description does not explain what valid resource values are or how they map to endpoints, leaving the single required parameter ambiguous.

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 verb (read) and an object (native schemas and endpoint arguments), but 'native schemas' is opaque jargon an agent cannot resolve without prior knowledge. It does not distinguish itself from discovery-oriented siblings such as aism_discover or aism_guide, which plausibly serve overlapping purposes.

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 clause 'before working with a resource' implies a sequencing prerequisite, which is useful, but no explicit when-to-use/when-not or alternative routing is given. Nothing tells the agent why to pick this over aism_discover or aism_guide.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds the meaningful constraint that only options 'approved' for the API key are readable and that schema metadata is returned, but says nothing about error behavior for unapproved names or about site scoping.

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 short sentence with the resource and return content front-loaded and no filler. Nothing could be removed 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?

There is no output schema, but the description discloses that the response includes the value plus its schema, which is the key return-shape fact. For a two-parameter read tool with full schema coverage and strong annotations, little is missing beyond failure-mode details.

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 parameters are already documented, including the site scoping and option name pattern. The description contributes only the 'approved option' qualification, which is already reflected in the schema's 'approved for this API key' wording, 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?

The description gives a specific verb ('Read') and resource ('one approved option value and its schema'). The word 'one' implicitly contrasts with the list sibling (aism_settings_list), but no sibling is named explicitly, so it stops short of full differentiation.

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

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

Usage is only implied: read a single approved option, versus list for enumeration or update for writes. There is no explicit 'use this when' guidance or named alternative, leaving the agent to infer the boundary from sibling names.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description still adds real value by explicitly stating no values are returned, heading off the expectation that 'list' produces setting contents.

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 compact sentence with the exclusion clause front-loaded alongside the purpose; nothing is wasted 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?

Adequate for a read-only one-parameter metadata tool: the schema covers the site argument, annotations cover safety, and the description rules out returning values. It could still note what the schema entries look like or point to aism_settings_update as the consumer, but nothing essential is missing.

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

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

Schema coverage is 100% and the single 'site' parameter is fully documented, including its link to aism_sites and the default-site behavior. The description adds nothing 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?

Specific verb (list) plus a specific resource (approved option names and schemas), and the clause 'does not return values' distinguishes it from aism_settings_get. Sibling differentiation is implicit rather than named, keeping it 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?

Usage is only implied: the 'approved option names and schemas' framing suggests calling this before aism_settings_get/update to learn valid keys, but neither the alternative tools nor the when-not condition are stated. An agent must infer the workflow.

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

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

Annotations already flag destructive, non-idempotent, open-world behavior; the description adds real value on top by stating that the whole value is replaced (not merged), that unrelated object fields must be preserved, and that no compare-and-swap protection exists — a concurrency hazard annotations cannot convey. It does not cover permissions or response behavior.

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

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

Three short, high-density sentences, front-loaded with the action and its destructive scope, then the prerequisite read, then the concurrency caveat. 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 destructive mutation with annotations and no output schema, the description covers the essential risks: wholesale replacement, the read-before-write requirement, and the absence of CAS. Missing only secondary details like error/response shape or scope of 'approved option'.

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 documents 'site' and 'option' at 67% coverage, so those are handled; 'value' has no schema description but is a free-form recursive anyOf. The description adds the key semantic that the value fully overwrites and that untouched object fields must be carried over, which is genuinely useful but not detailed enough to fully compensate.

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

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

The description names a specific verb and resource ('Replace the ENTIRE value of one approved option') and makes the wholesale-replacement semantics explicit, which separates it from a partial settings merge. It never names sibling aism_settings_get explicitly, but the scope is unambiguous.

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 operational guidance — 'Read it immediately before editing' — which effectively routes the agent through a read-then-write flow, and warns there is no compare-and-swap. It stops short of naming the specific sibling read tool or listing when not to use this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds real value beyond them with "Keys are never shown", a security-relevant disclosure about what the output will and will not contain.

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 sentence, front-loaded with the action and resource, with the field list and the key-suppression caveat packed into a tight parenthetical. No wasted words.

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

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

With no output schema, describing the returned fields (names, API base URLs, default flag) is exactly the right compensation, and the key-omission note prevents an agent from hunting for credentials. Only minor gap is not stating whether results reflect local config versus live remote state.

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 and the schema is an empty object, so there is nothing for the description to disambiguate. Baseline 4 applies; no param guidance is needed or 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?

Specific verb plus resource ("List configured site connections") and an enumeration of what each entry contains. It is clearly a read-only inventory tool, distinguishable in spirit from aism_settings_list, though it never names a sibling to sharpen the boundary.

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 by the word "configured" — an agent infers this is the entry point for discovering which sites exist before calling other tools. No explicit when-to-use, prerequisites, or alternative (e.g. aism_settings_list) is offered.

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=true, idempotent=false, and openWorld=true; the description goes beyond them by naming the capability required for deletion and the hard refusals (active theme, parent theme, multisite). It stops short of saying whether an update is rollback-safe or what the mutation returns, which is a modest remaining gap given annotation coverage.

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 sentences, purpose front-loaded, followed by prerequisites and edge cases in descending order of importance. No restatement of the name 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 three-parameter destructive mutation with no output schema, the description supplies what an agent most needs: how to obtain the identifier, the permission requirement, the disallowed targets, and the multisite restriction. Return values are not described, but the mutation outcome (activate/deactivate/delete) is implied clearly enough for correct invocation.

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

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

Schema coverage is only 33% (only `site` is described), so the description must carry `theme` and `action` – and it does: `theme` is defined as a stylesheet identifier obtainable from aism_themes_list, and each enum value is given behavior (activate swaps the active theme, update uses the advertised package, delete has permission/eligibility rules). Only the `site` parameter's default semantics are left to 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 first sentence gives three specific verbs (activate/update/delete) against a specific resource (an installed theme), and pins the identifier to the stylesheet slug sourced from aism_themes_list. 'Installed theme' implicitly separates it from aism_theme_install and aism_theme_upload, so an agent can pick correctly 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?

States concrete conditions: activation replaces the current active theme, deletion needs themes:delete and is blocked for the active theme or its parent, updates pull the WordPress-advertised package, and multisite mutations are unavailable. It lacks an explicit 'use aism_theme_install instead when the theme isn't present' sentence, but the prerequisites and exclusions are well above typical 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 and openWorldHint, but the description adds real context beyond them: the theme is left inactive, a parent theme may be pulled in as a side effect, specific capabilities are required, and installing introduces executable code. Those are exactly the side effects and auth requirements an agent needs before a mutating call.

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 sentences, zero filler, with the core action stated first and constraints, prerequisites, and the security note following. 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 destructive, open-world install with no output schema, the description covers preconditions, side effects, and the security implication. It leaves out failure modes (e.g., theme not found, permission denied) and any return information, but the essentials for correct invocation 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 coverage is 50%: `site` is fully documented in the schema while `slug` has only a pattern. The description implies `slug` is a WordPress.org directory slug (lowercase, hyphenated), which adds a little meaning, but it never explains the slug format or the default-site behavior beyond what the schema already says.

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 pairs a specific verb (Install) with a precise resource (a WordPress.org theme) and states the resulting state (inactive), which separates it from aism_theme_upload (local zip) and aism_theme_action (activate/update). An agent can tell which sibling to call 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?

It states the required capabilities (themes:write and install_themes) and the condition under which Core will also install a missing parent theme, giving clear preconditions. It does not explicitly exclude alternatives such as aism_theme_upload, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered; the description adds the genuinely new behavioral fact that a specific permission scope plus native theme access is required. It does not explain what "native theme access" means or how inactive themes appear in the result, but the core disclosure beyond annotations is present.

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

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

Two sentences, zero filler: the returned fields are front-loaded and the permission prerequisite follows. Every clause carries information an agent needs before calling.

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-optional-param, read-only list tool with no output schema, the description usefully enumerates the returned fields and the auth requirement. What remains thin is whether results cover inactive/child themes and whether pagination exists, but nothing essential for a correct 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?

With a single parameter and 100% schema description coverage ("Configured site name from aism_sites. Omit for the default site."), the schema does the work. The description adds nothing about the site parameter — no note on how multi-site results differ or how an invalid site name behaves — 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?

Specific verb+resource ("List installed themes") plus the exact fields returned (stylesheet identifiers, versions, active/inactive status), which distinguishes it from the mutation siblings aism_theme_install, aism_theme_upload and aism_theme_action. It stops short of naming those alternatives explicitly, so it is clear but not fully sibling-differentiated.

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

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

The description gives prerequisites ("Requires themes:read and native theme access") but no when-to-use guidance, no exclusions, and no pointer to the alternative tools for installing, uploading or activating a theme. Usage is only implied by the name and the sibling set.

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/openWorld/non-idempotent, so the description adds real value: the theme is installed INACTIVE, existing themes are not replaced, and it requires themes:write plus native install/upload capability. That capability prerequisite is exactly the kind of context annotations can't convey.

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

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

Two short sentences with the action and its key constraints front-loaded; no filler and 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 mutation with no output schema, the description covers the essentials an agent needs: required capability, inactive install state, and non-replacement behavior. Only the file_path semantics and any post-upload response/verification step are left unspecified.

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 50%: 'site' is well documented in the schema, while 'file_path' has no schema description. The phrase 'local theme ZIP' partially compensates by implying file_path points to a ZIP archive, but it doesn't say whether it's a server-side path, its format, or its constraints.

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: installing a new local theme ZIP. The 'without replacing existing themes' clause and the 'local ... ZIP' qualifier implicitly separate it from aism_theme_install (repo-based) and aism_plugin_upload, but neither sibling is named outright.

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?

'Install a new local theme ZIP' implies the use case (you have a ZIP on disk rather than a slug), and the non-replacement clause signals it's not an upgrade path. There is no explicit routing guidance to aism_theme_install or aism_theme_action for other cases.

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