Grigora

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

Annotations declare this is a destructive, open-world write, and the description adds context beyond them: project-administrator authorization is required, the backend performs DNS validation and SSL enablement automatically so no Verify click or validate API call is needed, and the caller is told to present DNS records verbatim. These are non-obvious operational facts not derivable from the schema or annotations.

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

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

Front-loads the action and return value in the first sentence, then layers prerequisites, idempotency, parameter guidance, and backend behavior in short declarative statements. No sentence is redundant with the schema or annotations.

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

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

Although there is no output schema, the description explains what comes back (DNS records to present exactly) and what happens afterward (automatic DNS checking and SSL). Combined with the auth requirement and idempotency contract, an agent has everything needed to call this correctly on first attempt.

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 the description carries the full burden and does so for the two non-obvious parameters: idempotency_key (unique per attempt, reused for retries, regenerated after cancel/re-add) and use_www (root domains default to www as primary). domain and project_id are left unexplained but are self-evident from their 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?

States a specific verb and resource ('Connect the owner's custom hostname') plus the side effect of returning DNS records. It is clearly distinguishable from the sibling get_custom_domain, which is explicitly named as a prerequisite rather than an equivalent.

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

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

Gives explicit sequencing ('Call get_custom_domain first'), an exclusion ('Do not replace an existing domain implicitly'), and the condition selecting the use_www variant ('only when the owner explicitly requests the root hostname as primary'). It also routes retries via the idempotency key, leaving little to inference.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the useful slug-uniqueness constraint, but mentions 'custom HTML fields' that do not exist anywhere in the schema, which is mildly misleading context. It says nothing about whether the created page is published or hidden.

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

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

Purpose is front-loaded in the first sentence and the Args block is one line per parameter with no filler. Given 0% schema coverage, the per-parameter lines are load-bearing rather than redundant.

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

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

An output schema exists, so return values need not be described, and the parameters are covered. What is missing is operational context for a write tool: required permissions, whether the page is immediately live, and how it relates to the project's publish flow.

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 the description carries the full burden and largely succeeds: it labels all five parameters and adds a real semantic constraint (slug must be unique in the project) that the schema does not express. The 'custom HTML' phrase, however, implies a parameter that is absent from the schema.

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

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

States a specific verb (Create) and resource (page) and enumerates the kind of payload it accepts (metadata plus optional SEO fields). It does not, however, distinguish itself from adjacent creation tools like create_cms_post or create_website, so the agent still has to infer that a 'page' is a distinct 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?

There is no statement of when to use this tool versus update_page, list_pages, or the CMS post/website creation siblings. The only conditional content is the slug uniqueness constraint, which is a validation rule rather than usage guidance.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, openWorldHint=true, so the mutation profile is covered. The description adds genuinely new behavioral context beyond the annotations: skip-if-already-linked semantics and, more importantly, all-or-nothing atomicity ('an unknown id fails the whole call'), which an agent must know before batching ids.

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

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

Two tight sentences front-load the behavior and the validation rule, followed by a compact Args block. The Args entries largely restate the schema titles, but the product_ids format note earns its place.

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

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

With an output schema present, return-value explanation is unnecessary, and the description covers the operation, the skip rule, atomic failure behavior, and parameter formats. The only real gap is routing guidance against the two closest siblings.

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 the description carries the full burden — and it does document all three params, including the JSON-array string format for product_ids with a concrete example ('["abc","def"]'). That is a meaningful addition the schema does not provide.

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

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

States a specific verb and resource ('Link products to a collection') plus the key differentiator 'skipping any already linked,' which separates it from the additive/replacing siblings. It does not name the alternatives (set_commerce_collection_products, remove_products_from_commerce_collection) explicitly, but the scope is unambiguous.

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

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

'Skipping any already linked' implies an additive, non-replacing use case that distinguishes it from set_commerce_collection_products, but the description never states when to prefer this tool over that sibling or over remove_products_from_commerce_collection. Usage is inferable rather than stated.

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

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

Annotations cover the safety profile (readOnlyHint=false mutation, destructiveHint=false, openWorldHint=true), but the description adds valuable context the annotations lack: the slug auto-generation behavior and the fact that the thumbnail URL is fetched and uploaded to the project CDN (an external side effect). It stops short of disclosing auth/permission needs or duplicate-name behavior, so a 4 rather than 5.

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

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

Purpose is front-loaded in the first sentence, followed by a well-organized Args list where each entry earns its place given the 0% schema coverage. Minor redundancy between the summary ('Name is required') and the Args entry ('required') prevents a 5.

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

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

For an 8-param mutation with an output schema (so return values need no explanation) and annotation coverage, the description is nearly complete. It omits auth requirements and error/duplicate handling, which are the remaining gaps.

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

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

Schema description coverage is 0%, so the description must carry the full parameter burden and largely does: it documents all 8 args, marks name as required, explains the slug default, and notes that the three thumbnail_* fields are stored in thumbnail_meta. It lacks detail on empty-string defaults or format constraints, keeping it below 5.

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

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

States a specific verb+resource ('Create a new CMS post category'), clearly distinguishing it from siblings like create_cms_post, create_commerce_collection, and update_cms_category. An agent can identify the target entity without opening the schema.

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

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

The description implies usage through required/optional semantics ('Name is required; slug is auto-generated from name if omitted') but never states when to reach for this tool versus create_cms_post or the other create_* siblings. No exclusions or alternative routing 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 establish this is a non-destructive write (readOnlyHint=false, destructiveHint=false). The description adds real behavioral context beyond them: content_blocks is stored as-is and overrides content HTML, setting excerpt flips the post to a custom excerpt, tags are created on the fly, and categories are matched and resolved server-side. It stops short of stating slug-uniqueness or permission behavior, keeping it from a 5.

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

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

The one-line purpose is front-loaded, followed by a clean Args list that is appropriately sized for 13 parameters. A few entries run long (e.g., featured_image_alt explaining SEO checks), but no sentence is filler given the parameter count.

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 an output schema present, return values need not be described, and the parameter/behavioral coverage is strong. The remaining gap is operational context: no mention of authentication, permissions, or how creation relates to the publish step, which an agent creating content would benefit from.

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 the description carries the entire burden for 13 parameters, and it does so thoroughly: each arg's meaning, format (HTML, URL, comma-separated lists, JSON block tree), defaults, and cross-parameter interactions (content vs content_blocks) are explained. This is exactly what a low-coverage schema requires.

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?

"Create a new CMS blog post" gives a specific verb (create) and resource (CMS blog post), cleanly distinguishing it from the many get_/update_/delete_/publish_ siblings. It does not explicitly name which alternative to use instead, but the create semantics are 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 never states when to use this tool versus update_cms_post or publish_cms_post, nor any prerequisites such as required project access or that publishing is a separate step. The only usage-like hints ("optional if content_blocks is set") are parameter-level, not tool-selection guidance.

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

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

Annotations already declare readOnly=false, openWorld=true, destructive=true, so the safety profile is covered. The description adds genuine behavioral context beyond that: drafts are not published to the storefront, slug is derived from title if empty, sort weight ordering, and product_ids display order.

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

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

Purpose is front-loaded in the first line, followed by a clean Args block. Given the 0% schema coverage, the per-parameter lines all earn their place rather than being redundant padding.

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

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

For a 9-parameter commerce mutation, the description covers purpose, all parameters, and several behavioral quirks. An output schema exists so return values need not be explained; only auth/permission requirements and error behavior are absent.

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

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

Schema description coverage is 0%, so the description must carry the full burden—and it documents all nine parameters with meaning, including the JSON array format for product_ids (["abc","def"]) and the seo object shape ({title, description, image_url, canonical_url, robots}). This fully compensates for the empty schema.

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

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

States a specific verb+resource ("Create a product collection") and clarifies the concept with two concrete examples ("New arrivals", "Under $50"). It does not explicitly differentiate from the many other create_* siblings, but the resource is distinctive enough that an agent can identify 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?

No when-to-use or when-not-to-use guidance is provided relative to alternatives like set_commerce_collection_products or add_products_to_commerce_collection. "Only title is required" is a minor helpful note, but nothing tells the agent when this tool is the right choice.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and openWorldHint=true, so the safety profile is covered. The description still adds genuine behavioral context beyond that: slug auto-generation from title, product_type forcing pricing_type, field suppression for physical products, and storefront visibility tied to status. It doesn't cover auth/permission requirements or failure modes.

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

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

Front-loads purpose and the critical money-format rule, then proceeds to a dense Args list. The list is long, but with 29 parameters at 0% schema coverage nearly every line is load-bearing; only a few entries (e.g. 'project_id: The project ID.') add little.

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?

An output schema exists, so return values need not be described. Combined with the annotations, the description covers essentially everything needed to invoke the tool correctly, including the cross-tool variants workflow. Remaining gaps are minor: error behavior, permission requirements, and create-vs-update routing.

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 the description carries the full parameter burden and does so: it documents all 29 parameters with units (price_amount in cents), conditional behavior (physical forces one_time), and concrete JSON shapes for the string-typed structured fields (options, variants, highlights, faqs, gallery, delivery_details, social_proof, seo, discount), including the max-3 options and max-12 collection limits.

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

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

States a specific verb and resource ('Create a product in the store') and immediately scopes requirements ('Only title is required'). It also distinguishes itself from the confusing siblings in the commerce family by explaining when to use `options` here versus calling generate_commerce_variants or passing `variants` explicitly.

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

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

Gives clear conditional guidance: money is in the currency's smallest unit, physical products force one_time pricing, checkout_url is ignored for physical products, and only active products appear on the storefront. It stops short of explicit when-not-to-use guidance (e.g., create vs update_commerce_product, or error behavior on duplicate slugs).

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

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

Annotations already declare readOnlyHint=false and openWorldHint=true, so the write nature is covered; the description adds real beyond-schema context: the 409 duplicate-combination failure, the required prior call to set_commerce_product_options, and the meaning of the -1 sentinel for optional amounts. It never addresses the destructiveHint=true annotation beyond the generic write framing, but the added failure/prerequisite detail is substantive.

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

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

Purpose, prerequisite, and failure mode are front-loaded in the opening two sentences, and the Args block is well-organized one-line-per-parameter. Given 0% schema coverage the length is justified, though 'Leave -1 to skip' is repeated four times and could be stated once.

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 12-parameter mutation tool with an output schema (so return values need no explanation) and covering annotations, the description supplies the prerequisite, failure mode, and full parameter semantics. It omits which parameters are required and any permission/authorization expectations, but nothing essential to calling it correctly is missing.

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

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

Schema description coverage is 0%, so the description carries the entire burden, and it does: every one of the 12 parameters is documented, including non-obvious conventions like -1 meaning 'inherit' or 'skip' for price_amount, compare_at_amount, weight_grams, and inventory_quantity, the deny/continue semantics of inventory_policy, the ISO currency default, and a concrete option_values JSON example. This is meaningfully richer than the bare 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 first sentence gives a specific verb and resource with scope: 'Add one variant to a product.' The word 'one' implicitly separates it from the bulk sibling generate_commerce_variants, and the following lines clarify its prerequisite. It stops short of naming the alternative tool outright, so it is clear but not fully self-differentiating.

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 states an explicit prerequisite ('call set_commerce_product_options first') and a concrete failure condition ('Fails with 409 if the combination already exists'), which is strong context for invocation ordering. It does not say when to choose this over generate_commerce_variants or update_commerce_variant, so the alternative-selection guidance is only partial.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the safety profile of this write is covered. The description adds useful substance the annotations do not: the full enumeration of allowed field types and the slug format constraint. It still omits any side-effect context such as slug uniqueness, permission requirements, or what happens on duplicate slug.

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

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

One-sentence purpose followed by a compact parameter list; every line carries information and nothing is padded. The Python-style 'Args:' docstring formatting is slightly unconventional for a tool description but is well organized and front-loaded.

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

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

An output schema exists, so return values need not be explained, and annotations cover the safety profile. Combined with full parameter documentation, the description is sufficient to invoke the tool correctly; what is missing is invocation context (permissions, slug collision behavior, usage guidance), which keeps it short of complete.

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

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

Schema description coverage is 0%, so the description carries the entire burden and does so well: it documents all four parameters, clarifies that 'fields' is a JSON array of field objects despite being typed as a bare string in the schema, specifies required vs optional field keys (type, label required; id optional), and enumerates the twelve valid field types. The slug format constraint is not present anywhere in 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 opening line gives a specific verb and resource ('Create a new directory collection'), which is enough to distinguish it from list/update/delete_directory_collection siblings. It does not, however, differentiate it from the other create_* tools (create_directory_field, create_directory_item, create_commerce_collection), leaving the agent to infer the distinction from the name alone.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives. The Args block documents parameter shapes but never says when a directory collection is the right construct versus a CMS category, commerce collection, or a directory field/item. The agent gets no routing help.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the mutation/safety profile is covered structurally. The description adds one useful behavioral fact — field_id is auto-generated if omitted — but does not say whether field_type is immutable after creation, how ID collisions are handled, or what permissions the create requires.

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 one-line purpose is front-loaded and the Args block is scannable with no filler. Some entries are terse ('The project ID.') but nothing is wasted or redundant.

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

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

An output schema exists, so return values needn't be described, and the parameters are fully covered. What's missing for a create-in-collection operation is ordering/prerequisite context and whether the new field type constrains existing or future items — relevant given the paired create_directory_item and update_directory_field tools.

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

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

Schema description coverage is 0%, so the description carries the full parameter burden, and it does so: it documents all five parameters, including the optional field_id default. Critically, it enumerates the valid field_type values (text, richtext, image, link, datetime, switch, option, reference, map, html, multiimage, video), which the schema does not expose as an enum — without this an agent could not construct a valid call.

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

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

The first sentence states a specific verb and resource: 'Create a new field in a directory collection.' That distinguishes it from create_directory_collection, create_directory_item, and update_directory_field in the sibling list. It doesn't explicitly name or contrast those siblings, so it stops short of a 5.

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

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

There is no guidance on when to choose this tool, what prerequisites exist (e.g., the collection must already exist), or when to prefer update_directory_field. The agent must infer all of this from the name and the directory_* sibling cluster.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=false, and destructiveHint=false, giving the agent the safety profile. The description's 'Create a new directory item' merely restates this and adds nothing behavioral beyond annotations, such as slug uniqueness constraints, permission requirements, or whether 'fields' values must conform to defined directory fields.

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

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

The purpose is front-loaded in a single sentence, followed by an Args list covering each parameter. It is appropriately sized, though the param descriptions add little beyond their titles, resulting in minor syntactic waste.

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

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

With an output schema present, return values need not be described, and annotations cover the safety profile. Combined with per-parameter documentation, this is largely sufficient for a create tool, though it omits the relationship between items and their parent collection and doesn't note any required field/collection preconditions.

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 the description carries the full burden, and it does document all five parameters by name with brief meaning. 'fields: JSON object mapping field_id to value' is genuinely informative, though several entries ('The project ID', 'Item name') are thin restatements and the fields JSON format is left largely undefined.

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

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

The description states a specific verb+resource combination ('Create a new directory item'), which an agent can distinguish from the sibling create_directory_collection and create_directory_field. However, it offers no differentiation from those near-neighbors or context on how an 'item' relates to its collection, so it is clear but not sibling-aware.

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

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

There is no guidance on when to use this tool versus alternatives, no prerequisites, and no mention of which siblings (e.g. update_directory_item, create_directory_field) cover adjacent tasks. The agent must infer usage entirely from the name.

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

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

Annotations only declare the generic safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false); the description adds real behavioral content beyond them: the required OAuth scope newsletter:write and the retry-safe idempotency_key contract. It stops short of describing side effects such as whether the field is immediately available in forms or what happens on a key collision.

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

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

