WebCake Storefront MCP

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

Annotations only indicate a non-read-only, non-destructive write. The description adds rich behavioral context: no network, durable per-section cache, no timeout, section re-id to avoid collisions, quick validation, and warnings that are surfaced but never block. This goes well beyond what 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?

The description is three tightly packed sentences with no wasted words. It front-loads the core action, then adds essential behavioral context in parentheses and a short prerequisite note.

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 lack of an output schema and minimal annotations, the description covers purpose, prerequisites, operational behavior (local, durable, no timeout), and edge-case handling (warnings don't block). It is complete for an agent to invoke the tool correctly in the draft workflow.

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 documented. The description adds meaning by stating the section should be built with new_section and that it will be re-id'd, which supplements the schema's 'section node (from new_section)' with process details.

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+resource: 'Append ONE section to a local page draft', and distinguishes it from network-dependent operations with 'NO network — this is the durable per-section cache step'. It also clarifies that it operates on drafts, not live pages, separating it from sibling tools like add_section.

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 an implicit usage guideline by instructing 'Build the section with new_section', indicating a prerequisite step. However, it does not explicitly state when to choose this tool over alternatives such as commit_page_draft or add_section, leaving the agent to infer the workflow context.

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 state readOnlyHint=false and destructiveHint=false; the description goes well beyond by disclosing the full read-append-validate-save pipeline, the re-id step to avoid collisions, and the dry_run default. This is the kind of operational detail an agent needs before committing a write.

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

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

Three tight sentences, front-loaded with the verb+scope, then sourcing rules, then the safety workflow. No filler or restated name/title content.

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 nested-object mutation tool this is nearly complete: sourcing, re-id behavior, and the two-step save flow are all present. The only gap is that with no output schema, the description never indicates what is returned (e.g., validation results or the new section id).

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 baseline is 3, but the description adds genuine value by cross-referencing which sibling tools produce each input ('section built with new_section', 'template ... from list_section_templates') and reaffirming dry_run's default-true preview semantics.

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 ('Append a section to an EXISTING page's source') with explicit scope. The capitalized 'EXISTING' and the note that the id is re-generated distinguish it from new_section (which builds a section) without needing 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?

Clearly routes the agent: build a section with new_section, or supply template:{category_id,id} from list_section_templates, and explains the dry_run=true default preview workflow. It does not, however, contrast itself against similar mutators like add_draft_section or update_page_source, so the 'when-not' side is only partially 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 provide only readOnlyHint=false, so the description carries most of the burden. It usefully discloses that this is an additive, non-read-first mutation in contrast to a full rewrite, which is genuine behavioral context, but it omits permission requirements and what happens if the target field is empty or missing.

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, each earning its place, with the core additive behavior front-loaded before the alternative-tool pointer. No redundancy 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?

For a 3-param mutation tool with no output schema, the description covers purpose, usage, and the sibling alternative well. It stops short of stating return behavior or edge cases, but nothing critical 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?

Schema description coverage is 100%, so field, code, and position are already fully documented. The description reinforces the append/prepend distinction and the kinds of code supported but adds no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb pair (append/prepend) and resource (custom code field) with clear scope, and explicitly contrasts with the sibling update_site_custom_code. An agent can distinguish it from the update and get variants 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 an explicit when-to-use condition (adding new CSS rules, JS, script tags) and names the alternative (update_site_custom_code) for the opposite case (full rewrites). Both the trigger and the exclusion are present.

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

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

With only readOnlyHint=false available, the description carries the behavioral load well: dry_run defaults to true, validation errors block the real save, duplicates are refused with blocked:true plus an existing page_id, only 'custom' pages can be created repeatedly, and special types auto-enable their data sources (store→use_store, member→use_member, etc.). It also warns that omitting seo publishes an empty title/description.

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, then the dry_run workflow, then the edge-case constraints, so the agent gets the critical path first. Four dense sentences with little waste, though the uniqueness sentence packs several distinct rules together.

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 7-param nested-object create tool with no output schema, the description covers the safety flow, source format, type side effects, and conflict behavior. The only real gap is that the success return (e.g. the new page_id) is not described, though the failure path's page_id is.

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, but the description adds cross-parameter meaning beyond the schema: source must take the shape { sections: [...] } built via new_section, and dry_run must be read as a two-phase flow rather than a simple flag. These additions go beyond 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 specific verb+resource and an explicit scope differentiator: 'Create a brand-new page AND set its full content source in one step.' That 'one step' framing implicitly separates it from the sibling pair create_page/update_page_source. However, it never names those siblings, so an agent must still infer which of the many page-related tools to pick.

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 operational guidance: call dry_run=true first then false, build sections with new_section, and the uniqueness rules (one main/error/maintain page per site, unique slugs, duplicates refused and return the existing page_id to edit instead). It lacks explicit when-not guidance (e.g. 'use update_page_source to modify existing content'), but the create-vs-edit boundary is derivable from the duplicate rule.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is known. The description adds real value beyond them by delimiting blast radius — it discloses what is NOT destroyed (the backend page derived from the draft), which the annotations cannot express. It still says nothing about irreversibility or whether confirmation is required before clearing.

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

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

A single sentence, front-loaded with the verb and resource, and the parenthetical is genuinely load-bearing rather than filler. Nothing could be cut without losing routing 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 one-parameter destructive cleanup tool with annotations covering the safety profile, the description covers the essential gap (scope vs. backend pages). It stops short of noting that the action is irreversible or how to discover the draft_id, which would make it fully self-sufficient.

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?

One parameter with 100% schema description coverage, so the schema already documents draft_id (albeit thinly, as "Draft id"). The description adds no syntax, format, or provenance guidance such as obtaining the id from list_page_drafts; 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 ("Delete") and a precise resource ("a local page draft"), and the parenthetical scopes it against the backend page objects that sibling tools like delete_page and commit_page_draft operate on. An agent can tell this apart from delete_page and commit_page_draft without opening any schema.

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

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

The parenthetical implies the appropriate context (discarding a local draft that has not been, or should not be, published), but no tool is named as an alternative and no explicit when-to-use / when-not-to-use rule is given. Usage is inferable rather than stated.

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

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

Annotations only declare readOnlyHint=false; the description adds substantial behavioral context: incremental one-section-per-request writes, a 120s per-request timeout, dry_run preview semantics, and full resumability via retained page_id + committed_count. This is exactly the kind of mutation/recovery detail 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?

Front-loaded with the core action, then the dry_run modes, then a capped RESUMABLE block for the failure path. Three compact segments, no filler, and the escalation-worthy detail is surfaced with emphasis.

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 and only two parameters, the description covers the write behavior, timeout risk, dry-run preview, and failure recovery. Nothing an agent needs to invoke it correctly or recover from a mid-commit failure 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 goes further: dry_run=true validates the assembled page and previews stats while false creates then appends sections, adding meaning beyond the schema's terse wording. draft_id origin is only noted in the schema, so no extra credit there.

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 (persist/commit), resource (local page draft), and distinguishing mechanism (incremental, one section per request). The dry_run paragraph clarifies both modes, and the resumable note tells the agent exactly what the tool does on failure. It is clearly separable from start_page_draft and add_draft_section.

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

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

Explains the dry_run default and what each mode does, which implicitly guides usage, but never explicitly states when to call this versus start_page_draft/add_draft_section or that it must follow draft construction. Usage is inferable from the workflow but not spelled out.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description adds the aggregation/grouping behavior, which is genuine context, but it says nothing about scope (all orders? date-limited? site-limited?) or the shape of the returned counts, so the behavioral picture stays thin.

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, purpose first and usage hint second, with no filler. Every word 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 zero-argument read-only aggregate with annotations covering the safety profile, this is nearly sufficient. The only real gap is the absence of any statement of scope (which orders are counted) and the return structure, though no output schema exists to cover the latter.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool applies. The description correctly implies no inputs are needed.

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

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

States a specific verb and resource with output shape: it counts orders and groups the count by status. That is clear enough to distinguish from list_orders or get_order, but it never names or contrasts those siblings explicitly.

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

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

"Useful for dashboard overview" implies the intended context, which is more than nothing, but there is no guidance on when to use this versus list_orders (e.g. avoiding fetching full order records just to tally them) and no exclusions.

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

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

Annotations already declare this is a non-read-only, non-destructive write, so the safety profile is covered. The description adds genuinely non-obvious behavior: the backend generates id and slug, posts are auto-filed under a default category, and SEO is deliberately excluded from creation. It omits auth/permission needs and what the response actually returns, 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?

Purpose is front-loaded in the first clause and every sentence carries usable information (surfaces, pipeline, image hosting, category linkage, SEO follow-up). It is dense and slightly long, but 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?

For a 5-param write tool with no output schema, the description covers prerequisites and the create-then-update workflow, implying the returned id needed for the SEO step. It does not explicitly state the response shape, which is the only real 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 coverage is 100%, so the baseline is 3, but the description adds semantics the schema lacks: title + optional summary framing, the cover-image convention, and the auto-filing side effect of category_ids. It goes beyond restating the JSON 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 precise verb+resource ('Create a blog article') and grounds it in the consuming surfaces (post-list, grid-blog, post-overlay). An agent can distinguish it from update_article, create_blog_category, and other create_* siblings 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 routes the agent: category_ids come from create_blog_category or list articles' categories, image URLs must be hosted via search_images/upload_images, and SEO must be set afterwards with update_article({ id, seo }). Prerequisites and follow-up steps are all named.

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 signal this is a non-read-only, non-destructive write. The description adds genuine workflow behavior beyond that: the call returns a new category id, the image must be a hosted URL, and SEO cannot be set here and requires a separate update_blog_category call. No permission or rate-limit detail, but the follow-up dependency is valuable.

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

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

Three tight sentences, front-loaded with the action, then the downstream wiring, then the SEO caveat. 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?

With no output schema, the description compensates by explaining the returned category id and exactly where to use it, plus the SEO follow-up path and the image constraint. 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 all three parameters are already documented in the schema. The 'Image must be a hosted URL' note largely restates the schema's 'Hosted image URL', and the id/return guidance concerns output rather than inputs, 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 ('Create a blog/article category'), and the 'blog/article' qualifier cleanly separates it from the sibling create_product_category. An agent knows immediately what object is being created 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 downstream context (pass the returned id to create_article's category_id) and routes the SEO follow-up explicitly to update_blog_category({ id, seo }). It lacks an explicit when-not-to-use note (e.g., vs create_product_category), but the workflow guidance is strong.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the mutation/safety profile is covered. The description adds the file-type taxonomy but omits important behavior such as what happens if the file already exists, whether creation overwrites, or any permission requirements. It adds modest value beyond the annotations.

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

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

Two short sentences, front-loaded with the action and no filler. The type list is somewhat redundant with the schema enum, which slightly dilutes conciseness.

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 create tool with annotations present and no output schema, the description is minimally adequate but leaves key questions unanswered: collision/overwrite behavior, required permissions, and where the file lands. It covers the what but not the surrounding context.

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 in the schema. The description only restates the type enum that the schema already defines, adding no syntax or format meaning beyond it. Baseline 3 is appropriate.

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

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

States a specific verb and resource ("Create a new CMS file") that an agent can distinguish from update_cms_file and edit_http_function. It does not explicitly name or contrast those siblings, but the create-vs-update distinction is clear 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 guidance on when to use this versus update_cms_file, edit_http_function, or save_file_version, and no prerequisites or conditions. The agent must infer the routing decision entirely from the tool name.

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

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

Annotations already mark this as a non-read-only, non-destructive mutation, so the bar is lower. The description adds real behavioral detail: the collection is seeded with system columns (id/inserted_at/updated_at/creator_id) and the dashboard exposes no direct record-insert API, which is a meaningful capability limitation.

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, all front-loaded with the core action first, then the system-column behavior, then the important write-path caveat. No filler; the NOTE earns its place by preventing a wrong-invocation attempt.

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 mutation with no output schema and safety already covered by annotations, the definition covers creation semantics, default state, and the record-write alternative. Nothing essential for a 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?

Schema coverage is 100%, so the baseline is 3. The description goes slightly beyond the schema by framing the initial system columns and explaining that `columns` adds custom fields on top of them, which helps the agent understand what is and isn't supplied at creation.

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

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

States a specific verb ('Create') plus resource ('collection'), then clarifies the resource as a 'custom data TABLE', which an agent cannot infer from the name alone. Together with sibling verbs (get_collection, update_collection_columns, delete_collection) the create action is unambiguous.

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

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

Explicitly routes the agent away from attempting record insertion here, naming the alternative (an HTTP function via get_http_function) and the mechanism (db.model(table).create). It gives clear context for the write path but does not state when a collection is preferable to, say, a CMS file or product type.

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=false and destructiveHint=false, so the description carries most of the behavioral burden and delivers: it discloses the dual persist+embed side effect, the render consequence (header to top, footer to bottom), and the two-step dry_run safety model with an atomic save. This is substantial context beyond the annotations.

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

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

Front-loaded with the core action in the first sentence, followed by ordering and safety details. Dense but every clause is informative; the multi-line layout is slightly heavy but not 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?

For a non-read-only, side-effecting write tool with no output schema and thin annotations, the description covers prerequisites, side effects, and the dry_run safety model. It falls just short of full completeness by not addressing failure behavior or permission requirements, but 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?

Schema coverage is 100% so the baseline is 3, but the description adds real value: it clarifies that the section param should be the node produced by new_section, that page_ids defaults to every page for header/footer, and that dry_run defaults to preview. These mappings go 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+resource (create a reusable global section: Header/Footer/shared block) and explains the dual effect of persisting a record plus embedding into page sources. It clearly distinguishes this from siblings like new_section by presenting that tool as a prerequisite rather than an alternative.

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 to build the section first with new_section and then pass it here, and describes the dry_run preview-vs-commit workflow. It lacks an explicit contrast against ambiguous siblings such as add_section, but the when-to-use and ordering guidance is strong.

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

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

Annotations already declare this is a mutation (readOnlyHint=false) that is not destructive, so the safety profile is covered. The description adds nothing beyond that: no auth/permission requirements, no idempotency or duplicate-handling behavior, no mention of what state the new source starts in.

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

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

Two short, front-loaded sentences with no filler; the verb and resource lead. Slightly redundant with the schema since the component examples are repeated rather than adding new 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 simple three-parameter create tool with full schema coverage and annotations covering the mutation profile, the description is minimally adequate. It still omits usage context and any post-creation behavior, but nothing essential to invoking 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 the baseline is 3 and the schema already documents 'type', 'source', and 'component'. The description repeats the component example values ('cart-droppable', 'popup') that the schema's component property already provides, adding no new meaning for 'source' or 'type'.

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 global source component'), which is clearly distinguishable from siblings like create_global_section or create_page. However, it never explicitly contrasts itself with adjacent tools (e.g., update_global_source, create_global_section), so sibling differentiation is left implicit.

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

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

No guidance on when to use this tool versus alternatives, no prerequisites, and no indication of what happens to an existing source with the same name. The component type list is domain data rather than usage guidance.

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

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

Annotations declare this is a write (readOnlyHint=false) and non-destructive, so the safety profile is covered. The description goes further by disclosing the duplicate-slug refusal behavior and that the error surfaces the existing page_id, plus the side effect of publishing with an empty title unless seo is passed. It stops short of describing permissions or the success return payload.

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 the build_page alternative are front-loaded, followed by constraints. Information-dense and mostly waste-free, though the parenthetical re-listing of the type enum slightly duplicates the schema and the final sentence is packed with three separate rules.

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 5-param mutation tool with no output schema, the description covers the routing decision, the uniqueness constraints, and the empty-title pitfall. Missing only auth/permission requirements and the shape of the success response, which an agent could reasonably want.

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 it: type is a KIND mapped to a numeric backend type, the slug uniqueness/one-per-site rules that govern valid values, and the consequence of omitting seo. That is genuine semantic enrichment, not repetition.

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 new (empty) page') and immediately scopes it against the sibling build_page for pages with content. The agent can distinguish it from other page tools 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 names the alternative tool and the condition that selects it ('For a page with content use build_page instead'), plus hard constraints: one page per site for main/error/maintain, unique slugs per site, and only 'custom' repeatable. This is when/when-not/alternatives in full.

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 write/non-destructive; the description adds real behavioral context the schema doesn't state: the backend auto-generates id and slug, auto-publishes, and synthesizes one default variation with the price/stock for the simple case. It does not cover permissions or error/rollback behavior, so it falls just short of a 5.

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

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

Front-loads the simple/advanced split, then constraints, then SEO follow-up in short labeled clauses; density is high and little is wasted. It runs slightly long with the SEO and images reminders, but each clause carries actionable content.

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 11-parameter create tool with no output schema, it covers the two viable calling patterns, required-vs-optional inputs, image sourcing prerequisite, and the auto-generation/publish side effects an agent must anticipate. Nothing essential to a 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?

Schema coverage is already 100%, so the baseline is 3, but the description adds the conditional relationship that price is only needed when variations are omitted and that images come specifically from search_images/upload_images. It clarifies the two mutually exclusive invocation shapes rather than just restating fields.

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 product) and immediately differentiates itself from siblings by framing the simple vs advanced paths and pointing SEO changes at update_product. An agent can distinguish this from update_product, delete_product, and create_product_category 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 splits 'Simple use' (name + price + images + category_ids) from 'Advanced use' (attributes + variations), tells the agent to call search_images/upload_images first for hosted URLs, and routes SEO to update_product afterwards. Both the when and the alternative are named.

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=false and destructiveHint=false, so the safety profile is covered. The description still adds real context beyond that: it discloses that the call returns a new category id and how to consume it, plus the hosted-URL constraint on image. It does not mention auth requirements, uniqueness constraints on name, or failure behavior, keeping it shy 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?

