WebCake Storefront MCP

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

With no annotations, the description carries the full burden and reveals key behaviors: 'NO network,' 'can't time out,' re-id'ing to avoid collisions, quick validation, and non-blocking warnings. It does not mention side effects or return values, but the most critical operational traits are transparent.

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 concise, front-loaded sentences with no filler. Each sentence provides distinct, essential information: what it does, its key constraints, and how to construct the input.

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 2-parameter tool with no output schema, the description covers the critical operational context (no network, durability, validation behavior) and workflow linkage (new_section). It could mention the follow-up commit step (commit_page_draft), but the core usage is clear enough.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by instructing to build the section with 'new_section' and noting that sections are re-id'd, which clarifies parameter usage beyond the schema.

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

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

The description uses a specific verb ('Append') and resource ('local page draft') with a clear scope ('ONE section'), and it distinguishes itself from the sibling tool 'add_section' by emphasizing the local, no-network nature.

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

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

The description clearly implies when to use this tool: as a durable per-section cache step that avoids network timeouts. It also directs the agent to build sections with 'new_section,' providing a concrete prerequisite. However, it doesn't explicitly state when not to use it (e.g., when network access is acceptable).

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

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

No annotations exist, so the description takes on full responsibility. It discloses key behaviors: reading current source, appending, validating, saving only when dry_run=false, and re-id'ing sections to avoid collisions. This is exemplary transparency for a potentially 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?

Three sentences deliver purpose, process, and safety guidance without wasted words. The description is front-loaded and every sentence serves a distinct purpose.

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

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

The description covers the core workflow and side effects well. It is missing return value description (preview output) and behavior on validation failure, but the tool complexity is moderate and the safety workflow is well documented.

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 descriptions for all three parameters. The description adds extra meaning by directing users to build the section with new_section and explaining the re-id behavior, which clarifies the section parameter's role beyond its raw schema.

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

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

The description clearly states a specific action: 'Append a section to an EXISTING page's source.' This distinguishes it from page creation or draft-specific tools, especially with the mention of re-id and building with new_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 gives concrete usage context: it appends to existing pages, requires a section from new_section, and provides a two-step safety workflow with dry_run. It lacks explicit comparisons to alternatives like add_draft_section or update_page_source, 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?

With no annotations provided, the description carries the full burden for behavioral disclosure. It reveals a critical behavior: 'WITHOUT reading the existing content first,' which alerts the agent that this is a blind append/prepend operation. It also clarifies the additive nature, though it does not mention auth requirements, rate limits, or exact return values.

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

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

Three short sentences, front-loaded with the core action, followed by usage context and an alternative. Every sentence earns its place, with no redundancy or filler.

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

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

Given no annotations and no output schema, the description provides essential decision-making information: operation type, usage scenario, and an explicit alternative. It is sufficient for an agent to select and invoke the tool correctly, though it omits potential error cases and return format.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds some context by referencing CSS/JS/script tags as examples of 'code' and implies the 'position' parameter via 'append or prepend.' However, it doesn't add deeper semantics about the field enum or edge cases beyond what the schema already defines.

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

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

The description uses specific verbs ('Append or prepend') and names the resource ('custom code field'), clearly distinguishing it from sibling tools. It explicitly states 'For full rewrites, use update_site_custom_code instead,' which differentiates it from the update tool.

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

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

It explicitly states when to use: 'Use this when you need to ADD new CSS rules, JS code, or script tags — no need to read first.' It also provides a clear alternative ('For full rewrites, use update_site_custom_code instead'), giving both positive and negative guidance.

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

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

With no annotations, the description carries the disclosure burden. It transparently explains the two-step dry_run safety mechanism, that validation errors block the save, and the required source format. It does not mention auto-enabling data sources for special page types (covered in schema), but provides strong behavioral guidance.

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 sentences, front-loaded with the core purpose, followed by critical safety workflow and source requirement. Every sentence earns its place, with no redundant fluff.

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 a complex 7-parameter tool with a rich schema but no output schema, the description covers the essential workflow and validation behavior. It does not describe return values, but the stepwise safety info and source requirements make it largely complete for an AI agent to operate effectively.

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%, but the description adds meaning beyond the schema: it explains the dry_run validation/save sequence and directs users to build sections with new_section, clarifying the source parameter's structure and workflow. This adds practical parameter usage context.

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

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

The description clearly states 'Create a brand-new page AND set its full content source in one step,' combining a specific verb and resource. It differentiates from sibling tools like create_page by emphasizing the one-step source setting and 'brand-new' versus update semantics.

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 clear context for when to use the tool: when creating a page with full content source in one step, with a two-step dry-run workflow. It mentions new_section as a companion tool but does not explicitly state exclusions or alternatives (e.g., use update_page for existing pages).

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

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

With no annotations, the description carries the full burden. It discloses a crucial behavioral trait: the operation is scoped to the local draft and does not affect the backend page. This addresses the most important side-effect concern. It does not mention irreversibility or confirmation, but for a simple delete operation, this is adequate.

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

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

The description is a single, well-structured sentence. It front-loads the action and the critical caveat, with no unnecessary 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 one-parameter delete tool with no output schema, the description is nearly complete. It covers the core action and the important exception. Minor gaps exist regarding irreversibility and return values, but these are not critical for this tool's scope.

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 parameter 'draft_id' is already described as 'Draft id'. The description adds no additional meaning beyond the schema, so it meets the baseline of 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?

The description clearly states the tool's function: 'Delete a local page draft'. It uses a specific verb ('Delete') and resource ('local page draft'), and explicitly distinguishes it from deleting a backend page, which differentiates it from sibling tools like delete_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?

The description provides clear context by clarifying that this tool does NOT delete the backend page, which implies when not to use it. However, it does not explicitly name an alternative tool (like delete_page), so it falls short of a 5.

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

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

With no annotations, the description fully carries the burden and does so excellently. It discloses incremental persistence, per-request timeout, mode-specific behavior, progress saving, and failure recovery semantics (page_id + committed_count). This goes far beyond a generic 'commit draft' statement.

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 with clear emphasis (INCREMENTALLY, dry_run=true, RESUMABLE). No wasted words, and the structure naturally guides from primary purpose to operational modes to failure handling.

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 complexity (incremental, resumable, multi-request), the description is highly complete. It covers the process, retry behavior, and mode semantics. It does not describe return values or stats preview details, but the absence of an output schema makes this 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%, so baseline is 3. The description adds meaningful context: it explains the default dry_run=true, contrasts the two modes, and ties draft_id to the resumability mechanism. This enriches the schema descriptions rather than merely repeating them.

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

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

The description opens with a specific verb+resource: 'Persist a local page draft to the backend INCREMENTALLY' and clarifies the one-section-per-request behavior. This distinguishes it clearly from sibling tools like add_draft_section, get_page_draft, and clear_page_draft. The dry_run vs false modes further specify the tool's 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?

The description explicitly explains when to use dry_run=true (validate/preview) versus dry_run=false (create and persist), and notes resumability for retries. It does not explicitly name alternatives or say 'use X instead,' but the mode guidance provides strong practical direction for the primary use case.

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

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

No annotations are present, so the description carries the full burden. It states the aggregation behavior ('grouped by status') but doesn't add details like whether all orders are included, if zero-count statuses appear, or the exact return shape. For a simple read-only count, the lack of side effects is implied by 'get,' but additional context would be helpful.

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

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

The description is two short sentences with no filler. It front-loads the core action and adds a brief use case, making it highly efficient.

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 aggregation tool with no parameters and no output schema, the description gives the essential behavior and intended use. It could be improved by specifying the output structure (e.g., key-value pairs or list of status/count), but overall it is sufficient for an agent to select and 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?

The tool has zero parameters, and the schema coverage is trivially 100%. Per the baseline for 0 params, a score of 4 is appropriate, as there is no parameter information needed and the description does not need to compensate.

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

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

The description 'Get order count grouped by status' clearly specifies the verb (get), resource (order count), and grouping (by status). It distinguishes itself from sibling tools like list_orders or get_order, which return order details rather than aggregated counts.

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 'Useful for dashboard overview' provides a clear context for when to use this tool, implying it is for aggregate reporting rather than detailed order inspection. However, it does not explicitly name alternatives or exclusions, so it stops short of a 5.

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

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

With no annotations, the description carries the burden and adds useful behavior: articles are auto-filed under the default category, IDs and slugs are backend-generated, and image URLs must be hosted. It does not mention response format or publish/draft status, but it is fairly transparent for a create operation.

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

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

The description is dense but not overly long, front-loading the core purpose and then giving pipeline details. The phrase 'Built via dashboard command pipeline' is somewhat vague, but the overall structure is efficient and each sentence adds relevant 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?