Three tight sentences, front-loaded with the action and scope, then the idempotency contract, then cross-tool routing. No filler, though the trailing get_newsletter_schema pointer is the least essential sentence.

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

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

An output schema exists so return values need no explanation, and annotations cover the safety profile, but with 0% schema coverage the description should have covered the enum data_type and the options object. Auth scope, idempotency and routing are present; parameter semantics are largely absent.

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

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

Schema description coverage is 0% and six parameters exist, so the description must carry the load. It explains idempotency_key well (stable value, reuse on retries) but leaves key, label, data_type, options and project_id entirely undocumented — notably the enum data_type and the options object, which clearly interact.

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 names a concrete verb and resource ('Define a subscriber attribute') and adds ordering context ('before collecting it in forms'), which separates it from the read-only list_newsletter_custom_fields. It does not, however, explicitly distinguish itself from update_newsletter_custom_field, leaving the create-vs-modify boundary to inference.

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

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

It gives clear usage context ('before collecting it in forms') and names the complementary tool to consult for definitions (get_newsletter_schema). It never states when not to use this tool, e.g. that modifying an existing field should go through update_newsletter_custom_field.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the safety profile is covered. The description adds real behavioral context beyond them: the custom-domain prerequisite and the 403 failure mode. It stops short of explaining reversibility or duplicate-source behavior.

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

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