Four short sentences, front-loaded with the action and rationale, then the return-value contract and two constraints. The parenthetical explaining why a category is needed is slightly discursive but still earns its place as motivation; nothing is padded or 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?

There is no output schema, but the description compensates by stating what is returned (the new category id) and how downstream tools consume it. Combined with full schema coverage and non-destructive annotations, an agent has enough to call this correctly; only edge cases like duplicate names or error responses are unaddressed.

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

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

Schema description coverage is 100% and each of the 4 parameters is already documented, so the baseline is 3. The description's only parameter-level addition ('Image must be a hosted URL') restates the schema, and parent_id/description are never elaborated on, so it does not meaningfully exceed 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+resource ('Create a product category') and immediately distinguishes it from sibling operations by naming the follow-up tools (create_product, update_product_category) and the domain it belongs to versus create_blog_category. An agent can identify this as the category-creation entry point 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 explicit workflow routing: the returned id goes to create_product's category_ids, and SEO is set afterwards via update_product_category({ id, seo }). This tells the agent both when to call it and which sibling to use for the adjacent post-creation steps, rather than doing everything in one 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 only declare readOnlyHint=false and destructiveHint=false; the description goes well beyond by disclosing the backend auto-seed of sample products/categories/blog, the default deletion of that seed (retaining the non-deletable 'All' category), the session switch behavior, the absence of any pages, and the free-account 4-site quota failure. This is exactly the non-obvious behavior 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?