Given no output schema and no annotations, the description covers the tool's purpose, key parameters, and prerequisite relationships with sibling tools. It lacks explicit return-value details or whether the article is immediately published, but it is reasonably complete for a create operation.

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

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

The input schema already covers all parameters at 100% with descriptions, so the baseline is 3. The description adds value by explaining where category_ids come from, emphasizing that image URLs must be hosted, and clarifying that summary is optional—all beyond the schema.

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

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

The description states a specific action ('Create a blog article') with the exact resource and purpose ('so blog/post pages have content'), naming concrete page types. This clearly distinguishes it from sibling tools like update_article, delete_article, and list_articles.

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

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

The description gives clear context and directs the agent to source category_ids from create_blog_category and use hosted images from search_images/upload_images. However, it does not explicitly mention when not to use this tool (e.g., for editing an existing article, use update_article), so it stops short of full when/when-not coverage.

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

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

With no annotations, the description carries the full burden. It discloses that the tool creates a category, returns the new ID, and requires the image to be a hosted URL. It also notes that post-list/blog pages bind to the category, providing useful integration behavior. It lacks detail on permissions or error handling but adds meaningful behavioral context.

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

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

The description is two sentences, front-loaded with the main action. It efficiently communicates the purpose, return value, downstream usage, and an image constraint without redundancy or unnecessary detail.

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

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

For a simple 3-parameter create tool with no output schema, the description is complete. It explains the return value, how to use it with create_article, and a parameter constraint. The integration with post-list/blog pages gives sufficient context for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so each parameter already has a description. The tool description only reiterates the image URL requirement, which is nearly identical to the schema's 'Hosted image URL'. No additional syntax or format details are provided beyond the schema, so it meets the baseline.

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

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

The description clearly states 'Create a blog/article category', using a specific verb and resource. It distinguishes this from sibling create_product_category by specifying 'blog/article', and explains the returned category id's role with create_article, which further clarifies its purpose.

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 clear usage context by explaining to pass the returned ID to create_article's category_id, showing when to use this tool for grouping posts. It does not explicitly mention alternatives like create_product_category, but the 'blog/article' qualifier makes the intended domain 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?

No annotations are provided, so the description carries the full burden. It only states 'Create a new CMS file' and lists types; it does not disclose failure modes, permissions, whether existing names are overwritten, or what the response looks like. Minimal for a mutation tool.

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

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

Two short sentences, direct, no filler. The type list earns its place by clarifying valid values without redundancy.

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

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

Low complexity, schema fully covers parameters and default value. However, with no annotations or output schema, the description omits return/error behavior and usage context; it is acceptable but not 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 already documents all three params with descriptions (100% coverage), and the description's type list repeats the enum. No additional meaning is added beyond the schema, so the baseline of 3 is appropriate.

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

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

Clearly states 'Create a new CMS file' with a specific verb and resource. Listing types ('http_function', 'jobs_config', 'default') distinguishes this from update_cms_file and other sibling 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?

Implied usage: use to create new CMS files; the types hint at specialized file kinds. However, no explicit guidance on when to use this over update_cms_file or http_function-specific tools, nor when not to use it.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It reveals that collections start with system columns and highlights the platform limitation about no direct record insertion. However, it does not mention permission requirements, potential errors, or reversibility, so it stops short of full transparency.

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 sentences with no wasted words. The core action is front-loaded, followed by a useful note and a cross-reference. Every sentence earns its place.

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

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

The description covers the essential creation workflow and importantly warns about the record-write limitation, which is critical for the overall data management context. It does not describe the return value or error scenarios, but given the schema's completeness, this is 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?

The input schema has 100% coverage with descriptions for all three parameters (name, columns, table_name). The description's mention of 'pass columns to add custom fields' largely repeats what the schema already says, adding no new parameter-level details or constraints.

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

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

The description opens with 'Create a new collection (custom data TABLE)', using a specific verb and resource. It distinguishes from sibling tools by clarifying that a collection is a custom data table, and the parenthetical about system columns helps define its behavior.

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 explicitly states when to use this tool (to create a collection) and when not to: 'to WRITE records into it, use an HTTP function... the dashboard has no direct record-insert API'. It even points to get_http_function as the alternative, giving clear 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?

No annotations are provided, so the description carries the burden. It discloses the dual side effect: persisting a record and embedding the section into page sources, with header/footer placement behavior. It also explains the dry_run default and atomic save. It doesn't mention permissions or conflict handling, but the key behavioral traits (what gets modified and the safety mechanism) are transparent.

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 sentences with no filler. It front-loads the purpose, provides a prerequisite action, and explains the dry-run mode. Every sentence contributes meaning, and the structure is 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 mutation tool with no annotations and no output schema, the description covers the core behavior, the required sequence, and the safety mechanism. It doesn't specify response format or what happens on conflicts, but the essentials for invocation are present. The complexity is moderate, and the description is adequate.

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 input schema already has 100% coverage with descriptions for all five parameters, so the baseline is 3. The description adds workflow context (e.g., 'give it a real bg/padding + logo/menu/links' for the section parameter) and explains the `type` field's role in placement (header→top, footer→bottom) beyond the schema enum. This supplementary guidance elevates it above 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?

The description clearly states the tool creates a reusable global section and explicitly contrasts with the builder's behavior: it persists a global_section record AND embeds the section node into page sources. It distinguishes from sibling tools like new_section (which builds the section) and list_global_sections (which reads). The reference to 'Header / Footer / shared block' and the top/bottom placement provides concrete 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?

It gives explicit workflow guidance: 'Build the section first with new_section ... then pass it here.' It also explains the two-step safety with dry_run=true preview vs dry_run=false atomic save, which tells the user when to use each mode. It implies alternative/complementary tool (new_section) and the distinction between creating the content vs embedding it site-wide.

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

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

No annotations are provided, so the description carries the full burden. It discloses only the creation action and does not mention side effects, permissions, return values, or any behavioral constraints, leaving the agent without critical context.

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

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

The description is a single, direct sentence that immediately states the tool's purpose and includes useful component type examples. It is concise, front-loaded, and contains no filler.

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

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

For a simple create tool, the description covers the core purpose and parameter types, but without an output schema it does not explain the return value or any side effects. It is minimally adequate but lacks behavioral and outcome details.

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

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

The schema covers 100% of parameters with descriptions, so the description does not need to add much. The description restates the component type examples already in the schema, adding minimal value beyond the structured definition.

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

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

The description clearly states the action (create) and the resource (new global source component), and it distinguishes this from update/delete siblings by saying 'Create a new'. It also enumerates valid component types, adding specificity.

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 is provided on when to use this tool versus alternatives like create_global_section or update_global_source. There is no mention of prerequisites, exclusions, or preferred contexts.

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

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

With no annotations, the description carries full burden. It discloses meaningful behavioral details: 'type is a KIND ... mapped to the numeric backend type' and warns about empty-title publishing without seo. However, it does not mention possible side effects, permissions, return values, or error conditions, leaving gaps for a mutation tool.

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

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

Two sentences, front-loaded with the core action, and every sentence earns its place. The alternative tool and key caveat are packed efficiently without redundancy.

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

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

The description plus the rich schema (100% coverage, detailed slug/type notes) covers the main invocation concerns. It lacks an explicit return value statement (no output schema), but for a create tool with an empty page and alternative guidance, the provided context is largely complete. Could be improved by noting what is returned.

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. The description adds beyond schema by explaining that 'type is a KIND' underlying numeric mapping and why 'seo' matters (avoids empty-title publishing), which gives agents extra semantic context not present in the structured 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?

The description clearly states 'Create a new (empty) page' – a specific verb and resource. It also distinguishes the tool from sibling 'build_page' by noting the empty-page scope, so the purpose 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?

Explicit guidance is provided: 'For a page with content use build_page instead' names the alternative and gives the condition for using this tool. Additionally, the warning to 'pass seo so it doesn't publish with an empty title' instructs on a prerequisite for safe use.

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

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

No annotations are provided, so the description carries the burden. It discloses key behaviors: backend generates id/slug, publishes the product, auto-creates a default variation, and requires hosted URLs. It does not cover auth/error cases but sufficiently reveals side effects.

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

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

The description is compact, with three sentences covering purpose, usage modes, and key constraints. Every sentence adds value, and the line breaks for simple/advanced usage improve readability.

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

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

For a tool with 11 parameters and no output schema, the description provides high-level workflow context and prerequisites (hosted images, category IDs). It does not detail return values, but the schema already covers parameter specifics, making this adequate.

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 detailed descriptions, so baseline is 3. The description adds conceptual meaning by grouping parameters into simple vs. advanced usage and explaining relationships (e.g., name+price for simple, attributes+variations for multi-SKU), which goes beyond the schema.

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

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