Front-loads purpose, then the prerequisite, then a clean Args list. Every line is informative, though the Args block is long enough that it reads more like reference documentation than a tight summary.

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

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

An output schema exists, so return values need no explanation, and the description fully covers parameters and the key prerequisite. It omits conflict handling (e.g., existing redirect on the same source_path) and any auth/permission notes, leaving minor gaps.

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

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

Schema description coverage is 0%, so the description carries the full burden and does so: it defines each of the 6 params, their defaults, the internal/external branching for dest_type, valid status codes, and constraints (source_path cannot be '/', dest_url must start with http(s)).

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

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

States a specific verb+resource ('Create a URL redirect for a project') and scope, letting an agent distinguish it from update_url_redirect, delete_url_redirect, and list_url_redirects without opening any schema.

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

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

Gives a concrete precondition — a custom domain must be connected or the API returns a 403 — which tells the agent when the call will succeed. It does not explicitly name alternatives (update/delete/list redirects) or when-not-to-use, so it falls short of the 5 bar.

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, openWorldHint=true, readOnlyHint=false; the description adds critical context beyond that: the build runs asynchronously in a few minutes, consumes AI credits and the plan's website limit, the site is NOT published, and refused attachments fail before build/charge. This is exactly the behavioral detail annotations cannot convey.

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

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

Front-loaded with the core verb+resource, then sequencing, then args. Every sentence earns its place, though the attachments paragraph is dense and the multi-line wrap of the opening sentence is slightly awkward. No filler.

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

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

Given a destructive, credit-consuming, async operation with 0% schema coverage, the description covers cost, latency, publish state, follow-up tools, and the local-file upload path. An output schema exists, so return values needn't be explained; nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 0% so the description carries the full burden, and it does: prompt content guidance, name being optional and derived from prompt, attachments syntax (list of up to 10 public URLs, 80 MB cap, links only), plus the local-file workaround via get_attachment_upload_url. This is far richer than the bare schema allows.

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

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

States a specific verb+resource ('Create a NEW Grigora website with AI') and clarifies it is a background build from a prompt, distinguishing it from edit_website, publish_project, and get_website_build_status. An agent can tell exactly what this tool produces.

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

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

Explicit when-to-use ('call it once per website the user actually asked for'), when-not-to (must poll build status before using other tools), and names both the next step (get_website_build_status) and downstream alternatives (edit_website, publish_project). Nothing is left to inference.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and openWorldHint=true, so the safety profile is covered. The description still adds a non-obvious behavioral rule – folder paths must end with '/' – which is exactly the kind of context the annotations cannot express. It does not disclose whether deletion is recursive or permanent beyond what destructiveHint implies.

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

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

Two short blocks with the operation stated first and parameters second; no filler. The 'Args:' list format is slightly mechanical but front-loads the important scoping rule (trailing slash) before the parameter details.

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

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

An output schema exists, so return values need not be described. Both required parameters are documented, the trailing-slash convention is explained, and safety is carried by annotations. Remaining gaps (recursion semantics, effect on dependent pages) are minor for this tool's complexity.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden, and it does: project_id is identified as the project ID, and files is explained as a JSON array of paths with a concrete example. That clarification is genuinely valuable because the schema types 'files' only as a plain string, and the description resolves that 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?

States a specific verb (Delete) and resource (assets – files and/or folders) with a clarifying parenthetical, so an agent can distinguish it from the many delete_cms_*/delete_commerce_* siblings that target other resources. It does not, however, explicitly name or contrast itself with the asset-management siblings (list_assets, get_asset), so it stops short of full differentiation.

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

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

The description says what the tool does but never states when to use it versus alternatives, nor any prerequisites, permissions, or caution about irreversible removal. With 0% schema coverage and a destructive operation, the absence of any usage context is a real gap.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds almost nothing beyond that: it doesn't say whether the deletion is permanent, whether it cascades to posts/associations, or what permissions are needed.

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 definition is short and front-loads the action and resource before the Args block. No sentence is wasted, though the Args lines are largely restatements.

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?

An output schema exists, so return values need not be explained, and annotations cover destructiveness. However, for an irreversible delete the description omits permanence and side effects, leaving it only minimally 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 0%, so the description must compensate. It names both parameters, but 'The project ID' is tautological; only '(from list response)' on category_id adds real acquisition guidance. Marginal but minimally functional for a 2-param tool.

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

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

States a specific verb and resource ('Delete a CMS post category by ID'), which clearly separates it from deletion siblings like delete_cms_post and delete_commerce_product. It stops short of explicitly naming alternatives, so it lands just below a 5.

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

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

There is no explicit guidance on when to use this versus alternatives such as update_cms_category, nor any warning about prerequisites. The lone hint is the parenthetical '(from list response)' on category_id, which only faintly implies list_cms_categories is the source.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and openWorldHint=true, so the agent knows this is a permanent, mutating, externally visible operation. The description adds nothing behavioral beyond that — it does not state whether the deletion is reversible, whether it requires a publish step first, or what happens to related data. Given the annotations carry the safety profile, a baseline 3 is appropriate.

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?

Extremely tight: one action sentence followed by param notes. The purpose is front-loaded, and there is no filler or repetition. Every line serves a 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?

An output schema exists, so return values need not be documented, and annotations cover the destructive/safety profile. For a two-parameter destructive tool this is close to adequate, but the absence of any irreversibility or prerequisite note, plus the tautological project_id description, leaves a small completeness gap.

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

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

Schema description coverage is 0%, so the description must compensate. It does so well for post_id, clarifying it can be a UUID from a list response or a full SK like cms-post-data-<uuid> — genuinely useful format guidance. However, project_id is only restated tautologically ('The project ID'), leaving half the parameters without added 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?

States a specific verb+resource: 'Delete a CMS blog post'. This distinguishes it from the many other delete_* siblings (delete_assets, delete_cms_category, delete_directory_item) by naming the exact resource. It stops short of differentiating itself from adjacent CMS post tools (unpublish_cms_post, update_cms_post), but the purpose itself is unambiguous.

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

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