Reasonably front-loaded, leading with the create-and-switch action before the seeding nuance. It is information-dense and most sentences earn their place, though the parenthetical about the 'All' category and the step-by-step workflow add length that could be tightened.

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 explicitly states what is returned (an EMPTY, CLEAN site with no pages) and what the caller must do next to make it usable. For a creation tool with four parameters, 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 baseline is 3, but the description adds real meaning: it explains the consequence of keep_seed:true (keep sample data) versus the default deletion, rather than merely restating the flag. It does not expand on name/slug syntax beyond what the schema already 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 and resource ('Create a brand-new storefront site for the current account') and immediately scopes it as an empty/clean site rather than a template-based one, which distinguishes it from the sibling create_site_from_template. An agent knows exactly what this produces 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 use (start from a blank on-theme store) and an explicit follow-on workflow (get_build_guide → new_section/new_element → build_page). It does not explicitly name create_site_from_template as the alternative for pre-populated sites, so the sibling routing is left partly 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 real behavioral context beyond the annotations: it discloses exactly what content is cloned into the fresh site and that the session switches to the new site so you can edit immediately. This is consistent with readOnlyHint=false / destructiveHint=false (additive, non-destructive creation) and enriches the picture.

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 prerequisites, then follow-on workflow. No filler; the cloning list is informative rather than 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 4-param, no-output-schema mutation tool with annotations present, the description covers prerequisites, side effects, and next steps. It could be slightly richer on what the call returns (e.g., the new site id), but it is well-rounded for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents name, slug, theme_id, and switch_to. The description reinforces theme_id's source and the switch behavior but adds little 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 precise verb+resource (create a NEW site from a marketplace TEMPLATE) and explicitly notes it is the dedicated 'use this template' API, distinguishing it from the sibling create_site. The cloning scope (pages, global sections, cart, popups, styles, fonts) makes the behavior concrete.

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?

Clearly names the prerequisite discovery tools (semantic_search_themes / list_template_themes) and the ordering ('pick a template ... then pass its theme_id here'), plus follow-on steps (update_page_element(s), site-style tools, publish_site). It doesn't explicitly contrast with create_site for a blank site, so an explicit when-not is missing.

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=false, which is a thin signal, so the description carries most of the burden. It usefully discloses that nothing is deployed and that execution result plus console logs are returned, but says nothing about execution side effects, timeouts, or permissions.

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 clauses, zero filler, with the core action and the key constraint front-loaded. Every word earns its place.

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

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

There is no output schema, and the description does briefly cover the return values (execution result and console logs). Parameters are fully documented in the schema, so the only minor gap is the lack of any note on execution semantics or failure behavior.

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

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

Schema description coverage is 100% with three well-documented parameters (content, function_name, params), so the schema does the heavy lifting. The description adds no additional meaning about how content and function_name relate or how params are passed.

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

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

States a specific verb and resource ('Run JS code'), plus a scoping qualifier ('in debug mode, without deploying') and the return content. It is clear what the tool does, though it never names the closely related sibling run_function, so differentiation has to be inferred from 'without deploying'.

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

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

The parenthetical '(without deploying)' implies this is the safe, non-deploying counterpart to run_function, which is useful implied guidance. However, there is no explicit 'use this when.../use X instead' statement, so the agent must infer the routing rule.

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

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

Annotations already flag destructiveHint=true, but the description adds genuinely new context: this is a SOFT delete that merely removes articles from the site, implying the content survives server-side. That materially tempers an otherwise alarming destructive annotation. It stops short of 5 because it doesn't state whether the soft delete is reversible, how bulk deletes behave, or any confirmation requirement.

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

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

A single front-loaded sentence with no wasted words; the most decision-relevant fact (soft delete) is placed immediately after the verb and resource.

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

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

For a simple two-parameter delete with no output schema and annotations carrying the safety profile, the description covers purpose and the key soft-delete nuance. It leaves minor gaps: reversibility of the soft delete and any confirmation step, but 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%, with both id and ids documented in the schema, so the baseline is 3. The description adds no syntax, ordering, or interaction detail between single and multiple delete.

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

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

States a specific verb ("Delete") and resource ("blog articles"), which cleanly separates it from delete_page, delete_product, delete_collection and other delete siblings. The parenthetical narrows scope further. It does not explicitly contrast against siblings, so it stops short of a 5.

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

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

There is no when-to-use, when-not-to-use, or alternative routing (e.g., delete_page for pages, or an archive tool for reversibility). The soft-delete note informs behavior but gives no guidance on choosing this tool.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing the blast radius ('all its records', i.e., cascading data loss) and the irreversibility of the operation, which the annotations do not state.

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

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

Two short sentences, zero filler, with the destructive scope and irreversibility front-loaded. 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-parameter delete with no output schema and annotations covering the safety flags, the description is nearly sufficient. A note on confirmation requirements or whether deletion can be undone via restore would close the remaining gap.

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

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