The description clearly states the tool creates a product for storefront merchandise, with a specific verb and resource. It distinguishes from siblings like update_product/delete_product by emphasizing creation and the resulting published product.

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 explicit usage guidance: 'Simple use' and 'Advanced use' with parameter combinations, and instructs to obtain hosted URLs from search_images/upload_images. It implies but does not explicitly name alternatives like update_product for modifications, so a 4 is appropriate.

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

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

With no annotations provided, the description carries the full burden. It discloses a key behavioral trait (returns the new category id) and a constraint (image must be a hosted URL), but does not mention potential side effects, required permissions, or error cases. This is adequate but 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?

The description is two well-structured sentences. The first states the purpose and the second provides the return value and a key constraint. Every word earns its place, with no redundancy or filler.

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

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

Given there is no output schema, the description appropriately discloses the return value (category id) and its intended use. It also explains the purpose and the image constraint, covering the essential information for a simple create tool. A minor gap is not explaining potential validation errors or parent_id prerequisites, but overall it is fairly complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds no new parameter information beyond the schema; the 'Image must be a hosted URL' note duplicates the schema's 'Hosted image URL' description. No additional semantics are provided.

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

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

The description clearly states the action ('Create a product category') and the specific resource, distinguishing it from sibling tools like create_blog_category and update_product_category. It also explains the purpose ('so grid-category / a category page has something to show, and products can be filed under it'), adding specificity.

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 context on when to use the tool, such as needing categories for category pages or to file products, and explicitly instructs to pass the returned id to create_product's category_ids. However, it does not explicitly mention when not to use it (e.g., for blog categories) or name alternatives, but the context is clear enough.

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

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

With no annotations, the description carries full behavioral burden and does so excellently. It discloses that the backend auto-seeds sample data, that the tool deletes it by default, that the site has no pages, and that free accounts have a 4-site quota. These are critical non-obvious behaviors.

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 dense and well-organized, starting with the primary action and then layering important caveats and workflow steps. There is no fluff, and every sentence adds meaningful 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?

Despite having no output schema, the description covers the creation process, default behaviors, quota limitations, and next steps. It provides enough context for an agent to invoke the tool and understand the immediate consequences and follow-up actions.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra semantic value by explaining the practical effect of keep_seed (keep sample data vs. delete) and switch_to (changes session context), which goes beyond the schema's straightforward definitions.

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

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

The description clearly states the tool creates a brand-new storefront site for the current account, with specific behavior (switching to it, returning an empty clean site). It distinguishes itself from related sibling tools like create_site_from_template by emphasizing the blank, no-template nature of the created site.

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

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

The description provides clear context on when to use this tool and a recommended follow-up workflow (get_build_guide → new_section/new_element → build_page). It does not explicitly mention alternatives like create_site_from_template, so it lacks explicit exclusion guidance, but the context 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?

With no annotations, the description carries the behavioral burden. It discloses that the tool clones the template's pages, global sections, cart, popups, styles and fonts, and that it switches the session to the new site—a key side effect. It implies the new site is not yet published by directing next steps to publish_site, which is useful disclosure, though return values and error cases are not mentioned.

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 sentences, each earning its place: what it does, what it clones, and how to use it next. It is front-loaded with the core purpose and avoids 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?

Even without annotations or an output schema, the description provides a complete operational picture: prerequisites, cloned content, session switching, and next steps for editing and publishing. This is sufficient for an agent to select and 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?

All four parameters are already described in the schema (100% coverage), so the baseline is 3. The description adds meaningful workflow context by explaining where theme_id comes from (semantic_search_themes/list_template_themes) and confirming the switch_to behavior, which helps an agent correctly construct the invocation.

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 opening sentence states a specific action ('Create a NEW site from a marketplace TEMPLATE') and designates it as the dedicated API, distinguishing it from the sibling create_site. It also names the cloned resources (pages, global sections, cart, popups, styles, fonts), making the tool's role unmistakable.

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 a concrete workflow: pick a template with semantic_search_themes/list_template_themes, pass its theme_id, then edit with update_page_element(s)/site-style tools and publish_site. This explicitly frames the prerequisite and follow-up actions, and the 'dedicated API' wording subtly distinguishes it from create_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?

With no annotations, the description carries the transparency burden. It states that execution happens in debug mode without deploying and that results and console logs are returned, but it does not disclose potential side effects, permissions, resource limits, or safety considerations beyond the 'without deploying' qualifier.

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

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

The description is a single, concise sentence with no filler. It front-loads the action and includes key modifiers ('debug mode', 'without deploying', 'returns execution result and console logs') without unnecessary elaboration.

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 tool's moderate complexity and lack of output schema, the description provides a good overview of purpose, behavior, and expected return. It could mention prerequisites or edge cases, but for a debug execution tool, the essentials are covered.

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

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

Schema description coverage is 100%, with all three parameters (content, function_name, params) adequately described in the schema. The description adds no additional param-level detail, so the baseline of 3 applies.

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

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

The description uses a specific verb ('Run') and resource ('JS code') with a clear scope ('in debug mode (without deploying)'). It also distinguishes from sibling tools like run_function by highlighting the debug-only nature and return of console logs.

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

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

The description implies use for testing code without deployment but does not explicitly mention alternatives or explain when to use this tool over run_function or other code execution tools. Context is present but no direct comparison or exclusions are given.

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

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

With no annotations, the description carries the full burden of behavioral disclosure, but it only states the action 'Delete' without indicating permanence, side effects, required permissions, or any other consequences. For a destructive operation, this is a significant gap.

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

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

The description is a single, clear sentence that is extremely concise and front-loaded. It contains no fluff or unnecessary words, making it efficiently scannable for an agent.

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

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

The tool is simple with one parameter and no output schema, but it is a destructive operation. The description omits any mention of permanence, whether it can be undone, effects on related data, or success/failure outcomes, leaving the context incomplete for an agent.

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

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

The schema fully describes the only parameter 'id' with 'Article ID' (100% coverage). The description adds no additional parameter semantics, so the baseline of 3 is appropriate given the schema's completeness.

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

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

The description uses a specific verb 'Delete' and resource 'blog article', clearly distinguishing it from sibling tools like delete_page and delete_product. It adds the modifier 'blog' which provides refinement beyond the tool name 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 is provided about when to use this tool versus alternatives, nor any conditions, prerequisites, or warnings. The description is purely a statement of function with no usage 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?

With no annotations provided, the description carries the full burden. It explicitly discloses that the action is irreversible and removes all records in the collection, which are critical behavioral traits. It does not mention permissions or return values, but the key destructive behavior is well covered.

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 concise: two short sentences that immediately state the action and its irreversible nature. There is no filler or redundant information.

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

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

For a simple delete operation with one parameter and no output schema, the description covers all essential aspects: what is deleted, the scope (all records), and irreversibility. The low complexity means nothing important 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 schema describes the only parameter (collection_id) with 'Collection id.', and the tool description reinforces 'by id.' Since schema coverage is 100%, the description adds little beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description states clearly that the tool deletes a collection (table) and all its records by id. This is a specific verb+resource+scope, and it distinguishes the tool from siblings like get_collection, update_collection_columns, 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?

The description implies usage—when you need to permanently delete a collection—but does not explicitly state when to use it versus alternatives, nor does it mention exclusions or prerequisites. The irreversibility warning is more of a caution 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?

With no annotations provided, the description carries the full burden of disclosing behavior. It clearly indicates the destructive nature ('Delete', 'remove... from every page source') and adds safety context (two-step dry_run, atomic save). It does not mention irreversibility or auth requirements, but the dry_run safety mechanism is a significant transparency win.

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 concise sentences: the first states the core action and scope, the second explains the safety workflow. No filler or redundant phrasing. All information is necessary and front-loaded.

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

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

The tool is a destructive mutation with no annotations or output schema. The description covers what it does, the affected scope, and the safety flag. It does not describe the return value or error behavior, but for a delete tool with a dry run, this is reasonably complete.

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

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

Schema description coverage is 100%, so the schema already documents both parameters well. The description names the parameters (dry_run, section_id) and explains the dry_run flow, but this adds little beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'Delete' and specific resource 'global section (Header/Footer/block)', further specifying that it removes the node from every page source. This distinguishes it from sibling tools like delete_global_source and delete_page, making the 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 description provides clear context on how to use the dry_run parameter (preview vs. perform), but it does not explicitly state when to use this tool versus alternatives like delete_page or delete_global_source. No exclusions or alternative recommendations are given, so it's adequate but not explicit.

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

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

With no annotations provided, the description carries the full burden for behavioral disclosure. It does reveal a key trait—that it also deletes the published version—which goes beyond the bare action. However, it omits other destructive-operation traits like irreversibility, permission requirements, or cascading effects, leaving significant gaps.

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

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