There is no explicit when-to-use, when-not-to-use, or prerequisite guidance. With siblings like unpublish_cms_post and update_cms_post in the same CMS post family, the description should clarify that this permanently removes the post rather than merely unpublishing it, but it offers no such routing. The agent is left to infer usage entirely.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new context beyond that: the deletion is non-cascading and products grouped by the collection are preserved, which is exactly the kind of side-effect detail that matters for a destructive operation.

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

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

Front-loaded with the action and the key side-effect in two short sentences. The Args block is largely redundant with the schema but costs little; nothing else is wasted.

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

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

Output schema exists so return values need no explanation, and annotations carry the destructive/read-only profile. Still missing for a destructive mutation: permission requirements, whether the collection must be empty, and whether deletion is reversible.

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 both parameters are required, yet the Args block only restates each parameter name ('The project ID', 'The collection ID to delete') without adding format, source, or lookup guidance. The description does not compensate for the coverage 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?

States a specific verb (Delete) and resource (collection), plus a scope clarification that the grouped products survive. An agent can distinguish it from delete_commerce_product or delete_directory_collection by inference, though no sibling is named explicitly.

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

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

No when-to-use guidance, no prerequisites, no mention of alternatives or recovery path. The only contextual signal is the non-cascade note, which is behavioral rather than usage-routing guidance.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the safety profile is covered; the description adds genuine behavioral value by disclosing the cascading deletion of stock counters and the 409 conflict condition with open orders, which annotations cannot express.

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 two substantive sentences are front-loaded and zero-waste; the trailing Args block is mostly redundant given the schema, slightly diluting an otherwise tight description.

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 an output schema and full annotation coverage, the cascade effect and conflict semantics are the key missing pieces an agent needs, and both are supplied. Only parameter provenance/format guidance is absent.

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

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

Schema description coverage is 0% and both parameters are required, so the description carries the full burden — yet it only restates the names ('The project ID', 'The product ID to delete') with no format, ID source, or lookup guidance. It adds essentially nothing beyond the schema's property titles.

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

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

States a specific verb and resource ('Delete a product') and adds the non-obvious cascade scope ('and its stock counters'), which distinguishes it from delete_commerce_variant, delete_commerce_collection, and other delete_* siblings.

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

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

Gives an explicit precondition and failure mode: 409 while any order referencing the product is open, plus the remediation path (fulfil, refund, or cancel first). It does not name alternative tools, but the when-to-use context is clear and actionable.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely useful side-effect detail beyond that: the stock counter is dropped but product options are preserved, which tells the agent what survives the deletion.

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

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

The behavioral note is front-loaded in the first two sentences and the Args list is short and scannable. The Args block is largely redundant given the schema, but it costs little space.

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?

An output schema exists, so return values needn't be described, and the key side effect (variant removed, stock counter dropped, options kept) is covered. However, for a destructive operation with 0% parameter coverage, there is no guidance on permissions, error conditions such as removing a last variant, or recovery.

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 all three parameters are bare string fields. The Args block only restates the parameter names as 'The project ID', 'The product ID', and 'The variant ID to remove', adding no format, lookup, or dependency semantics to compensate for the coverage 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?

States a specific verb (remove) on a specific resource (one variant of a product) and clarifies the scope by noting the product's options survive. It implicitly separates itself from delete_commerce_product by targeting a single variant, though it doesn't name that sibling explicitly.

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

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

No explicit when-to-use or when-not-to-use statement, and no alternatives are named. The note that options are retained 'so the combination can be re-added later' implies a scenario (temporarily removing a variant) but leaves the agent to infer it.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds value beyond them by disclosing the cascade: deleting the collection also removes all its items, which is a materially larger blast radius than the tool name implies. It still omits irreversibility/permission requirements, so not a 5.

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

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

Front-loaded with the destructive scope in the first sentence, and the total length is minimal. The 'Args' block is redundant filler given the schema, but the cost is small.

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 an output schema present and annotations covering the safety profile, the description need not explain return values. It covers the essential cascade behavior; only permission/irreversibility context is missing.

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

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

Schema description coverage is 0%, so the description carries the burden, but its 'Args' block merely restates the schema property titles ('The project ID.', 'The collection ID.') with no format, ID-source, or lookup guidance. It provides no semantics beyond what the schema already shows.

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

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

States a specific verb+resource ('Delete a directory collection') and adds meaningful scope ('and all its items'), so an agent knows this is a cascading delete rather than a single-item delete. It does not explicitly contrast with siblings like delete_directory_item or delete_directory_field, but the resource naming is unambiguous.

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

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

There is no guidance on when to use this tool versus the other delete_* siblings, no prerequisites (e.g. permissions, whether the collection must be empty), and no warning that the operation is irreversible. The agent must infer usage from the name alone.

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

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

Annotations already supply the safety profile (destructiveHint=true, readOnlyHint=false), so the bar is lower, but the description adds nothing beyond that: no mention of permanence, whether items or stored data referencing the field are affected, or any prerequisites. The Args block merely restates the schema rather than disclosing behavior.

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

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

The one-line purpose is front-loaded and efficient, but the boilerplate Args list duplicates the input schema with no added value, padding the definition without informing the caller.

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?

An output schema exists, so return values need not be explained, and annotations cover the destructive nature. However, for a permanent deletion tool the description omits any consequence or data-loss context an agent should weigh before invoking it.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, but the Args entries are tautological ("The project ID", "The collection ID", "The field ID to delete") and add no semantics such as ID format or where these IDs come from.

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

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

The first sentence gives a specific verb+resource ("Delete a field from a directory collection"), which lets an agent distinguish it from delete_directory_collection and delete_directory_item. It is clear, though it doesn't explicitly name or contrast sibling delete 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?

There is no guidance on when to use this versus update_directory_field (to modify) or delete_directory_collection (to remove the whole collection). The scope is implied by the name alone with no conditions or alternatives 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 declare readOnlyHint=false and destructiveHint=true, so safety semantics are covered by structured data; the description adds nothing further. It does not say whether the delete cascades to children, whether it requires elevated permissions, or whether it is reversible, which is exactly the extra context expected of a destructive tool.

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

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

The text is short and front-loaded with the action, with no filler prose. The Args block is largely redundant with the schema, but it costs little and is easy to scan.

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

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

An output schema exists so return values need no explanation, and annotations cover the destructive/read-only profile. The remaining gap is the three fully required, zero-coverage parameters, for which the description offers no compensating detail; it is minimally viable rather than 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 0%, so the description carries the full burden, and it only restates the parameter names as 'The project ID / collection ID / item ID to delete.' There is no format, no hint about where these IDs come from, and nothing the schema titles don't already imply.

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 names a specific verb ('Delete') and resource ('directory item'), so the core action is unambiguous. However, it makes no attempt to distinguish itself from the adjacent destructive siblings such as delete_directory_collection or delete_directory_field, so the agent gets no help choosing among them.

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

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

There is no when-to-use guidance, no note that the deletion is permanent/irreversible, and no mention of alternatives (e.g., update_directory_item to modify instead of remove). The description stops at the verb and resource.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the agent knows this is an irreversible-style mutation without the description saying so. The description adds no further behavioral context (permanence, effect on live traffic, auth requirements), so it earns no extra credit above the annotation-covered baseline.

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

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

Two lines plus a short Args block, with the action front-loaded. The Args section is slightly redundant against the schema but stays brief and earns its place by carrying the ID-source hint.

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?

An output schema exists, so return values need not be described. Still, for a destructive tool with 0% parameter documentation and no usage guidance, the definition is only minimally complete — it omits any note on permanence or prerequisites.

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 the description must carry the parameter burden. It names both required params and gives one genuinely useful hint (redirect_id comes from list_url_redirects), but "The project ID" is purely tautological and adds nothing for a 0%-coverage schema.

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

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