Schema description coverage is 100% with a single documented required parameter (collection_id), so the schema already carries the parameter semantics. The description only restates 'by id' and adds nothing about format or source of the id; 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 (Delete), resource (collection/table), scope (all its records), and the identifying parameter (by id). It does not distinguish itself from the numerous sibling delete tools (delete_page, delete_product, delete_article, delete_global_section), but the resource is unambiguous.

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

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

No guidance on when to choose this over alternatives such as delete_page or delete_product, and no prerequisites or preconditions (e.g., confirm mode, ownership) are mentioned. The agent must infer usage entirely from the name.

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

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

Annotations only say readOnlyHint=false and destructiveHint=true; the description adds the crucial blast radius (the node is removed from every page source, not just one page) and that the save is atomic. It also explains the safe default of preview mode, which an agent needs to avoid accidental mass deletion.

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 packed sentences with the destructive scope front-loaded and the safety workflow second. No filler or restatement of the tool name.

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

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

For a destructive, 2-param tool with no output schema, the description covers the main risks: cascade scope, atomicity, and preview-first default. It omits whether the operation is reversible/undoable and any permission prerequisites, which would round it out.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds concrete meaning to dry_run by explaining what the preview actually returns (which pages would change) and that false performs the atomic save. section_id gets no extra detail beyond the schema's pointer to list_global_sections.

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

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

States a specific verb (delete) and resource (global section, clarified as Header/Footer/block) plus the cascading scope 'remove its node from every page source'. This distinguishes it from nearby siblings like delete_page and delete_global_source, which operate on different resource 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?

Clearly documents the intended two-step workflow: dry_run=true (default) previews which pages change, dry_run=false commits the delete. It does not explicitly compare against alternatives (e.g., removing a section via page-level edits), so it stops just 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 declare readOnlyHint=false and destructiveHint=true, so the safety profile is covered. The description contributes one genuinely useful behavioral fact beyond that: deletion cascades to the published version. It stops short of stating irreversibility or any permission requirement.

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 nine-word sentence with the destructive verb front-loaded and no filler. Nothing could be removed without losing meaning.

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

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

For a one-parameter destructive tool with annotations carrying the safety profile and no output schema to explain, the description covers the essential cascade effect. What remains missing is modest: irreversibility/recovery and whether the target must be in a particular state.

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

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

Only one parameter and schema coverage is 100%, so the schema fully documents global_source_id. The description adds no format, naming, or ID-sourcing detail beyond what the schema already says, which is the baseline case for a fully documented single 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 (Delete) plus resource (global source) and adds scope detail that the resource's published version goes with it. This distinguishes it from get_global_source_detail / update_global_source, though it never explicitly contrasts with the similarly named delete_global_section sibling.

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 prerequisites (e.g., must the source be unpublished first?), and no reference to alternatives such as unpublishing/updating instead. The agent must infer the occasion entirely from the tool name.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the safety profile is covered. The description adds nothing beyond that - it never states that deletion is irreversible, whether child pages/elements are removed, or what happens to drafts, which is the information an agent would actually need beyond the annotation.

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 three-word phrase with zero filler is maximally front-loaded, but it is under-specified rather than genuinely concise - there is no second sentence earning its place by adding the destructive semantics.

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, likely irreversible operation with no output schema and no annotations describing consequences, the description should at minimum warn about permanence and side effects. The safety annotation covers the hint flag, but the operational consequences of calling it are left entirely unstated.

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

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

Schema description coverage is 100% and the single page_id parameter is documented as "Page ID to delete" in the schema, so the baseline of 3 applies. The description adds no format, source, or lookup guidance for the ID.

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?

"Delete a page" names a specific verb and resource, so the basic purpose is legible, but it offers no scope detail (permanent vs. draft, cascading effects) and does nothing to distinguish itself from the many sibling delete tools such as delete_article, delete_product, or delete_global_section.

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

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

There is no guidance on when to use this tool, what preconditions must hold, or which alternatives exist (e.g., clear_page_draft or delete_global_section). The agent must infer everything from the name alone.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the bar is lower. The description adds only the batch-capability detail; it does not disclose whether deletion is permanent or reversible, what happens to related records (orders, categories), or what confirmation/authorization is required for a destructive 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?

A single short sentence that front-loads the verb and resource with zero filler. There is nothing to trim.

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

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

For a one-parameter destructive tool with annotations covering the safety profile, the description is minimally viable. It omits the consequences an agent needs to act responsibly (permanence, cascading effects, batch partial-failure behavior), which matters more here than for a 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 coverage is 100% with a single self-documented array parameter, so the schema carries the semantics. The description's 'one or more' and 'by id' merely restate the array-of-ids shape without adding format, limit, or partial-failure 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 specific verb (delete) and resource (products) with the identifier basis (by id), and the phrase 'one or more' signals batch semantics that distinguish it from single-item paths. It doesn't name a sibling to contrast against (e.g., delete_product_category), but the resource is unambiguous.

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

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

No when-to-use guidance, no prerequisites (e.g., required permissions, whether the product must be unpublished first), and no mention of alternatives such as update_product or set_product_published. An agent gets no routing help.

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 readOnlyHint=false, so the safety profile is conveyed structurally. The description adds that multiple ids can be deleted in one call, but omits what happens to products assigned to a deleted category, whether the operation is reversible, or whether partial failures are possible — meaningful gaps for a destructive batch 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?

A single eleven-word sentence that front-loads the verb and resource with no filler. Nothing is wasted, though it is so terse that it also fails to carry usage or behavioral 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?

For a one-parameter tool with full schema coverage and destructive annotations, the essentials are present. What is missing is the domain consequence of deletion (cascade vs. rejection when products reference the category), which an agent would want before calling a destructive tool.

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

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

Schema description coverage is 100% and the single 'ids' parameter is documented as 'Category ids to delete'. The description's 'by id' phrasing is consistent but adds no format, limit, or ordering 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?

The description gives a clear verb+resource ('Delete ... product categories') and adds scope detail ('one or more', 'by id'), so an agent knows it is a batch delete keyed on category ids. It does not distinguish itself from siblings like delete_product, delete_collection, or delete_blog_category, which is the only gap.

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

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

There is no guidance on when to use this tool versus delete_blog_category or update_product_category, and no mention of prerequisites such as confirming the categories are empty or that deletion is permanent. Usage must be entirely inferred from the name.

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

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

Annotations declare readOnlyHint=false, confirming mutation. The description adds real behavior beyond that: replace_function replaces the entire function and the server finds boundaries automatically, add appends at end of file, remove deletes a function, update_imports targets lines before the first export, and the return value is the updated function list. It does not mention whether edits are reversible or versioned, which is a minor gap for a destructive tool.

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

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

Front-loaded with the core purpose and the sibling comparison before the action breakdown. The bulleted action list is scannable and each line earns its place, though the total length is on the longer side.

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 states the return value (updated function list). It covers all four actions, param pairing, and the sibling alternative. Safety/undo semantics for the destructive remove/replace paths are the only notable omission.

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 action, code, and function_name. The description restates the param-to-action pairing in prose but adds little syntax or constraint detail beyond what the schema provides, so baseline 3 applies.

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

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

States a specific verb (edit), resource (HTTP function file), and scope (by function name), then immediately distinguishes itself from update_http_function. An agent can route between the two 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 names when to use this tool (targeted changes: fix a bug, rename, add one function) and the alternative for the opposite case (multiple new functions or refactors → update_http_function with full content). The action list further clarifies per-mode 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?

Annotations already declare readOnlyHint=true, so safety is covered. The description adds nothing behavioral beyond that: it does not say whether a missing customer errors or returns empty, whether ID/phone/email matching is exact, or whether multiple matches are possible. With no output schema, that gap matters.

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

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

A single front-loaded sentence with no filler; the lookup keys are listed immediately after the verb. It is efficient, though thin rather than deliberately minimal.

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

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

For a two-parameter read tool with full schema coverage and a safety annotation, the description is minimally sufficient. It leaves unaddressed the key behavioral question an agent faces: what a lookup returns when nothing matches or when phone/email formats vary.

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 'by' enum documents the three accepted fields, so the schema does the heavy lifting. The description merely restates those same keys without adding format or matching-semantics detail, which is baseline 3.

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?

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

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

