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

Discloses duplicate-name refusal, the force parameter as a deliberate override for legitimate repeated areas, and the /contents [] behavior until edit-mode opens. These traits go well beyond the annotations' basic hints.

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

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

Three focused paragraphs, each earning its place: main action, parameter semantics, and edge-case behavior. Front-loaded and no 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?

For a create tool without output schema, it covers purpose, parameters, behavioral quirks, and error handling. The duplicate policy and force escape hatch are critical context that is fully explained.

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?

Despite only 40% schema coverage, the description adds deep meaning to name (layout tag matching), content_type (valid values), and force (default false, why you'd flip it). This compensates for the sparse 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?

Clearly states it creates a content area + linked text on a blog article, and explicitly distinguishes from sibling page_add_content. The verb+resource+scope are specific and 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 a specific use case (seeding freshly-created article body/gallery), names the alternative tool page_add_content, and explains when to use force for duplicate names. This is explicit when/alternative 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?

Description explicitly states the tool is NOT idempotent, aligning with idempotentHint=false. It explains the autosaved fields convention and publish behavior (sets publishing:true atomically), adding behavioral context beyond annotations. No contradictions with annotations.

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

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

Description is well-structured with purpose first, then required/optional fields, then special behaviors. At 6 sentences, it is appropriately sized for the tool's complexity, though it could be slightly more concise without losing clarity.

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 11 parameters and no output schema, the description covers creation essentials, publish flow, and idempotency. It omits return value (e.g., created article ID) and error handling, but these are often inferred from the tool's nature. Overall, it's 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?

Schema description coverage is only 27%, but the description adds meaning for key parameters like path (auto from title), tag_names (array), data (custom dict), publish (default false), and explains autosaved fields. It compensates for low coverage, though not all 11 parameters are detailed.

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 starts with 'Create a new blog article' with specific verb and resource. It lists required and optional fields, clarifying the tool's purpose. Sibling tools like article_update and article_delete indicate distinct usage, so the description effectively distinguishes it.

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?

Description states when to use (to create articles) and notes non-idempotency, which guides repeat calls. However, it does not explicitly mention alternatives like article_update for editing or when not to use. Still, the context is clear for basic 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?

Adds beyond annotations: explicitly states deletion is IRREVERSIBLE and that Voog does not retain deleted articles. Annotations already had destructiveHint=true, so description adds meaningful context.

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

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

Two concise sentences, no filler. 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 delete tool with destructive hint and no output schema, description lacks details on return values, error handling, or post-deletion state. Could mention what the response looks like.

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 0%. Description only mentions force parameter, ignoring site and article_id. No explanation of parameter types, formats, 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 clearly states the action ('Delete an article') and the resource. It distinguishes from siblings like article_create, article_get, articles_list by specifying deletion and irreversibility.

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

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

No guidance on when to use this tool vs alternatives like article_delete_data or article_set_data. No mention of prerequisites or conditions beyond force=true.

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

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

The description adds significant behavioral context beyond the annotations (destructiveHint=true, etc.), notably the irreversible nature ('IRREVERSIBLE — the key is removed permanently'), the force requirement, and the server-protected key restriction. No contradictions with annotations.

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

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

The description is three sentences long, each sentence providing essential information without fluff. It is front-loaded with the main action and logically 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 destructive tool with 4 parameters and no output schema, the description covers the key behavioral aspects: action, irreversibility, force requirement, and key restrictions. It does not specify the expected return status (e.g., 204), but this is not critical given the lack of output schema. Slightly more detail on the response could 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?

With only 25% schema description coverage (only the 'force' parameter has a schema description), the description adds value by explicitly stating that force must be true to execute the deletion. However, it does not detail the 'site', 'article_id', or 'key' parameters beyond their path usage, which the schema already provides as required. The baseline is 3 due to low coverage, and the description partially compensates.

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 deletes a specific key from an article's data, including the HTTP method and path. It distinguishes itself from siblings like article_delete (which deletes entire articles) and article_set_data (which sets data).

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

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

The description explains that force=true is required and that internal_ keys are rejected, providing clear usage conditions. However, it does not explicitly compare this tool to alternatives or state when to use it over article_set_data or article_delete, but the context from sibling names offers implicit guidance.

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

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

Annotations already indicate readOnlyHint, destructiveHint, and idempotentHint. The description adds value by listing the returned fields (title, path, body, etc.), giving agents concrete expectations beyond the annotations.

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

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

The description is a single, front-loaded sentence followed by a parenthesized list of fields. Every word serves a purpose, and it is appropriately terse for a simple retrieval 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 low complexity, presence of annotations, and lack of output schema, the description provides the return fields which is helpful. However, it does not clarify parameter constraints (e.g., article_id must be an integer) or potential error conditions.

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 0% description coverage, and the description does not explain the parameters 'site' or 'article_id' beyond referencing 'by id.' It fails to add meaning about parameter types, formats, 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 clearly states the action: 'Get full article details by id.' It lists the specific fields returned, distinguishing it from sibling tools like article_create, article_update, and article_delete.

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 marks the tool as read-only, implying it is safe for retrieval. However, it does not explicitly state when to use it versus alternatives (e.g., articles_list) or provide exclusions, relying on context from sibling names.

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

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

The description discloses critical behavioral details beyond annotations: the race window in fallback mode, the idempotent nature (via PUT with publishing:true), and the rejection of mixed autosaved_args. Annotations (readOnlyHint false, destructiveHint false, idempotentHint true) are consistent and complemented by these 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 well-structured: a concise purpose sentence, a key explanation of why a separate tool is needed, and a clear two-mode breakdown. Every sentence adds value, and the most critical 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?

Given no output schema, the description could mention expected return values (e.g., published article object) or error scenarios. However, the mode selection and race condition are fully covered, making it adequate for an agent to use correctly. A minor gap exists regarding success behavior.

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

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

The schema covers 60% of parameters with descriptions (autosaved_* group). The description adds significant meaning by explaining the mode logic and how these parameters control fast vs fallback path. For site and article_id, no extra info is provided but their purpose is self-evident.

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 'Publish an article' and explains the two modes, distinguishing this tool from article_update by highlighting the need for a separate tool due to the autosaved field copying requirement. The purpose is specific and well-differentiated from siblings.

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

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

The description provides explicit guidance on when to use the fast path (pass all three autosaved_* args) vs the fallback (pass none), and warns against mixed args. However, it does not explicitly state when to use article_update instead, though the context implies it.

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

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

Annotations already indicate idempotency and non-destructiveness. The description adds important behavior: keys starting with 'internal_' are rejected client-side. It also mentions the HTTP method, aligning with annotations. No contradictory information.

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 brief: two sentences with a clear structure. The first sentence states the action and HTTP method, the second provides an alternative and a constraint. Every sentence adds value 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?

Given the required parameters and lack of output schema, the description covers the core operation, key deletion alternative, and a security constraint. It does not mention overwriting behavior, but that is implied. Combined with schema descriptions, it is sufficiently 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 only 25%, and while the value parameter's description is detailed (non-null, nested storage), the main description does not explain site, article_id, or key beyond their basic role. The description adds minimal semantic value for these parameters.

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

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

The description clearly states the tool sets a single article.data.<key> value, with the HTTP method included. It differentiates from the sibling tool article_delete_data, 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 explicitly tells when to use article_delete_data instead (for deletion) and warns about rejected 'internal_' keys. It lacks guidance relative to other data-related siblings but provides sufficient context for common use cases.

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

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

Annotations already indicate readOnlyHint, destructiveHint, and idempotentHint as true/false. The description adds value by stating 'Read-only' and listing the returned fields. No additional behavioral traits (like pagination limits or side effects) are surfaced, but the description aligns with annotations.

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

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

The description consists of two concise sentences that convey the tool's purpose, fields, filter optionality, and read-only nature. Every sentence adds value 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?

Given the 7 parameters (1 required), high schema coverage, and annotations, the description is mostly complete. It lists returned fields despite no output schema. Minor gap: no mention of pagination, but that is acceptable for a basic list tool.

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

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

Schema description coverage is high (86%). The description confirms all parameters except site are optional, adding clarity beyond the schema. However, it does not explain parameter meaning 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 states the tool lists blog articles on the Voog site and enumerates the simplified fields returned. It unambiguously distinguishes this list operation from sibling tools like article_get or article_create.

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 notes all filters are optional and the operation is read-only, providing clear usage context. However, it does not explicitly contrast with sibling tools or state when not to use this tool.

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

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

Discloses that title/body/excerpt go to autosaved_* fields (not immediately public), data has merge semantics via PATCH, and calls without data use PUT. This adds context beyond annotations (readOnlyHint, destructiveHint, idempotentHint) without contradiction.

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

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

Two well-structured paragraphs with clear grouping of information. First paragraph introduces categories and requirement; second paragraph details data field behavior. No extraneous information; every sentence 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?

Given the complexity (autosaved vs. published, PATCH/PUT duality) and no output schema, the description covers input behavior thoroughly, including edge cases like key deletion via sibling tool. Missing return value details are acceptable for a mutation tool with annotations.

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

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

With 0% schema coverage, the description compensates by grouping parameters into autosaved vs. direct-update categories, explaining data's merge behavior, and stating the requirement of at least one field. Provides meaningful semantics beyond the schema structure.

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 'Update an existing article' and distinguishes two categories of fields (autosaved vs. direct) with clear roles, differentiating from sibling tools like article_create, article_publish, and article_delete_data.

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 this tool: for updating article fields, with specific guidance that autosaved fields require article_publish to become public, and that data field uses PATCH semantics while non-data uses PUT. Also directs to article_delete_data for key deletion.

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?

Discloses that the operation creates a new asset, leaves the old one in place, and returns both ids. Consistent with annotations (non-readOnly, non-destructive, non-idempotent). Does not detail authorization or rate limits but covers the key behavioral trait beyond annotations.

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

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

Two concise sentences: first states the purpose and workaround, second details outcome and next steps. Front-loaded, no wasted words.

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

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

Despite no output schema, the description documents the return (both ids), explains the workaround, and provides manual cleanup steps. Sufficient for an agent to correctly invoke and follow up.

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 clear parameter descriptions. The description adds no new meaning beyond the schema (repeats the filename constraints). Baseline 3 is appropriate because schema already 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?

Explicitly states 'Rename a layout_asset by creating a new one with the desired filename' – a specific verb, resource, and workaround for API limitation. Distinguishes from sibling tools like layout_asset_update, which cannot change filenames.

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

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

Clearly explains when to use (when a filename change is needed, because PUT is rejected) and gives post-usage instruction (delete old asset manually after updating templates). Lacks an explicit 'when not to use' but context implies alternatives are inappropriate.

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

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

Goes well beyond the annotations by detailing the multi-step POST/PUT/PUT flow, the 120s async polling and 5s interval, the 150/600/1280/2048 derivative caps, the duplicate reuse/suffix orphaning behavior, and the CDN 403 caching pitfall. It also clarifies that sizes_complete=false indicates partial results after timeout. No contradiction with annotations.

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

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

The description is long but every sentence serves a purpose: it covers the multipart workflow, sibling discrimination, output format, derivative sizing rules, duplicate behavior, timeout semantics, and a CDN caching warning. It is structured in focused paragraphs and front-loaded with the core 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 the tool's complexity (upload plus async resize, duplicate handling, partial results, CDN side effects) and the absence of an output schema, the description fully discloses the return value shape (id, dimensions, public path, sizes), the 'sizes_complete' flag, and the consequences of HTTP HEAD checks. It anticipates the likely failure modes and tells the agent exactly how to use and interpret 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?

Despite 100% schema coverage, the description enriches each parameter: files are 'absolute paths' with supported extensions, allow_duplicate and wait_for_sizes receive behavioral consequences (e.g., 'Pass allow_duplicate=true to force a new asset', 'Pass wait_for_sizes=false to skip the wait'). The duplicate-risk explanation adds meaning beyond the schema's raw defaults.

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 'Upload local image files into the site's media library' and explicitly distinguishes from product_set_images with 'use product_set_images when the images are a product's gallery.' It names the exact resource (media library) and verb (upload), making the tool's scope 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 explicitly says 'Use for images referenced from site.data / page.data maps, article galleries or template markup; use product_set_images when the images are a product's gallery.' It also explains when to set allow_duplicate=true (forced re-upload) and wait_for_sizes=false (skip wait), giving clear decision criteria.

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

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

The disclosure mentions validation is left to Voog and that invalid combos return a 422, adding context beyond annotations. Annotations show it's not read-only, destructive, or idempotent, but description adds behavioral nuance.

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 are concise and front-loaded with the main action. The second sentence adds structural details, though it could be slightly more streamlined.

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

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

No output schema is provided, and the description does not mention return values. For a tool with 10 parameters and nested objects, more detail on response or side effects would be helpful.

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?

Despite 0% schema coverage, the description explains the inner structure of conditions and result, but only covers 2 of 10 parameters (conditions, result). Required fields are listed but not described individually.

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 'Create a cart rule' and provides the endpoint. It clearly distinguishes from sibling tools like cart_rule_delete, cart_rule_get, cart_rules_list, and cart_rule_update.

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 (to create a cart rule) but does not state when not to use or provide alternatives. It gives details on the structure but lacks explicit usage guidance.

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

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

Annotations already indicate destructiveness; description adds that force must be true and past orders are unaffected, providing extra context beyond the annotations.

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

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

Two concise sentences that convey the essential information without superfluous content.

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

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

Covers the main delete action, force requirement, and effect on past orders. Could mention irreversibility but is sufficient for a delete tool with annotations.

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

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

With 0% schema description coverage, the description partially compensates by noting force=true requirement but does not clarify the site or cart_rule_id parameters.

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

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

The description clearly states the action (Delete a cart rule) and provides the endpoint. It distinguishes this tool from sibling tools like cart_rule_create or cart_rule_update by specifying the delete 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?

Explicitly mentions that force=true is required and that past orders are unaffected. However, it does not explicitly contrast with alternatives like cart_rule_get or cart_rule_update.

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

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

Annotations already provide readOnlyHint, destructiveHint, and idempotentHint. The description adds the HTTP method and endpoint, reinforcing that this is a safe read operation. No contradictions, but no additional behavioral context (e.g., rate limits, auth needs) beyond annotations.

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

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

The description is a single, front-loaded sentence with no unnecessary words. Every part is essential and immediately conveys 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?

The description fails to cover return values, error scenarios, or required context. With no output schema and minimal parameter guidance, the agent lacks information to invoke the tool confidently.

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

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

The input schema has 2 required parameters (site, cart_rule_id) with zero description coverage. The description only mentions 'by id' but does not explain the site parameter, its purpose, or format. No value added beyond schema names.

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 action ('Get a single cart rule by id'), the resource ('cart rule'), the HTTP method and endpoint, and marks it as read-only. This clearly distinguishes it from sibling tools like cart_rules_list, cart_rule_create, etc.

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 fetching a single cart rule, contrasting with cart_rules_list for listing. However, it does not explicitly state when to use this over alternatives, nor does it provide exclusions or prerequisites.

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

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

Annotations already provide readOnlyHint, destructiveHint, idempotentHint; description adds 'Read-only' which is consistent but redundant. No additional behavioral info like pagination or rate limits.

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

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

Single sentence with front-loaded verb and resource, zero waste. Perfectly 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?

For a simple list tool with one parameter and no output schema, the description is minimal. It fails to explain the required 'site' parameter, leaving the agent without enough context to use 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 has 0% description coverage for the required 'site' parameter, and the tool description does not explain its purpose, format, or allowed values. The agent has no clue what to pass.

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 'List all cart rules' with HTTP method and path, and adds 'Read-only' to confirm safety. This distinguishes it from sibling tools like cart_rule_get (single rule) and cart_rule_create (write).

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?

Description implies usage for retrieving a list of all cart rules, but does not explicitly state when to use this over alternatives like cart_rule_get or how to filter results. No guidance on prerequisites.

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

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

Annotations already indicate idempotentHint=true. Description adds that it's a partial update and at least one field must be supplied, but lacks details on side effects, permissions, 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?

Two sentences, front-loaded with key information, no redundancy. Could benefit from clearer structure but efficient overall.

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 11 parameters, no output schema, and no param descriptions, the description is insufficient. It misses details on required permissions, error cases, and parameter semantics beyond two fields.

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

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

With 0% schema description coverage, the description should compensate but only mentions two common fields (enabled, position) and an envelope structure that doesn't match the flat schema. Most parameters remain unexplained.

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 (update), the resource (cart rule), the HTTP method and endpoint, and gives common update fields. It distinguishes from sibling tools like cart_rule_create and cart_rule_delete.

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

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

The description implies this is for updating an existing cart rule, but it does not explicitly compare to alternatives or provide when-to-use guidance. It mentions partial updates but no exclusions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description confirms read-only nature and lists fields, but adds no new behavioral traits beyond what annotations provide (e.g., pagination, auth requirements). No contradiction.

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

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

The description is two sentences. The first sentence defines purpose and endpoint, and the second provides actionable usage guidance. No redundant or unnecessary text. Front-loaded with key 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 the tool has only one parameter and no output schema, the description lists return fields and links usage to another tool. However, it fails to explain the 'site' parameter, which is critical for invocation. This gap reduces completeness for a low-complexity tool.

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

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

The schema has one required parameter 'site' with 0% description coverage. The description does not explain what 'site' represents (e.g., site identifier or domain), leaving the agent to guess. The description adds no 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 'List all ecommerce product categories' and includes the endpoint path. It explicitly mentions the fields returned (id, name, slug, parent_id, depth, created_at, updated_at) and provides a usage example linking to products_list, distinguishing it from sibling tools like category_get.

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 explicit guidance on using the output with products_list via 'Use category.id from the results as the products_list(category_id=...) filter.' It also marks the tool as read-only. However, it does not state when not to use this tool or mention alternatives like category_get for a single category.

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

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

The description adds value beyond annotations by disclosing that Voog does not support description/image_id on categories despite some documentation suggesting otherwise, based on empirical verification. This is a notable behavioral trait not covered by annotations. However, it does not mention permissions or 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 extremely concise (two sentences plus a note) and front-loads the purpose. Every sentence provides essential information, and the empirical note is valuable without being verbose.

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 4 parameters and no output schema, the description covers the key aspects: required/optional, auto-generation, and a known limitation. It does not detail the response structure or error handling, but it's sufficient 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?

Schema coverage is 0% (no property descriptions in schema), so the description carries full burden. It explains that name is required, slug is optional and auto-generated if omitted, and parent_id is for sub-categories. This adds meaningful semantics beyond just listing parameters.

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

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

The description starts with 'Create a category' and includes the HTTP endpoint, making the action and resource clear. It specifies required and optional parameters, and it's distinct from sibling tools like category_update or category_delete.

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 notes that slug auto-generates if omitted and parent_id is for sub-categories, which provides some context. However, it lacks explicit guidance on when to use this tool versus others (e.g., root vs sub-category, or compared to batch creation endpoints).

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

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

The description adds important behavioral details beyond the annotations: products are orphaned (not deleted) and the operation may be rejected for categories with child categories. The annotations already indicate destructiveHint=true, and the description aligns with that.

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—two sentences front-load the purpose and key conditions. Every sentence adds value 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 covers the destructive behavior and a rejection condition, but does not mention return values, success/error responses, or any other behavioral implications. Since there is no output schema, more context would be helpful.

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 3 parameters with 0% description coverage. The description only adds context for the 'force' parameter (requires force=true), but does not explain 'site' or 'category_id', leaving meaning ambiguous.

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

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

The description clearly states the action ('Delete a category') and includes the exact HTTP endpoint. It also specifies that products are orphaned, which uniquely distinguishes this tool from sibling tools like category_update or category_get.

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 mentions that force=true is required and that deletion may be rejected if the category has child categories, providing usage conditions. However, it does not explicitly state when to use this tool over alternatives like category_update or category_create.

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

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

The description adds the REST endpoint (GET) and reinforces the read-only nature. Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, so the description complements these by providing the HTTP method 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 extremely concise with one sentence plus endpoint and read-only flag. Every word is purposeful and no 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 simplicity of a GET operation with two parameters and no output schema, the description is adequate but lacks explanation of the 'site' parameter and does not describe the return value. More detail 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?

Schema description coverage is 0%, and the description only hints at 'by id' for category_id but completely ignores the 'site' parameter. It does not add meaningful semantics beyond the schema's bare types.

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' and resource 'single category by id'. It effectively distinguishes from siblings like categories_list (list all) and category_create/delete/update (write operations).

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

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

The description does not provide explicit guidance on when to use this tool versus alternatives (e.g., categories_list for multiple categories). The context of retrieving a single category by ID is implied, but no when-not-to or alternative tool mentions 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?

Annotations indicate mutability, non-destructiveness, and idempotency. The description adds partial update behavior and the envelope format. It does not contradict annotations but lacks details on authentication, rate limits, or 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?

Two sentences pack essential information: action, endpoint, envelope, and partial constraint. 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?

Covers core usage, partial update detail, and required optional fields. Without an output schema, a note on return value or error handling would improve completeness, but the current description is sufficient for 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?

With 0% schema description coverage, the description compensates by stating that at least one of name/slug/parent_id must be supplied, adding critical constraint beyond the schema's required fields. It also explains the envelope structure, enhancing parameter 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 the tool updates a category, specifies the HTTP method and endpoint (PUT /admin/api/ecommerce/v1/categories/{id}), and indicates partial update with mandatory fields. It unambiguously distinguishes from sibling tools like category_create or category_delete.

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 mentions partial update and required fields, providing clear context. However, it does not explicitly compare to alternatives or state when not to use this tool (e.g., preferring bulk update).

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

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

Annotations declare destructiveHint=true, but the description adds crucial behavioral details: the call is rejected without force=true, and Voog returns 204. This provides safety and response info beyond the annotation, though permission requirements 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?

Three sentences covering HTTP method, return code, prerequisite, and a critical requirement, with no fluff. Well-structured for quick comprehension.

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 simple delete operation and no output schema, the description sufficiently covers action, prerequisites, safety mechanism, and HTTP response. No critical gaps for an AI agent to invoke 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 input schema already describes 75% of parameters, but the description adds context by linking to comments_list for the id and emphasizing the force flag requirement, enhancing understanding beyond schema details.

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

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

The description clearly states the action 'Remove a comment' with specific verb and resource, and includes the HTTP method and URL path for precision. It distinguishes from siblings like comment_toggle_spam by focusing on deletion.

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 a prerequisite ('Run comments_list first to confirm the id') and a requirement ('Requires force=true'), providing clear usage context. However, it does not specify when not to use this tool compared to alternatives like comment_toggle_spam.

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

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

Annotations already declare readOnlyHint, destructiveHint, idempotentHint. Description adds the endpoint method (GET) and the return shape, providing moderate additional context beyond annotations.

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

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

Two efficient sentences: first states action and endpoint, second lists return fields and a usage hint. No superfluous 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?

Covers the tool's purpose, output shape, and a key prerequisite. Lacks detail on the 'site' parameter but overall adequate for a simple list tool with strong annotations.

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

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

Schema coverage is 50% (only article_id has a description). The description reinforces article_id's purpose but omits the 'site' parameter, leaving it unexplained. Baseline 3 with partial improvement.

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 action ('List comments on an article'), provides the HTTP endpoint, lists the returned fields, and distinguishes from sibling mutation tools like comment_delete and comment_toggle_spam by emphasizing 'Read-only'.

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 specifies the prerequisite 'Use article_id from articles_list', and the read-only nature implies it's for retrieval, not modification. While it doesn't explicitly exclude misuse, the context is clear.

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

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

Annotations indicate the tool is idempotent and not read-only; the description adds that the body is flat and the endpoint is used by Voog's UI. This provides enough behavioral context beyond the annotations.

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

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

The description is three concise sentences: action, body format, and context/alternative. No wasted words, and the most important 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?

Given the tool's simplicity (4 params, no output schema), the description adequately covers purpose, parameters, and alternative tools. It is complete enough for an agent to use correctly.

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

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

Schema description coverage is 75% (site missing). The description adds value by specifying the flat body format and the boolean nature of is_spam, which complements the schema's existing parameter 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 clearly states it flips a comment's spam flag, specifies the HTTP method and path, and distinguishes the tool from siblings by noting that for other field edits, one should use voog_admin_api_call.

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 guidance: use this tool for toggling spam, and for other field edits use voog_admin_api_call. It implies the appropriate usage context without explicit when-not-to-use, but the alternative is 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?

Annotations already indicate idempotentHint=true, readOnlyHint=false, destructiveHint=false. The description adds behavioral details: PUT body is flat, update is idempotent, and the requirement for at least one field. No contradiction with annotations.

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

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

The description is two sentences, front-loaded with the purpose, and includes only essential details. Every sentence adds value 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?

For an update tool with 4 parameters and no output schema, the description covers the essential aspects: function, idempotency, flat body requirement, and field constraints. It omits error handling or auth requirements but is generally 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 50% (body and metainfo have descriptions in schema). The description adds context about the flat PUT body and the requirement to supply at least one of the two optional fields, but does not explain the `site` or `content_partial_id` parameters beyond being required.

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 'Update' and the resource 'content partial', defines what content partials are, and distinguishes this from sibling tools which target different entities. The HTTP method and endpoint are also mentioned.

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 critical usage constraints: at least one of `body` or `metainfo` must be supplied, and the operation is idempotent. However, it does not explicitly state when to use this tool over alternatives, nor does it mention prerequisites or when not to use it.

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

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

Annotations indicate non-readOnly, non-destructive, non-idempotent. The description confirms it creates a discount via POST, and adds empirically verified enum values. It does not mention authentication, rate limits, or error behavior beyond client-side validation.

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 with the endpoint and required fields. The use of bullet-like enumeration organizes information well, though it could be slightly more 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 and 14 parameters, the description covers enums and required fields but lacks information about return values, error handling, or behavior for optional fields. More details on the response or side effects 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?

With 0% schema description coverage, the description compensates by listing all optional parameters, specifying enum values for 4 parameters, and noting date format (ISO8601). This adds significant 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 ('Create a discount'), specifies the HTTP method and endpoint (POST /admin/api/ecommerce/v1/discounts), and lists required fields. This distinguishes it from sibling tools like discount_update or discount_delete.

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 indicates when to use the tool (to create a discount) and provides required parameters. However, it does not explicitly mention when not to use it or compare with alternative tools like discount_update for modifications.

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

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

The description adds valuable behavioral context beyond annotations: it explains that the deletion only prevents future use and that past orders retain the discount record. This complements the destructiveHint and idempotentHint annotations without contradiction.

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

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

The description is extremely concise: a single sentence that starts with the action, then the endpoint, requirement, and behavioral nuance. Every part is informative with no redundancy or 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?

The description covers the core action and key nuance (past orders unaffected) but is incomplete regarding parameter definitions. Given the simple tool and presence of annotations, it is adequate but could be improved by explaining 'site' and 'discount_id'.

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

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

With 0% schema description coverage, the description must explain all parameters. It only addresses 'force' ('Requires force=true') but provides no explanation for 'site' or 'discount_id', leaving the agent to infer their meaning from names and the URL path.

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 action ('Delete a discount'), includes the HTTP method and endpoint path, and distinguishes it from sibling tools like discount_create, discount_get, discount_update, and discounts_list by its specific verb and 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?

The description gives clear usage context: requires force=true and explains the effect on past and future orders. However, it does not explicitly contrast with alternatives or provide when-not-to-use guidance, though the uniqueness is implied.

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

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

Annotations already provide readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds no additional behavioral context beyond restating 'Read-only'. This is adequate but does not go beyond what annotations convey.

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

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

Two concise sentences, front-loaded with the core purpose. No extraneous information. Every word earns its place.

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

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

The tool is simple (get by id) and annotations cover safety. No output schema, so return format is not described, but this is standard. Missing error handling info (e.g., 404), but overall nearly complete for the operation.

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

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

Schema coverage is 0%, meaning the description does not describe parameter semantics beyond the schema. However, the schema parameter names ('site', 'discount_id') are self-explanatory. The description adds no extra meaning, such as format 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 clearly states 'Get a single discount by id', specifying the verb and resource. It distinguishes from sibling tools like discounts_list (listing) and discount_update/discount_delete (mutation).

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 indicates it's a read-only operation and provides the endpoint. However, it does not explicitly mention when to use this tool vs alternatives like discounts_list or discount_update. The tag 'Read-only' implies safe usage but 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?

Annotations already declare readOnlyHint, destructiveHint, and idempotentHint. The description confirms read-only but adds no additional behavioral traits (e.g., pagination, rate limits, or result format). No contradiction.

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

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

The description is extremely concise, front-loading the action and endpoint, with no wasted words. Every sentence is necessary.

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 list operation with one parameter and annotations, the description is adequate but not richly informative. It lacks details about return values, pagination, or parameter format, relying heavily on inferred knowledge.

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 0% with one required parameter 'site' lacking description. The description does not mention the parameter or provide any guidance on its usage, leaving the agent to infer meaning.

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 lists all ecommerce discounts, includes the API endpoint, and notes it's read-only, which effectively distinguishes from sibling tools like discount_create or discount_get.

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 (to list all discounts) but provides no explicit guidance on when not to use it or how it differs from siblings like discount_get or discounts search tools. The context of sibling tools is not addressed.

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

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

Annotations provide idempotentHint=true, and description adds client-validated enum constraints. No contradictions, but the description could disclose more about side effects or error states.

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

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

Concise, front-loaded with purpose, and every sentence provides necessary information 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?

Given 15 parameters and no output schema, the description covers partial update behavior and enum constraints. Could mention response format or that discount_id is required, but overall complete for an update 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?

With 0% schema coverage, the description adds value by enumerating enum-restricted fields and their allowed values, helping the agent understand constraints without detailed param 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 clearly states the tool updates a discount, specifies the HTTP endpoint, and distinguishes from siblings like discount_create by noting it's a partial update.

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?

Indicates partial update with at least one field required and lists enum restrictions. While it doesn't explicitly compare to alternatives, the context from sibling tools is sufficient.

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

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

Annotations declare readOnlyHint=true and idempotentHint=true. The description adds context about per-language translations and the relationship to product price interpretation, complementing the annotations without contradiction.

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

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

The description is concise, with the main purpose in the first sentence and additional context in the second. It is well-structured and front-loaded, though slightly verbose in listing fields.

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

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

Given one parameter with no schema description and no output schema, the tool description should explain both input and output. It lists returned fields but omits what 'site' is, leaving a gap despite adequate context on usage.

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 only parameter 'site' has no description in the schema (0% coverage) and the tool description does not explain its meaning or expected format. The description lists returned fields but fails to clarify the input parameter.

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

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

The description clearly states 'Get ecommerce store settings' with a specific verb and resource, and lists example fields. It is distinct from the sibling 'ecommerce_settings_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?

The description explicitly marks the tool as 'Read-only' and explains its role as the source of truth for 'price_entry_mode', helping agents decide when to use it vs. product tools. However, it does not explicitly 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?

Annotations already indicate idempotent and non-destructive behavior. The description adds useful context about the payload envelope and runtime discovery of translation keys with caching, which goes beyond annotations.

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

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

The description is concise with three sentences, front-loading the action. It could be more structured, but it avoids 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?

The description covers the envelope and translation discovery but does not mention return values, errors, or permissions. For an update tool, response information would be beneficial.

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

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

With 0% schema description coverage, the description must compensate. It gives brief examples for attributes but lacks detailed structure or allowed values for the object parameters, leaving ambiguity.

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 updates ecommerce settings, distinguishing between attributes (flat fields) and translations (nested), and specifies the payload envelope. This differentiates it from sibling tools like ecommerce_settings_get.

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 hints that translatable keys are discovered from GET /settings, implying a prerequisite, but does not explicitly state when to use this tool versus 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?

Annotations indicate mutability (readOnlyHint=false) and non-destructiveness (destructiveHint=false). The description adds behavioral details: 'Body is FLAT.' and the precedence rule for element_definition_id over title, and auto-generation of path. These go beyond the annotations without contradicting them.

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 very concise, consisting of two sentences with key information front-loaded. Every sentence adds value: the purpose, the flat body requirement, and the required/optional breakdown. 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?

The tool has 7 parameters and no output schema. The description covers conditional requirements, auto-generation, and the values parameter. However, it lacks details on return values, error handling, and the site parameter. The error about required parameters also detracts from 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?

Schema description coverage is high (86%), so baseline is 3. However, the description misstates required parameters: it claims element_definition_id or element_definition_title is required and omits site, which contradicts the schema's required list. This error significantly misleads the agent, reducing the score.

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 an element (POST /elements).' This is a specific verb+resource combination that distinguishes the tool from sibling tools like element_update, element_delete, and element_get. The mention of the HTTP method further clarifies the action.

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

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

The description implies usage by describing what it creates, but it does not explicitly compare with sibling tools or provide when-not-to-use guidance. However, the context is clear enough for an agent to infer when to use this tool versus others like element_update.

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

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

The description confirms the tool is read-only, aligning with annotations, and adds context about mutation handling being deferred to another API. This goes beyond the annotations by explaining how mutations should be performed.

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 concise sentences that front-load the core purpose and return structure, then immediately provide usage guidance. Every sentence adds value 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?

Given the lack of an output schema, the description adequately describes the return fields but omits details about the 'site' parameter. This gap reduces completeness for a simple list 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 description does not explain the 'site' parameter at all. With 0% schema description coverage, the description should clarify the parameter's meaning and format, but it fails to do so, leaving ambiguity.

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 it lists element definitions with specific fields (id, title, property_keys) and explicitly tells how to use the returned id for element_create, which distinguishes it from similar sibling tools like elements_list.

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 indicates this tool is read-only and directs mutations to voog_admin_api_call, providing clear guidance on when to use this tool versus alternatives. It could be more explicit about not using it for filtering or other operations, but the guidance is sufficient.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds valuable behavioral details: the need for force=true (without it the call is rejected), the response code (204), and the prerequisite to confirm the id. No contradiction with annotations.

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

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

The description is three sentences, each conveying essential information: what it does, the force requirement, and a prerequisite. It is concise and front-loaded with the core 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 delete tool with no output schema and three parameters, the description covers the action, return code, mandatory flag, and prerequisite verification. This provides sufficient context 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?

Schema coverage is 67% with descriptions for element_id and force. The description reinforces the force parameter's requirement ('requires force=true') and echoes the need to get the id from elements_list, adding clarity. The site parameter lacks extra context, but overall the description enhances 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 explicitly states the action (Delete an element), the HTTP method and endpoint, the expected response (204), and key requirements (force=true). This clearly distinguishes it from sibling tools like article_delete or element_update.

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 guidance on when to use the tool (to delete an element) and a prerequisite (run elements_list first to confirm the id). It does not explicitly mention when not to use it or alternatives, but the context is sufficient for a delete operation.

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

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

Annotations already carry readOnlyHint, destructiveHint, idempotentHint. Description adds 'full values hash' but does not expand on behavioral traits beyond what annotations already provide.

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

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

Two sentences, no filler. Front-loaded with purpose and output. Every sentence 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?

Simple tool (get by id) with no output schema. Description covers purpose and output. Could add more on what 'full values hash' entails but enough for typical use.

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

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

Schema coverage is 50% with one parameter (element_id) described. Description does not add meaning to the site parameter but reinforces element_id's origin via reference to elements_list. Baseline 3 is appropriate.

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

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

States 'Get a single element by id' with verb and resource clearly. Mentions 'full values hash' to describe output. Distinguishes from sibling 'elements_list' to find ids.

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

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

Explicitly says when to use the tool (get by id) and directs to 'elements_list' to find ids, providing context. Lacks explicit 'when not to use' but sufficient for a simple retrieval.

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

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

The description's 'Re-order or re-parent' implies mutation, consistent with readOnlyHint=false. The idempotentHint=true from annotations is not echoed in the description, but no contradiction exists. The description adds context about query-string param usage but doesn't significantly expand on behavioral traits beyond annotations.

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

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

The description is concise, well-structured, and front-loaded with the core action. Every sentence adds value, including the scope note and docs reference. No wasted words.

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

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

Given 5 params (2 required) and no output schema, the description covers purpose, usage, parameter semantics, and scope. It references related tools for ID discovery. It lacks details about return values or error states, but for a reorder tool, the description is largely 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 description explains the role of page_id, before, and after in plain language, adding value over schema descriptions (e.g., 'supply at least one of' and mutual exclusivity implied). With 80% schema coverage, it effectively compensates.

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 'Re-order or re-parent an element instance' and distinguishes from element_definitions (schema) and sibling tools like node_move. It specifies the HTTP method and path, 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 explains that inputs are query-string params, requires at least one of page_id, before, or after, and references elements_list for finding IDs. It doesn't explicitly state when not to use this tool but provides clear context and alternatives.

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

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

Annotations already provide readOnlyHint, destructiveHint, idempotentHint. The description reinforces 'Read-only' and adds useful behavioral context: include_values is off by default because values clutter, and recommends element_get for detailed data. No contradictions.

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: one sentence for fields, one for filters, one for include_values caveat, and ends with 'Read-only'. No redundancy or unnecessary text.

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

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

While there is no output schema, the description lists the fields returned. For a list tool, this is adequate. It references element_get for full shape. Could mention pagination, but not essential given simplicity.

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

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

Schema coverage is high at 90%. The description adds meaning beyond the schema by explaining the include_values default and clutter concern, and describing the filters parameter as an escape hatch with pattern 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 uses a specific verb 'list' with a clear resource 'elements', lists the returned fields, and distinguishes from element_get by recommending it for full shape. Sibling tools are also differentiated by context.

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 states when to use include_values (rarely) and advises using element_get for full shape. However, it lacks explicit when-not guidance compared to other list tools like articles_list, but the context implies this is for elements under a 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?

Discloses partial nature, flat body, and required fields beyond annotations which already indicate idempotence and non-destructiveness.

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 sentences, front-loaded with purpose, no 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?

Covers key aspects for an update tool, though could mention that the element must exist and does not specify return value.

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?

Adds critical constraint that at least one of title/path/values is required and confirms they are updatable, enhancing schema with 80% 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?

Clearly states action (Update), resource (element), HTTP method (PUT), and supports partial updates, distinguishing from element_create and element_delete.

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?

Specifies to supply only fields to change and requires at least one updatable field besides element_id, but does not explicitly mention when not to use or alternatives.

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

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

Annotations already declare read-only and idempotent; description adds endpoint and fields, consistent with annotations.

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

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

Short, front-loaded with key info (purpose, endpoint, fields), no wasted sentences.

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

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

Describes returned fields but omits explanation of the 'site' parameter and does not mention missing 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?

Schema has 0% description coverage for the required 'site' parameter; description does not explain its purpose or allowed values.

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 'List all payment gateways' with HTTP endpoint and returned fields, distinguishing it from siblings like products_list or orders_list.

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

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

No explicit when/alternatives, but context is clear for a unique list tool; no sibling confusion.

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

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

Annotations (readOnlyHint=false, destructiveHint=false) indicate it is a mutation. Description adds a note about flat body structure but lacks details like existence handling or authorization needs.

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

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

Two sentences, front-loaded with purpose and key parameters, no unnecessary wording. Efficient and to the point.

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

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

Covers essential aspects: purpose, required/optional params, body format. But omits error scenarios (e.g., duplicate code) and does not mention return value, which is acceptable given no 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?

Schema coverage is high (89%). Description reiterates required and optional params with some context (e.g., content_origin_id for duplication), adding marginal 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 'Add a new language to the Voog site' and provides the HTTP method and endpoint, making the purpose clear. It distinguishes from sibling tools like language_delete and languages_list.

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

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

No explicit guidance on when to use versus alternatives. While no sibling update tool exists, the description does not mention when not to use or potential constraints like code uniqueness.

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

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

The description goes beyond the destructiveHint annotation by detailing that the language is 'IRREVERSIBLE' and that it 'unbinds associated content'. This adds behavioral context about what happens during deletion, which is not fully captured by the annotation alone.

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 exceptionally concise, consisting of two sentences that front-load the core action and then deliver critical warnings. Every sentence adds essential information 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 covers the destructive nature, force requirement, and a safety suggestion, but lacks details on prerequisites (e.g., required permissions), response behavior, or asynchronous processing. For a delete tool with no output schema, it is adequate but not exhaustive.

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 description adds minimal value beyond the input schema. It repeats the force=true requirement already documented in the schema and does not explain the 'site' parameter or provide new insights into 'language_id'. With 67% schema coverage, the description falls short of compensating for gaps.

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: 'Remove a language from the site (DELETE /languages/{id})', identifying the verb, resource, and HTTP method. It distinguishes itself from sibling tools like language_create or languages_list by specifying deletion of a language, 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 usage guidance by noting the requirement for force=true and suggesting a site_snapshot first if uncertain. However, it does not explicitly advise when to choose this tool over alternatives (e.g., other delete tools), leaving the context of use implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds fields returned and purpose, reinforcing the read-only nature but not adding new behavioral traits.

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

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

Two sentences: first states purpose and returned fields, second gives usage hint. No unnecessary words, 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?

Describes return fields and provides usage context. Lacks details on parameter format, pagination, or error conditions, but sufficient for a simple list tool.

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

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

Schema has one required parameter 'site' with no description. The description does not explain what 'site' should be (ID, name, etc.), leaving the agent to infer from 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?

Clearly states 'List all languages on the Voog site' with specific fields, distinguishing it from sibling tools like language_create and language_delete.

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 guidance: 'Use the returned ids for page_create.language_id / article fields.' However, does not mention when not to use it or alternatives.

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

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

Annotations are all false (readOnly, idempotent, destructive), so they provide little. The description compensates by disclosing an important encoding behavior: `data` crosses a JSON boundary, literal \uXXXX escapes arrive decoded, and raw U+2028/U+2029 and C0 controls are refused as a fingerprint of that issue. This adds real behavioral context beyond the schema, though it does not cover other aspects like response format or 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 dense but not overly long. It front-loads the core purpose, then provides encoding warnings, alternative tools, and parameter guidance. Some redundancy exists (e.g., 'TEXT content only' and later 'this tool is for text assets'), and the image-upload protocol sentence is wordy, but every sentence contributes 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?

For a create tool with no output schema and minimal annotations, the description covers key context: constraints, parameter requirements, encoding pitfalls, and alternatives. It does not mention the `site` parameter despite it being required in the schema, and it doesn't state what the successful response looks like. Still, it is reasonably complete for an AI agent to use correctly.

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

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

Schema coverage is only 25% (only `data` has a description). The description adds value by listing `asset_type` enum values, explaining the encoding constraint on `data`, and stating required fields. However, it entirely omits `site` and gives no semantic context for `filename`. It partially compensates for the low schema coverage but not completely.

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 layout_asset' – a specific verb and resource – and immediately clarifies it is TEXT content only, distinguishing it from sibling tools like layouts_push and layout_asset_upload. It explicitly states the tool is for text assets (CSS/JS/HTML fragments), leaving no ambiguity about its 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 provides explicit when-to-use and when-not-to-use guidance: use for text assets, avoid for images (use product_set_images), avoid for binary uploads (use layout_asset_upload), and avoid for tracked file deployment (use layouts_push). It names the exact alternative tools, making the decision tree clear.

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

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

Annotations indicate destructiveHint=true and readOnlyHint=false, but description adds context: irreversibility and that templates referencing deleted file will render with empty content, going beyond annotations.

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

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

Description is concise with two sentences covering key points: action, irreversibility, force requirement, and side effect. Well front-loaded but slightly fragmented.

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, description covers critical behaviors: irreversibility, force requirement, and template impact. Missing explanation of parameters and error conditions, but overall adequate for a simple delete tool.

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

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

Schema description coverage is 0%, so description must compensate. It explains the 'force' parameter's necessity but does not describe 'site' or 'asset_id', providing only partial semantic help.

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 'Delete a layout_asset' with specific verb and resource, and distinguishes from sibling tools like layout_asset_create/update by emphasizing irreversibility and force requirement.

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?

Description mentions that the tool 'Refuses without force=true', providing a clear usage condition, but lacks explicit guidance on when to use vs alternatives or when not to 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?

Annotations indicate a non-read-only, idempotent, non-destructive operation. The description adds crucial behavioral information: filename causes a 500 error, data is not byte-exact due to JSON decoding, and raw U+2028/U+2029 or C0 controls are refused. These details go well beyond the annotation hint and are essential for safe use.

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 every sentence provides a necessary caveat or alternative. It leads with the core action, then systematically covers read-only field, encoding behavior, alternative tool, and input validation rules—all 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?

Given the tool's complexity (PUT with JSON boundary issues, read-only fields, external alternatives), the description is remarkably complete. It covers purpose, restrictions, alternative tools, error conditions, and encoding pitfalls. With no output schema, it provides enough context for an agent to invoke the tool correctly.

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

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

Schema coverage is only 25% (only filename has a description). The description compensates by explaining the semantics of `data` (JSON decoding, not byte-exact) and `filename` (rejected, use asset_replace). `site` and `asset_id` are self-evident from the tool name and context, so the added detail is 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 updates a layout_asset's content, using the specific HTTP PUT method and resource path. It distinguishes from sibling tools by explicitly recommending asset_replace for rename and layouts_push for deploying tracked files.

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 explicit when-to-use and when-not-to-use guidance: use asset_replace for rename, use layouts_push for tracked files, and warns against sending filename. This makes the tool's usage boundaries clear relative to alternatives.

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

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

Beyond annotations (destructiveHint=true, idempotentHint=false), the description adds critical behavioral details: same filename creates a second asset, result is editable=false, Voog derives asset_type/content_type, and assets are served from /images not /photos. This significantly clarifies the tool's behavior without contradicting annotations.

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

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

The description is front-loaded with the core purpose in the first sentence and uses paragraphs logically. It contains some minor extras (issue #140 item 4) that aren't essential but don't harm clarity. Overall it's efficient for the amount of context it provides.

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

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

For a mutation tool with no output schema, the description is reasonably complete: it explains the endpoint, serving path, asset types, editable=false, and duplicate behavior. It doesn't explicitly state the return value or error cases, but the provided context is sufficient for an agent to select and invoke this tool correctly.

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

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

Schema coverage is 67% (site lacks description). The description adds some context about binary files and serving paths, but doesn't enhance parameter meaning beyond the schema's existing descriptions for filename and file_path (default, absolute path, allowed extensions). The site parameter remains unexplained in both description and schema, and the description doesn't fully compensate for the gap.

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

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

The description opens with a specific verb+resource: 'Upload a BINARY layout asset from disk', and clarifies scope (favicon, icon, font, inline image) with an explicit endpoint. It distinguishes itself from sibling tools by contrasting with layout_asset_create (text data only) and asset_upload (photos).

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 when-to-use and when-not-to-use guidance: binaries needed a raw curl call before, photos should use asset_upload, and layout_asset_create is for text data. It also warns about duplicate filenames and recommends asset_replace for replacement, going beyond a simple use case.

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

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

Annotations indicate readOnlyHint=false, destructiveHint=false, idempotentHint=false. The description adds context by explicitly stating it is NOT idempotent and mentions the return value (new id). It does not contradict annotations and provides useful behavioral cues.

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 (3 sentences), front-loaded with the main purpose, and every sentence adds value. No 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 create tool with 5 parameters (4 required), the description covers the non-idempotency, return value, and parameter-specific behaviors. Annotations are present and consistent. No output schema, but the return value is mentioned. Complete for the 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%. The description adds meaning beyond the schema: it explains the effect of 'kind' on behavior, defaults and ignored status of 'content_type', and constraints on 'title' (no '/', '\', or leading '.').

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 layout or component', references the HTTP endpoint, and distinguishes between kind='layout' and kind='component' with their respective behaviors. It is specific and actionable.

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

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

The description explains when to use each kind and notes that content_type is only relevant for layouts. It also warns about non-idempotency. However, it does not explicitly compare to sibling tools like layout_update or layout_delete.

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?

Discloses irreversibility (IRREVERSIBLE — Voog does not retain), the need for force=true, and the restriction on deletion when pages are assigned. This goes beyond the destructiveHint annotation by adding specific 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?

Four sentences, each adding essential information. No redundancy, front-loaded with the core purpose. 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?

Given the simple parameter set (3 params, no output schema) and annotations (destructiveHint=true), the description fully covers prerequisites, behavior, error conditions, and best practices. A model example.

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 0%, so description must compensate. It explains the force parameter (Refuses without force=true) but does not define site or layout_id. The parameter names are self-explanatory, but the description adds minimal extra 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 starts with 'Delete a layout,' which is a clear verb-resource pair. It distinguishes from sibling layout tools (layout_create, layout_rename, etc.) by specifying the deletion action. No 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?

Explicitly states when to use (with force=true if needed), when to avoid (if pages are assigned), and provides alternative actions (reassign pages via page_set_layout) and a precaution (backup with site_snapshot).

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

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

Annotations indicate idempotent and non-destructive; description adds that renaming is reversible and details title constraints, which helps the agent understand behavior beyond the annotations.

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

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

Two concise sentences with front-loaded purpose. Every word adds value; no 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?

For a simple rename tool with three well-documented parameters and clear annotations, the description provides sufficient context including reversibility and title constraints. No gaps identified.

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 provides full coverage with descriptions for all three parameters. The description adds additional constraints on new_title (no '/' or '\' or starting with '.'), which enhances 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?

Clearly states the tool renames a layout, provides the HTTP method and path, and specifies constraints on the new title. Distinguishes from sibling tools like layout_create, layout_update, and layout_delete.

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

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

Explains the tool is for renaming layouts and is reversible. However, it does not explicitly mention when not to use it or provide alternatives like layout_update for other property changes.

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

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

The description directly contradicts the idempotentHint annotation. It states 'REFUSES to overwrite an existing tree that already contains .tpl files', meaning repeated calls on the same target directory will fail, which is not idempotent behavior. Per the rubric, any contradiction of annotations warrants a score of 1. The description does disclose useful behaviors (skip binaries, manifest, preservation of non-tpl files) but the contradiction is a severe issue.

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

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

The description is a single dense paragraph, but each sentence carries meaningful information: what is fetched, where it is written, what is skipped, manifest generation, and refusal behavior. It is front-loaded with the core action. Slightly long but appropriate for the tool's complexity.

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 explains the tool's side effects (writing files, manifest) and edge cases (binary skip, refusal, preservation). It does not explicitly mention what the function returns, but the extensive behavioral details cover the essential context for selection and invocation. Sibling differentiation is adequate via the explicit reference to layout_asset_upload.

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

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

Schema description coverage is 100%, so baseline is 3. The description echoes the schema's parameter meanings (site from voog_list_sites, target_dir absolute path) and adds a bit of context about what gets written there, but does not provide any additional parameter-level constraints or examples beyond the schema. No compelling need for more given full 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 states the verb ('Fetch every layout + component') and the resource (/layouts, layout_assets), and explicitly notes the output destination (target_dir). It also distinguishes from siblings by mentioning layout_asset_upload for binary assets, which differentiates its 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 tells when to use this tool (to pull text-based layouts/components/assets to local disk) and explicitly excludes a specific alternative ('Binary assets are skipped... use layout_asset_upload for those'). It also provides a clear caveat about existing .tpl files, guiding use in fresh or clear directories. It does not enumerate other alternatives but the context is sufficient.

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

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

The description discloses rich behavioral details beyond the annotations: content read directly from disk (avoiding JSON boundary decoding), files filter semantics, 200-without-persisting reported as failure, per-entry error capture without aborting the batch, and return breakdown. No contradiction with annotations (idempotentHint=true, readOnlyHint=false, destructiveHint=false).

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

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

The description is dense but well-organized, front-loading the core action, then filter behavior, critical warning, error handling, and pre-flight recommendation. A few sentences are long with embedded details, but each earns its place. Slightly tighter formatting would 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?

With no output schema, the description compensates by explaining the per-file success/failure breakdown and non-aborting error handling. It also mentions the pre-flight snapshot. Minor gaps remain (e.g., exact response format, how IDs are resolved from manifest), but overall it is complete enough for a deployment tool of moderate 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?

The input schema already covers all 3 parameters with descriptions (100% coverage). The description adds meaningful semantics: files=null/omitted means 'push all manifest entries', target_dir must contain manifest.json, and clarifies how file content is handled relative to layout_asset_update. This exceeds 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 clearly states the tool reads manifest.json and tracked files from target_dir and PUTs each to the type-mapped endpoint (layout or layout_asset), with explicit endpoint mapping. This specific verb+resource+scope distinguishes it from siblings like layouts_pull and layout_asset_update.

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 positions this as the 'BYTE-EXACT WAY' to deploy JS/CSS assets, contrasting with layout_asset_update's JSON decoding issue. It also recommends site_snapshot as a pre-flight. However, it doesn't provide comprehensive when-to-use/when-not-to-use guidance for all sibling 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?

The description adds significant behavioral detail beyond the idempotentHint annotation, explaining reversibility and the JSON boundary edge case with literal \uXXXX escapes and refusal of raw U+2028/U+2029 and C0 controls. This is exactly the kind of context that helps an agent avoid subtle failures and does not contradict any annotation.

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

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

The description is three sentences, each with a distinct role: core purpose, constraints/reversibility, and a niche gotcha with an alternative. No filler or repetition; it communicates dense information efficiently.

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

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

It covers the main function, constraints, idempotency, reversibility, an edge case, and an alternative tool. It does not explicitly mention return values or error handling, but given there is no output schema and the operation is straightforward, this 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?

Schema coverage is only 25% (only body has a description). The description deepens understanding of body by explaining decoding/escaping behavior, but site, layout_id, and title receive no added meaning beyond their names. It partially compensates for the low schema coverage but does not fully describe all parameters.

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

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

The description explicitly states 'Update a layout' with specific fields (body, title, or both), making the operation clear. It distinguishes itself from the sibling layouts_push by noting the latter is for byte-exact deployment of tracked .tpl files.

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

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

It provides clear usage constraints ('At least one must be supplied', 'Reversible by calling again') and gives an explicit alternative for a specific scenario ('use layouts_push'). However, it does not compare with other layout-related siblings like layout_rename or layout_create, leaving some ambiguity about when to prefer this over them.

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