Paperboy CMS

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

Annotations declare readOnlyHint=true/openWorldHint=true, and the description is consistent ('It saves nothing'). Beyond that it adds substantial context the annotations cannot: the {result, provider} return shape, the truncation fallback when no model is configured, which tasks are refused and why, and the permission requirements. No contradiction with readOnlyHint since nothing is persisted.

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?

Dense but front-loaded: capability list first, then the critical 'saves nothing' contract, then fallbacks, then the alt-text exception, then permissions. Every sentence carries 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?

For a multi-task generation tool with no output schema and open-world behavior, the description covers return values, persistence contract, model dependency, refusals, alternative tools, and access control. 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, but the description adds meaning beyond the schema: it clarifies that 'variants' yields a JSON array of exactly 3 strings, that write expects a topic/brief, and that alt_text is refused. These operational details about parameter behavior are not fully derivable from the enum listing alone.

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

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

States a concrete verb+resource ('Run the CMS's writing assistant on a piece of text') and then enumerates the actual task space (SEO text, summaries, polishing, rewrites, variants, translation, drafting, schema.org fields). This clearly separates it from sibling content tools like set_field or update_content, which persist rather than generate.

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: 'It saves nothing — write the result with set_field or update_content' and 'write that yourself and save it with update_asset_alt'. It also states the precondition for the model dependency and the permission/role scope (Author limited to their own sections), plus which tasks are refused.

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 flag destructiveHint=true and non-idempotent; the description goes well beyond, disclosing exactly what is destroyed (the target locale's draft and its unpublished edits), what survives (published version stays live until publish_content), that the copy is verbatim text, and the auth requirement (content.update with role-scoping details). This is rich behavioral context beyond structured fields.

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

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

Dense but every sentence earns its place: core action front-loaded, then destruction semantics, then translation follow-up, then return shape, then alternative tool, then permissions. No filler despite the length.

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 states the return value ('target locale's new draft in the get_content shape'). Combined with the disclosed destructive behavior, permissions, and sibling routing, 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 are already documented (site, toLocale, documentId, fromLocale). The description adds usage context — text copied as-is, translate via assist_writing — but no per-parameter syntax or value detail beyond the schema. Baseline 3 is appropriate when the schema carries the parameter burden.

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

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

States a specific verb (copy), resource (a document's working version) and scope (name, slug, EVERY field; locale-to-locale; server-side and atomic). It explicitly distinguishes itself from duplicate_content (new item) and contrasts with re-typing field by field, so an agent can tell it apart from siblings 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 an explicit when: 'USE THIS to move content that landed in the wrong language branch'. Names alternatives with conditions — duplicate_content for a new item, assist_writing/set_field for translating the copy. When-to-use and when-to-use-something-else are both covered.

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

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

Annotations cover only the safety hints (not read-only, not idempotent, not destructive), so the description carries the real behavioral burden and does so: the item is created as an unpublished draft, missing `data` yields an empty shell until update_content/set_field fills it, a type mismatch is refused, and the response includes a `hint` when filling/placing is still needed. It also discloses the permission model (content.create; Author limited to their own sections), which annotations do not.

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-call contract, then ordered by decision relevance (data → placement → type → return → next step → alternative → permissions). It is long and dense for a single paragraph, but nearly every clause carries decision-relevant information rather than 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 states the return shape (the get_content shape: documentId, locale, revision, data) plus the conditional `hint`. Combined with the placement, type-inheritance, locale-matching and permission guidance, an agent has everything needed to invoke this 9-parameter tool correctly and interpret the result.

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

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

Schema coverage is 100%, so the schema already documents each parameter and the 3 baseline would apply on its own. The description nonetheless adds cross-parameter meaning beyond the schema: parentId determines a page's URL and rendering template, `type` is inherited under a list page and refused on mismatch, and locale is framed as the language branch that must match the content language. That is genuine added semantics over the per-field schema text.

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

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

States a precise verb and resource ('Create a new content item (page, block or global)'), including the resulting state (unpublished draft) and the one-call filling behavior. It explicitly names the alternative for copying (duplicate_content) and the follow-up (publish_content), so an agent can place it in the workflow without opening a schema.

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

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

Gives concrete when-to-use rules: pass `data` to get a filled draft, call list_content_types first for shapes, use list_tree to find parentId (blog posts under their blog page), omit parentId only for top-level sections, omit `type` under a list page, and use duplicate_content to copy an existing item. Exclusions and failure conditions (type mismatch refused) are stated rather than 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 only assert a non-read-only, non-destructive, non-idempotent write; the description goes well beyond them by disclosing the 15-minute expiry, the multipart/form-data POST with a returned header, per-file and per-request limits (5 MB, 20 files), supported formats, the PUBLIC_URL refusal condition, and the required content.create permission with role scoping.

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

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

The purpose is front-loaded in the opening clause, and the remaining text is information-dense with no filler: each sentence contributes a usage rule, a constraint, or a follow-up step. Nothing here could be removed without losing an operational detail.

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

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

Despite having no output schema, the description enumerates the exact response shape ({uploadUrl, headers, expiresAt, example, limits}), the accepted media types, size/count limits, auth requirements, and the refusal/fallback path. For a single-parameter tool with safety already covered by annotations, this leaves nothing an agent needs unstated.

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

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

With a single parameter at 100% schema description coverage, the baseline is 3. The description adds actionable meaning beyond the schema by clarifying the multisite behavior ('The link uploads as you, into this site (pass `site` to upload into another)'), which gives an agent the reason to set the parameter.

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

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

The first sentence states a specific verb and resource ('Get a 15-minute link for uploading LOCAL files ... into the media library') and immediately frames its niche versus the nearest sibling by contrasting local-machine files with the server's inability to read them. 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?

It explicitly names when to use this tool (files on your own machine), when not to (public URL or stock photo -> use upload_asset instead), and the fallback condition (server has no PUBLIC_URL configured -> upload_asset with dataBase64). It even cross-references set_field and update_asset_alt for the follow-up steps.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description goes well beyond them: irreversible, row plus stored file both removed, dangling references are not blocked and silently resolve to null, and it names the required permission (content.delete, Admin/Editor). This is behavior an agent cannot infer from the schema or hints.

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?

Every sentence earns its place: identity disambiguation, irreversibility, the dangling-reference consequence, the set_field alternative, the return shape, and the permission. Front-loaded with the destructive core before the caveats.

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

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

Covers everything an agent needs for a destructive, no-output-schema tool: what is destroyed, that it cannot be undone, the orphan-reference side effect, the safe alternative, the return value ({ok:true}), and the permission required. Nothing material is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning by specifying that documentId must be the asset's id from list_assets rather than a page's id — a distinction the schema description only partially conveys. The 'site' parameter's multisite behavior is 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 ('Permanently delete a media asset'), then immediately disambiguates which identifier to pass ('the asset's documentId from list_assets, not a page's'), routing the agent away from a common mix-up with sibling tools like get_content/list_assets.

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 the alternative path: 'To stop using an image on one page, just clear that field with set_field and keep the asset' — a clear when-not-to-delete rule naming the sibling tool. It also prescribes the prerequisite action ('clear or replace them first') before deleting referenced assets.

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 destructiveness, but the description adds critical context beyond them: the live site is unchanged, the discarded draft cannot be recovered, the operation is refused for never-published content, the exact permission required (content.update) with role nuances, and the return shape ({ok:true}). This is rich behavioral disclosure that goes well beyond the structured hints.

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

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

The description is a single dense paragraph that front-loads the core action, then layers consequences, refusal conditions with alternatives, return value, and permissions. Every sentence carries essential information with no wasted words.

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

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

For a destructive mutation tool with no output schema and full parameter coverage in the schema, the description covers all an agent needs: what it does, side effects, irreversibility, refusal condition, alternatives, required permissions, and return value. 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%, so the schema already documents all three parameters. The description repeats the locale omission behavior and clarifies documentId's role, but adds no new syntax, format, or edge-case details beyond what the schema provides. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description states a specific verb ('Throw away') and resource ('unpublished draft changes of one item') with clear scope ('in one locale'). It explicitly differentiates from siblings by naming trash_content for never-published content and restore_version for rolling back to older versions, 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?

It provides explicit when-to-use context (discard draft to fall back to published), when-not (refused for never-published content — use trash_content instead), and an alternative for a related goal (restore_version for older versions). Nothing 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 cover the safety profile (readOnly=false, destructive=false, idempotent=false). The description adds substantial behavior beyond them: children are not copied, pages get a fresh slug that never collides with the original URL, locale affects only which language is returned, and the auth model (content.create; Admin/Editor/Author, with Authors limited to their own sections).

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?

Dense but front-loaded: the copy semantics and naming/slug behavior come first, then the locale caveat, then return shape, then alternatives and permissions. Every clause carries non-redundant 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, yet the description tells the agent what comes back (the new item in the get_content shape) and what to do next (edit, then publish_content). Combined with the permission model and the children/slug caveats, 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 description coverage is 100%, so all three parameters are already documented, including the locale behavior and the site/multisite caveat. The description restates locale semantics rather than adding syntax or format detail beyond the schema, 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 precise verb (copy) and resource (content item), plus the exact outcome: a NEW unpublished document beside the original, same parent, named "<name> (copy)", with a fresh slug and no children copied. It also explicitly distinguishes itself from copy_variant and create_content, so an agent can route correctly without opening any schema.

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

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

Names both alternatives with the exact condition that selects them: copy_variant when copying one language into another locale of the SAME item, create_content when starting from nothing. It also gives the follow-on workflow (edit it, then publish_content) and the permission requirement.

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, and the description adds genuinely useful behavioral context beyond them: the draft-else-published resolution rule, the not-found refusal for unknown or foreign-site documentIds, locale defaulting, and the required content.read permission with role scoping (Author limited to own sections). This is auth-need and edge-case disclosure the annotations do not 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?

Front-loaded with the core purpose and return shape, then sequencing, then edge cases, then permissions. It is a dense single paragraph with essentially no filler, though its length pushes close to over-stuffing for a three-parameter read.

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, yet the description enumerates the return shape (name, slug, status, revision, full data field map) and ties it to list_content_types' valueFormat. Combined with the permission, site, and locale semantics, 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 coverage is 100%, so the baseline is 3, but the description adds meaning the schema doesn't: omit locale for the item's own language, pass site to reach another site, and how revision is meant to be reused in a later update. It stops short of detailing format/syntax, but the added semantics are real.

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 precise verb+resource+scope: reads one content item's working version (draft if present, else published) in one locale, returning name, slug, status, revision and the data map. It explicitly distinguishes the 'editing view' from delivery_get's 'public view', so an agent can separate it from siblings 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 sequencing ('Read this before update_content so you merge into current values') and the condition for passing revision ('when replacing with merge:false'). It also names the alternative path (delivery_get for published-only, private fields removed), so when-to-use and when-not are both covered.

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

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

Annotations declare readOnlyHint/openWorldHint, but the description adds substantial context beyond them: no paging (so a big library is a big response), empty library returns [], the exact fields returned, per-site media isolation, and the permission requirement including the Author-within-own-sections caveat.

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 result shape, then routing and permission guidance. Dense and largely earned, though the 'no paging, so a big library is a big response' phrasing and listed return fields add some length.

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 appropriately documents the return payload (documentId, filename, mime, size, url, alt text, attribution, folder) and the empty-case behavior. Permission, scope, and sibling routing are all covered for a single-parameter read tool.

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

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

Schema description coverage is 100% and already documents `site` in detail, so the schema carries most of the burden. The description reinforces the per-site semantics ('Media is per site: pass `site` to see another site's library'), adding light corroboration but no new syntax or format detail — slightly above the baseline 3 because it clarifies the operational consequence of the parameter.

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 and scope: 'List this site's whole media library (images and PDFs), newest first, in one call'. It is clearly distinguishable from siblings like search_stock_images, upload_asset, list_content, and create_upload_link, and even enumerates the fields returned.

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: 'Use it to reuse an existing image: an image field stores the asset's documentId, set with set_field. To add a new file use upload_asset ... or create_upload_link'. It also names the alternative for another site's library via the `site` parameter and states the required permission tier.

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 (readOnlyHint), but the description adds real behavioral context: the required content.read permission with per-role caveats (an Author only within their own sections), the no-paging guarantee ('Everything comes back in one call'), the fact that nothing is purged automatically, and the shared-vs-inline block distinction that affects blast radius of edits. This is well beyond what the annotations declare.

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 return shape before the per-kind detail, and every clause carries information. It is dense and slightly long, with some parenthetical enumeration that could be trimmed, but there is no filler or repetition.

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

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

No output schema exists, so the description carries the return contract itself, naming the fields returned (documentId, name, type, per-locale status, parentId, folderId, deletedAt) plus ordering. Combined with the permission and paging disclosures, an agent has everything needed to call it correctly and interpret the result.

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

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

Schema coverage is already 100%, so baseline would be 3, but the description meaningfully enriches both parameters: it defines what each kind actually contains, notes that trash items carry deletedAt and are newest-first, and explains the 'site' parameter's failure mode ('an empty tree or search usually means the wrong site, not missing content').

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 item of one kind in this site') and immediately scopes it as one flat array, distinguishing it from the tree-walking alternative by name. An agent can tell it apart from list_tree and get_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?

Gives explicit when-to-use guidance per enum value: 'page' to find one by name or pick a parent, 'block' for shared reusable blocks, 'global' because it is the only way to enumerate singletons, 'trash' for removed items. It names the alternative (list_tree shows one level in display order) and the follow-up tools (get_content/update_content, restore_content), 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?

Goes well past the readOnlyHint/openWorldHint annotations: it discloses the required content.read permission with a role breakdown (Author restricted to own sections), the error behavior for an unknown name (refused with the real names listed), and the cost/size characteristic of omitting name. That is exactly the extra context 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?

Purpose is front-loaded in the first clause, followed by the parameter behavior, the downstream call to make, the sibling boundary, and the permission caveat. Dense but every sentence carries routing or behavioral value; only the parenthetical field enumeration is slightly overloaded.

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 sketching the returned structure (name, kind, displayName, schemaType, fields with type/required/options/allowed blocks) and the per-field valueFormat/valueExample. Combined with permissions and error behavior, an agent has enough to invoke and consume 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%, so the baseline is 3, but the description adds real meaning: name yields a single type's full definition, and the returned field metadata (valueFormat, valueExample) is framed as the exact JSON shape create_content/update_content expect. It stops short of documenting format constraints 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 the content model') and immediately scopes it as instance-wide and shared by all sites. It also distinguishes itself from the template/recipe toolset, so an agent can separate it from siblings like get_content or schema tools without inspecting 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 an explicit when-to-use rule ('Call this before writing content of a type'), an explicit parameter-selection preference ('prefer name' over omitting it because the full dump is large), and names the alternative location for templates. Nothing 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 cover read-only and closed-world, but the description goes well beyond them: it documents the exact return shape (sites, activeSiteId, tokenScopedTo, activeSite, locales), the permission requirement with role nuances ('an Author only within their own sections'), and the key behavioral fact that content in another site is invisible to every tool. Rich disclosure 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?

Front-loaded with the core purpose, then a structured Returns inventory, then usage. Dense with parentheticals and long, but nearly every clause carries information (locale selection, permission model, multisite invisibility). Slightly over-packed rather than wasteful.

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 fully enumerates the returned fields and their meanings (including the previewBaseUrl template), so an agent knows exactly what it gets. Permission, scoping, and locale-picking context round it out; nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100% and the single `site` param is already documented, so the baseline is 3. The description adds cross-tool meaning — a slug from here is what you pass as `site` elsewhere, and passing `site` here shows that site's setup — which is genuine value beyond the schema text.

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

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

States a specific verb and resource ('report where this server acts and in which languages') and explicitly carves out its boundary: 'It lists no content (use list_tree or list_content for that).' An agent can distinguish it from every content-listing sibling without opening a schema.

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

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

Gives concrete when-to-use guidance ('Use it to pick the `locale` matching the language you write', 'a slug to pass as `site` to other tools') and names alternatives for the content case. It also supplies a diagnostic heuristic: an empty tree or search usually means the wrong site, not missing 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?

Annotations only declare readOnlyHint and openWorldHint=false, so the description must carry the rest, and it does: trashed pages excluded, ordering by container sort, [] instead of an error for leaf or unmatched parentId, and required content.read permission with the Author-scoped caveat. The 'check hasChildren first' warning is actionable behavioral advice, not restatement.

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 level-by-level scope before return shape, exclusions, siblings and permissions. It is dense but long; a few clauses (the parenthetical permission role list) could be tightened without losing meaning.

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

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

With no output schema, the description still enumerates the returned node fields (documentId, type, name, per-locale status, hasChildren) and the empty-array case, plus auth requirements. An agent has everything needed to call it and interpret the result.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond it by tying parentId to recursion semantics ('call list_tree again with a node's documentId') and by warning that an empty tree usually signals a wrong site rather than missing content — meaning the schema alone 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 with exact scope: 'List ONE level of the page tree: the direct children of parentId, or the top-level pages when it is omitted.' It immediately distinguishes itself from the sibling list_content by naming what it does not return (shared blocks, 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?

Gives explicit when-to-use ('Use it to find the parentId for create_content/move_content') and explicit alternatives ('For every page at once use list_content {kind: page}'; blocks/globals elsewhere). The recursion guidance — call again with a node's documentId to go deeper — removes the main inference burden.

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, openWorldHint=false), yet the description adds real behavioral context: no paging/complete results, newest-first ordering, not-found refusal for unknown documentId, and the required content.read permission with role caveats (Author limited to own sections). It omits return size/rate considerations, so it is strong but not exhaustive.

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 alternatives, then permissions. Despite being dense, every clause carries actionable information with no repetition of the name or 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?

No output schema exists, so the description compensates by enumerating the returned fields (id, versionNumber, status, live flag, name, creator/time). Combined with error behavior, permissions, and sibling routing, 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 coverage is 100%, so the baseline is 3; the description still adds value by clarifying that locale selects the language branch and defaults to the item's own variant, and by flagging the id-vs-versionNumber distinction used downstream in restore_version.

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

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

States a specific verb+resource (list a content item's version history) with scope qualifiers: one locale, newest first, complete/no paging. It is immediately distinguishable from siblings like list_content and get_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?

Explicitly routes to alternatives: use restore_version with the version's `id` (not versionNumber) to roll back, and get_content for the current draft itself. When-to-use versus when-to-use-something-else 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?

Annotations declare it non-destructive and idempotent, but the description goes well beyond them: it discloses the automatic 301 redirect, that the whole subtree moves, the exact refusal conditions, the sibling-order caveat under computed sorts, and the required content.update permission with role-level nuance. This is rich behavioral context not derivable 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?

Front-loaded with the core action and densely packed, with nearly every clause carrying distinct information (redirects, refusals, permissions). The parenthetical-heavy style makes it slightly harder to scan than an ideally structured description, but there is little waste.

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

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

For a mutation tool with no output schema, the description covers the return value ('Returns {ok:true}'), refusal cases, permission requirements, and side effects like the 301 redirect and subtree move. 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 baseline is 3, but the description adds genuine meaning: parentId 're-parents' it and the URL path follows, beforeId/afterId place it among siblings, and sibling order only sticks under manual sort. That last constraint is not in the schema and materially affects how an agent sets these params.

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 ('Move a page in the page tree') and immediately distinguishes itself from siblings by scoping to tree repositioning rather than content editing. An agent can tell it apart from update_content, duplicate_content, and trash_content 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: 'To change only the URL's last segment, set a new slug with update_content instead' and 'blocks and globals are not in the tree.' It also names the permission and role conditions under which the tool is available, giving clear when-to-use and when-not-to-use guidance.

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

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

Annotations only declare the write/non-idempotent/non-destructive profile; the description goes far beyond by disclosing scheduling semantics, automatic unpublication via expireAt, the 301 on slug/position change, the content.published event, language-mismatch refusal, and required-field/review refusals. It also warns against faking a schedule with a date field, which prevents a real misuse.

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?

Dense but front-loaded: the core action and its scheduling semantics come first, with routing and refusal details trailing. Every sentence carries information, though the prose runs long for a single tool and could be tightened slightly.

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 stating the return shape (the item in get_content shape with its new status) and covering the full behavioral envelope: scheduling, expiry, redirects, events, and refusals. 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 coverage is 100%, so the baseline is 3, but the description adds genuine meaning: it explains the locale branch/language-mismatch interaction, that publishAt schedules rather than publishes now, and that rescheduling is done by re-calling with a new publishAt. It does not restate the schema's own wording verbatim.

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 (publish/make live) and resource (a content item's working draft), scopes it to one locale, and distinguishes the sibling actions unpublish_content and discard_draft. An agent can tell this apart from update_content or create_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 (go live now vs. schedule via publishAt), how to reschedule (call again with a new publishAt), and which sibling to use instead for takedown or discarding edits. Failure/refusal conditions are enumerated, so the agent knows when the call will be rejected.

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 mark it non-readonly/non-idempotent/non-destructive; the description adds substantial behavior beyond them — descendants come back too, restored content is NOT republished, refusal conditions (trashed parent, URL taken by a live sibling), no locale scoping, required content.delete permission, and the {restored: count} 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?

Front-loaded with the action and scope, then refusal conditions, return value, discovery hint, and alternative. Every sentence 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?

Despite no output schema, the return value is stated, and permissions, preconditions, non-republish behavior, and the alternative tool are all covered. 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 baseline is 3; both parameters are already fully documented in the schema. The description adds a meaningful clarification beyond the schema by explaining that no locale parameter exists and every language is restored, which prevents an agent from hunting for a locale argument.

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 ('Bring a trashed item back to its old place in the tree, together with the descendants'), and explicitly distinguishes itself from siblings publish_content and restore_version. An agent can tell it apart from restore_version 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 routing: use list_content {kind:'trash'} to find ids, call publish_content per locale to go live, and use restore_version instead for non-trashed rollback. It also names preconditions (parent must not still be trashed) that gate a successful call.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, but the description adds substantial context: it REPLACES the current draft so unpublished edits are lost, published versions remain in history, a rollback can itself be rolled back, and nothing goes live until publish_content. This is exactly the kind of behavioral disclosure that goes beyond structured 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 long but front-loaded with the core action and effect, then layers on routing, side effects, and permissions. Every sentence carries information, though the density is high enough that a slightly tighter grouping of side effects would help.

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?

Despite having no output schema, the description specifies the return shape ('Returns the new draft in the get_content shape'), covers side effects, alternatives, and permissions. An agent has everything needed to call this mutation correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: versionId must be the `id` from list_versions of the SAME locale, not the versionNumber. That disambiguation is valuable beyond the schema's own phrasing and prevents a common mistake.

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 ('Roll back an item to an older version') and immediately clarifies the mechanism (copy name, slug and fields into the working draft of one locale). It differentiates itself from siblings by explicitly naming restore_content and discard_draft as different operations.

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 and when-not-to-use guidance: use restore_content for trashed items, use discard_draft to drop unpublished edits. It also states the permission prerequisite (content.update) and the role constraints, including the Author scoping caveat.

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=true, so safety is covered; the description adds substantial context beyond them — up to 24 results best-match-first, per-item fields (id, description, attribution), the fact that nothing persists, the graceful refusal with a hint when no key is configured, and required permission plus per-role scoping. This is 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 what the tool does, then the follow-up workflow, then the fallback and permission caveats. Every sentence carries routing or constraint value (return shape, non-persistence, refusal, permission); none is 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 supplies the return contract (up to 24 candidates, best match first, id/description/attribution). Combined with the import workflow, alternative tool, refusal behavior, and permission requirements, 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% and both parameters (site, query) are documented in-schema, so the schema does the heavy lifting. The description adds no syntax or format detail for query or site beyond what is already there, 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+resource ('Search the configured stock photo provider ... for photos') and immediately scopes it as candidate discovery, not storage ('nothing is stored yet'). It distinguishes itself from siblings like list_assets (reuse existing) and upload_asset (import), so an agent can route 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?

Explicitly gives the end-to-end path: search here, then upload_asset {stockImageId} to import, then set_field with the returned documentId. It also names the alternative for a different intent ('To reuse a photo you already have, list_assets') and the refusal condition (no provider key). Nothing 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 cover only idempotency/safety flags, and the description adds substantial behavior beyond them: it cancels a pending scheduled publish, refuses invalid values with expected shape and example, refuses language mismatches by default, and states the required content.update permission plus the Author-scoped caveat.

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?

Dense but front-loaded: the core action and its safety rationale lead, then alternatives, then side effects and permissions. Six sentences is on the long side, though nearly every clause carries actionable 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?

With no output schema, the description still closes the loop by saying it returns the saved draft in the get_content shape and that publishing is a separate call. Permissions, refusal behavior, and scheduling side effects are all covered for a mutation 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 already 100%, so the baseline is 3, but the description adds real meaning: which field kinds are legal (text/markdown/select/datetime/image from list_content_types) or 'name', that an image takes an asset documentId, that value is the field's whole new value, and the allowLanguageMismatch guard behavior.

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

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

States a precise verb+resource+scope: 'Write ONE field of an item's draft as a plain string; the other fields are kept.' It immediately distinguishes itself from update_content by naming that sibling and the cases it doesn't cover (richtext, contentArea, reference, multiple fields).

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: use this for long text/Markdown because a flat string survives client serialization, and use update_content for richtext/contentArea/reference fields or several fields at once. It also notes when allowLanguageMismatch is needed and that publish_content is separate.

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 entire subtree is trashed, all locales are unpublished and removed from delivery, the operation is recoverable via restore_content (returned as drafts), unknown documentIds are refused, and it requires content.delete (Admin, Editor). This is rich operational context. The destructiveHint=false annotation is consistent with the explicitly stated recoverability, so no contradiction.

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

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

Front-loaded with the core action and scope, then recovery, then the error case, return shape, alternative, and permission. Every sentence carries distinct, necessary 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 supplies the return value ({trashed: n}), the permission requirement, the recoverability path, and the sibling alternative. Nothing an agent needs to call it safely and 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 already 100%, so baseline is 3. The description adds real meaning: it explains why no locale parameter exists ('every locale is unpublished at once ... so there is no locale to pass'), and clarifies the documentId not-found failure mode. That goes beyond what the schema documents.

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 ... to the trash') plus resource ('a content item AND its whole page subtree') and scope ('every locale'). It explicitly differentiates from siblings, naming restore_content for recovery and unpublish_content for the softer alternative, so an agent can route correctly 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?

Gives an explicit alternative: 'To only take it off the live site, use unpublish_content instead,' and names restore_content as the inverse. The recoverability caveat and 'publish again explicitly' note make the when-to-use decision 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?

With annotations covering the safety profile (destructiveHint true, readOnlyHint false), the description still adds rich context: the URL answering 404, content-area reference dropping, the content.unpublished webhook firing, retention of content and version history, and the required content.publish permission. This is exactly the behavior-beyond-annotations 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 core action and effect, then layers webhook, reversibility, routing, return shape, and permissions. Dense but every sentence carries information; slightly blocky as a single paragraph rather than cleanly separated.

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

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

Complete for a mutation tool with no output schema: it describes the return shape (get_content shape, unpublished in that locale) and the permission requirement, while annotations already handle the safety hints. 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 coverage is 100%, so the baseline is 3, but the description adds semantic value: it explains that the locale names the 'branch' and that omitting it targets the item's own language, and that other locales remain unaffected.

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 (unpublish) and resource (content item) with scope (one locale), and clarifies the observable effects (404, dropped references). It explicitly distinguishes itself from siblings publish_content and trash_content by naming both.

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 routing: 'To remove the item entirely use trash_content' for the destructive alternative, and notes publish_content as the reversing action. The locale-omission rule (omit for the item's own language) is stated as an operating condition, not 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?

Adds substantial context beyond annotations: alt text lives on the asset not the page, unknown documentId is refused as not found, the required permission and role scoping, and the return value. Annotations already cover idempotent/non-destructive, and the description reinforces rather than repeats.

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?

Dense but front-loaded with the core action, and nearly every sentence carries distinct information (scope, id semantics, alt conventions, permissions). Slightly long, but little is redundant.

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

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

For a 3-param mutation tool with no output schema, it covers permissions, failure behavior, return value, and cross-page effects. 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: documentId is the asset's (not a page's) from list_assets/upload, and alt should be one sentence with "" reserved for decorative images. This resolves the main ambiguity the schema alone leaves open.

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

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

States a specific verb and resource ("Set (overwrite) an image asset's alt text") and immediately distinguishes it from siblings set_field/update_content. An agent knows exactly what this does and what it is not.

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 alternatives that cannot do this (set_field/update_content) and the tool that cannot generate the text (assist_writing), with the condition (needs the image itself). Provides the when-to-use routing directly.

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

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

Annotations are modest (idempotent, non-destructive), and the description adds substantial unrevealed behavior: merge-by-default semantics, the 409 refusal on stale revision, that an agent edit marks the draft for review and cancels a pending scheduled publish, the shape-mismatch refusal, the language guard, and the required permission set. This is well beyond what annotations supply.

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 dense block, but front-loaded with the core purpose and merge rule before the edge cases. Nearly every clause carries actionable information; the long run-on construction around the field-shape list and the set_field aside slightly hurts scanability.

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

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

For a 10-parameter nested-object mutation with no output schema, the description covers the required permission, the return shape ('the saved draft in the get_content shape, with its new revision'), the concurrency contract, and the main refusal modes. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description contributes real meaning not in the schema: concrete value shapes per field type (string, TipTap doc, block array, {documentId}), the merge:false consequence, and the revision/409 contract. It does not fully re-explain name, slug, or locale handling, which holds it below a 5.

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

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

States a specific verb and resource ('Save fields into a content item's working draft') and immediately scopes it against publish_content ('nothing goes live until publish_content'). An agent can distinguish it from create_content and set_field without opening a schema.

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

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

Gives explicit routing conditions: use set_field for one long text/markdown value, use merge:false plus revision to replace the whole map, use allowLanguageMismatch only for deliberate cross-language writes. When-not guidance (draft vs live) is front-loaded.

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 (not read-only, open-world, non-idempotent, non-destructive), and the description adds substantial context beyond them: the 5 MB cap, per-redirect-hop refusal of private-network addresses, download cutoff behavior, the always-new-asset semantic, and the content.create permission with role scoping for Authors.

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 and source constraints are front-loaded, and each sentence carries operational weight (limits, permissions, cost, alternatives). It runs long as a single dense block, so structure could be improved, but there is little wasted text.

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

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

For a multi-source upload tool with no output schema, the description covers the return value's use ('set its documentId on an image field with set_field'), the permission requirement, size and network constraints, and sibling alternatives. An agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning the schema doesn't: the three sources are mutually exclusive ('from exactly one source'), the URL must be publicly reachable, and stock photos are stored with their attribution. It stops short of documenting the site/filename interplay more fully.

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 precise verb+resource ('Add a file ... to the media library') and immediately scopes the three allowed sources, distinguishing it from siblings like create_upload_link, search_stock_images, and list_assets. An agent can identify the operation and its boundaries without opening the schema.

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

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

Explicitly routes the agent: use create_upload_link for local files, list_assets to reuse an existing asset, set_field to attach the returned documentId, and search_stock_images as the source of stockImageId. It also names when-not (a new asset is always created). Nothing 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.