States a specific verb and resource ("Delete a URL redirect") and narrows the target with "by ID", so the action is unambiguous. However, it never distinguishes itself from the closely related siblings create_url_redirect, update_url_redirect, and list_url_redirects, which is the only thing keeping this from a 5.

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

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

There is no guidance on when to use this versus update_url_redirect (which would be the non-destructive alternative). The parenthetical "(from list_url_redirects)" hints at where the ID originates, but that is a data-sourcing note, not usage guidance or an exclusion.

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

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

Beyond the annotations (destructiveHint=true, openWorldHint=true), it discloses that changes apply asynchronously in the background over minutes, consume AI credits, nothing is published, the build_in_progress error contract, and that a no-build outcome surfaces a question in 'reply'. This is rich behavioral context an agent needs before invoking.

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

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

Front-loaded with the core action and constraints, then a well-organized Args block. It is on the longer side and the attachments paragraph is dense, but nearly every sentence carries actionable information; only marginal trimming is possible.

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 an output schema present, return values need not be explained, and the description instead covers the async lifecycle, error codes, credit cost, and attachment prerequisites. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 0%, so the description carries the full burden and does: project_id defined, prompt defined with a concrete example, and attachments fully specified (up to 10 public URLs, 80 MB each, refer by filename, never pass file contents, local-file upload workflow). It compensates completely for the missing schema 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?

States a specific verb (change/edit) and resource (existing AI-built Grigora website) and immediately scopes it to 'AI-builder websites', distinguishing it from siblings like update_page or create_website. An agent knows exactly what this does and what it operates on.

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 it works only on AI-builder websites, that only one build runs per site, that it should be routed through get_website_build_status, that related changes should be combined, and it names get_attachment_upload_url as the prerequisite path for local files. This is close to a full when/when-not/alternative guide.

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

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

Annotations already mark this destructive and open-world, and the description goes well beyond them: existing variants are matched by option combination and preserve id, SKU, price and stock, while missing combinations are added at the product's price, all capped at 100. That is exactly the kind of side-effect detail an agent needs before invoking a mutation.

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 core behavior is front-loaded in two dense, informative sentences with no filler. The trailing Args block is pure repetition of the parameter names with no added value, which is the only waste.

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

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

An output schema exists, so return values need not be described, and the description covers the key semantics: matching rule, price default, and the 100-variant cap. It could be stronger by noting prerequisites or what happens when the cap is exceeded.

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's Args block only restates the names ('project_id: The project ID', 'product_id: The product ID'), adding no format, source, or constraint information. It fails to compensate for the schema 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 uses a specific verb and resource ('Generate every combination of a product's current options as variants') and bounds the scope with '(max 100)'. It is clearly distinguishable from the sibling create_commerce_variant, which creates one variant, and list_commerce_variants, which reads them.

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 describes the bulk-generation behavior and the max-100 constraint, which implies the context for use, but never states when to prefer it over create_commerce_variant for a single variant or what prerequisites (e.g. options must already be defined via set_commerce_product_options) apply. Usage is implied, not prescribed.

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 readOnly=true, idempotent=true, destructive=false and closed-world, so the safety profile is covered without description help. The description's real added value is the Umami-connection prerequisite, which no annotation conveys; it says nothing about rate limits or result truncation, so a 3 is appropriate.

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

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

Purpose is front-loaded in the first sentence, followed by a compact Args block that earns its space by adding formats, defaults and enum values the schema omits. Slightly list-like, but no filler sentences.

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

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

With an output schema present, return values need no explanation, and the description covers the prerequisite, all six parameters, their formats and defaults. Complete enough for a read-only analytics query, with only timezone formatting left implicit.

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

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

Schema description coverage is 0% (only titles and defaults), so the description carries the burden and does so well: it supplies YYYY-MM-DD formats for both dates, defaults (last 30 days, today, UTC), the meaning of limit (top pages only), and the enum values for unit (minute/hour/day/month/year) that the schema lacks entirely. The timezone string format (e.g. IANA) is left unspecified, keeping it from a 5.

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

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

States a specific verb and resource ("Get Umami analytics for a project") and enumerates the payload (pageviews, visitors, top pages), so an agent knows exactly what comes back. No sibling tool competes for analytics, so there is nothing to distinguish against, but the definition also doesn't say how it relates to the broader project/website toolset.

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

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

It gives one useful precondition ("Requires Umami connected to the project"), which tells the agent when this call will succeed. However, it never states when to reach for this versus other data-gathering tools, nor what to do if Umami is not connected; usage is only implied by the precondition.

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, idempotentHint, destructiveHint=false and closed-world scope, so the safety profile is fully covered by structured data. The description adds that the response contains a URL and metadata, which is useful, but says nothing about failure behavior for missing paths or whether reads are cached/stale.

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

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

The purpose is front-loaded in a single tight sentence, followed by a conventional Args block. Nothing is padded, though the restated 'project_id: The project ID.' line is dead weight.

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

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

With an output schema present, the return shape need not be described, and a read-only single-entity lookup has little behavioral surface to cover. Both required parameters are at least named in the description, so an agent has enough to invoke it correctly; only error/missing-path behavior is unaddressed.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden. It does give the 'path' format and a concrete example ('images/photo.jpg') and notes it is relative to the project, which is genuine added meaning. But 'project_id' is explained only as 'The project ID.', a tautology that adds nothing.

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

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

States a specific verb and resource ('Get a single asset') plus the lookup key ('by path') and what comes back ('URL and metadata'), which cleanly separates it from list_assets and get_asset_upload_urls. It stops short of naming those siblings explicitly, so it is clear but not fully self-differentiating.

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 word 'single' implies this is for one already-identified asset rather than enumeration, which implicitly routes the agent away from list_assets. However, there is no explicit when-to-use statement, no exclusion, and no mention of what to do if the path does not exist or whether get_asset_upload_urls is the counterpart for writing.

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/openWorldHint/idempotentHint/destructiveHint, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the fact that the caller must issue a PUT to the returned upload_url and that cdn_url is the post-upload access path. It omits signed-URL expiry and permission requirements, keeping it from a 5.

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

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

Front-loaded with the core action and consumption workflow before the Args listing, so a reader gets the essential contract in the first sentence. Every sentence earns its place; the Args block is standard but slightly 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?

Output schema exists, so return-value explanation is not required, yet the description still usefully names upload_url and cdn_url. Parameters are covered. For completeness it could mention signed-URL lifetime and whether the files array creates assets up front, but an agent can invoke this correctly as written.

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 the description carries the burden, and it largely does: it documents all three parameters and crucially clarifies that files is a JSON array of filenames (with an example like ["images/photo.jpg", "doc.pdf"]) despite the schema typing it as a plain string. folder's "prefix" semantics are stated. project_id is documented only tautologically ("The project ID").

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

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

States a specific verb and resource ("Get signed upload URLs for one or more files") and goes further by explaining the two-step upload workflow. It is immediately clear what the tool returns and how to consume it. It does not explicitly distinguish itself from the close sibling get_attachment_upload_url, so it stops short of a 5.

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

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

The description gives solid guidance on how to USE the result (PUT to upload_url, then read cdn_url), which is real usage context. However, it never says when to pick this tool over the sibling get_attachment_upload_url or get_asset, nor any prerequisites. Usage is implied rather than routed.

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

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

Beyond the readOnly/idempotent annotations, it discloses link lifetime (15 minutes), single-use behavior ('one-time', 'one link per file'), size ceilings, allowed MIME types, and the notable privacy property that file contents never pass through the conversation. This is rich behavioral context an agent could not infer from the annotations.

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

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

The critical action and constraints are front-loaded, and the Args block is separated cleanly. Every sentence adds actionable information; there is no filler.

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

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