The description is a single sentence, front-loaded with the action verb, and contains zero filler. Every word adds value: the resource, the action, and the notable detail about the published version.

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 delete tool with no output schema, the description is largely complete: it states the action, the target, and an important scope detail. It does not explain error conditions or post-deletion behavior, but given the tool's simplicity, those omissions are not critical.

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

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

The schema already fully describes the single parameter (global_source_id) with a description ('Global source ID to delete'), and the tool description adds no additional semantic meaning beyond repeating the schema. With 100% schema coverage, the baseline is 3, and no enhancement is provided.

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

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

The description uses a specific verb ('Delete') and resource ('global source') and adds a key differentiator ('and its published version'), clearly distinguishing it from sibling tools like update_global_source, get_global_source_detail, 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?

The description implies usage (when you need to delete a global source) but provides no explicit guidance on when to use this tool versus alternatives, nor any exclusions. The mention of deleting the published version hints at scope but does not cover prerequisites or alternative actions like unpublishing.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It fails to mention whether deletion is permanent, if it cascades to dependent resources, or if any confirmation is needed. For a destructive operation, this lack of side-effect disclosure is a significant gap.

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

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

The description is a single concise sentence with no unnecessary words. It is front-loaded and immediately communicates the action, making it appropriately sized for a straightforward tool.

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?

Although the tool is simple with one parameter, it is destructive and the description lacks essential warnings about permanence or side effects. Without annotations or an output schema, the description should compensate but fails to provide a complete picture for safe 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% for the single parameter page_id, whose description 'Page ID to delete' is present. The tool description adds no additional meaning beyond what the schema already provides, so it meets the baseline for high coverage.

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 'Delete a page' uses a specific verb (Delete) and a specific resource (a page), clearly distinguishing it from sibling tools like create_page, update_page, and list_pages. It communicates the exact action without ambiguity.

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 no guidance on when to use this tool versus alternatives, nor does it mention any prerequisites, consequences, or conditions. It is simply a bare statement of the action, leaving the agent without context for appropriate usage.

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

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

With no annotations provided, the description carries full burden for behavioral disclosure. It only says 'delete' which implies mutation, but does not mention potential consequences like permanence, required permissions, or whether the operation is a hard or soft delete. This is a notable gap 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?

The description is a single, concise sentence that directly communicates the tool's purpose. It contains no filler or redundant content, making it highly efficient.

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 tool's simplicity (one required parameter with full schema coverage, no output schema needed), the description is adequate. It explains the core function and the parameter. However, a brief note on irreversible effects or authorization requirements would make it more 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?

The input schema covers 100% of parameters with a clear description for product_ids, so the baseline is 3. The description's 'by id' adds no new information beyond the schema, making it redundant but not harmful.

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 'Delete one or more products by id' with a specific verb (delete), resource (products), and method (by id). It clearly distinguishes from sibling delete tools like delete_product_category and delete_article by explicitly targeting products.

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

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

The description gives no guidance on when to use this tool versus alternatives such as set_product_published (which could be used to unpublish instead of delete) or other delete tools. It only states the action itself without contextual cues or exclusions.

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

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

With no annotations provided, the description needs to disclose behavioral traits such as whether deletion is permanent, whether it cascades to related products or subcategories, or any required permissions. The description only states the core action without any such context.

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

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

The description is a single, focused sentence that conveys the action immediately, with no unnecessary 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?

Although the tool is simple, it is destructive and no annotations or output schema exist. The description lacks any mention of irreversibility, side effects, or what happens to associated products, leaving the agent with insufficient context for safe 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?

The input schema already documents the 'ids' parameter with its type and description, covering 100% of parameters. The description adds only a slight clarification that deletion is 'by id' and supports 'one or more', which is already implied by the array type, so it adds marginal value.

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

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

The description clearly states that the tool deletes one or more product categories identified by id, using the specific verb 'Delete' and the resource 'product categories'. This distinguishes it from sibling tools like delete_product, delete_page, or update_product_category.

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 no guidance on when to choose this tool over alternatives, such as when it is appropriate to delete a category versus archival, or any prerequisites. There are no exclusions or alternative recommendations.

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

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

With no annotations, the description carries the disclosure burden. It reveals useful behavior: server finds function boundaries automatically, replacement is whole-function, appending goes to end of file, and update_imports affects lines before first export. It also discloses the return value. However, it doesn't explicitly warn about the destructive nature of replace/remove or error handling.

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 well-structured: a leading sentence for purpose, a clear alternative, a bulleted action list, and a return note. Every sentence adds information; no tautology 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?

Despite lacking annotations and output schema, the description fully covers the tool's actions, parameter usage, and return value. It also provides usage boundaries versus update_http_function. No significant gaps are apparent for this complexity level.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by mapping each action to which parameters are meaningful and how they're used (e.g., replace entire function vs append; import block vs code). It clarifies the relationship between action, code, and function_name beyond the schema's short descriptions.

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

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

The description uses a specific verb ('Edit') with a clear resource ('HTTP function file') and scope ('by function name'). It lists four concrete actions and explicitly contrasts with update_http_function, 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?

It explicitly states when to use this tool ('best for targeted changes...') and when to use an alternative ('For writing multiple new functions or major refactors, use update_http_function with full content instead'). This is a clear when/when-not statement naming the alternative.

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

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

With no annotations, the description carries the burden for behavioral disclosure. It explains the return contents (image bytes, element_id, source_type, source_id) and the pre-built items template, but it does not explicitly state whether the operation has side effects, requires authentication, or has payload/rate 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?

The description is well-structured with a summary and numbered workflow, making it easy to follow. However, the final sentence redundantly restates the step 3 instruction about filling placeholders, so it is not maximally concise.

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

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

The workflow and return format are clearly explained, which is good for a single-purpose helper. But missing parameter semantics, no output schema, and no mention of edge cases or failure behavior leave notable gaps for an agent to safely invoke this tool in all situations.

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

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

Schema description coverage is only 40%, with page_id, max_size_mb, and scope lacking descriptions in the schema. The description only mentions using 'scope/limit' and never explains the meaning of the enum values or the other parameters, so it fails to compensate for the low schema coverage.

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

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

The description clearly identifies the tool as a one-shot helper for filling image_alt, returning image bytes and element metadata, and distinguishes it from siblings like read_images and set_image_alts by prescribing a specific workflow. The verb 'fetch' plus 'images_for_alt_fill' makes the 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?

Provides explicit workflow context: call with scope/limit, receive images and metadata, draft alts, then call set_image_alts once. This effectively tells when to use the tool, though it does not explicitly mention alternatives or when not to use it.

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

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

No annotations are provided, so the description carries the full burden. It only states the core action without disclosing return behavior, error handling, or whether the operation is strictly read-only. The term 'find' suggests non-mutating, but this is not explicit.

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

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

The description is a single sentence with no filler, front-loading the action and resource. Every word contributes meaning, making it highly concise and well-structured.

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

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

For a simple lookup tool with two parameters and no output schema, the description covers the resource and search fields but omits explicit return value details, behavior when no match is found, or potential multiple matches. It is adequate but has gaps.

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

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

The input schema already provides 100% coverage with clear descriptions for both parameters, including the enum for 'by'. The description adds little beyond restating the search fields, so it does not significantly enhance understanding beyond the schema.

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

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

The description clearly states the action (find), the resource (customer), and the three supported search fields (ID, phone, email). This is specific and distinguishes it from list_customers and other customer-related 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?

The description implies usage for looking up a single customer by one of the specified identifiers, but it does not explicitly mention when to prefer it over alternatives or when not to use it. No comparison with list_customers or other search tools is 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?

With no annotations provided, the description carries the burden of behavioral disclosure. It transparently explains the exact activity filter (is_activated=true and time range), but it does not mention other behaviors such as pagination, sorting, or absence of side effects. As a simple read operation, this is adequate but 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?

The description is a single, concise sentence that defines both the action and the exact criteria for 'active'. It is front-loaded with the main purpose and contains no redundancy or filler.

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

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

This is a simple zero-parameter read operation with no output schema. The description provides the necessary filter context to understand what the tool returns. However, it could slightly benefit from mentioning its read-only nature or how it differs from list_promotions, though such omissions are not severe given the simplicity.

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

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

The input schema is empty (0 parameters), and the description correctly focuses on the tool's behavior rather than parameter details. Since there are no parameters, the baseline is 4; the description adds value by explaining the implicit filtering 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?

The description clearly states the tool's function: 'Get all currently active promotions' with explicit filtering criteria (is_activated=true and within start_time/end_time range). This is a specific verb+resource combination, but it does not explicitly distinguish itself from sibling tools like list_promotions or search_promotions, which may also return 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?

The description implies when to use this tool: when you need only currently active promotions. However, it does not explicitly state when not to use it or mention alternative tools for broader queries or more complex filtering, leaving some ambiguity.

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

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

