Paperboy CMS

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

Annotations declare readOnlyHint=true and openWorldHint=true, and the description reinforces this with 'does NOT save anything' (no contradiction). It goes well beyond annotations by disclosing the dependency on the Settings → AI model config, the degraded basic-truncation fallback for only three tasks, that other tasks return an error, and that alt_text is unavailable. Rich behavioral disclosure.

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

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

Front-loads the most important fact (no saving, write it yourself) ahead of secondary detail. Sentences are dense with em-dashes but every clause carries actionable information; minor run-on structure keeps it from a 5.

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

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

For a read-only generation tool with no output schema and no sibling overlap, the description covers the critical gaps: non-persistence, model config dependency, degraded-mode task coverage, and the alt_text exclusion with a routing alternative. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3 and the schema already documents task/input/site/targetLocale. The description adds value beyond the schema by specifying which task values remain functional without a configured model (meta_title, meta_description, summarize), a constraint that directly affects task selection.

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 ('Run the CMS's writing assistant on a piece of text') and immediately delimits scope by declaring it saves nothing. An agent can distinguish it from sibling write tools like update_content or set_field without opening any schema.

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

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

Explicitly routes the agent: 'write the output yourself with set_field/update_content' and 'write it and save with update_asset_alt' for alt text. It also names when NOT to expect this tool to work (alt_text is refused) and names the alternative, which is exactly the when/when-not/alternative pattern.

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

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

Beyond the annotations (which already declare idempotent, non-destructive, non-read-only), the description adds that the copy is server-side and atomic, copies EVERY field, and that the destination receives a draft requiring a separate publish. This is exactly the kind of downstream-state disclosure annotations cannot convey.

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

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

Purpose is front-loaded, followed by the routing guidance and a motivating anecdote. It is slightly long, but the parenthetical story earns its place by warning against the manual re-typing anti-pattern rather than padding.

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

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

With no output schema, the description still conveys the key outcome (a draft in the target locale, published separately) and the atomicity guarantee. It omits what identifiers are returned, but for a copy tool this is close to complete.

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 documentId, fromLocale, toLocale and site are already well documented in the schema. The description's 'name, slug and EVERY field' clarifies copy scope rather than adding parameter-level syntax, so the baseline 3 is appropriate.

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

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

States a specific verb (copy), resource (a document's working version), and scope (name, slug and EVERY field) plus the directional transform (locale to locale). This clearly distinguishes it from siblings like duplicate_content, move_content, and update_content without opening their schemas.

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

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

Gives explicit when-to-use (content that landed in the wrong language branch) and a strong when-not (never re-type field by field), reinforced by a concrete failure anecdote. It stops short of naming an alternative sibling tool by name, so it falls just short of the top mark.

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

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

Annotations only declare the safety profile (mutation, non-destructive, non-idempotent). The description adds real behavioral consequences beyond them: omitting data leaves a blank page, a root-level blog post renders with a generic/empty layout, and type/language mismatches are refused ('a mismatch is refused'). These are refusal and side-effect disclosures that annotations do not carry.

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

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

Front-loaded with the core action and the one-shot `data` guidance before the caveats. It is dense and long for a single paragraph with heavy ALL-CAPS emphasis, but the length is largely justified by the number of non-obvious constraints. Loses a point for the wall-of-text presentation.

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 9-parameter mutation tool with no output schema, the description covers prerequisites (get_content_type, tree), guard behavior, the empty-vs-filled create fork, and top-level vs nested placement. Nothing an agent needs to call it correctly is missing; output values are not needed here.

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 schema already documents each parameter; baseline 3. The description nonetheless adds meaning beyond the schema by explaining cross-parameter relationships (parentId determines URL and frontend template; type inheritance under a list page; allowTypeMismatch as a deliberate override), which the per-parameter schema text does not connect.

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

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

States a specific verb+resource+scope: 'Create a new content item (page/block/global) as a draft.' It explicitly positions itself against siblings (update_content, set_field, get_content_type, tree) so an agent can tell it apart without opening schemas.

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

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

Gives explicit when/when-not: pass `data` for a one-shot filled create (strongly preferred), omit it to get an empty shell that must be filled later; call get_content_type first; call tree first and set parentId; omit parentId only for genuinely top-level pages. Alternatives and preconditions are 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 the safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), and the description adds real context beyond them: the instance-wide scope, the auth requirement of a non-site-limited token, and validation behavior ('a bad one is refused with the offending path'). This is unusual depth for a create 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?

Four sentences, front-loaded with the core create action, then scope/auth, then the alternative, then failure behavior. No filler; each sentence carries distinct information.

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

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

For a mutation tool with no output schema, the description covers what an agent needs: what it creates, the token scope, an alternative for common cases, and error behavior on invalid input. Nothing material is missing.

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

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

Schema description coverage is 100%, and the schema already documents the site slug and the ContentTypeDef shape with examples. The description reinforces 'full ContentTypeDef' and adds the validation-on-bad-input behavior, but adds little parameter syntax beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Create a new content type') and clarifies what a content type is ('the schema editors fill in') from a full ContentTypeDef. It routes the agent away from siblings by naming list_type_templates + instantiate_type_template as the faster path for common shapes.

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

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

Explicitly names the alternative workflow ('Faster for common shapes: list_type_templates + instantiate_type_template') and states the token prerequisite (instance-wide, not limited to one site). Both when-to-use and the alternative are 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 only declare the mutation profile (readOnly=false, idempotent=false, destructive=false). The description adds genuinely non-obvious behavior: the secret is returned exactly once and must be stored immediately, the admin-only restriction, and the security consequence of preview keys reading drafts.

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

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

Three sentences, front-loaded with the action and permission, then the type trade-off, then the one-time-secret warning. No filler and the most failure-prone detail (store the secret now) is last and emphatic.

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

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

No output schema exists, and the description compensates by explaining the return (the secret, shown once). For a 3-parameter mutation tool it covers permission, parameter choice, and the irreversible consequence.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds meaning for the type parameter beyond the enum text by framing public as safe for a public build and preview as server-side-only, and it contextualizes the site parameter's multisite fallback behavior.

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

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

Specific verb (Mint) plus resource (Delivery API key) plus scope (this site) and permission gate (Admin only). It is trivially distinguishable from its siblings list_delivery_keys, revoke_delivery_key and rename_delivery_key.

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 the decision rule for the two key types — public for a website build, preview when drafts are needed — plus the admin-only prerequisite and the security caveat for preview keys. It stops short of explicitly naming when not to use it or pointing at sibling tools like revoke_delivery_key.

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

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

Annotations already cover the safety profile (readOnly=false, destructive=false, idempotent=false), and the description adds genuinely non-obvious behavior: chained redirects are collapsed to the final destination, loops are refused, and auto-generated 301s may already exist. It stops short of stating whether the rule takes effect immediately or whether it requires a publish step.

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, then the two argument families, then status semantics, then the routing tip to list_redirects. Dense and mostly waste-free, though the long em-dashed clauses make it slightly harder to scan than ideal.

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 8-parameter mutation tool with no output schema, the description covers source/target semantics, status codes, and redirect-resolution behavior well. The remaining gap is the return value and whether creation is immediate or requires publishing, which the agent would otherwise need from elsewhere.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes beyond the schema: it explains that a full old-site URL is reduced to its path, that a target path naming a published page is stored as that page, and that 301 'passes link equity' while 410 requires no target. These are semantics the schema does not convey.

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?

Opens with a specific verb+resource ('Create a redirect rule') and then defines the two core concepts (source forms, target forms) precisely enough to distinguish it from siblings like update_redirect and delete_redirects. It also explicitly contrasts itself with list_redirects ('check list_redirects before adding one by hand'), which the agent would otherwise have to infer.

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 real when-not guidance: publishing a new slug or moving a page already creates 301s automatically, so check list_redirects first. It does not, however, mention when to prefer update_redirect or delete_redirects over creating a new rule, leaving one sibling gap.

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

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

Annotations already declare the mutation profile (not read-only, not destructive, not idempotent), so the bar is lower. The description adds the reserved-name constraint and the link to instantiate, but omits what happens on a name collision (error vs overwrite) and any permission requirements — relevant for a non-idempotent write.

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

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

Two sentences, front-loaded with the core action, and no filler. The parenthetical 'starter/backup recipe' is slightly decorative but clarifies intent cheaply.

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 2-parameter tool with full schema coverage and no output schema, the description covers purpose, naming, and the downstream instantiate relationship. The main missing piece is collision/overwrite behavior on a non-idempotent save.

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

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

Schema coverage is 100%, so baseline is 3. The description adds genuine meaning by explaining that the template name becomes the content type name that instantiate materialises by default, which is semantics the schema does not convey.

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

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

The description states a specific verb and resource — 'Save a content type definition as a reusable template' — and clarifies the recipe/starter purpose. It implies separation from create_content_type by framing the artifact as a template rather than live content, though it never names a sibling directly.

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

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

It gives a naming rule ('use a name no existing template takes; built-in names are reserved') and hints at the instantiate relationship, but never states when to choose this over create_content_type, update_type_template, or import_type_templates. Usage is implied rather than specified.

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

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

Annotations only say this is a non-read-only, non-destructive, non-idempotent call; the description adds the details that actually matter: the link is short-lived (15 minutes), it uploads as the calling user, it targets a specific site, and the response enumerates a documentId per stored asset. Those are behavioral facts no structured field carries.

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 purpose, then mechanics, then expiry/attribution, with zero filler. The parentheticals and the curl aside are useful rather than decorative, though the first sentence carries several stacked clauses and could be split for faster scanning.

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

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

For a one-param tool with no output schema, the description supplies everything an agent needs: why the tool exists versus the server-side alternative, the exact invocation format, the follow-up tools for the returned documentId, and the lifetime/identity semantics of the link.

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' param is already well documented in the schema (slug/id, omit for default, pointer to list_sites). The description's 'into this site' confirms the param's effect on upload destination but adds no syntax or format detail beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb+resource ('get a short-lived link for uploading LOCAL files ... into the media library') and explicitly differentiates itself from the sibling upload_asset by scoping to files on the user's own machine, which 'this server can't read'. An agent can distinguish this from upload_asset without opening either schema.

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

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

Gives a clear triggering condition (local files the server cannot read) and a concrete usage recipe — POST the link as multipart/form-data, several -F file=@ per request, with a curl example — plus the downstream steps (set_field for documentId, update_asset_alt for alt text). It never names the sibling alternative (upload_asset) explicitly, so it stops short of a full when-to-use-this-vs-that statement.

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

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

Annotations cover the safety profile (readOnly=false, destructive=false, idempotent=false), and the description meaningfully extends it with auth requirements (admin-only, instance-wide token), the return shape ('Returns {id}'), and operational guidance on password transfer and self-service 2FA. This is real context beyond the structured fields, though rate limits or error behavior are unaddressed.

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

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

Front-loaded with the core purpose, then credential, return, and password-handling details in tight succession. Every sentence contributes, and there is no redundant restatement. Slightly dense but well structured.

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

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

For a 6-parameter, 4-required mutation with no output schema and no annotations beyond hints, the description covers purpose, authorization prerequisites, return value, and post-creation password handling. It is close to self-sufficient, with only edge-case behavior (validation failures, duplicate email) left implicit.

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

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

Schema description coverage is 100%, so all six parameters are already documented in the schema (roles, sections, site, etc.). The description repeats the email/password concept and clarifies the instance-wide site scope but adds no new parameter semantics. Baseline 3 applies when the schema carries the load.

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

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

States a specific verb+resource ('Create a CMS user account') and adds scope ('instance-wide, all sites'), which cleanly separates it from content CRUD siblings like create_content. It does not explicitly name the adjacent user-management siblings (update_user, list_users), 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?

Provides clear preconditions for use: 'Admin only; needs a token not limited to one site.' This tells the agent when it is permitted and what credential scope is required, effectively acting as an exclusion. It doesn't name an alternative tool or fallback, but the context is unambiguous.

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

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

Annotations only say this is a non-readOnly, non-idempotent write; the description adds substantive behavior: HMAC-SHA256 signed payloads, refusal of private-network URLs, admin-only access, and that the signing secret is returned exactly once. Those are operational facts an agent cannot get from the structured fields.

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

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

Roughly 50 words in tightly packed sentences with the action first, the security caveat second, and the one-time-secret warning last. No filler clauses; every sentence carries a distinct fact.

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

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

No output schema exists, and the description covers the one return detail that matters (the secret is returned ONCE and must be stored), plus security constraints and permissions. Nothing needed to invoke this webhook-creation tool correctly is missing.

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

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

Schema description coverage is 100%, so url/name/site/events are already documented in the schema; the description reinforces the public-endpoint and secret semantics but adds no parameter-level detail beyond it. 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 ('Subscribe a URL to this site's events') along with the mechanism (Paperboy POSTs a signed JSON payload), which clearly separates it from list_webhooks and delete_webhook siblings.

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

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

Gives a concrete usage context ('to trigger a static-site rebuild') and a prerequisite ('Admin only'), so an agent knows the scenario and the permission bar. It stops short of naming alternatives such as list_webhooks or delete_webhook or stating when-not to use it.

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

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

Annotations confirm destructive and non-idempotent behavior, but the description adds substantial context beyond them: both the database row and the stored binary file are removed, references are not blocked, and pages silently lose the image via null resolution. It also discloses the return shape ({ok:true}). This is genuinely useful behavioral disclosure.

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 tight sentences, front-loaded with the irreversible action, then the consequence, then the mitigation, then the return value. 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?

Though there is no output schema, the description supplies the return value, the destructive scope, and the side effects on dependent content. Nothing an agent needs to call this safely is missing.

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

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

Schema description coverage is 100%, so documentId and site are already fully documented in the schema, including the pointer to list_sites and list_assets. The description adds no parameter-level detail, so the baseline 3 applies.

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

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

States a specific verb and resource — 'Permanently delete a media asset' — and immediately clarifies scope: 'the database row and the stored file.' The word 'permanently' distinguishes it from the softer sibling trash_content, so an agent can tell the two apart without opening either schema.

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

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

Provides a clear prerequisite: content pointing at the asset must be cleared or replaced first, because delivery resolves dangling references to null. It gives the condition for safe use but never names the obvious alternative (trash_content) for non-permanent removal, so it stops short of explicit alternatives.

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

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

Annotations already declare destructiveHint=true and non-idempotent behavior. The description adds important operational context beyond annotations: irreversibility, audit logging, required permission, and return behavior when the submission does not exist.

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

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

The description is tightly structured and front-loaded with the core action and its destructive nature. Every sentence adds useful information without filler.

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

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

Given the destructive mutation, full schema coverage, and existing annotations, the description covers the critical gaps: irreversibility, audit logging, permission requirement, missing-submission behavior, and the sibling alternative. No output schema exists, so return values need not be explained further.

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

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

Schema coverage is 100%, so both parameters are fully documented in the input schema. The description reinforces that only one submission is affected via submissionId but does not add syntax or format meaning beyond the schema.

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

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

The description states a specific verb and resource: 'Permanently delete ONE form submission'. It also scopes the operation to one submission and explicitly distinguishes it from erase_form_submissions, so an agent can tell it apart from 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 names the alternative erase_form_submissions and the condition that selects it: erasing everything one person sent. It also states the required permission (submission.manage), which is essential for correct invocation.

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, so the safety profile is covered; the description adds real value on top by disclosing the post-deletion behavior (old URLs answer 404 or resolve to a newly published page) and the response payload {deleted: <count>}, effectively serving as a lightweight output schema.

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

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

Three short sentences, front-loaded with the action and its irreversible nature, then the consequence, then the return shape. Every clause earns its place with no filler.

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

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

For a no-output-schema, destructive, two-parameter tool, the description supplies the consequence of deletion and the return shape, which is enough for correct invocation. It could still note any permission requirements or bulk-deletion limits, 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 both parameters (ids, site) are fully documented there, including the multisite fallback and the list_sites hint. The description only restates 'by id' and the return count, adding nothing beyond the structured fields, so the baseline of 3 applies.

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

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

States a specific verb+resource ('delete redirect rules by id') with the permanence qualifier, which cleanly separates it from the sibling update_redirect/create_redirect/list_redirects family. An agent can identify the operation without opening the schema.

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

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

It implies the usage context (removing redirects so old URLs 404) and tells you to verify with list_not_found afterwards, but never states when this is preferable to updating a redirect or that the ids come from list_redirects (that detail is only in the schema). No explicit exclusions or alternatives.

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

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

Goes beyond the annotations (which already flag destructiveHint=true and idempotentHint=false) by disclosing the key cascade behavior: content types instantiated from the template and their content are NOT affected, and built-ins are protected. This answers the most important 'what does destroying this touch' question. It stops short of noting behavior on already-deleted names, which is relevant given idempotentHint=false.

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, no filler, front-loaded with the destructive action. Each sentence earns its place: action, built-in exclusion, non-cascade reassurance, and return value.

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 delete with no output schema, the description supplies the return value ({ok:true}), the protection rule, and the non-cascade consequence. Combined with annotations that carry the safety profile, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents the 'name' and 'site' parameters, including multisite guidance. The description adds no parameter-level detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('Permanently delete a stored type template from the library') and scopes it against built-ins. This clearly separates it from sibling write tools like delete_asset, delete_user, and delete_redirects, and there is no ambiguity about what gets removed.

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

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

Provides an implicit when-not ('built-ins can't be deleted') and reassures the caller about scope, but never names an alternative (e.g. update_type_template for modification) or states prerequisites. Usage is implied rather than explicitly routed.

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 destructiveness and non-idempotency, but the description adds important behavioral context: the effect on sign-in, browser session termination, content retention, irreversibility, admin constraints, and the return shape. It does not contradict the annotations.

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

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

The description is compact and front-loaded: identity of the operation, access restriction, effects, constraints, irreversibility, and return value are all stated without filler. Every sentence carries operational meaning.

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

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

For a painless destructive admin tool with complete schema coverage and annotations, the description supplies all missing decision-critical context: irreversibility, session termination, content retention, self/last-admin exclusions, and return format. No output schema exists, so the return note is useful.

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

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

Schema description coverage is 100%, so the input schema already documents both the 'id' and optional 'site' parameters. The description does not add further parameter-level syntax or meaning beyond what the schema provides, so the 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 states a specific destructive verb and resource (permanently delete a user account), names the admin-only restriction, and clearly differentiates the operation from sibling tools like create_user, update_user, and list_users. An agent can identify the exact action and scope without opening the schema.

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

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

It gives explicit usage conditions and exclusions: 'Admin only', 'you cannot delete yourself or the last Admin', and 'Irreversible'. These tell the agent when the tool is valid and when it must not be called.

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, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered. The description adds real value beyond them: irreversibility ('Permanently'), the side effect on event delivery, an auth requirement ('Admin only'), and a return shape ('{ok:true}'). It does not address failure modes or the notably non-idempotent behavior, keeping it from a 5.

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

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

A single front-loaded sentence carrying purpose, privilege, effect, and return value with no filler. Every clause earns its place.

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

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

For a two-parameter destructive delete, the description covers what gets destroyed, the auth bar, the side effect, and the return value, while annotations and the schema cover the rest. Only the absence of failure-mode/idempotency context leaves a small gap.

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

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

Schema description coverage is 100%, including a helpful note that 'id' comes from list_webhooks and a multisite note for 'site'. The description adds nothing about either parameter, so the baseline of 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?

States a specific verb and resource ('Permanently delete a webhook') plus the observable consequence ('no further events are sent to its URL'). It is clearly distinguishable from create_webhook/list_webhooks by the verb alone, but it never names a sibling explicitly, so it stops short of the 5 benchmark.

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

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

Usage is implied by the destructive framing and the '(Admin only)' prerequisite, but there is no explicit when-to-use statement, no when-not-to-use, and no pointer to alternatives such as list_webhooks or create_webhook. The agent must infer that this is the removal path.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, but the description adds real behavioral context: published-only unless preview, private fields removed, computed urlPath/fieldTypes/SEO metadata, and null on no match. That is well beyond what the annotations provide.

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

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

Three tight sentences: identity and semantics first, return shape second, sibling routing last. No filler, and the most decision-relevant clause is front-loaded.

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

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

With no output schema, the description carries the return-value burden and does it: it enumerates the computed fields and the null-on-miss case. Combined with annotations and full param coverage, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so preview, site, locale, populate and documentId are all documented at the source; baseline 3 applies. The description retouches preview ('unless preview') but adds no syntax or format detail beyond the schema.

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

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

States a specific verb and resource ('Read one content item by documentId') and pins down the exact semantics ('exactly as the website receives it', 'as the public Delivery API serves it'). This distinguishes it from get_content and the other delivery_* readers without requiring the agent to open 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?

Explicitly names an alternative and the condition that selects it: 'Use get_content to read a draft for editing.' That is clear routing guidance. It does not differentiate from the closely-named siblings delivery_get_by_slug / delivery_get_by_path, leaving a small gap for a sibling set this crowded.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: published-only unless preview, private fields stripped, and a null return when nothing matches. It could say more about preview access requirements (the schema carries that) but this is well above the annotation baseline.

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 front-loaded sentences: the purpose first, then return semantics, then the routing alternative. No filler, and the most decision-relevant fact (what the live URL returns) leads.

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

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

No output schema exists, so the description carries the return burden and does so: it explains the item shape (public fields, computed urlPath/fieldTypes/SEO metadata) and the null case. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so all five parameters are already documented in the schema, including preview and populate semantics. The description only echoes 'unless preview' and adds no syntax or defaults beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb (read) and resource (the page a visitor gets at a URL path) and frames the exact use case ('check what a live URL shows'). It clearly differentiates itself from get_content (drafts) and, by implication, the other delivery_* readers.

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

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

Names the alternative explicitly ('Use get_content to read a draft for editing') and states the condition that selects this tool ('the way to check what a live URL shows'). The published-vs-draft boundary is the deciding factor and it is spelled out.

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

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

With readOnlyHint already covering safety, the description adds substantial context beyond annotations: published-only unless preview, private fields removed, the computed urlPath/fieldTypes/SEO fields on pages, and the null return when nothing matches. This is exactly the return-shape and filtering disclosure that a read operation needs.

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

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

Four dense sentences, zero filler. The core 'read by slug' scope is front-loaded, followed by disambiguation, then return behavior. Every clause carries information.

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

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

No output schema exists, but the description fully covers the return contract (published-only filtering, computed fields, null on miss) and prerequisites (preview needs site-wide read). Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents all five parameters and the baseline is 3. The description adds real semantic value on top: slug uniqueness only among siblings, and preview semantics tying to the draft/live distinction, which informs how the parameter should be set.

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 content item by its slug') with a precise scope clause (slug = last URL segment). It proactively distinguishes itself from siblings delivery_get_by_path and get_content, so an agent can select it without opening other schemas.

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

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

Explicit routing advice: 'prefer delivery_get_by_path for a page's full URL' and 'Use get_content to read a draft for editing.' Both the preferred alternative and the when-not condition are named, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, but the description goes well beyond them: published-only unless preview, private fields removed, null when nothing matches, preview requires site-wide read access, and computed urlPath/fieldTypes/SEO fields are returned. That is rich behavioral context for a read 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?

Core action is front-loaded in the first sentence, followed by discovery, return semantics, and the alternative. The middle sentence is dense with stacked parentheticals (computed fields, preview caveat), costing a little readability, but every clause carries information.

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

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

With no output schema, the description still explains the return shape (published content, private fields stripped, computed fields, null on no match), and annotations cover the safety profile. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so each of the four parameters is already documented in the schema; baseline 3 applies. The description restates preview semantics ('published only (unless preview)') but adds no syntax or format detail beyond what the schema provides.

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

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

States a specific verb and resource ('Read a global singleton ... by its type') and names the scope ('as the website receives it'), which cleanly distinguishes it from get_content and the delivery_* readers. An agent can identify what it does without opening the schema.

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

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

Names two concrete alternatives with their selecting conditions: 'Find the types with list_globals' and 'Use get_content to read a draft for editing.' It also implies when-not by contrasting public delivery reads against draft editing.

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

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

Annotations only declare readOnlyHint=true and openWorldHint=false; the description goes further by disclosing that private fields are stripped, that omitting sort falls back to the parent's declared child order, and that the response is { items, total }. It stops short of covering the preview/permission nuance (that lives in the schema) or any rate-limit/paging caveats.

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

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

Two sentences, purpose front-loaded, and the final clause carries the return shape rather than padding. Dense but every clause carries information; only the parenthetical example borders on 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?

With nine parameters, no output schema, and nested filter objects, the description supplies the return shape, private-field removal, and default sort behavior an agent needs. It is thin on how populate/locale/preview interact, but those are reasonably covered in the schema itself.

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 semantics the schema does not: the default ordering when sort is absent, and the fact that filters apply to data fields specifically. This meaningfully supplements the parameter docs.

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 the published content of one type') plus the delivery-side framing ('as the website receives it'), which cleanly separates it from the management-content siblings and from delivery_search/delivery_get_by_id. The BlogPost example makes the unit of return 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?

The description implies when this tool applies (enumerating all items of one type for a listing) but never names an alternative such as delivery_search or get_content, nor states when-not to use it. Usage is inferable but not guided.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real behavioral context beyond that: only published content is matched unless preview, private fields are never matched or returned, and the return shape is { items, total }. It doesn't disclose pagination or result-ordering behavior, which keeps it below a 5.

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

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

Two sentences with zero padding. The core scope and constraint are front-loaded, and the routing hint to siblings is placed last where it belongs.

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

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

No output schema exists, and the description compensates by stating the return shape. Combined with published-only/private-field behavior, locale scoping, and the preview-access caveat, an agent has everything needed to call this correctly for a read-only search tool.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above it by explaining what the query actually matches against (item names and public field text) and that search is scoped to a single locale, which meaningfully qualifies the query and locale parameters beyond the schema's wording.

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 (full-text search) and resource (website content: item names + public field text), plus scope constraints (one locale, published only unless preview, private fields excluded). It also names the sibling tools it is not (list_pages, tree), so an agent can route without opening either schema.

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

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

Explicitly routes away from this tool for editing use cases: 'To find content for editing, list_pages or tree are usually faster.' That names alternatives and the condition selecting them. It lacks a positive 'use this when' framing (e.g. visitor-facing lookup), but the scope statement covers most of that implicitly.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, but the description adds substantial behavioral context beyond that: it returns published content only unless preview is set, strips private fields, adds computed urlPath, fieldTypes and SEO metadata on pages, and returns null when no start page is set or nothing matches.

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

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

The description is front-loaded with purpose and return behavior, and each sentence mostly earns its place. The null condition is stated twice in slightly different forms, which is a minor redundancy, but overall it remains efficient and well structured.

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

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

There is no output schema, but the description explains the returned item structure and the null cases clearly. Combined with the fully documented input schema and read-only annotations, an agent has everything needed to invoke and interpret this tool correctly.

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

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

Schema description coverage is 100%, so the four parameters are already fully documented in the input schema. The description mentions preview and general delivery behavior but does not add syntax or format details beyond what the schema provides, making the baseline 3 appropriate.

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

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

The description states a specific verb and resource: read this site's start page served at /. It distinguishes clearly from sibling get_content by naming it as the tool for reading drafts. An agent can identify the exact operation without opening the schema.

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

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

It gives explicit usage context: use this to read the public Delivery API view of the start page, and use get_content instead when reading a draft for editing. The published-only / preview distinction further clarifies when this tool is appropriate.

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, but the description adds real context beyond them: the live site is unchanged, the discarded draft is unrecoverable, the document falls back to the published version, and the operation is refused for never-published content. The only minor gap is it doesn't describe the failure/response shape, but the behavioral profile is well disclosed.

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

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

Three tightly written sentences, front-loaded with the core action, then the side-effect/irreversibility, then the refusal condition and alternative. Every sentence earns its place.

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

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

For a destructive mutation with no output schema, the description supplies the fallback semantics, irreversibility, scope (one locale), and the negative case routing, all on top of annotations that cover the safety profile. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100% and each parameter (site, locale, documentId) is fully documented in the schema itself. The description only alludes to the locale parameter scope; it adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (throw away), a precise resource (unpublished draft changes of one locale), and the resulting state (working version falls back to published). It also names the sibling it is not for, so an agent can distinguish it from trash_content 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?

Explicitly covers when to use it (discard draft changes for a locale), the exclusion condition (refused for content that was never published), and the alternative to use instead (trash_content). Nothing about selection is left to inference.

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

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

Annotations only declare the generic non-read-only/non-destructive/non-idempotent profile; the description adds substantive traits: the copy lands in a new unpublished document with a fresh slug so it cannot collide with the original URL, children are NOT copied, and all locale working-version fields are carried over. These are exactly the behavioral details an agent needs and none are recoverable from the annotations.

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

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

Three tightly packed sentences, front-loaded with the core action and followed by the collision/children caveats and the follow-up workflow. 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 3-parameter, no-output-schema duplication tool, the description covers what is created, where it lands, naming, slug safety, child behavior, and the return value plus next action. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the parameter baseline is 3; the description adds meaning by referring to per-locale working versions, clarifying what the locale parameter selects. It does not add syntax detail beyond the schema, but the locale clarification is a genuine increment.

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 (copy/duplicate) plus the exact resource and result shape: a NEW unpublished document beside the original, same parent, named "<name> (copy)", with working-version fields. It also implicitly separates itself from copy_variant by scoping to a whole content item rather than a locale variant, and from create_content by copying existing content.

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

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

Gives clear workflow context ("Returns the new item; edit it, then publish") and states the copy is unpublished, so an agent knows the next steps. It does not explicitly name alternatives (e.g. copy_variant for a single locale version) or the when-not to use this rather than create_content.

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?

Despite annotations already flagging destructiveHint=true, the description adds substantial context: irreversibility, the required submission.manage permission, the return shape {deleted: <count>}, the audit-log behavior (records the erasure, never the address), and the caveat that backup copies persist until rotation. This is rich behavioral disclosure an agent can act on.

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 dense sentences, front-loaded with the core action and then the safety-critical facts (irreversibility, permission, return shape, retention). No filler; each clause carries operational weight.

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 supplies the return shape, plus permission requirements and backup-retention caveats that matter for a destructive bulk operation. An agent has everything needed to invoke this correctly.

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

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

Schema description coverage is 100%, so both parameters are already documented, and the description largely restates the email matching rule ('case-insensitively across all answers'). It adds no new syntax or format detail and does not address the site parameter, so the baseline 3 applies.

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

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

Uses a specific verb (erase/delete) on a specific resource (form submissions) and defines scope precisely: EVERY submission in the active site whose answers contain the email, in any field. This clearly distinguishes it from the sibling delete_form_submission, which targets a single submission.

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 framing 'Data-subject erasure' makes the intended scenario clear, and the email-match semantics imply when this bulk tool is appropriate versus a single-deletion sibling. It stops short of explicitly naming delete_form_submission as the alternative for single-record cases, so no true when-not 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=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the export is audit-logged, requires the submission.read scope, and constitutes a copy of sensitive visitor personal data — all things an agent should weigh before calling.

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

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

Two sentences with no filler: the output contract leads and the sensitive-data/permission caveat follows. Every clause carries information 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?

There is no output schema, so the description correctly compensates by stating the CSV structure and the returned row count. It also covers the auth requirement, leaving little an agent would need to know before invoking it.

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

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

Schema description coverage is 100% and both parameters (site, formId) are fully documented there, including the list_sites/list_forms pointers. The description adds no parameter syntax or scoping detail, so the baseline 3 applies.

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

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

The description gives a specific verb and resource ('Export form submissions') and even specifies the output shape ('as CSV text, one row per submission, one column per field'). It never names a sibling tool, so it stops short of the explicit differentiation a 5 requires.

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 — an agent can infer this is for bulk CSV extraction rather than the JSON-returning list_form_submissions/get_form_submission, but the description says nothing explicit about when to prefer it or when not to use it.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond them: the exact returned document structure ({format, version, exportedAt, templates}) and cross-instance portability, which tells the agent the payload is a migration artifact, not just data. It does not discuss permissions or size limits, keeping it short of a 5.

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

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

Two sentences, zero filler, and the most decision-relevant facts (what the export is and who consumes it) are front-loaded before the scoping note about omitting names.

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 correctly compensates by describing the returned document shape and its intended consumer. Combined with a fully documented input schema and read-only annotations, an agent has enough to call it correctly; only error/edge behavior (e.g., unknown template names) is unaddressed.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: omitting names exports everything and explicitly includes built-ins, clarifying the scope of the schema's '(default: all)'. It adds no further guidance on the site parameter, which the schema handles well.

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

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

Names a specific verb (export) and resource (type templates), and states the exact output artifact: a portable JSON document with a defined shape. It also names the sibling consumer (import_type_templates) so the agent can immediately distinguish it from list_type_templates or get_type_template.

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?

Clear on the key usage decision: omitting names exports everything, including built-ins, and the output is meant to be consumed by import_type_templates on another instance. It stops short of stating when NOT to use it (e.g., use list_type_templates for inspection rather than migration), so it is clear context rather than full routing.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description goes further by disclosing the version-resolution rule (draft if one exists, else published) and enumerating what is returned (name, slug, status, revision, full data map), which is real behavioral context the annotations do not carry.

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

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

Three well-formed sentences, each earning its place: the return shape is front-loaded, then the merge workflow, then the alternative tool. Zero filler.

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

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

For a single-item read with no output schema, the description names the returned fields and the resolution behavior, and covers the mutation workflow it feeds into. An agent has everything required to call it correctly and use its result.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds actionable meaning by tying the returned `revision` value to the subsequent update_content call with merge:false, which is not expressed in the schema and clarifies how the returned fields are meant to be consumed.

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 (content item for editing) with precise scope: the working version, resolving draft-vs-published, in one locale. It explicitly distinguishes itself from the sibling delivery_get_by_id, so an agent can separate the editing view from the delivery view without opening either schema.

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

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

Gives explicit when-to-use guidance ('read this before update_content so you merge into current values') and an exclusion routing the agent to the alternative ('To see what visitors get instead... use delivery_get_by_id'). Nothing about tool selection is left to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real behavioral context beyond that: it returns null for an unknown name and that each field carries valueFormat/valueExample showing the exact JSON create_content/update_content expect.

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

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

Front-loads the resource and its contents, then adds the workflow directive and the null behavior. Dense but each clause earns its place; the parenthetical field list and trailing ellipsis make it slightly unpacked.

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

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

No output schema exists, so the description must describe the return value itself — and it does, including the field shape, value format, and null case. Coverage is strong, though the ellipsis leaves the full field enumeration open.

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 'name' and 'site' are fully documented in the schema (including the multisite gotcha). The description adds nothing about parameter meaning, so the baseline 3 applies.

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

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

States a specific verb ('Get one') and resource ('content type's definition') and then enumerates the exact return surface (name, kind, displayName, schemaType, fields). The singular framing cleanly distinguishes it from the sibling list_content_types.

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

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

Gives a concrete trigger — 'Call this before writing content of a type' — tying it to create_content/update_content. It does not explicitly contrast with list_content_types or get_content, so the alternative-selection guidance is implicit rather than spelled out.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context beyond that: it requires submission.read and describes that the returned submission includes answers with field-label snapshots, the parent form, receipt time, and retention deletion time.

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

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

Two sentences with no waste. The core retrieval behavior and returned content are front-loaded, followed by the concise permission requirement.

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

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

For a simple read-by-ID tool with full schema coverage and annotations, the description is complete. It covers the return payload despite the absence of an output schema, and adds the necessary authorization requirement.

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

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

Schema description coverage is 100%, and both parameters are fully documented in the input schema. The description adds only 'one form submission' and the permission requirement, not additional parameter syntax or format details, so baseline 3 is appropriate.

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

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

States a specific verb ('Get'), resource ('one form submission'), and scope ('in full'), with the singular framing distinguishing it from sibling list_form_submissions and export_form_submissions. An agent can immediately tell this is the single-record read operation.

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

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

The description clearly frames this as retrieving one submission by ID and adds an authorization prerequisite ('Requires submission.read'). It does not explicitly name alternatives such as list_form_submissions for finding IDs, but the single-record context and schema reference to list_form_submissions make usage clear.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so 'Read-only' in the description is largely redundant. It does add useful meaning about the returned values (startPageId may be null, previewBaseUrl is the admin preview origin), but says nothing about permissions, error states, or default-site fallback when site is omitted.

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 that defines both returned fields and closes with the safety trait. No filler or redundancy; every clause carries information.

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

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

With no output schema, the description usefully explains the two config fields an agent will receive, and the schema handles the sole parameter. It is nearly complete for a simple read tool, though it omits any note on behavior when the site is unknown or lacks a configured start page.

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, including the multisite fallback and the list_sites hint. The description adds no parameter-level detail, so the 3 baseline for high coverage applies.

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

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

The description gives a specific verb+resource (get this site's configuration) and enumerates the exact fields returned (startPageId, previewBaseUrl), so an agent knows precisely what it fetches. It does not explicitly differentiate itself from adjacent siblings like set_start_page or list_sites, which keeps 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?

There is no when-to-use guidance, no stated prerequisites, and no named alternatives. The agent is left to infer that this is the read counterpart to set_start_page. Only the implicit context of 'configuration' hints at usage.

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

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

With readOnlyHint=true and openWorldHint=false already covering the safety profile, the description adds useful return-shape context: full ContentTypeDef fields annotated with valueFormat + valueExample, and that templates may be stored or built-in. It does not add permission, rate-limit, or error behavior details.

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

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

The description is two tight sentences with no wasted words. It front-loads what the tool returns, then immediately gives the intended usage context.

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

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

Given no output schema, the description adequately explains what an agent receives: a full ContentTypeDef with per-field valueFormat and valueExample annotations. The input schema already covers parameter details, so the definition is complete for calling this read-only lookup tool.

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

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

Schema description coverage is 100%, so the name and site parameters are already documented in the schema. The description only restates that lookup is by name and does not add additional parameter semantics beyond the schema.

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

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

The description states a specific verb and resource: get one type template's full ContentTypeDef by name, including stored or built-in templates. It distinguishes this one-template read from siblings like list_type_templates and make_type_template by emphasizing the full definition and field annotations.

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

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

It clearly names two use cases: inspecting a template before instantiate_type_template and using it as a starting definition for create_content_type. However, it does not explicitly state when not to use it or contrast it directly with list_type_templates.

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

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

Annotations declare the mutation/external-network profile (readOnlyHint=false, openWorldHint=true), and the description adds genuinely useful behavior beyond that: it downloads the image, stores it as a regular asset, and attaches alt text + attribution. It does not spell out that repeat calls create duplicate assets (non-idempotent), so it stops short of a 5.

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

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

Two dense sentences that front-load the operation, then the mechanics, then the downstream instruction. No filler and nothing repeated from structured fields.

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

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

For a 3-param mutation with no output schema, the description covers purpose, side effects, and the follow-up step well enough to invoke correctly. The one gap, that importing the same providerId twice yields duplicate assets, is partially mitigated by the idempotentHint=false annotation.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters (alt override, site, providerId). The description's phrase 'by the id from search_stock_images' adds provenance for providerId, but the rest adds no meaning beyond the schema, so baseline 3 holds.

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 (import), resource (stock photo), and destination (the media library), and ties the input source directly to the sibling search_stock_images. It is clearly distinguishable from upload_asset and search_stock_images without opening any schema.

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

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

It establishes the workflow context (get the id from search_stock_images, then set the returned documentId with set_field), which tells the agent where this sits in the chain. It stops short of any when-not guidance or explicit exclusions versus alternatives like upload_asset.

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

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

Annotations only supply the generic write profile (readOnly=false, destructive=false, idempotent=false). The description adds real behavior beyond that: per-template create/skip outcomes, the built-in-name skip policy, and the overwrite gate. It does not mention permissions or the 200-item cap, so not a 5.

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

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

Three tight sentences with the core action front-loaded, followed by outcome semantics and return shape; every clause carries information and none is padding.

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

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

With no output schema, the description usefully discloses the return shape {created, updated, skipped:[{name, reason}]} and the built-in skip rule, which are the facts an agent needs before calling. It omits error/limit behavior (e.g., the 200-template max), keeping it just short of complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description hints at overwrite's effect ('existing stored templates are skipped unless overwrite: true'), which mildly enriches the schema's own wording, but it adds nothing for site or templates. Baseline holds.

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 ('Import') and resource ('type templates') plus the source ('from an export document'), which cleanly separates it from create_type_template and its natural counterpart export_type_templates. An agent can identify the operation without opening the schema.

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

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

It establishes the context of use (bulk restore from an export document) and the conditional rule for overwrite:true, but never names export_type_templates as the producing sibling or states when to prefer per-template creation instead. Context is clear; alternatives are left implicit.

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

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

Adds substantial behavior beyond the annotations: the default action, the 409 refusal on name collision, the kind-match prerequisite for updateExisting, the explicit note that existing content is not migrated, and the recursive, non-overwriting semantics of withBlocks. The annotations only declare it is a non-read-only, non-idempotent, non-destructive write; the description supplies the failure modes and side effects an agent needs.

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

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

Front-loads the default behavior before the exception branches, and each clause covers a distinct decision the caller must make. It is dense and uses heavy capitalization for emphasis, but the length is justified by the number of distinct branches; nothing reads as 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?

Covers creation, collision handling, naming, and block dependencies for a 5-parameter write tool, which is nearly everything needed. The one gap is that with no output schema present, the description never says what is returned (e.g., the new type's id/kind), so the caller cannot tell how to reference the created type afterwards.

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 meaning beyond the schema: the asName regex ^[A-Z][a-zA-Z0-9]*$ with a worked example, and the clarification that withBlocks recurses and leaves existing types untouched. The 'kind must match' constraint on updateExisting is likewise not in the schema description.

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

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

States a specific verb and resource: 'Materialise a type template into a real content type.' This clearly distinguishes it from the sibling template-authoring tools (create_type_template, update_type_template) and from create_content_type, which makes a type from scratch rather than from a template.

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

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

Gives explicit when-to-use conditions for each mode: default creation, updateExisting: true when the type already exists, asName when a different name is wanted, and withBlocks for built-in templates like FaqPage. It does not name sibling tools as alternatives, but the branching guidance is concrete enough that an agent knows which parameters to set in which situation.

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

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

Annotations already establish the safety profile (readOnlyHint=true, openWorldHint=false), so the description's added value is the returned-field inventory, the documentId/set_field relationship, and the write-path alternatives. It doesn't mention pagination or result limits, which is the remaining gap for a listing 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?

Front-loaded with the core action and scope, then dense but useful detail. The field enumeration is long but earns its place since there is no output schema; no filler sentences.

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 one fully documented parameter and no output schema, the description usefully substitutes for a return-schema by naming the asset fields. Only pagination/ordering behavior is 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 100% and the single 'site' parameter is fully documented in the schema, including the list_sites pointer and the empty-tree troubleshooting hint. The description adds nothing about the parameter, so the baseline 3 is correct.

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

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

States a specific verb ('List') and resource ('this site's media library (images and PDFs)'), then enumerates exactly which fields are returned. An agent can distinguish this read/list tool from the write-path siblings without opening any schema.

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

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

Explicitly routes the agent away from this tool for writes by naming three alternatives (upload_asset, create_upload_link, import_stock_image), and clarifies the cross-tool relationship with set_field. It doesn't spell out when to prefer this over any other listing, but no close sibling list tool exists, so the guidance is effectively complete.

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

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

Beyond readOnlyHint/openWorldHint it discloses the log is append-only, that results are ordered newest-first, that the actor's surface is recorded (ip 'mcp' = agent), and a non-obvious auth constraint — a token scoped to a single site cannot use it. That auth detail is exactly the kind of failure mode an agent would otherwise hit blind.

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

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

Three compact sentences, front-loaded with what it returns before the use case and the auth requirement. Dense with signal and free of 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 an 8-parameter read tool with no output schema, the description covers return content (actor, action, time, document, surface), ordering, and auth. Paging mechanics and default row limits are not addressed, but the schema documents those adequately.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds only indirect value: the action examples ('create, publish, delete, login, export…') hint at the vocabulary the 'action' prefix parameter expects, and 'newest first' motivates the 'before' cursor, but the cursor and limit behavior are left entirely 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?

States a specific verb and resource ('Read the append-only audit log') plus the ordering ('newest first') and the record shape ('who did what... when, to which document, from which surface'). No sibling tool does audit-log reading, so an agent can select it unambiguously.

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 it to find out who changed something' gives a concrete triggering scenario, and the prerequisite ('Requires audit.read and a token not limited to one site') is stated explicitly. It stops short of naming an alternative or a when-not-to-use case, but no sibling offers overlapping capability.

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

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

The readOnlyHint annotation already establishes this is a safe read, but the description goes further by explaining the shared-reference semantics (one edit updates every page using them) and enumerating the returned fields (documentId, type, name, per-locale status, folderId). That return-shape disclosure is genuinely valuable given there is no output schema.

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

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

Three sentences, front-loaded with the core purpose, then the return shape, then the edit path, then the exclusion. Every sentence carries distinct information with no repetition of the name or structured fields.

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

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

For a single-parameter, read-only list tool with no output schema, the description covers purpose, the crucial shared-vs-inline distinction, the returned fields, and the follow-up editing path. Nothing essential for correct invocation 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?

There is only one parameter (site) and schema description coverage is 100%, so the schema already documents it fully, including the multisite default behavior and the list_sites pointer. The description adds only the implicit 'this site's' scoping; baseline 3 is appropriate.

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

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

States a specific verb (list) and resource (shared/reusable blocks), and immediately disambiguates from inline blocks — a real distinction an agent would otherwise miss. It also names the representative subtypes (banners, forms, CTAs), making it distinguishable from siblings like list_pages and list_globals.

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

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

Provides a clear exclusion (inline blocks are not listed here) and routes the agent to the correct follow-up tools for modification (get_content/update_content on documentId). It does not explicitly contrast against other list tools such as list_globals or list_pages, so it stops short of full when/when-not guidance.

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false), but the description adds real behavioral context the annotations do not: the call is expensive ('Large') and its results are instance-wide ('shared by all sites'), which warns the agent against expecting a small, site-scoped payload. It stops short of stating pagination or size limits, so not a 5.

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

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

Front-loaded with the purpose and return shape, then the routing hint; no filler sentences. The heavy em-dash chain in the first sentence makes it dense but every clause carries information (scope, fields, field annotation keys).

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 correctly carries the burden of describing return values, and it does: type name, kind enum, and per-field valueFormat/valueExample described as 'the JSON shape update_content expects,' which also connects it to the downstream mutation tool. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100% for the single `site` parameter, so baseline is 3. The description earns an extra point by clarifying that content types are shared across all sites, which explains why `site` has limited filtering effect here — a nuance the schema text does not convey.

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

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

States a specific verb and resource ('List every content type in the instance') and goes further by enumerating the returned shape: name, kind (page | block | global), and fields with valueFormat + valueExample. It also distinguishes itself from the sibling get_content_type, so an agent can choose between them 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?

Explicitly gives the alternative and the condition that selects it: 'Large; when you already know the type, get_content_type returns just that one.' That is a when-to-use and when-not-to-use rule in a single clause.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations: it states that the operation is 'Admin only' and warns that 'Secrets are never shown again after creation,' which is important for an agent to understand the scope and security limitations of this read operation.

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

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

The description is compact and front-loaded: it starts with the core action and resource, then appends the returned fields and important caveats. Every phrase earns its place, and there is no redundant or filler language.

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

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

For a simple, read-only, single-optional-parameter tool with no output schema, the description is complete enough. It lists the fields returned (id, name, type, timestamps), notes the admin-only requirement, and explains that secrets are not retrievable, covering what an agent needs to invoke and interpret the tool correctly.

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

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

Schema description coverage is 100%, and the single 'site' parameter already has a detailed schema description covering multisite behavior, defaults, and a pointer to list_sites. The description adds no additional syntax or semantics for the parameter, so the baseline of 3 is appropriate when the schema does the heavy lifting.

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

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

The description uses a specific verb ('List') and resource ('this site's Delivery API keys'), then explains what those keys are: 'the credentials a website uses to read content.' It also enumerates the returned fields (id, name, type, timestamps), making the tool's purpose unambiguous and easy to distinguish from sibling delivery-key tools like create_delivery_key or revoke_delivery_key.

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

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

The description provides one clear usage constraint ('Admin only') and hints that secrets are not retrievable after creation, which implies this tool is for reviewing existing keys rather than creating them. However, it does not explicitly state when to use this tool versus alternatives such as create_delivery_key, rename_delivery_key, or revoke_delivery_key, leaving sibling 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?

Annotations already establish readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful non-annotation context: that returned data includes submission counts/last-submission timestamps, and that the data touches visitor personal data behind an Admin/Editor permission. It doesn't discuss pagination or limits, but it goes well beyond restating the annotations.

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

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

Three sentences, front-loaded with the resource and return fields, followed by the routing rule and then the permission/sensitivity note. Every sentence carries distinct, actionable information 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?

With no output schema, the description compensates by enumerating the returned fields. It also covers permission requirements, data sensitivity, and relative ordering versus sibling form tools, while the schema handles the site-default behavior. An agent has everything needed to call this correctly.

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

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

Schema coverage is 100% and the single 'site' parameter is documented in the schema with multisite/default-site guidance and a pointer to list_sites. The description adds nothing about the 'site' parameter, so the schema carries the full burden and baseline 3 applies.

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

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

Specific verb+resource ('List the forms (Form blocks) in this site') and it enumerates the fields returned (formId, name, submission count, last submission time). It clearly distinguishes itself from sibling tools like list_form_submissions and export_form_submissions by positioning itself as the enumeration step.

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

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

It explicitly says to use this 'before list_form_submissions or export_form_submissions', giving the agent a clear entry-point rule, and it names the required permission (submission.read, Admin/Editor) with the reason (visitor personal data). Both the when-to-use condition and the prerequisites are stated.

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

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

Annotations give readOnlyHint, but the description adds genuinely new behavioral context: newest-first ordering, pagination, a permission requirement ('requires submission.read' for visitor personal data), and the important snapshot semantics where labels reflect submission time and resist later form edits.

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 core list scope, then behavior, then the alternative. Every sentence adds distinct value 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?

No output schema exists, yet the description covers what comes back (submissions with historical field-label snapshots), ordering, and paging. Combined with full schema coverage and readOnly annotations, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so all four parameters (site, limit, formId, offset) are already documented in the schema. The description adds nothing per-parameter, so the baseline 3 applies.

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

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

States a specific verb and resource ('List form submissions') plus scope ('in this site') and ordering ('newest first'). It also implicitly distinguishes itself from export_form_submissions and get_form_submission by describing itself as a paged list rather than a file or a single record.

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

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

Explicitly routes the agent to export_form_submissions when a file copy is wanted, and states the paging model ('one page at a time'). It does not mention get_form_submission for single-record retrieval, so guidance is clear but not exhaustive.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds meaningful context that globals live outside the page tree, are not blocks, and behave like ordinary documents for editing. It does not cover return shape or ordering, but as a list tool with annotations the bar is low.

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, zero filler: the identity/scope comes first, then the crucial structural fact, then the editing route. Every clause earns its place.

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

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

For a read-only enumeration tool with annotations covering safety and a fully documented parameter, the description supplies the key structural insight (globals are not in the tree/blocks) plus editing guidance. The only mild gap is the absence of any return-shape note, though the examples imply the item type.

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 (including the multisite default and the list_sites hint). The description adds no parameter-level detail, so the baseline 3 applies.

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

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

States a specific verb (List) and resource (this site's global singletons), with concrete examples (header, footer, site settings). It explicitly differentiates from sibling concepts by noting globals are NOT in the page tree and are not blocks.

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

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

Explicitly says this is the only way to enumerate globals, ruling out list_pages/list_blocks/tree for this content type, and it routes the agent to the follow-up editing tools (get_content/update_content/set_field on the documentId), matching 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 readOnlyHint=true and openWorldHint=false. The description adds useful behavioral context beyond that: locales are 'enabled', returned 'in order', one is the default, and each content item has one variant per locale. It does not contradict the annotations, though it omits details like auth needs or exact return 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 tight sentences, with the core purpose front-loaded and the usage note immediately after. Every clause carries useful 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?

For a simple read-only list tool with no output schema, the description covers purpose, ordering, default-locale behavior, and the downstream use of the returned codes. The schema fully covers the only parameter, so nothing critical is missing.

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

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

Schema description coverage is 100%, and the single `site` parameter is fully documented in the schema itself. The description adds no parameter-level meaning beyond what the schema provides, so the baseline of 3 applies.

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

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

The description gives a specific verb and resource — 'List the enabled locales (language branches)' — and adds scope details (enabled, ordered, default locale). It is clearly distinguishable from all siblings, none of which deal with locale enumeration.

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 tells the agent what to do with the result: 'pass these codes as `locale` to other tools so text lands in the branch matching its language.' That is clear contextual guidance for a read-only helper tool. It does not state when not to use it, but no sibling alternative exists for this purpose.

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

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

Annotations already establish readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real behavioral detail beyond that: result ordering (most hits first), the normalization rule (path only, no query string), and how to interpret the coveredBy field. It stops short of explaining volume/pagination limits.

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

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

Three compact sentences, front-loaded with what the tool returns and followed by field interpretation and a call to action. Nothing is padded, though the final imperative is guidance rather than description of the tool itself.

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 usefully documents the returned shape (path, coveredBy) and ordering, which is what an agent needs to act on results. The only real gap is the absence of any pointer to the sibling tools that consume this output (create_redirect / test_redirect).

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

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

Only one optional parameter (site) exists and the schema describes it at 100% coverage, including the multisite default behavior and the pointer to list_sites. The description adds nothing about parameters, so the baseline 3 for schema-carried semantics 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 resource ('paths that answered 404 on the frontend') with a clear scope qualifier ('most hits first'), which is directly distinguishable from sibling list_redirects (redirect rules) and list_pages/list_content. An agent can tell what this returns without opening the schema.

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

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

It implies the follow-up action ('Create a redirect for the ones with real traffic'), which hints at why you'd call it, but never states when to use this versus list_redirects or test_redirect, nor any prerequisite like checking for an existing covering rule first. Usage is inferable but not explicit.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds useful behavioral context beyond that: the result is a single unscoped flat array (no tree walking), and it enumerates the returned fields including per-locale status. It does not contradict the annotations.

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

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

Two sentences, zero waste, with the scope and output shape front-loaded before the routing advice. Every clause earns its place.

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

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

For a single-param read tool with no output schema, the description compensates by describing the array shape and its fields (documentId, name, type, parentId, per-locale status). Combined with annotations covering the safety profile, an agent has everything needed to call it correctly.

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

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

There is only one parameter ('site') and schema coverage is 100%, so the schema already fully documents it, including the multisite fallback and the 'call list_sites' tip. The description adds nothing about the parameter, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb and resource ('List EVERY page you can see in this site') and pins down the output shape as 'one flat array'. It explicitly distinguishes itself from the 'tree' sibling, so an agent can choose without inspecting either schema.

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

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

Gives affirmative conditions ('find a page by name or to pick a parent/reference target') and a named alternative with its own use case ('use tree to see one level in display order'). This is explicit when-to-use plus when-to-use-the-other-tool routing.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description nonetheless adds genuinely non-obvious behavior: redirects only resolve on the frontend when no published page answers the path, and it enumerates the problem classes the output reports. No pagination or return-format detail, which keeps it below 5.

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

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

Three dense sentences, front-loaded with the core action and exposed fields, then the routing semantics, then the filter hint. Every clause carries distinct information 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 read-only list tool with two optional parameters and no output schema, the description supplies the return shape (live URL, hit counts, problem categories) and the resolution semantics. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100%, so both parameters are already well documented (site slug/id, targetDocumentId filter). The description still adds interpretive value by framing targetDocumentId as 'which old URLs point at one page', clarifying the intended use beyond the schema's literal wording.

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 the site's redirect rules') and goes further by naming the returned diagnostics (target-missing, target-unpublished, shadowed, chain, loop). An agent can immediately distinguish this read from siblings create_redirect, update_redirect, delete_redirects and test_redirect.

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

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

It gives a semantic context ('rules apply on the frontend ONLY where no published page answers the path') and a param-directed use case ('Pass targetDocumentId to see which old URLs point at one page'). However, there is no explicit when-to-use-vs-alternatives guidance (e.g., versus test_redirect or list_not_found), so selection is only implied.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real insight beyond that: the server is pinned to ONE site (PAPERBOY_SITE) and content in other sites is invisible to every tool here, which explains apparent empty results.

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

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

Two sentences, both earning their place, with the core purpose front-loaded and the diagnostic caveat following directly. No padding 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?

For a no-required-parameter read-only list tool with no output schema, the description covers purpose, scope, and the main failure mode. It could say more about what the returned site list looks like, but nothing essential to calling it correctly is missing.

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

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

Schema coverage is 100% and the single 'site' parameter is fully documented, including the 'omit to use default' behavior. The description largely restates that guidance rather than adding syntax, format, or edge-case detail beyond the schema.

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

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

States a specific verb and resource ('List the sites in this instance') and adds a distinguishing behavior ('say which one this server acts in') that no sibling offers. An agent can tell it apart from get_site_config or tree without opening another schema.

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

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

Gives clear context for when to reach for it: diagnosing empty trees or searches caused by the wrong site. It does not name an alternative tool or an explicit 'do not use this when' condition, so it falls short of a full 5.

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

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

Annotations already establish this as a safe read (readOnlyHint=true, openWorldHint=false), so the behavioral bar is lower. The description adds useful context by enumerating the returned fields (documentId, type, kind, name, deletedAt) and scoping visibility to the current site, but says nothing about ordering, pagination, or limits.

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

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

Two short sentences, front-loaded with the core action and terminating with an actionable next step. No filler or redundancy.

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

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

With no output schema, the description correctly compensates by listing the returned fields, and the single parameter is fully documented in the schema. For a read-only list tool this is nearly complete, lacking only ordering/limit 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 coverage is 100% and there is a single optional 'site' parameter whose schema description already explains multisite behavior and the list_sites fallback. The description's 'in this site' phrasing echoes the schema rather than adding new semantics, so baseline 3 applies.

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

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

The description states a specific verb and resource ('List the trashed content') and scopes it ('you can see in this site'), so the agent knows exactly what it does. It also names returned fields, but does not explicitly contrast itself with nearby siblings like tree or trash_content.

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 mention of 'Use the documentId with restore_content' points to the downstream restore flow, which suggests this is the discovery step before restore. There is no explicit when-to-use/when-not guidance or named alternative among the many list_* siblings.

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 and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that: built-ins are included in the result and are read-only, and the template name maps to the materialised content type name — both useful traits an agent can't get from the annotations.

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

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

Three tight declarative sentences, zero filler, and the core definition is front-loaded before the built-in/stored distinction. Every sentence contributes 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 read-only list tool with no output schema, the description adequately explains what the result contains and how to interpret template names. Return format details (pagination, ordering, field shape) are absent but not critical given the annotations and the tool's simplicity.

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' param is well documented in the schema, including the multisite fallback and the list_sites hint. The description adds nothing about the parameter, so the baseline 3 applies.

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

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

Specific verb (List) plus resource (content-type templates) and an explanatory gloss defining what a template is ('named ContentTypeDef recipes'). It also distinguishes the two categories returned (BUILT-IN library vs stored templates), which helps separate it from get_type_template (singular) and list_content_types (materialised types).

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: an agent infers this is the enumeration step before instantiate_type_template or get_type_template, but the description never states when to use it versus those siblings or any precondition. No when-not 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 declare readOnlyHint=true and openWorldHint=false, so the safety profile is already covered; the description adds the previously unstated authorization requirement (user.manage / Admin) and reveals the full return shape in the absence of an output schema. It stops short of disclosing pagination or result caps for what claims to be an instance-wide listing.

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

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

Two sentences, zero waste: the identity and return shape come first, the authorization prerequisite second. Nothing is repeated or padded.

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

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

With no output schema, the description usefully compensates by naming the returned fields, and it discloses the permission gate. It is nearly complete for a zero-required-param read tool, missing only notes on result limits or pagination for a potentially large instance-wide listing.

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 already carries a rich description (multisite behaviour, default site, pointer to list_sites). The description adds nothing about the parameter, so the baseline 3 for schema-does-the-work applies.

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

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

States a specific verb (List) with a precisely scoped resource (every CMS user account, instance-wide) and even enumerates the returned fields (id, email, name, roles, section scopes, locked flag, createdAt). It is unambiguously distinct from the sibling mutation tools create_user, update_user and delete_user by verb alone.

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

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

Usage is implied by the verb and the stated prerequisite 'Requires the user.manage permission (Admin)', which is a genuinely useful gating condition. However, it never says when to reach for this tool versus an alternative, and there is no guidance on filtering, scoping or pagination behaviour to help an agent decide how 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, covering the safety profile. The description adds useful behavioral context beyond annotations: it specifies ordering ('newest first') and details the returned fields (id, versionNumber, status, live flag, name, creator, timestamp), which is important since there is no output schema.

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

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

Two tightly written sentences with zero waste. The core action and output fields are front-loaded, and the follow-up action (rollback via restore_version) is presented efficiently as a second sentence.

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

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

For a read-only list tool with no output schema, the description compensates by explicitly enumerating the returned fields and the ordering. It also covers the key downstream integration (restore_version), making the definition complete for an agent to use correctly.

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

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

Schema description coverage is 100%, so the schema already fully documents site, locale, and documentId. The description reinforces that the listing is scoped to one locale, but adds no new syntax, format, or default behavior beyond what the schema provides. 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 states a specific verb ('List') and resource ('version history') with clear scope ('in one locale, newest first') and enumerates the returned fields. It distinguishes itself from siblings like get_content (current content) and restore_version (action) by focusing on version history retrieval.

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

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

It provides clear context: use this to see a content item's version history, and then pass a version's id to restore_version to roll back. It doesn't explicitly state when to use this versus alternatives like get_content, but the downstream action clarifies the primary use case.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds two pieces of context beyond that: an auth requirement ('Admin only') and a data-redaction behavior ('Secrets are not shown'), which tells the agent not to expect secret values. It stops short of describing pagination or result limits.

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 resource and its returned fields, followed by two short caveats. Every clause earns its place and nothing is padded.

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

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

With no output schema, the description compensates by naming the returned fields, and it discloses both the auth requirement and the secret-redaction behavior. Only minor gaps remain, such as pagination or ordering of results.

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 there, including the list_sites fallback advice. The description adds nothing about the site parameter, so the baseline 3 applies.

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

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

States a specific verb and resource ('List this site's outbound webhooks') and enumerates exactly what is returned: id, name, target url, subscribed events, status. The list/create/delete distinction against siblings create_webhook and delete_webhook is unambiguous from the verb alone.

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

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

No explicit when-to-use statement or comparison to alternatives; usage is only implied by the verb. It does supply a real prerequisite ('Admin only'), which constrains who may call it, but there is no guidance on scoping or when to prefer this over, say, audit tools.

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

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

Annotations cover the safety profile (readOnly=false, destructive=false, idempotent=true) but say nothing about side effects; the description adds substantial unannotated behavior: URL path changes, automatic 301 on the old URL, whole-subtree movement, and the sort-mode dependency. These are exactly the traits an agent needs before mutating content.

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

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

Front-loads the core action and parameter roles, then layers behavior and edge cases in dense, waste-free sentences. Nothing is redundant and the return claim is tacked on efficiently.

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

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

No output schema exists, and the description supplies the return shape ({ok:true}) as well as the side-effect and sort-mode caveats. An agent has everything needed to invoke this mutation correctly and predict its effects.

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 interaction semantics the schema does not: it explains how parentId and beforeId/afterId combine ('and/or') and that the subtree follows. This goes beyond the per-field descriptions, justifying a 4.

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

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

States a specific verb (move) and resource (a page in the tree) and immediately distinguishes the two operation modes: re-parenting via parentId vs. sibling placement via beforeId/afterId. An agent can tell this apart from update_content without opening the schema.

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

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

Gives clear context for when each parameter applies (give parentId to re-parent, and/or beforeId/afterId to place among siblings) and warns about the manual-vs-computed sort caveat. It does not explicitly rule out alternative siblings (e.g. update_content) or state prerequisites, so it stays short of a 5.

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

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

Annotations only say it is a non-read-only, non-destructive, non-idempotent write. The description goes well beyond that: a future publishAt leaves the draft unpublished and invisible to readers until go-live, surfaces it under Scheduled publishing, and re-invocation reschedules. It also discloses the language-mismatch refusal gate and its override, which is real behavioral context no structured field carries.

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?

Purpose is front-loaded, then the language-branch hazard, then scheduling, rescheduling, and a final warning. Every sentence carries distinct operational information and the capitalized emphasis flags the two highest-risk misinterpretations without padding.

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

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

For a 6-parameter mutation with no output schema, the description covers the important failure and side-effect modes (mismatch refusal, invisible-until-scheduled, reschedule). It does not describe what a successful call returns or any error shape, but with annotations covering safety and the schema fully documented, the remaining gap is minor.

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 genuine meaning beyond it: 'locale' is characterized as a LANGUAGE BRANCH with concrete failure semantics, and allowLanguageMismatch is explained as a deliberate override. publishAt's scheduling (not immediate-publish) semantics are clarified. expireAt is left entirely to the schema, which documents it 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 ('Publish the working draft of a content item for a locale'), which cleanly separates it from siblings like unpublish, discard_draft, and update_content. The scope (working draft, per-locale branch) is precise enough that an agent can select it without opening any schema.

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

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

Gives clear when-to-use context: with publishAt it schedules, without it goes live now, and re-calling either reschedules or publishes. It also supplies an explicit when-not ('NEVER fake scheduling by putting the date in a data field'). It never names the natural alternatives (unpublish, discard_draft, update_content), so sibling routing is left to inference.

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