There is no when-to-use guidance and no mention of alternatives such as list_customers for browsing or a search tool. The agent must infer that this is a single-record exact-match lookup rather than a filtered list.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description's main added value is operationalizing 'active' as is_activated=true plus a start/end time window, which prevents a misread of the filter. It says nothing about return volume, ordering, or pagination for what could be a large set.

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

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

A single sentence with the resource and the defining filter front-loaded; there is no filler and nothing that could be cut without losing meaning.

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

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

For a parameterless read with no output schema and a one-line annotation, the description supplies the one thing that matters: what 'active' means. Missing only secondary details such as result ordering or whether results are capped.

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

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

The tool takes zero parameters, so there is no parameter semantics to convey; the schema is empty and nothing in the description contradicts it. Baseline 4 applies for a no-parameter tool.

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

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

States a specific verb ('Get') and resource ('promotions') and pins down the scope with the parenthetical definition of 'active' (is_activated=true and within start_time/end_time). This implicitly separates it from sibling readers like list_promotions, search_promotions, and get_promotion, though none of those siblings are named.

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 'currently active' predicate implies when to reach for this tool versus an unfiltered listing, but there is no explicit when-to-use or when-not-to-use guidance and no named alternative. Usage must be inferred from the scope qualifier.

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 safety is covered. The description adds a genuinely useful behavioral detail beyond that: it returns null when the app is not installed, and that the type argument accepts either the numeric code or the name.

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 first sentence is tight and front-loaded, but the 18-item code enumeration is fully duplicated from the schema's parameter description, making the bulk of the text redundant rather than informative.

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

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

For a one-parameter, read-only getter with full schema coverage and no output schema, the description covers purpose, the not-installed null case, and accepted input forms. Only the shape of a successful app object is left unstated, a minor 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 coverage is 100% and the single parameter's description already lists every code. The description's code list and the 'number or name' note merely duplicate the schema, adding no meaning the schema does not already carry. 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 ('Get one installed app') with singular scope that cleanly separates it from list_apps, install_app, uninstall_app, and update_app. An agent can pick the correct sibling without opening any schema.

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

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

The description explains what the tool returns but never says when to reach for it over list_apps, nor any prerequisite (e.g. installed state, site/workspace context). No when/when-not guidance and no named alternative are provided.

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

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

readOnlyHint=true already establishes the safe-read profile, and the parenthetical adds genuinely useful context that the response carries full HTML content (volume/payload expectations). It stops short of permission needs, content-size caveats, or error behavior for missing IDs.

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 compact sentence, front-loaded with the action and resource, with the payload note in a parenthetical rather than padding. 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 single-parameter read tool with annotation-backed safety and no output schema, the description covers action, identifier, and what comes back. Only a brief note on when to prefer it over list_articles would make it fully 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% and the single 'id' parameter is documented in the schema as 'Article ID'. The description's 'by ID' simply echoes that; no format, type, or resolution details are added.

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: retrieves a single article by ID, and clarifies the payload includes full HTML. It is easily distinguished from list_articles/create_article/update_article by name, but the description itself does not name those siblings or contrast scope.

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

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

No guidance on when to use this versus list_articles or search alternatives, no prerequisites, and no exclusions. The agent must infer that this is the single-record fetch from the name alone.

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

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

The readOnlyHint annotation already establishes this as a safe, non-mutating read. The description adds the useful prerequisite framing ('read this before building'), but says nothing about whether the guide is static or reflects current site state, how large the payload is, or whether it should be re-read per session. Adequate, not rich.

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 load-bearing: the first defines scope by content type, the second states the triggering condition. The prerequisite instruction is front-loaded after the scope statement with zero filler.

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

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

For a zero-parameter, read-only documentation fetch with no output schema, the description covers what an agent needs: what the guide contains and when to fetch it. Minor residual gap is whether the content is site-specific or generic, but nothing required to select and call the tool is absent.

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

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

The tool takes zero parameters, so the baseline is 4 and there is no parameter meaning for the description to add. Nothing is missing or misleading on this dimension.

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 ('Get the BuilderX page authoring guide') and then enumerates the exact subject matter covered: page shape, grid layout model, styling, breakpoints, forms/data, build workflow. An agent can distinguish this from sibling guide/inspection tools like get_intake_guide or get_page_schema 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 explicit when-to-use guidance: 'Read this before building or heavily editing a page,' which ties invocation to a concrete task state. It stops short of naming alternatives or stating when it is unnecessary (e.g., for light edits), so it is clear context rather than a full decision rule.

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

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

readOnlyHint=true already establishes the safe-read profile, so the description gets a lower bar. It usefully discloses the response content (full schema plus records), which is real added value, but omits that records may be returned unbounded/unpaginated and says nothing about behavior when the id 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?

A single front-loaded sentence with the head verb and resource first, followed by the payload contents. The parenthetical enumeration is slightly dense but every element earns its place by telling the agent what comes back.

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 so by listing the schema facets and records. What is missing is scale/volume behavior for the records portion and error behavior for an invalid id, which would matter for an agent fetching a record-bearing collection.

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

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

Only one parameter and schema description coverage is 100%, so the schema already documents 'Collection ID' fully. The description adds no format hints (e.g., slug vs numeric id) 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?

States a specific verb+resource ('Get a specific collection') and enumerates what the payload contains (schema fields, types, constraints, references, plus records). This clearly separates it from create_collection/update_collection_columns, but it never names or contrasts with the closest siblings list_collections and query_collection_records.

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

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

There is no explicit when-to-use guidance, no prerequisites, and no mention of alternatives such as list_collections (for enumeration) or query_collection_records (for filtered record retrieval). The agent must infer from the name that this is the 'one collection by id' lookup.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description goes further by naming the two return groups (combo_items with counts, bonus_items as free gifts), which is useful since no output schema exists, but it says nothing about pagination, empty results, or error behavior for an invalid combo ID.

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, return shape stated up front, zero filler 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 simple two-parameter read tool with no output schema, the description covers what is fetched and the shape of the response, which is enough for correct invocation. Minor gaps remain around the is_variation_bonus effect and empty/error cases.

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

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

Schema description coverage is 100% with only two params, so the schema already documents combo_product_id and is_variation_bonus. The description adds no syntax, format, or semantics beyond the implied combo linkage, 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 (Get) and resource (items/bonus products composing a combo), and clarifies that it returns the components of a combo rather than the combos themselves. It is distinguishable from list_combos, though it never names that sibling explicitly.

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

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

The description says what is fetched but gives no when-to-use, no prerequisite framing (e.g. 'given a combo_product_id from list_combos'), and no guidance on choosing this over list_combos or get_product. Usage is only inferable from the resource name.

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

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

With readOnlyHint=true the safety profile is already covered, so the bar is lower, and the description still adds real value by disclosing the four pieces of state it surfaces (site_id, API URL, session, account). This is meaningful because there is no output schema, so the description is the only signal about what comes back.

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

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

Two short sentences with zero waste: the first defines the payload, the second gives the ordering advice. The most actionable instruction ('call this first') is placed where it will be read immediately.

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 zero-parameter, read-only, no-output-schema tool, the description covers the essentials: what it returns and when to call it. The exact shape of the returned payload (field names, nesting) is still unspecified, but that is a minor gap given the tool's diagnostic nature.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. There is nothing for the description to clarify about arguments, and it correctly avoids inventing any.

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 ('Show') and resource ('current connection context') and enumerates exactly what that context contains: site_id, API URL, session, and account info. This is far more specific than a tautology, though it never names or contrasts with adjacent siblings like get_site_info or list_my_sites, which also touch on site identity.

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

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

'Call this first to confirm you're working on the right site' gives an explicit sequencing directive and the goal that motivates the call, which is exactly what an agent needs before mutating a site. It does not state when *not* to use it or point at alternatives, so it stops 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 declare readOnlyHint=true, so safety is covered. The description goes beyond that by disclosing the shape and intent of what it returns (an authoritative default skeleton you can copy and edit, plus meaningful config keys and allowed values), which materially helps the agent use the result.

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

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

Two front-loaded sentences with no filler: the first lists the return contents, the second states the usage rule. Slightly dense parenthetical enumeration, but 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?