No annotations are provided, so the description carries the full burden. It adds useful behavioral context: returns null if not installed and accepts number or name. But it doesn't describe the return object structure, error behavior for invalid codes, or any read-only confirmation. This is a partial 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?

Two sentences: the first states the core function and null behavior, the second lists codes compactly. Every element earns its place, and the information is front-loaded.

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

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

For a simple getter with one parameter and no annotations, the description is nearly complete. It covers the return-null case and parameter format, but could mention what the returned app object contains. Since there is no output schema, a brief note about the return shape 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?

The schema description covers 100% of the parameter semantics, and the description duplicates the same information. No additional meaning is added beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description states a specific action ('Get one installed app') with a clear parameter (type code). It distinguishes itself from siblings like list_apps (which lists all) and install/uninstall/update_app by focusing on retrieval of a single app.

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

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

The description clearly indicates when to use the tool: to fetch one app by type code, with a useful null return semantics for not-installed. However, it doesn't explicitly name alternatives or state when not to use it, though the context is clear enough.

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

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

With no annotations provided, the description must carry the full burden of behavioral disclosure. It describes a read operation semantically, but it does not state return format, error behavior (e.g., 404 for unknown IDs), authorization requirements, or whether the retrieved article is a draft or published version.

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

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

The description is a single focused sentence, front-loads the action, and contains no unnecessary words or repetition of schema details.

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, the description is minimally viable: it states the operation and the key. However, with no output schema and no annotations, it leaves a gap by not specifying the shape or scope of 'article details', making the returned data unclear to the agent.

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 input schema already documents the single 'id' parameter with type string and description 'Article ID', covering 100% of parameters. The description adds little beyond the schema, just restating that lookup is by ID, which matches the baseline 3 for high schema coverage.

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 'Get article details by ID' uses a specific verb ('get') and resource ('article'), and specifies the lookup key ('ID'), clearly distinguishing it from sibling tools like list_articles. It unambiguously identifies a single-resource retrieval operation.

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

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

No guidance is provided about when to prefer this tool over siblings such as list_articles, update_article, or delete_article. The phrase 'by ID' implies usage with a known identifier, but there is no explicit context, prerequisites, or exclusions.

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

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

With no annotations, the description carries the transparency burden. The verb 'Get' implies a read-only operation, and the content list clarifies what the guide covers, but it doesn't explicitly state that it has no side effects or describe the output format. This leaves some behavior unspecified.

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

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

The description is two sentences: the first delivers the core purpose and content, the second gives usage guidance. There is no wasted wording, and it is well-structured with front-loaded 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 guide-retrieval tool with no parameters and no output schema, the description covers the essential context: what the guide contains and when to read it. It might have explicitly mentioned that it does not modify pages, but that is reasonably implied by 'Get'.

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 input schema has zero parameters, so schema coverage is 100%. According to the baseline for 0 params, a score of 4 is appropriate. The description adds no parameter info because none 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?