It even describes the two outputs to expect (the curl command and the url) despite an output schema existing, and covers limits, workflow, and exclusions. For a three-param tool with a fully undocumented schema, this is 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 0%, so the description must carry the whole burden, and it does: file_name gets an example and usage note, mime_type gets concrete examples, and size_bytes explains how to compute the value ('wc -c < FILE'). No parameter is left 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 opening states a specific verb (get), resource (one-time upload link), and scope constraint (for a LOCAL file to attach to create_website / edit_website). It is clearly distinguishable from the sibling get_asset_upload_urls and from simply passing a public URL.

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 spells out the exact workflow (run the returned curl, then put the url in the attachments list of create_website or edit_website) and gives an explicit when-not: 'For a file that is already online, skip this and pass its public URL directly.' Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered without the description. The description adds little beyond that, though 'null if not parseable' for content_blocks is genuine behavioral context about a partial-failure case.

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

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

Front-loaded with purpose, followed by a compact return summary and a short args list. The return-value sentence is somewhat redundant given an output schema exists, but overall the text is tight and wastes little.

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?

Since an output schema exists, the return-value detail is a bonus rather than a requirement, and the description covers both required params and the nullable-block edge case. Missing only error behavior for a nonexistent or inaccessible post, which is minor for a read tool.

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

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

Schema coverage is 0% (both params are bare 'Post Id'/'Project Id' strings), so the description must compensate. It gives post_id real format guidance ('UUID from list response, or full SK like cms-post-data-<uuid>'), which is meaningful; project_id gets only a tautological gloss.

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

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