With no output schema, the description carries the return-value burden and does it well by naming the constituent parts (category, container flag, ATTRIBUTES, skeleton node). It is nearly complete for a single-param reference lookup; only minor details like pagination or size limits are absent, which are unlikely to matter 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 description coverage is 100% and the single 'type' parameter is documented with examples ('text', 'button', 'grid-product'). The description reinforces 'element type' but adds no 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 specific verb+resource ('Get the full detail of an element type') and enumerates exactly what is returned: category, container flag, summary, ATTRIBUTES reference, and a live skeleton node. This clearly distinguishes it from list_elements (enumeration) and get_page_element (an instance on a page).

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 tells the agent when to use it: 'Read this before authoring/editing an element so you set the right keys.' That is a clear usage context, though it does not name an alternative tool or state exclusions.

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

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

Annotations already declare readOnlyHint=true, and the description adds genuinely useful context: each version carries its saved content, and that content is what gets fed back to mutation tools. The caveat that update_http_function applies specifically to the http_function file is a helpful non-obvious detail. It stops short of describing ordering or pagination behavior.

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

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

Two tight sentences with zero filler; the tool's function leads and the actionable restore path follows. 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?

With no output schema, the description correctly compensates by explaining what a version contains (its saved content). Combined with the restore routing, an agent has enough to call it and act on results; only return ordering/shape details are absent.

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

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

Only one parameter and schema description coverage is 100%, so the schema fully documents cms_file_id. The description adds no format, ID-source, or filtering detail beyond it, 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?

States a specific verb and resource ('View version history of a CMS file'), which an agent can distinguish from sibling tools like get_page_versions or save_file_version. It never explicitly contrasts itself with those siblings, but the resource scope is unambiguous.

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

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

Gives a clear follow-up workflow: to restore, pass the version's saved content to update_http_function (for the http_function file) or update_cms_file, or call restore_file_version. This effectively tells the agent when to use each downstream alternative, though it doesn't state when this tool itself should be preferred over other history/inspection 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?

With readOnlyHint=true already covering the safety profile, the description adds real value: it discloses the compact-tree output shape, the per-line format, and the 3-5x token saving versus raw JSON. It does not cover pagination or limits, but explains the tradeoff against the raw option.

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 purpose then format then recommended use. Every sentence earns its place, including the dense but purpose-relevant line-format legend.

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 correctly shoulders the burden of describing the return format via the per-line legend, and the raw parameter is covered in the schema. Complete enough for an agent to call it, though edge cases like empty sections or very large trees are unaddressed.

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

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

Schema description coverage is 100%, with both global_section_id and raw fully documented in the schema, so the baseline is 3. The description's mention of the compact format does not add syntax or meaning beyond what the schema already states.

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

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

States a specific verb (get), a singular resource (one global section), and the output representation (COMPACT tree), which cleanly distinguishes it from the sibling list_global_sections. An agent can tell what it 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?

Explicitly names a use case — 'learn how a real Header/Footer/block is composed before building your own' — which routes the agent toward the tool for pre-build reference. It does not state when NOT to use it or name a direct alternative, but the context is clear.

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

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

Annotations already declare readOnlyHint=true, so safety is covered; the description adds genuine value by disclosing the returned payload categories (style, config, specials, events, bindings, responsive bp1..bp4, children IDs). It does not cover pagination or auth, but for a read-only fetcher this is solid 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?

A single front-loaded sentence with no filler; the enumerated detail is the information an agent needs and every element 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?

With no output schema, the description's field enumeration is important and largely compensates by telling the agent what is returned. It is nearly complete for a two-param read tool, missing only pagination/error behavior.

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 both IDs, including the element_id format example ('MENU-1'). The description adds no meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb ('Get full detail') and resource ('a single element inside a global section'), and the parenthetical enumerates the exact fields returned. It implicitly distinguishes from get_global_section (whole section) and search_global_section_elements (search), but does not name those siblings explicitly.

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

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

The phrase 'of a single element inside a global section' implies when this is used (retrieving one element by ID), but there is no explicit when-to-use/when-not guidance or named alternative such as search_global_section_elements for discovery.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description's contribution is limited to confirming it returns multilingual content. It says nothing about return shape, pagination, or whether missing components yield 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?

A single front-loaded sentence with no waste. It is terse to the point of being a fragment, but nothing is redundant 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?

For a one-parameter read tool with annotations and no output schema, the definition is adequate but thin: it doesn't describe the structure or scope of the 'multilingual contents' returned, which the absent output schema leaves undocumented.

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

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

Schema coverage is 100% with a single well-documented 'component' parameter including examples, so the schema carries the semantics. The description's 'by component type' adds only marginal meaning beyond it; 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 clear verb+resource+scope: 'Get multilingual contents for global sources by component type'. This distinguishes it from most siblings, though it doesn't clarify how it differs from close relatives like get_global_source_detail or update_global_source_contents.

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 offers no when-to-use guidance, no prerequisites, and does not name any alternative among the many global-source siblings. The agent must infer its role purely from the name.

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

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

Annotations only declare readOnlyHint=true; the description goes beyond that by disclosing the exact return format ("ID [type] text .class [events] [bindings] (children_count)"), which is valuable since there is no output schema. It still does not mention size limits or pagination.

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

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

Three sentences, front-loaded with the purpose before the output-format details. The dense line-format string earns its place by describing the return shape, though it is harder to parse than a short prose summary.

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 so by explaining the tree line format; annotations cover safety and the schema covers both params. An agent has enough to call it correctly, though the relationship to get_global_source_contents remains 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% and the schema description already explains the component hint, so the baseline is 3. The description adds the marginal insight that component can be omitted after calling list_global_sources, but does not enrich global_source_id 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 ("Get full detail of a global source") and even describes the output shape (compact tree view of all elements). It does not differentiate from the close sibling get_global_source_contents, which sounds like it could return similar detail, so sibling differentiation is incomplete.

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?

"Provide component for faster lookup; omit if you already called list_global_sources" gives one actionable condition tied to a sibling, but it is guidance about a parameter rather than when to choose this tool over alternatives like get_global_source_contents. Usage is implied rather than explicitly scoped.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description adds the useful detail of which facets are returned, but says nothing about permissions, lookup cost, or what happens when an element ID is not found.

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

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

A single front-loaded sentence with zero filler; the parenthetical enumeration is dense and directly useful.

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's enumeration of returned fields carries meaningful weight, and annotations cover the safety profile. It is complete enough for a low-complexity read tool, though error/empty-result behavior is unstated.

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

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

Schema description coverage is 100% with only 3 parameters, so the schema already documents global_source_id, element_id, and the optional component hint. The description adds no additional meaning beyond the schema; baseline 3 applies.

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

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

States a specific verb (Get) and resource (full detail of a single element in a global source), and enumerates the returned facets (style, config, specials, events, bindings, responsive, children), which clearly separates it from the plural 'search_global_source_elements'. It does not name a sibling explicitly, so it stops short of 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 explicit when-to-use or when-not guidance. The word 'single' implicitly contrasts with the search_global_source_elements sibling and get_global_source_detail, but the agent must infer that routing decision from the name alone.

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

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

Annotations only provide readOnlyHint=true; the description adds real behavioral context by disclosing exactly what each mode returns (names + line ranges vs. full code + collection schemas) and which mode is default. It doesn't mention permissions or rate limits, but for a read-only getter the return-shape disclosure is the salient behavior.

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

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

Front-loads the core action, then uses bullets to separate the two modes, followed by a tip and guide flag. No sentence is wasted and the structure matches how an agent would reason about the choices.

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 so fully — it spells out the return content of both modes. Combined with complete parameter and mode guidance and a sibling pointer, the definition is sufficient to invoke 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 coverage is 100%, so the baseline is 3, but the description goes well beyond the terse schema text ('true=function list only, false=full code'). It explains what overview actually returns, notes the default, and describes include_guide's one-time nature, materially enriching both parameters.

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

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

States a specific verb and resource ('Get the main HTTP function file') and immediately differentiates itself from the sibling get_http_function_snippet, which it names. An agent can distinguish it from the many other 'get_*' tools 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 maps each mode to a task: overview=true for browsing/structure discovery, overview=false for writing/refactoring. It also names the alternative (get_http_function_snippet) and the condition (small fixes) that selects it. 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?