The description starts with a specific verb 'Get' and names the resource 'BuilderX page authoring guide', then lists the covered topics. This clearly distinguishes it from other tools like get_intake_guide and action-oriented siblings (build_page, update_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?

It explicitly states when to use the tool: 'Read this before building or heavily editing a page.' This is strong usage guidance. However, it does not mention any when-not cases or alternatives, so it misses the full 'vs alternatives' component.

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

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

With no annotations, the description carries the burden. It discloses the return contents (schema and records) but does not explicitly state that the operation is read-only or mention any side effects, permissions, or error conditions. The verb 'Get' implies read-only, which provides some transparency.

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

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

The description is a single, front-loaded sentence with no filler. Every word adds value, clearly stating the action, target, and notable output details.

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

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

The tool has only one parameter and no output schema. The description adequately explains the tool's purpose and key return data (schema and records). It does not mention pagination or potential errors, but these are not critical for a simple get operation.

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

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

The schema already provides 100% coverage for the single 'id' parameter ('Collection ID'). The description adds no additional parameter semantics beyond reinforcing that the id identifies a specific collection.

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 ('Get') and resource ('specific collection's details'), and adds detail about what's included (full schema and records), distinguishing it from siblings like 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?

The description clearly conveys the use case of retrieving a single collection's details with schema and records, implying when to use it. However, it does not explicitly name alternatives or exclusions, so it falls short of a 5.

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

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

With no annotations provided, the description carries the full burden. It goes beyond a simple statement of purpose by explaining the structure of the return (combo_items as required items with count, bonus_items as free gifts), which gives the agent a clear expectation of the output. It does not discuss side effects, but the 'Get' verb implies a read-only operation.

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

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

The description is a single, well-structured sentence. It front-loads the action and resource, then concisely explains the return format. All information is relevant and there is no redundancy or filler.

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

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

For a tool with only two parameters and no output schema, the description appropriately covers the return structure and distinguishes the two item types. It does not address error scenarios or the effect of optional parameters, but these are less critical for a simple read operation.

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

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

Schema description coverage is 100% (both parameters have descriptions), so the baseline is 3. The description adds minimal context about the parameters (e.g., linking bonus_items to free gifts), but it does not significantly elaborate on parameter semantics beyond what the schema already provides.

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

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

The description clearly specifies the action ('Get') and the resource ('items (products/variations) and bonus products that compose a combo'), distinguishing it from sibling tools like list_combos which focus on the combo list rather than its components. It also previews the return fields.

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

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

The description implies the tool is used when you need the component items of a specific combo, but it does not explicitly state when to use it over alternatives or provide exclusions. Given sibling tools like get_promotion_items, explicit comparative guidance would strengthen this aspect.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. 'Show' clearly implies a read-only operation, and the listing of what information is included gives the agent a good sense of the tool's return content. It does not explicitly state 'no side effects', but the non-mutating nature is strongly evident from the verb.

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

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

The description is two short sentences, front-loaded with the primary purpose and immediately followed by actionable guidance. Every word contributes value; there is no fluff or redundancy.

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

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

For a zero-parameter context getter with no output schema, the description explains what will be shown and why it matters, making it fully self-sufficient for an agent to select and invoke correctly. The context about confirming the correct site is particularly useful given the large roster of sibling tools.

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 input schema has zero parameters, and the baseline for zero-parameter tools is 4. The description adds no parameter-specific details because none exist, which is appropriate.

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

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

The description uses a specific verb ('Show') tied to a clear resource ('current connection context') and enumerates its contents (site_id, API URL, session, account info). This makes the tool's purpose unmistakable and distinguishes it from all sibling tools, none of which claim to expose current connection 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?

The phrase 'Call this first to confirm you're working on the right site' provides explicit when-to-use guidance. It does not mention alternatives or exclusions, but for a context-checking tool, the 'first call' directive is sufficient and clear enough to guide an agent.

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

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

With no annotations provided, the description carries the burden. It does describe behavioral output (live skeleton node, ATTRIBUTES reference) but does not explicitly state whether the operation is read-only or any other side effects, auth needs, or rate limits. The 'get' verb implies safety, but the description leaves those aspects implicit.

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

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

The description is two sentences with dense, structured information. It front-loads the main action and follows with a clear usage tip. Every clause adds value, and there is no filler or redundancy.

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

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

Given the tool has only one parameter and no output schema, the description thoroughly explains what the response will contain (category, container flag, summary, ATTRIBUTES reference, skeleton node) and provides usage context. This is sufficient for an agent to understand the tool's role and invoke it correctly.

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

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

The schema already fully describes the only parameter 'type' with examples. The tool description simply repeats 'element type' without adding any additional semantic context (e.g., valid values, case sensitivity, or relationship to other tools), so it adds no value beyond the schema.

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

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

The description explicitly states the tool gets the full detail of an element type, enumerating the specific contents (category, container flag, summary, ATTRIBUTES reference, live skeleton node). This clearly distinguishes it from sibling tools like get_page_element or get_global_source_element by focusing on 'element type' as a resource.

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

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

It provides a clear usage directive: 'Read this before authoring/editing an element so you set the right keys.' However, it does not explicitly mention when not to use it or name alternative tools, such as list_elements for a catalog overview or get_page_element for page-instance details.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It usefully reveals that each version includes its saved content and that restoring requires passing that content back or using restore_file_version. However, it omits details like ordering, pagination, or exact response structure. For a simple view-history tool, this is adequate but 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?

The description is concise, front-loaded with the core purpose, and every sentence adds value. The first sentence states what the tool does, and the second explains version content and restore options. No redundant or filler language is present.

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 tool with no output schema, the description covers the essential context: purpose, version content, and restore paths. It could mention ordering or whether all versions are returned, but these are minor gaps for a straightforward history-list operation. The description is complete enough for a user to confidently invoke the 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?

The schema already provides 100% coverage for the single parameter, describing cms_file_id as 'CMS file ID'. The description adds no additional parameter-level meaning, so the baseline score of 3 applies. It does tie the parameter to the concept of a CMS file but doesn't clarify format or constraints beyond the schema.

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

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

The description opens with a specific verb and resource ('View version history of a CMS file'), clearly identifying the tool's purpose. It also distinguishes itself from sibling tools by explicitly mentioning restore alternatives (restore_file_version, update_cms_file), making its read-only history role unambiguous.

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

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

The description provides concrete guidance on when to use this tool vs. alternatives: it tells you to pass saved content back to update_http_function/update_cms_file or to use restore_file_version for restoration. It doesn't explicitly state 'do not use this for restoring,' but the contrast is clear enough. No exclusion criteria are given, but the usage context is well implied.

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

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

No annotations are provided, so the description carries the full burden. It discloses the compact tree format, token savings, and the raw option's large-result cache behavior via the schema. However, it fails to explain the meaning of Nbind and Nev, and does not explicitly state that the compact tree is a lossy summary compared to raw JSON, leaving behavioral gaps.

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 sentences, each contributing essential information: the action and format, the line-by-line output structure, and the intended use case. There is no verbose or redundant phrasing.

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 tool with well-described parameters, the description covers purpose, output format, and usage guidance. The lack of an output schema is compensated by the line-format explanation. Minor gaps around abbreviations and potential lossy nature prevent a perfect score.

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?

Both parameters are fully described in the schema (100% coverage), so the description adds little per-parameter semantics. The line-format explanation provides context about the default output of the raw parameter, but this is a minor enhancement over the schema's descriptions. Baseline 3 is appropriate.

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

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

The description clearly states the action: 'Get one global section as a COMPACT tree', specifying both the resource and output format. It distinguishes from siblings by emphasizing the compact tree vs. raw JSON and the learning purpose, which is unique among related tools like get_global_section_element or list_global_sections.

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 explicit usage context: 'Use this to learn how a real Header/Footer/block is composed before building your own.' This tells the agent when to choose this tool, though it does not explicitly mention alternatives or exclusion cases, so it falls short of a 5.

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

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

With no annotations, the description carries the burden. It adds context by listing the return content, which indicates read-only behavior via the verb 'Get', but it does not disclose error behavior, prerequisites, or any hidden side effects. The listing of returned fields is helpful but not comprehensive for behavioral transparency.

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

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

The description is a single, focused sentence that front-loads the purpose and lists specific details in parentheses. Every word contributes value, with no redundancy or filler.

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

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

For a simple 2-parameter read tool, the description covers the purpose and return scope well, and the sibling context helps differentiate. However, without an output schema, the description could be more precise about the structure of the returned detail, and it omits potential caveats like failure modes. Still, it is largely complete for the tool's complexity.

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 both parameters (element_id and global_section_id). The description does not add additional parameter semantics beyond the schema, so the baseline score of 3 applies.

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

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

The description clearly states a specific verb ('Get') and resource ('full detail of a single element inside a global section'), enumerating the included details (style, config, specials, events, bindings, responsive bp1..bp4, children IDs). This distinguishes it from siblings like get_global_section (section-level details) and search_global_section_elements (searching).

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 scope ('inside a global section') and detail level ('full detail') imply when to use this tool, but there is no explicit guidance on when not to use it or alternatives. The description lacks direct sibling differentiation or exclusions, so it's merely implied usage.

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

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

With no annotations provided, the description carries the full burden. It implies a read operation via 'Get', but does not disclose behavior such as whether all languages are returned, whether the component parameter is required, or any limits. Lacks detail beyond the obvious read nature.

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

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

The description is a single sentence, front-loaded with the verb, and contains no waste. Every word contributes to the 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?

The tool is simple with one parameter and no output schema, so the description is relatively adequate. However, it leaves ambiguity about whether it returns contents for all global sources or a specific one, and does not describe the multilingual content structure. Given the low complexity, a 3 is appropriate.

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 an example for the 'component' parameter. The tool description adds no further parameter-specific semantics, but the schema already handles it, so the baseline of 3 applies.

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

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

The description uses a specific verb 'Get' and identifies a clear resource ('multilingual contents for global sources') with a scope ('by component type'). This clearly distinguishes it from sibling tools like update_global_source_contents or get_global_source_element, which have different purposes.

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

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

No guidance is provided about when to use this tool versus alternatives such as search_global_source_elements or get_global_source_detail. The description only states what it does, not the intended context or exclusions.

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

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

With no annotations provided, the description carries the full burden. It discloses the exact line format of the returned tree, including ID, type, text, class, events, bindings, and children_count, which gives the agent concrete expectations. It also mentions the performance behavior ('faster lookup') for the optional parameter.

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

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

The description is extremely concise: one sentence for purpose, one for output format, and one for usage hint. Every part carries actionable information with no fluff, and the front-loaded 'Get full detail' immediately clarifies the operation.

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 there is no output schema, the description fully specifies the return format and how to use the optional parameter. For a read-only detail tool, this is complete: it tells the agent what to expect (the tree lines) and how to optimize lookup, with no missing critical 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?

The schema already provides descriptions for both parameters (100% coverage). The description adds extra semantic value by explaining when 'component' should be omitted (if list_global_sources was already called) and reinforcing its role as a lookup hint, which goes 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?

The description uses a specific verb 'Get' with a clear resource ('full detail of a global source') and specifies the output as 'compact tree view showing all elements'. This clearly distinguishes it from sibling tools like get_global_source_element or get_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 gives practical guidance on the 'component' parameter ('Provide component for faster lookup; omit if you already called list_global_sources'), implying when to use the tool effectively. However, it does not explicitly contrast with alternative retrieval tools, so it lacks explicit 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?

With no annotations provided, the description must convey behavioral traits. It discloses what the response contains, but it does not explicitly confirm the operation is read-only, mention error conditions, or note any side effects. The verb 'Get' implies read-only, and the list of returned attributes adds value, but the absence of explicit safety statements leaves a gap.

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

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

The description is a single, focused sentence that front-loads the core purpose and lists key content categories without extraneous words. It is concise and well-structured.

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

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

Given no output schema, the description effectively summarizes the return content by listing the element's attributes. It is sufficient for a simple get tool with three parameters, though it could be more explicit about return structure or error behavior. Overall, it covers the essential 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?

The input schema describes all three parameters with meaningful descriptions (e.g., 'Element ID (e.g. TEXT-3)', 'Global source ID'). The description adds no additional parameter semantics beyond the schema, so the baseline of 3 applies.

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

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

The description clearly states the tool retrieves full detail of a single element and enumerates the included attributes (style, config, specials, events, bindings, responsive, children). This distinguishes it from sibling tools like search_global_source_elements (search vs. full detail) and get_global_source_detail (source-level detail).

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

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

The description implies usage when full element details are needed, but it does not explicitly state when to use this tool versus alternatives like search_global_source_elements or get_global_section_element. No exclusions or alternative guidance is 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?

No annotations are provided, so the description carries the full transparency burden. It clearly discloses what each mode returns (function names/line ranges vs full code + schemas) and explains the include_guide behavior. No contradictory or misleading statements.

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

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

The description is compact at four sentences, uses bullet points for clarity, and every sentence provides useful information. No fluff or redundancy.

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

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

For a tool with two optional boolean parameters and no output schema, the description covers purpose, modes, parameter usage, and a recommended workflow. It is self-sufficient and 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%, but the description adds significant meaning beyond the schema by detailing the practical effects of each boolean parameter and providing use-case guidance for them. This exceeds the baseline.

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

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

The description states 'Get the main HTTP function file' with a specific verb and resource. It also distinguishes two modes (overview vs full) and references the sibling tool get_http_function_snippet, making differentiation clear.

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

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

Explicitly explains when to use overview=true (browsing, structure) vs overview=false (writing, refactoring). Provides a concrete tip for small fixes to use overview first then snippet, naming the alternative 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?

No annotations are provided, so the description carries the burden. It discloses the read-only nature via 'Read' and adds the performance trait of token-efficiency. However, it does not mention return format, error handling, or behavior for non-existent function names.

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 concise sentences, front-loaded with the action and resource. The token-efficiency rationale is valuable and there is no wasted wording.

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 tool with one parameter and no output schema, the description effectively communicates the core action and a key benefit. It could add the return type or explicitly note non-mutation, but the current level is sufficient for selection and basic 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?

The input schema has 100% coverage for the single parameter function_names, including an example. The description adds little beyond the schema, only reinforcing the 'by name' aspect, which does not meaningfully improve parameter understanding.

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

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

The description clearly states the verb 'Read' and the resource 'specific function(s)' with the scope 'by name'. It also distinguishes itself from sibling tools like get_http_function by emphasizing token-efficiency compared to reading the full file.

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

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

It gives a clear usage context: use this when you need specific functions by name and want to avoid the token cost of reading the entire file. It implies the alternative (reading the full file) but does not explicitly name the sibling tool or state when not to use it.

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

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

With no annotations provided, the description deserves credit for outlining the workflow: ask a short batch, restate the plan, get a yes, then build. It discloses the sequential behavior, but it does not clarify what the tool returns (e.g., the exact questionnaire content) or any potential side effects, leaving a minor gap.

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

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

The description is just two sentences, front-loaded with the primary purpose and followed by concise usage guidance and exclusions. Every word contributes value, with no unnecessary repetition.

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

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

For a zero-parameter guide tool, the description sufficiently covers purpose, timing, and skip conditions. It does not specify the return format, but the description implies the output is a questionnaire/batch, which is probably enough for an agent. A more explicit statement of the output structure would improve completeness.

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 has zero parameters, so the schema already provides complete coverage. The description adds no parameter details, but none are needed. The baseline of 4 for zero-parameter tools 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 clearly states the tool 'gets the INTAKE questionnaire + build flow' and specifies the exact context ('before creating a new site/store/page'). It uses a specific verb and resource, and the mention of fresh builds distinguishes it from sibling tools like get_build_guide.

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

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

It provides explicit when-to-use instructions ('at the start of any fresh build') and when-to-skip conditions ('tiny edits, data questions, or when the user already gave the brief / says "just do it"'). This gives the agent concrete decision rules for invocation.

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

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

With no annotations, the description carries the burden of explaining behavior. It discloses the return content (customer info, items, etc.) and the verb 'Get' suggests a read-only operation, but it does not explicitly state side effects, permissions, or error behavior. This is adequate but 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?

The description is a single, front-loaded sentence that specifies the action, target, and key content areas. There is no superfluous text; every word adds value.

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

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

For a get-by-id tool with one parameter and no output schema, the description adequately outlines what the return contains (customer info, items, payment, shipping, discounts). It could be more precise about the response shape, but the 'full details' phrasing plus the enumerated list covers the main expectations.

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 single 'id' parameter is already documented in the schema as 'Order ID'. The description adds 'full details' context but no new parameter syntax or format details, aligning with the baseline for high schema coverage.

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

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

The description uses a specific verb ('Get') and resource ('full order details by ID'), and enumerates the included information (customer info, items, payment, shipping, discounts). This clearly distinguishes it from list_orders and count_orders_by_status, which are about order listings and counts rather than single-order detail retrieval.

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

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

The description implies the tool is for fetching a single order's full details when an ID is known, which is clear context. It does not explicitly state when not to use it or name alternative tools, but the scope is evident from the 'by ID' qualifier and the detail focus.

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

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

With no annotations provided, the description carries the full burden. It clearly signals a read-only inspection (via 'Inspect'), discloses the conditional output ('if a commit is in progress'), and notes the draft is local. It does not cover error behavior or details of 'meta', but the core behavioral traits are transparent.

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

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

The description is a single compact sentence, front-loaded with the action and resource. Every phrase adds value—naming the object, listing return fields, and noting the conditional behavior—without any redundancy or filler.

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

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

For a simple tool with one parameter and no output schema, the description adequately covers the return values, including the conditional behavior. It could optionally mention what happens if the draft doesn't exist, but this is not essential given the tool's simplicity.

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

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

The single parameter draft_id is fully described in the schema ('Draft id'), yielding 100% schema coverage. The description adds no additional meaning about the parameter itself, but the parameter is simple and self-explanatory, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb 'Inspect' and clearly identifies the resource 'a local page draft'. It enumerates the exact contents returned (meta, section ids, total section count, and conditional page_id + committed_count), distinguishing it from sibling tools like start_page_draft, commit_page_draft, or list_page_drafts.

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

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

The description implies usage when you have a draft_id and want to inspect its state, but does not explicitly state when to use this tool versus alternatives. It doesn't mention exclusions or contrast with sibling tools like list_page_drafts, making the usage guidance implicit 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?

With no annotations, the description carries the full transparency burden. It clearly indicates a read operation and enumerates the returned data fields (style, config, specials, events, bindings, responsive, children IDs). This provides useful behavioral context, though it does not explicitly address authentication prerequisites or error 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?

The description is a single, well-structured sentence that leads with the action and scope, follows with an illustrative example, and concludes with the return payload. No unnecessary words or repetition.

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

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

For a simple getter with two parameters and no output schema, the description provides sufficient detail about what the tool returns and how to specify the target element. It does not need to explain return values in deeper detail since the listed categories are informative enough.

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?

Both parameters are already described in the schema with 100% coverage. The description adds a small example for element_id, but this duplicates the schema's description. There is no additional semantic meaning for page_id. Baseline of 3 is appropriate because 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 clearly states the tool's function: retrieving full details of a single element by ID. It provides concrete examples of element IDs and lists the returned data categories. However, it does not explicitly distinguish itself from the sibling tool 'get_element', which may perform a similar function.

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

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

The description implies when to use the tool (when full detail of a single element is needed) but does not explicitly mention alternatives, exclusions, or when to prefer it over similar tools like 'get_element' or 'search_page_elements'. Usage context is implied rather than clearly 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?

With no annotations, the description carries the transparency burden. It discloses the tool returns the authoritative schema (read-only nature) and clarifies it does not enforce semantic rules (validate_page does). However, it doesn't explicitly state no side effects or mention any error behaviors, but for a simple getter the key traits are covered.

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 focused sentences pack significant detail: the resource, the schema version, the shape, and the distinction from validation. No fluff, front-loaded with the verb and target.

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 zero parameters, no output schema, and no annotations, the description sufficiently explains what is returned, why it matters, and how it relates to validation. It covers the essential context for an agent to use this tool correctly without needing additional information.

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 has 0 parameters, so baseline is 4. The description provides context about the schema's structure and purpose, adding value by explaining what the returned schema governs, though there are no parameters to elaborate on.

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?

Description clearly states the tool retrieves the authoritative JSON Schema for page source, with specific details (Draft 2020-12, sections array, structural contract fields). It distinguishes itself from siblings by positioning this as the shape definition versus validate_page for semantic rules.

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 when to use: 'Use it as the shape to emit' and contrasts with validate_page which 'enforces the semantic rules'. This gives clear context for selection among sibling tools like validate_page or get_page_source.

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

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

With no annotations to rely on, the description carries the burden of disclosing behavior. It clearly states that the tool returns a summary/overview (counts and class names) and does not mention any mutations or side effects, implying a safe read operation. It could go further by noting whether this is the entire source or just a summary, but the provided information is sufficient for basic understanding.

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 only two sentences: the first states the output content, the second gives usage guidance. It is front-loaded, contains no filler, and every sentence adds value. This is an exemplar of concise, structured tool documentation.

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?

This is a simple tool with one parameter and no output schema. The description explains exactly what the tool returns (section count, element type counts, custom CSS classes) and gives contextual guidance for the next step. It is complete for the tool's complexity and fits well within the sibling 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 coverage is 100% because the single parameter page_id is documented in the schema. The description does not add any additional meaning or constraints about the parameter, sticking to the baseline where the schema provides all necessary 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?

The description uses a specific verb 'Get' with a clear resource 'page source overview'. It enumerates concrete outputs (section count, element type counts, custom CSS classes), which clearly distinguishes it from siblings like get_page_schema or list_elements. It also names search_page_elements, showing awareness of its complementary role.

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 use this tool ('Use this first') and provides the specific alternative for the next step ('then use search_page_elements to find specific elements'). This is clear, actionable guidance for an agent deciding between 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 no annotations provided, the description carries the full burden of behavioral disclosure. While 'View' implies a non-destructive operation, the description does not mention any additional behavioral traits such as output format, pagination, or permission requirements. It adds no context beyond the tool 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 description is a single, focused sentence that clearly communicates the tool's purpose with no wasted words. It is appropriately sized for a simple one-parameter tool.

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 tool's simplicity (one required parameter, no output schema, no nested structures), the description is largely sufficient. However, it does not explicitly describe the return value, which might be expected for a 'view' operation, especially without an output schema.

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

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

The schema has 100% description coverage for the single parameter (page_id), so the baseline is 3. The description does not add any semantic meaning beyond the schema, but the schema is clear and self-sufficient.

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

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

The description clearly states the tool's function with a specific verb ('View') and resource ('version history of a page'). It also distinguishes from sibling tools like get_file_versions and restore_file_version by specifying 'of a page' as the 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 is provided on when to use this tool versus alternatives such as get_file_versions or restore_file_version. It does not mention any conditions, prerequisites, or scenarios where this tool is preferred.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states 'Get full product details' without detailing return format, error behavior, permissions, or whether it reads published or draft data. This is a minimal statement that does not reveal behavior beyond the basic operation.

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

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

The description is concise and front-loaded, starting with the action and resource. The list of returned fields is informative, though the trailing 'etc.' is slightly vague and adds little value, preventing a perfect score.

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 tool's simplicity (single required parameter, no output schema), the description is adequate but not comprehensive. It lists major return content, but without an output schema or annotations, it does not fully specify the response structure or edge 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?

The schema already fully documents the single required parameter 'id' with the description 'Product ID', achieving 100% coverage. The tool description does not add additional parameter-level meaning, but none is needed because the parameter is self-explanatory.

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

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

The description clearly states the tool's function: retrieving full product details by ID, and explicitly lists the included fields (name, description, price, variations, images, attributes, SEO). This distinguishes it from sibling tools like list_products or search_products, which have different scopes.

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' gives clear context for when to use this tool: when you have a specific product ID and need full details. It does not explicitly mention alternative tools or exclusion scenarios, but the implied usage is unambiguous for typical retrieval tasks.

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

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

With no annotations, the description carries the burden. It indicates a read operation ('Get') and discloses the return content in detail. No hidden side effects are apparent, though error handling or prerequisites are not addressed.

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

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

One sentence, front-loaded with the primary purpose, and enumerates expected fields without unnecessary words. Every part is 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 simple one-parameter tool without an output schema, the description lists the main return fields, giving a clear expectation. The trailing 'etc.' introduces some ambiguity, but it's acceptable for a comprehensive detail object.

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 one parameter 'id' described as 'Promotion ID'. The description adds context by saying 'by ID' and listing what details are returned, but it doesn't add new parameter-level meaning beyond the schema.

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

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

The description clearly states the action ('Get'), the resource ('promotion details by ID'), and enumerates the covered fields (name, type, schedule, discount rules, etc.). This distinguishes it from sibling tools like list_promotions (listing all) and get_promotion_items (maybe only items).

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

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

The description implies when to use: when you have a promotion ID and need full details. It doesn't explicitly mention alternatives or exclusions, but the sibling tool names provide context. Clear usage intent without explicit 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?

With no annotations, the description carries the full burden of disclosure. It states the return content (items with discount details), which adds useful behavioral context. However, it does not explicitly confirm that the operation is read-only or free of side effects, though the 'get_' prefix implies this. The description adds some transparency but not comprehensive details.

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

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

The description is a single, concise sentence that immediately states the action and the key return information. There is no redundant filler, and every word contributes to understanding the tool's purpose.

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 straightforward retrieval tool with three well-documented parameters and no output schema, the description provides sufficient context about the resource scope and return details. It could explicitly mention pagination behavior, but the page and limit parameters already imply this. Overall, it is complete enough for an agent to use 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?

All parameters (id, page, limit) already have descriptive schema entries, so the description does not need to add much. It does not provide any additional parameter-specific meaning beyond what the schema offers, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool retrieves products/variations/categories attached to a promotion, with a specific verb ('Get') and resource scope. It distinguishes itself from sibling tools like get_promotion or list_promotions by focusing on the items attached to a promotion and their discount details.

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 conveys a clear use case: fetching items attached to a promotion. It does not explicitly mention when to use it over alternatives like get_combo_items or get_promotion, but the context is clear enough. No exclusions or alternative tool names are provided, so it earns a 4 rather than 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?

With no annotations provided, the description carries the full behavioral burden. It discloses the two modes, the token-saving rationale, and the include_guide behavior. It does not detail response format or error handling, but for a straightforward read-only tool this is adequate and adds context beyond a simple 'get' statement.

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 concise and front-loaded: a one-sentence purpose followed by bullet-pointed mode details. Every sentence earns its place, and the structure makes the two modes and include_guide flag easy to parse. No fluff or repetition.

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

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

For a simple read tool with two optional parameters and no output schema, the description fully covers the tool's behavior: default return all fields, filtered return specific fields, and include_guide behavior. It explains what the tool returns and how to invoke it, making it self-contained and complete for the given complexity.

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

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

Schema coverage is 100% for both parameters, with detailed schema descriptions already explaining fields (enum values, omit for all) and include_guide (first-call guide). The description adds minimal extra semantics, such as 'saves tokens', but does not materially enhance parameter understanding beyond the schema.

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

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

The description clearly states 'Get custom code of the site (CSS/JS)' with a specific verb and resource. It also explains two modes (default all fields vs. field filter), distinguishing it from sibling tools like update_site_custom_code, and making its purpose unmistakable.

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 clear context for when to use each mode: default returns all 4 fields, field filter saves tokens when only CSS or JS is needed, and include_guide=true is recommended on the first call. However, it does not explicitly mention alternatives or when not to use this tool relative to other getters like get_global_source_element or get_page_source.

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

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

With no annotations provided, the description carries the full burden of disclosing behavior. The word 'Get' implies a read operation, but it does not clarify which site is referenced (e.g., current active site), whether any settings are returned in a specific format, or if there are any limitations. This lack of detail is a significant gap given the presence of site-switching tools.

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

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

The description is a single, front-loaded sentence that immediately states the action and resource. The parenthetical list of settings is concise and avoids unnecessary filler. It earns its place by providing examples of what constitutes 'full site 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?

The description lists several included categories (name, domain, settings with examples), which gives a reasonable overview. However, it ends with 'etc.', introducing ambiguity about the exact scope of the return value. Since no output schema is provided, the description should more precisely define what 'full site information' includes.

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 has zero parameters, so the input schema is empty and schema coverage is 100%. Per the rubric, a baseline of 4 applies when there are no parameters. The description does not need to add parameter details since there are none, and it correctly focuses on the return value.

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

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

The description clearly states the tool's function: 'Get full site information' followed by a list of included fields (name, domain, settings). This distinguishes it from sibling tools that are more specialized, such as get_site_custom_code, by emphasizing a comprehensive 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?

The description provides no explicit guidance on when to use this tool versus alternatives. It neither mentions situations that warrant this tool nor contrasts it with related getters like get_site_custom_code or list_my_sites. Usage has to be inferred from the tool name and description.

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

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

No annotations are provided, so the description must carry the transparency burden. It does add behavioral context by mentioning the output is a 'compact tree view' and shows the 'full element hierarchy', which goes beyond a simple 'get' statement. However, it does not disclose any limitations, error conditions, or side effects, though the getter nature implicitly suggests non-destructiveness. The disclosure is adequate but 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?

The description is two sentences, front-loaded with the primary action ('Get all cart global sources with compact tree view') followed by a valuable clarification ('Shows full element hierarchy — no need to call get_global_source_detail separately'). Every sentence earns its place with no filler.

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

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

For a zero-parameter, no-output-schema tool, the description covers what the tool returns (compact tree view with full hierarchy) and its benefit over a sibling. It does not dive into the exact structure of the tree, but given the simplicity of the tool and strong sibling context, the completeness is sufficient for an agent to select and invoke it correctly.

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

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

The tool has zero parameters and the schema is empty, so schema coverage is trivially 100%. With 0 parameters, the baseline is 4; the description correctly adds nothing about parameters because there are none to explain.

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

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

The description uses a specific verb ('Get') and identifies the resource ('cart global sources') plus the output format ('compact tree view'). It also distinguishes itself from the sibling tool get_global_source_detail by explicitly stating that calling the latter separately is unnecessary, making the tool's scope clear.

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

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

The description provides an explicit usage hint by stating 'no need to call get_global_source_detail separately', which tells the agent when this tool can replace an alternative. It does not explicitly enumerate when not to use it, but the guidance is clear enough for a simple retrieval 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?

No annotations are present, so the description carries the full burden. It discloses a non-obvious behavioral trait: the output is a structural blueprint, not an exact reproduction ('Not a 1:1 clone'), and it lists exactly which elements are captured. This provides solid, actionable expectations for the agent.

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, no superfluous text. The action and resource are front-loaded, and the key caveat ('Not a 1:1 clone') is placed at the end, ensuring each sentence earns its place.

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

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

The description covers input, processing, output scope, and a downstream step (new_section). With no output schema, it could detail the blueprint's exact structure more, but for a one-parameter tool with clear intent, it is nearly 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?

The input schema already documents the single parameter with 100% coverage ('Raw HTML to analyse'). The description adds value by qualifying the input as 'reference HTML', implying it's a sample for design extraction, and by linking the output to rebuilding sections, which enriches the parameter's purpose.

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

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

The description identifies a specific verb ('Parse'), a clear resource ('reference HTML'), and a distinct outcome ('structural blueprint' with explicit list of elements). It also differentiates from a simple clone by stating 'Not a 1:1 clone', which clarifies what the tool does not do.

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

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

The description implies usage by stating 'Parse reference HTML' and suggests a concrete workflow: 'you can rebuild as BuilderX sections with new_section'. It does not explicitly mention when to avoid this tool or compare with ingest_url, but the context makes the intended scenario clear.

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