States a specific verb and resource ('Get a single CMS blog post's content') and specifies the retrieval mode ('as HTML and as blocks'), which distinguishes it from list_cms_posts and the create/update/delete CMS siblings. It stops short of naming the sibling to use for batch retrieval, so it is clear but not fully differentiated.

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

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

Usage is only implied: 'single' implies the alternative to list_cms_posts, and the post_id hint ('UUID from list response') hints at the list-then-get workflow. There is no explicit when-to-use/when-not statement or named alternative.

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

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

Annotations already declare this a safe, idempotent, closed-world read, so the safety profile needs no restating. The description adds genuine behavioral constraints beyond that: collection_id is required unless slug is supplied, and products come back in link order. It says nothing about auth or pagination, keeping this at a solid but not rich 3.

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

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

The purpose sentence is front-loaded, followed by a compact Args list. Every line earns its place given the zero schema coverage, though the plain Args enumeration is functional rather than elegant.

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?

An output schema exists, so return values need no prose. With all four inputs documented and the read-only profile covered by annotations, the definition is complete enough for a single-resource fetch; the only gap is the absence of any sibling routing.

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 the description carries the full burden, and it does so well: all four parameters are explained, including the mutually exclusive collection_id/slug behavior and the link-order meaning of include_products. Only the format/type nuances of project_id and collection_id are left implicit.

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

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

States a specific verb and resource ('Get one collection'), and the singular 'one' plus the optional product expansion cleanly separates it from list_commerce_collections. It does not name or reference any sibling explicitly, so it is clear but not differentiated by comparison.

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

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

There is no explicit when-to-use or when-not-to-use guidance and no routing to alternatives such as list_commerce_collections or get_commerce_product. The id/slug rule is an invocation constraint rather than usage guidance, so the agent must infer when this tool applies.

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, idempotentHint and non-destructive, so the safety profile is covered. The description adds genuine context by enumerating that the response includes live stock and a public URL, signaling dynamic/fresh data rather than a cached record.

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

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

One front-loaded sentence delivering purpose and return scope, followed by a tight Args block. No filler sentences; every clause adds 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?

An output schema exists, so return values needn't be spelled out, and the description still previews the payload. All parameters are accounted for and the id/slug fallback is covered, leaving little an agent needs and cannot find.

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 the description carries the burden and does so well: it names all three params and explains the conditional relationship (product_id required unless slug given; slug used when product_id is empty). Minor gap: no format or format-of-id detail.

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

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

States a specific verb+resource+scope: 'Get one product' with the enumerable contents (options, variants, live stock, public URL). The word 'one' cleanly distinguishes it from the sibling list_commerce_products without opening either schema.

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

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

Usage is implied by the singular 'one product', and the args section hints at the product_id-vs-slug routing condition, but there is no explicit when-to-use guidance or named alternative (e.g., when to prefer list_commerce_products or get_commerce_collection). Minimum viable.

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 readOnly/idempotent/non-destructive, but the description adds a security-relevant disclosure: payment gateway credentials are never returned, only connection status. That is genuine behavioral context beyond the structured fields.

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

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

Front-loaded with the returned-field list and the credential caveat, then the args. The trailing 'Args' block is largely redundant but the overall size is appropriate.

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?

An output schema exists, so return structure is covered elsewhere; the description still usefully previews the field set and the credentials limitation. Adequate for a single-parameter read tool, with only the missing usage guidance as a gap.

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

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

Schema coverage is 0% and the description merely restates 'project_id: The project ID.', adding no meaning beyond the schema's own title. It does not compensate for the coverage gap, though the parameter is nearly self-explanatory.

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

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

States a specific verb (Get) and resource (store/commerce settings) and enumerates the returned fields, making the scope concrete. It is distinguishable from update_commerce_settings by the verb, though it does not explicitly name the write counterpart.

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

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

No when-to-use or when-not-to-use guidance is given, and no alternatives are named. The read intent is only implied by the verb 'Get'.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without the description. The description does add that the payload is structured as header/body/footer, which is genuinely useful context, but says nothing about permissions or missing-code behavior.

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

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

Front-loaded purpose sentence followed by a compact Args block; nothing is padded or redundant. The Args section largely duplicates the schema but is brief enough not to hurt.

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?

An output schema exists, so return-value explanation is unnecessary, and annotations cover the safety profile. The description is adequate for a one-parameter read tool; only the missing sibling differentiation and any permission context hold it below a 5.

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 the schema itself carries no parameter documentation. The description's 'project_id: The project ID.' is a tautological restatement of the name and adds no format, source, or acquisition details. For a single self-evident required parameter this is minimally acceptable.

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

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

States a specific verb and resource ('Get custom code') and adds scope by naming the returned sections (header, body, footer). It does not explicitly distinguish itself from the sibling update_custom_code, though the read verb makes the split inferable.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of the sibling update_custom_code as the mutation alternative. The description is a bare definition with no routing information.

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 readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds genuine behavioral context beyond that: DNS verification and SSL activation occur automatically in the backend, and this call has no side effects on activation. Useful out-of-band behavior disclosure.

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

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

Front-loads the purpose in the first sentence and is appropriately sized. Slight redundancy: 'Read-only' duplicates the annotations, and 'does not validate or activate' partially restates the prior sentence about automatic backend verification.

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

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

No output schema exists, so the description must describe returns — it does list domain state, DNS records and check status. For a one-parameter read tool whose annotations carry the safety profile this is nearly complete, with the only gap being the undocumented project_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?

The single parameter project_id has 0% schema description coverage, and the description never mentions it or explains its format/role. With one undocumented parameter the description should compensate but does not, leaving the agent to infer that project_id scopes the lookup.

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

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

States a specific verb and resource ('Get the connected/pending custom domain') and enumerates what it returns (exact DNS records, automatic check status). The 'get' scope is clearly distinct from the sibling add_custom_domain without opening either schema.

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

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

Gives clear context for use — 'safe to call for progress' implies polling for verification progress, and it clarifies the tool does not validate or activate. However, it never names add_custom_domain as the alternative for actually adding or triggering a domain, so routing is left to inference.

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

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

The annotations already declare readOnlyHint, idempotentHint, destructiveHint, and openWorldHint, so the safety profile is covered. The description adds no behavioral context such as auth requirements, error behavior, or rate limits, despite not contradicting 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 short, front-loaded, and free of filler. The Args block is mechanical and largely mirrors the schema names, but given the 0% schema description coverage it provides minimal useful structure.

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

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

For a simple read tool with rich annotations and an output schema, the description is mostly sufficient: it names the action and all three required parameters. The main gap is the absence of guidance on when to use this tool versus list_directory_items.

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 the description must compensate for the three undocumented parameters. It lists project_id, collection_id, and item_id, but only labels them as 'The X ID,' which adds almost no meaning beyond the schema property 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 states a specific verb, resource, cardinality, and lookup key: 'Get a single directory item by ID.' This distinguishes it from siblings like list_directory_items (plural) and get_directory_collection (different 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?

There is no explicit when-to-use or when-not-to-use guidance. It does not mention alternatives such as list_directory_items or get_directory_collection, and the 'by ID' phrasing only weakly implies context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, and the description helpfully adds the required OAuth scope ('newsletter:read'), which is genuine auth context beyond the structured fields. It stops short of describing pagination or response shape, but an output schema exists to cover returns.

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 compact sentences with no filler, but the second sentence ('Use get_newsletter_schema for document, filter and field definitions') is redundant with the name and the first sentence, so it does not earn its place.

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

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

For a read-only, single-parameter discovery tool with an output schema, the description covers the main content domains and adds the auth scope. The remaining gap is the unexplained project_id argument.

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

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

The single parameter (project_id) has 0% schema description coverage, so the description must compensate — yet it never mentions project_id or what scope of project it expects. This leaves the only parameter unexplained in both schema and description.

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

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

The description names a specific verb+resource (get the newsletter schema) and enumerates the schema domains it exposes: operations, merge tags, signup fields, email document blocks, and filter/field definitions. No sibling tool serves this discovery role, so an agent can distinguish it, though the second sentence largely restates the name.

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

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

Usage is only implied ('Use get_newsletter_schema for document, filter and field definitions'), which is close to tautology and gives no when/when-not guidance or routing relative to siblings like list_newsletter_lists or list_newsletter_custom_fields. The agent can infer this is a metadata-discovery call but is not told explicitly.

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, idempotentHint, destructiveHint=false and a closed world, so the safety profile is covered. The description adds genuine behavioral context beyond that by scoping the response to metadata and explicitly excluding page content, which is the key trait an agent needs to know before calling it.

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

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

The purpose and its metadata-only scope are front-loaded in the first clause, which is exactly right. The trailing Args block is largely redundant with the schema and could be dropped, but it costs little and the total length is appropriate.

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?

An output schema exists, so return values need no prose, and the annotations fully cover the safety and idempotency profile. With only two required string params, the description's scope note plus parameter list is nearly sufficient; only ID format/source details are missing.

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

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

Schema description coverage is 0% for two required parameters, so the description must carry the load. Instead the Args block merely restates the parameter names ('The project ID.', 'The page ID.') with no format, source, or constraint information, adding essentially nothing over the schema's own titles.

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?

Clear specific verb+resource (get a single page by ID) with a useful scope qualifier: 'metadata only; no content'. This distinguishes it from a content-fetching or listing tool, but it never names the relevant siblings (list_pages, update_page, get_asset) so differentiation is left to inference.

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 'metadata only; no content' note implies when this tool is appropriate (single-entity metadata lookup rather than listing or content retrieval), but there is no explicit when-to-use, when-not-to-use, or named alternative. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, covering the entire safety profile. The description adds nothing beyond that – no note on what a project lookup requires or how it relates to site vs project scope.

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 tool line is short and front-loaded, which is good, but the trailing 'Args:' block merely repeats the schema field name with zero added information and therefore does not earn 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?

An output schema exists, so return values need not be explained, and the operation is simple with one required param. Still, for a lookup tool it omits where project_id comes from and how it relates to list_projects.

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 the description carries the burden for the single parameter, yet it only restates 'project_id: The project ID.' with no format, source, or example. The only required parameter remains effectively undocumented.

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

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

States a specific verb and resource ('Get details of a specific project/site'), which is unambiguous and distinct from the many create/update/delete siblings. However, it does not differentiate itself from the closest alternative, list_projects, or explain what 'details' means relative to that listing.

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

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

The description gives no when-to-use guidance, no prerequisites, and names no alternative. Usage is only implied by the obvious reading of the name; an agent gets no help deciding between this and list_projects.

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 readOnly=true, idempotent=true, destructive=false, so the safety profile is covered. The description adds genuinely useful context beyond that: it enumerates the return surface (data.settings, editable_fields, can_update, requires_version, ai_mutation_version) and explains that site-level schema is generated from these settings, which is non-obvious behavior.

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

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

Front-loaded with the action and its purpose, then the return contract, then the coverage list. Efficient and well-ordered; the enumerated coverage list is slightly long but each item is informative.

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

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

An output schema exists, so the return-value detail is arguably redundant but reinforces the contract. Purpose, coverage, and mutation-versioning context are all present; only the lone input parameter goes undescribed.

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 the description carries the burden for the single project_id parameter, yet it never mentions it or its format. The parameter is trivially self-explanatory, warranting minimum viable rather than penalized, but no added meaning is provided.

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

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

States a specific verb+resource ('Read Grigora's existing SEO settings') and frames it against the write path ('before making SEO/schema changes'), which cleanly distinguishes it from the sibling update_seo_settings. An agent knows exactly what this does without opening the schema.

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

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

Gives clear context: use it before making SEO/schema changes, implicitly positioning it as the read prerequisite to update_seo_settings. It stops short of naming the alternative sibling or stating exclusions, so it's strong but not exhaustive.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so safety is covered. The description adds real value beyond that: build duration expectations, a warning against rapid polling, and the meaning of the 'reply' field as the builder's summary.

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

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

Front-loaded with the status enumeration, then usage timing, then Args. Every sentence earns its place, though the Args block is slightly verbose relative to the two simple parameters.

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?

An output schema exists, so return values needn't be explained, yet the description helpfully names the 'reply' field. With parameters fully documented and usage context provided, nothing critical is missing for correct invocation.

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

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

Schema coverage is 0%, so the description carries the full parameter burden and does so well: project_id is sourced from create_website or list_projects, and build_id is optional, sourced from create_website, and defaults to the latest build. It omits only the string format of the IDs.

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

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

States a specific verb and resource ('Status of a website's AI build') and enumerates the possible return states (running, completed, failed, none). No sibling tool reports build status, so the agent can distinguish it immediately.

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

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

Explicitly says to use it 'after create_website or edit_website' and adds timing guidance ('wait a little between checks rather than polling rapidly'). It gives clear when-to-use context but no explicit when-not or named alternative, since no sibling performs this role.

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

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

The annotations already declare this as a safe, read-only, idempotent, non-destructive, non-open-world operation. The description adds scope context by specifying that assets live in the project CDN and can be filtered by folder, but it does not disclose return limits, pagination, or authentication requirements.

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 action and scope, followed by a compact Args block. Every line is useful and there is no filler.

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

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

Given the low-complexity list operation, rich annotations, and the presence of an output schema, the description is mostly complete. It covers purpose and parameters, but stops short of explaining when to choose this tool over siblings or how folder paths relate to the CDN structure.

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 the description must carry the parameter meaning. It adds the folder examples and optionality, but project_id is described only as 'The project ID,' which is nearly tautological and does not clarify format or source.

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

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

The description states a specific verb (List) and resource (assets, files and folders) in a specific scope (project CDN). It clearly distinguishes the operation from mutating siblings like delete_assets or get_asset, though it does not explicitly name or differentiate those alternatives.

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

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

There is no when-to-use guidance, no prerequisites, and no named alternatives. The description only says what the tool does, leaving the agent to infer that it should be used whenever asset enumeration is needed.

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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the full safety profile is covered structurally. The description adds nothing on top of that — no pagination, result-count, or permission context — so it earns no credit beyond restating the operation.

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

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

Front-loaded one-sentence purpose, appropriately short. The 'Args:' block is pure duplication of the schema and adds size without value, but the overall footprint is small.

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?

An output schema exists, so return values need not be explained, and annotations cover the safety profile. Still thin on where project_id comes from and whether the listing is paginated or filtered — adequate but with clear gaps for a listing 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% and the single required parameter is only restated as 'The project ID,' which is a tautology of the schema title 'Project Id'. No format, source (e.g. from list_projects), or validity constraint is given, so the description fails to compensate for the coverage 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?

Specific verb+resource: 'List all CMS post categories for a project' clearly states the operation and its scope. The verb distinguishes it from create/update/delete_cms_category and from list_cms_posts, though the description never explicitly routes between them.

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

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

No when-to-use guidance, no prerequisites, no named alternatives. The agent must infer from the name that this is the read counterpart of create_cms_category/update_cms_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?

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered structurally. The description adds only the project scoping, which is minimal; with annotations carrying the behavioral burden, a 3 is appropriate.

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 lines, front-loaded with the core action. The Args section is boilerplate and tautological, but the overall size is appropriately small for a one-parameter list 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?

An output schema exists, so return values need not be described, and the tool is simple with a single parameter. Still, for a list operation nothing indicates result volume, ordering, or filtering behavior, leaving it merely adequate.

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

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

There is one parameter (project_id) at 0% schema description coverage, and the description's 'project_id: The project ID.' merely restates the name tautologically. It adds no format, source, or constraint information, so it fails to compensate for the schema 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?

States a specific verb+resource+scope: 'List all CMS blog posts for a project.' An agent can distinguish this from get_cms_post (single post) and create_cms_post (write) by the 'list all' framing. It does not explicitly name a sibling or contrast, so it lands at 4 rather than 5.

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

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

No when-to-use guidance, no exclusions, no mention of the sibling tools it should be preferred or avoided over (e.g. get_cms_post for a single post). Nothing tells an agent the conditions under which this is the right call.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that the result set includes linked product ids, which is useful return-shape context, but says nothing about pagination or result limits for a list operation.

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

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

The core sentence is front-loaded and the docstring-style Args block is compact. Slight redundancy in restating 'status' as a filter, but no meaningful waste.

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

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

An output schema exists, so return values need not be explained. For a two-parameter read-only list tool the description is nearly sufficient, but it omits pagination/ordering behavior and says nothing useful about project_id beyond restating its name.

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 the description must carry the load. It does document both parameters, and usefully specifies the accepted 'status' values (active/draft) and that empty means all — information absent from the schema. However, 'project_id: The project ID' is circular and adds nothing.

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

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

States a specific verb (List) and resource (product collections / storefront groupings) and even clarifies the payload ('with their linked product ids'). It is distinguishable from the singular get_commerce_collection and other list_* siblings, though it does not name a sibling explicitly.

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

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

No when-to-use or when-not-to-use guidance is given, e.g. no rule for choosing this over get_commerce_collection or list_commerce_products. The 'status' filtering note is parameter-level, not usage-level context.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real behavioral context the annotations do not: results default to summaries unless 'full' is set, search matches title/slug/SKU case-insensitively, and limit is capped at 500. It does not mention pagination beyond offset or ordering, so not a 5.

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

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

The one-line purpose is front-loaded and the Args block is dense and free of filler, with each line adding distinct information. Only minor cost is that the docstring header style is slightly boilerplate.

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 an output schema present, return shape need not be explained, and the description documents every parameter plus filtering behavior. For a read-only list tool whose annotations already convey safety, nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 0%, so the description carries the full burden and does so for all 8 parameters, including allowed status/product_type values, the meaning of empty strings, the summary-vs-full distinction, and the limit default/max. This is meaningfully more than the bare schema provides.

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

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

States a specific verb (List) and resource (products in a project's store), which cleanly separates it from siblings like list_commerce_collections, list_commerce_variants, and get_commerce_product. It does not explicitly name an alternative, so it stops short of a 5.

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

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

Filter semantics are spelled out ('Empty for all'), which implies how to broaden/narrow a query, but there is no explicit when-to-use guidance versus get_commerce_product or list_commerce_variants for looking up product data. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive behavior, so the safety profile is covered. The description still earns credit for two genuinely useful behaviors beyond the annotations: stock is live, and products without options return a single synthetic variant with id "default".

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

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

The purpose sentence is front-loaded and the synthetic-variant note is high-value, but the trailing Args block is pure filler that duplicates structured schema fields. The description is not bloated overall, but one of its three sections earns nothing.

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 an output schema present and annotations covering the read-only/idempotent profile, return values and safety need not be explained, and the synthetic-variant edge case is covered. The remaining gap is the absence of any real parameter semantics for a 2-param tool, leaving the definition merely adequate.

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

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

Schema description coverage is 0%, so the description carries the full burden, yet its Args block only restates each parameter name as 'The project ID' / 'The product ID'. That is tautological and adds no format, source, or constraint information an agent could not already infer from the schema titles.

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

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

States a specific verb and resource ('List a product's options and variants') and adds scope ('with live stock'), which clearly separates it from list_commerce_products and get_commerce_product. It does not explicitly name a sibling, so it stays just short of 5.

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

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

Usage is implied: call this to enumerate variants for a given product. There is no explicit when-to-use versus when-not-to-use guidance and no routing to alternatives such as get_commerce_product, so it is only minimally viable.

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, idempotentHint=true, destructiveHint=false and closed-world, so the safety profile is fully covered. The description adds only the project scoping context, not return shape, ordering, or pagination behavior.

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

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

The opening sentence is front-loaded and efficient, but the 'Args:' block duplicates the schema without adding information, wasting roughly half the 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?

An output schema exists so return values need not be described, and there is only one parameter. Still, the description leaves an agent without any routing guidance among the many list_* siblings, which is the main gap.

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

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

Schema coverage is 0% and the single parameter is restated tautologically as 'The project ID' — no format, source, or example is added beyond the schema's own 'Project Id' title.

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

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

States a specific verb+resource ('List all directory collections') and scopes it to a project. It does not explicitly distinguish itself from near siblings like list_directory_items or list_directory_fields, but the resource is unambiguous.

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

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

No when-to-use guidance, no mention of alternatives, no prerequisites or pagination caveats. The read-only list intent is only implied by the verb 'List'.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds nothing beyond that: no pagination behavior, no scoping to a specific collection version, no auth context. It restates the operation the annotations already qualify.

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 one-line purpose is front-loaded and appropriately short. However, the appended Args block is redundant boilerplate that restates parameter names without adding value, so the entry is not waste-free.

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?

An output schema exists, so return values need not be explained. For a simple read-only list tool this is minimally adequate, but it leaves pagination, ordering, and the relationship between collection and fields unaddressed.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it does not. The Args section is pure tautology — 'project_id: The project ID' and 'collection_id: The collection ID' add no format, source, or relationship information beyond the property names themselves.

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

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

States a specific verb+resource: 'List all fields for a directory collection.' An agent can distinguish this from sibling list_directory_collections and list_directory_items based on the resource named. No explicit sibling differentiation, so not a 5.

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

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

No guidance on when to use this versus list_directory_collections, list_directory_items, or get_directory_item. No prerequisites, no exclusions. The description only says what it does, not when to reach for it.

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive, so the description gets no credit for the safety profile. It adds nothing beyond that: no pagination behavior, no result ordering, and no indication of what a 'collection' item listing contains, even though those are the traits an agent would care about for a list operation.

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

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

The first sentence is front-loaded and efficient, but the Args section is redundant filler that repeats structured data already present in the schema. It is appropriately short overall, but not every line 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?