The readOnlyHint annotation already establishes that this is a safe read operation, and the description's 'Read specific function(s)' is consistent with that. The additional token-efficiency statement is useful behavioral context, but the description does not disclose return format, auth needs, or other operational traits.

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

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

Two short sentences with zero waste. The main action is front-loaded and the token-efficiency benefit is stated immediately after, making the description easy to scan.

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

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

For a simple read-only tool with one well-documented parameter and readOnlyHint annotations, the description is nearly complete enough to select and invoke correctly. It could mention the return shape since there is no output schema, but that omission is minor for this low-complexity tool.

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

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

Schema coverage is 100%, and the single function_names parameter is already well documented in the schema with an example. The description's phrase 'by name' adds minimal meaning beyond the schema, so the baseline of 3 applies when the schema carries the parameter semantics.

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 specific function(s) by name.' It also distinguishes itself from reading the full file, which helps separate it from broader file-read siblings. It does not name the sibling tool get_http_function directly, so it is clear but not fully differentiated by name.

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

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

Provides clear usage context by saying it is much more token-efficient than reading the full file, implying use it when only specific functions are needed. It does not explicitly name the alternative tool or state when not to use this tool, so guidance is strong 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?

readOnlyHint=true already tells the agent this is a safe read, and the description is consistent with that (fetching a guide mutates nothing). It adds genuine behavioral context beyond the annotation: what the tool returns (questionnaire + build flow) and how it fits the workflow. It stops short of describing format or size of the returned guide.

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 zero filler; the core action is front-loaded and the skip conditions follow immediately. Every clause carries actionable 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 carries the burden and does state what is returned (questionnaire + build flow) and the workflow it drives. Minor gap: it does not clarify the relationship to get_build_guide, a plausible sibling that could be confused with 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?

The tool takes zero parameters, so the baseline is 4 per the rubric. There is nothing parameter-wise for the description to compensate for, and it correctly implies no input is needed.

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

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

Specific verb+resource ('Get the INTAKE questionnaire + build flow') with a clear temporal scope ('to run BEFORE creating a new site/store/page'). It is distinguishable from build-time siblings, though it does not explicitly name alternatives like get_build_guide, so differentiation is implicit rather than stated.

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

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

Explicitly states when to call it ('at the start of any fresh build'), the exact procedure (ask one short batch, restate plan, get a yes, then build), and the exclusions ('Skip only for tiny edits, data questions, or when the user already gave the brief / says just do it'). This is a textbook when/when-not definition.

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 safe-read profile is covered. The description usefully discloses the breadth of returned data (customer info, items, payment, shipping, discounts), but says nothing about authorization requirements, not-found behavior, or pagination, keeping it at a 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?

A single tight sentence that front-loads the core action and then maps out the return contents. No filler, though the trailing 'etc.' slightly weakens the enumeration's precision.

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 must carry return-value meaning – and it does, listing the major fields returned. For a one-parameter read tool this is close to complete, with the only gap being the vague 'etc.'.

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 'id' parameter is already documented as 'Order ID'. The description adds no format or syntax detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb ('Get') and resource ('order details') scoped by ID, and enumerates the returned sub-resources (customer, items, payment, shipping, discounts). It implicitly distinguishes itself from the singular/plural sibling list_orders via 'by ID', but never explicitly contrasts the two.

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

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

Usage is only implied by 'by ID' – an agent infers it applies when an order ID is known. There is no explicit when-to-use, when-not-to-use, or reference to alternatives such as list_orders or count_orders_by_status.

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

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

readOnlyHint=true already establishes this is a safe read, so the bar is lower; the description still adds real value by disclosing the conditional output shape (page_id + committed_count appear only when a commit is in progress). It doesn't mention auth or rate limits, but the read-only nature and conditional return are well conveyed.

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

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

A single front-loaded sentence with zero filler; the enumerated fields follow the verb and the conditional clause is placed last, which is exactly 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?

For a read-only single-param tool with no output schema, the description usefully enumerates the returned fields and their conditional nature, so an agent knows what to expect. Only the absence of routing guidance to sibling draft tools keeps it from being fully 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 coverage is 100% with the single draft_id parameter documented as 'Draft id', so the schema carries the burden. The description's phrase 'a local page draft' implies the id refers to a local (not published) draft but adds no format or sourcing detail beyond the schema baseline.

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

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

States a specific verb ('Inspect') and resource ('a local page draft') and enumerates the concrete data returned (meta, section ids, section count, and commit progress fields). This clearly separates it from list_page_drafts (plural listing) and commit_page_draft, though it never explicitly names those 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?

The description explains what the tool returns but gives no when-to-use or when-not-to-use guidance, and never names alternatives like list_page_drafts or get_page_source. The parenthetical about an in-progress commit hints at context but is not an actionable usage rule.

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

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

readOnlyHint=true already establishes this as a safe read, so the bar is lower. The description adds real value by enumerating the returned facets (style, config, specials, events, bindings, responsive, children IDs), which is the main behavioral context an agent needs here.

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

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

Two tight sentences with the core action front-loaded and zero filler. The return-field list is compact and earns its place given the absence of an output schema.

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

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

With no output schema, the description correctly compensates by summarizing what is returned. Combined with readOnlyHint and full param coverage, an agent has enough to invoke it correctly, though the missing sibling disambiguation is a minor 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 coverage is 100% and both parameters are fully documented, so baseline 3 applies. The ID examples in the description largely duplicate the examples already present in the element_id schema field, adding little 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 ('Get full detail') and resource ('a single element by its ID') with concrete ID examples ('TEXT-3', 'BUTTON-1'). It is distinguishable from list_elements/search_page_elements, though it never names the near-identical sibling get_element to disambiguate.

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 saying it fetches full detail for a single element when you have its ID. There is no explicit when-to-use/when-not guidance and no mention of alternatives such as get_element or list_elements, despite several highly similar 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=true, so safety is covered. The description adds genuinely beyond that: it characterizes the return as the authoritative contract, names the draft version, and enumerates the node fields (id/type/specials/runtime{style,config}/children/events/bindings) in the CSS-grid model.

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, front-loaded with the core action and resource before the contract details and the validate_page pointer. The parenthetical field list is information-rich rather than filler, though it slightly burdens the 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?

No output schema exists, so the description carries the burden of conveying the return value, and it does so by describing the schema shape and its node fields. For a zero-param read tool this is close to complete, with only the draft/version dependency 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?

The tool takes zero parameters, so there is nothing to disambiguate and the baseline of 4 applies. The description correctly implies a no-argument fetch.

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

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

States a specific verb ('Get') and resource (the authoritative JSON Schema for a page source), and scopes it precisely as the Draft 2020-12 structural contract. It contrasts cleanly with sibling validate_page, which the agent can distinguish 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?

Tells the agent how to apply the result ('Use it as the shape to emit') and names the complementary alternative validate_page with its distinct role (semantic rule enforcement). No explicit 'when not to use' is given, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds useful behavioral context by specifying what data the overview returns (counts plus custom CSS classes), which tells the agent what to expect without a formal output schema. It omits pagination or rate-limit behavior, keeping 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 tight sentences with zero filler; the useful scoping and return-content information is front-loaded, and the routing guidance follows immediately.

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 steps in by listing what the response contains, and the annotation covers the read-only safety profile. It is nearly complete for a one-parameter read tool, though it stops short of describing the response's structure or shape.

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 single page_id parameter is already documented by the schema. The description adds no syntax or format meaning beyond the schema, matching the baseline 3 when schema fields do 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 ('Get page source overview') and enumerates the exact return contents (section count, element type counts, custom CSS classes). It explicitly distinguishes itself from the sibling search_page_elements, 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 prescribes an order: 'Use this first, then use search_page_elements to find specific elements.' This names the alternative and the condition that selects it. However, it does not mention other plausible alternatives such as get_page_schema or list_page_contents, so it 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?

The annotations already declare readOnlyHint=true, so safety is covered externally. The description adds nothing beyond that: no pagination or result-limit behavior, no ordering (newest-first?), no indication of whether the current live version is included, and no note about how many versions 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?

One short, front-loaded sentence with zero filler. It is efficient, though its brevity borders on under-specification rather than true economy.

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 one-parameter read tool with annotations covering safety, this is roughly adequate. Because there is no output schema, the description should have hinted at the returned structure (version identifiers, ordering), which it does not.

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?

Single required parameter page_id with 100% schema description coverage, so the schema already documents it. Baseline 3 applies; the description contributes no extra meaning such as ID format or how to obtain a page_id.

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: 'View version history of a page.' The 'page' qualifier implicitly separates it from get_file_versions and save_file_version, but it never explicitly names or contrasts those siblings, and it doesn't say what 'version history' contains (IDs, timestamps, authors).

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 prerequisites, and no alternatives offered. An agent cannot tell from this text whether it should call get_page_versions, get_page_source, or list_page_drafts to inspect a page's prior states.

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

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

The readOnlyHint annotation already establishes this as a safe read operation, so the description's main added value is listing the returned fields. It adds useful detail about what data comes back but does not cover error behavior, permissions, or other operational traits.

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

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

A single sentence, front-loaded with the action and resource, then efficiently listing returned fields. It is appropriately sized for a simple lookup tool and contains no wasted text.

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

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

For a simple one-parameter read tool with full schema coverage and a readOnlyHint, the description supplies enough context. It gives a useful field list despite no output schema, though the 'etc.' leaves the return shape slightly open-ended.

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 only parameter is already documented as 'Product ID' in the schema. The description's 'by ID' adds no new syntax or format details beyond the structured field.

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 product') and explicitly scopes it to 'by ID', which distinguishes it from list_products and search_products. It also enumerates the returned fields, making the tool's purpose 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 phrase 'by ID' implies the tool is for when the agent already has a product ID, but there is no explicit guidance on when to prefer it over siblings like list_products or search_products. Usage context is implied rather than stated.

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

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

The readOnlyHint annotation already establishes this is a safe read, so the description only needs to add context. It adds value by enumerating what the record contains, but says nothing about behavior on an unknown/invalid ID, auth requirements, or payload size.

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 compact, front-loaded sentence with no preamble. The trailing 'etc.' slightly weakens the otherwise precise field enumeration, but nothing is wasted.

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

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

With no output schema, the description usefully enumerates the returned fields so an agent knows what to expect. For a simple one-parameter read tool this is largely sufficient; only error/auth behavior 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 description coverage is 100% for the single 'id' parameter, so the schema already carries the semantics; the description's 'by ID' merely restates it. 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?

States a specific verb and resource ('Get full promotion details by ID') and enumerates the payload (name, type, schedule, discount rules, coupon settings, items, bonus products). It clearly distinguishes a single-record fetch from the list/search siblings, though it never names them explicitly.

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

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

Usage is implied by 'by ID' – call it when you already have a promotion ID. There is no explicit when-to-use or when-not-to-use guidance, and the closely related siblings (get_active_promotions, search_promotions, list_promotions) are not referenced for disambiguation.

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 that this is a safe read operation. The description adds useful context about the returned item structure, mentioning fixed_prices, level_info, and coupon_item_info, but does not describe pagination behavior or whether there are any rate or auth constraints.

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 wasted words. The core action and scope are front-loaded, and the parenthetical return detail is compact and useful.

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 tool with a simple schema and no output schema, the description is almost complete: it explains what is retrieved and names key return fields. Minor missing detail about pagination or response shape keeps it from being fully comprehensive.

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 id, page, and limit. The description adds no additional syntax, format, or constraints beyond indicating that id refers to a promotion. 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 and resource: getting products, variations, or categories attached to a promotion. It also names the kind of data returned (discount details), which clearly distinguishes it from sibling promotion tools like get_promotion or list_promotions.

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 description—use this when you need items attached to a promotion—but there is no explicit guidance about when to choose this tool over get_promotion, get_active_promotions, or search_promotions. No exclusions or prerequisites are mentioned.

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

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

readOnlyHint=true already establishes the safe-read profile, and the description adds behavioral detail beyond that: the default returns ALL 4 fields in full, filtering reduces payload, and the guide is a first-call-only artifact. It omits anything about response size limits or ordering, which keeps 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?

Purpose is front-loaded in the first clause, followed by a compact two-mode breakdown and a single advisory line. Efficient and scannable, with only mild redundancy between the bullet text and the parameter schema descriptions.

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, zero-required, read-only tool with no output schema, the description covers the mode selection and the optional guide flag adequately. An agent can call it correctly on the first try; only the shape of the returned code payload 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%, so the baseline is 3, but the description adds real context the schema lacks: why to filter (token savings) and the 'only needed on first call' nuance for include_guide. It stops short of naming the field values, which the schema's enum already covers.

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 ('Get custom code of the site (CSS/JS)') and breaks the tool into two named modes, so an agent immediately understands what comes back. It does not explicitly contrast with nearby siblings like get_page_source or update_site_custom_code, so it stops short of a 5.

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

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

Gives concrete when-to-use guidance for each mode: omit the filter for full content, pass fields to save tokens, and set include_guide=true on the first call. No exclusion criterion against alternative retrieval tools is given, but the conditional usage is clear.

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

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

readOnlyHint=true already conveys safety, so the description's added value is elsewhere: it discloses the return surface and, importantly, freshness semantics ('preview_img — the latest homepage screenshots ... refreshed after publish_site') plus exact viewport variants. It stops short of stating any auth, quota, or failure behavior, but for a zero-param read tool that gap is minor.

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

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

A single sentence, front-loaded with the primary payload and then the preview image detail. The parenthetical enumerations are dense but every item (colors, typography, layout, language, payment methods; 1920_1080 / 430_932) conveys concrete return content 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?

With no output schema, no input parameters, and only a readOnlyHint annotation, the description carries the full burden of describing what comes back — and it does, naming the top-level fields, the settings categories, and the image variants. 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?

The tool takes no parameters, so the baseline is 4 and there is nothing the description could add. It correctly avoids inventing pseudo-parameters.

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

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

Specific verb+resource ('Get full site information') immediately followed by an enumeration of the exact fields returned (name, domain, settings sub-fields, preview_img). This tells an agent how it differs from neighbors like list_my_sites (inventory) and get_current_context (ambient state).

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 rather than stated: the note that screenshots are 'refreshed after publish_site' hints at when the data is freshest, but there is no explicit when-to-use, when-not-to-use, or named alternative versus list_my_sites / get_current_context. The agent must infer that this is the detail-fetch for the active site.

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 safety is covered. With no output schema, the description's disclosure that results come as a compact tree with full element hierarchy is genuinely useful behavioral context, but it stops short of covering volume, scoping (which sources count as 'cart'), or pagination.

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

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

Two short sentences, front-loaded with the core action, and the second sentence adds a distinct routing benefit rather than restating the first. No waste, though the wording is slightly loose around 'cart'.

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 zero-parameter read-only tool this is close, and the description partially compensates for the missing output schema by describing the tree view. Still, it leaves 'cart' undefined and does not indicate result scope or size, so an agent cannot fully predict what it receives.

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

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

The tool takes zero parameters, so the schema baseline is 4. There is nothing parameter-wise for the description to clarify.

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 ('Get all cart global sources') plus the output shape ('compact tree view'), so the agent knows what it returns. It partially differentiates from siblings by referencing get_global_source_detail, though the ambiguous term 'cart' and the overlap with list_global_sources keep it from a 5.

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

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

It offers one routing hint — that a separate call to get_global_source_detail is unnecessary — which implies this is a one-stop retrieval. However it never states when to prefer it over the very similarly named list_global_sources or how it differs, so the guidance is implied rather than 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?

readOnlyHint=true already declares this is a safe read, so the description's job is lighter. It adds real value by disclosing the shape of the extracted blueprint and the scope caveat that the result is not a 1:1 clone, which sets expectations about fidelity. It omits any input-size limits or handling of malformed HTML.

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

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

Two tight sentences, front-loaded with the core action and output, with the scoping caveat placed last where it belongs. Every clause earns its place.

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