Mondovo

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

Annotations only declare the generic profile (not read-only, non-idempotent, non-destructive, open-world). The description adds the behavior that matters: items save as DRAFT and stay hidden by default, and a published item is pushed to the public site via collection auto-publish, so the public change should be confirmed first. Those are non-obvious side effects that go well beyond the annotation set.

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

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

Front-loads the core action and the draft default, then layers warnings and alternatives. Every sentence carries actionable weight (defaults, publish consequence, SEO rationale, two sibling redirects) with no restatement of the tool name or filler.

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

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

For an 8-parameter mutation tool with nested `seo` and full schema coverage, the description covers defaults, publish side effects, and sibling routing. It says nothing about what a successful call returns (e.g. the new item identifier) or how to follow up with update_collection_item, which would close the loop on a create-then-edit workflow.

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

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

Schema coverage is 100%, so the baseline is 3; the description rises above it by explaining why `seo` matters here at all — it carries the item page's own title/meta/keywords/JSON-LD, and notably update_page_seo cannot reach item pages. That cross-tool constraint is unavailable in the schema. It does not add anything about `fields` keying or `slug` derivation, which the schema already covers.

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

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

States a specific verb and resource ('Add ONE item to an existing collection') and immediately grounds it with concrete examples (blog post, dish, product, listing). It explicitly distinguishes itself from both create_collection and add_collection_items, so an agent can pick it without opening a sibling 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?

Explicit routing is given for both alternatives: 'Does not create the collection — use create_collection for that' and 'For several items at once use add_collection_items.' It also states the condition for the risky path ('Set status "published" only when the user explicitly asked for it'), which is exactly the kind of when-to-use guidance the schema cannot express.

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

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

Annotations only flag it as a non-idempotent, open-world, non-destructive write. The description adds substantive behavior: items are hidden from visitors unless published, published items are pushed live by collection auto-publish, and saves are per-item so a single bad item does not abort the batch. It even characterizes the result (the list of failures) despite there being no output schema.

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

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

Four dense sentences with the default behavior, the risky deviation, the safety precondition, and the failure model — each earning its place, with the safe default front-loaded ahead of the publishing caveat.

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

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

For a 5-parameter batch write with no output schema, the description covers everything an agent needs: input source, default vs. published outcome, the confirmation gate for public changes, partial-failure semantics, and what the response reports. Nothing material is left to inference.

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

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

Schema description coverage is 100%, so the schema already documents site_id, collection_type, status, items and user_goal. The description's notes on status defaulting and the draft origin of items largely restate the schema's own descriptions, adding little that is not already structured. Baseline 3 is appropriate.

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

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

States a specific verb ('Save'), resource ('items into one existing collection'), and a concrete scope ('up to 50 items ... in a single step'). It also positions itself against the closest siblings: it consumes the output of draft_collection_items and is the batch counterpart to the single-item add. An agent can distinguish it without opening the schema.

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

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

Gives explicit when/when-not: drafts are the default and stay hidden; "status to 'published' only after the user explicitly asks for it," plus a requirement to confirm the public change before calling. It also names the upstream source of inputs (drafts from draft_collection_items that the user kept).

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

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

Goes well beyond the destructiveHint=true and idempotentHint=false annotations: it warns that removing A/B variants discards their path steps and that adding a terminal step can stop downstream paths, and that a confirmation must be reviewed. It also discloses channel prerequisites for SMS, which the 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?

Front-loaded with the core action and anchor requirement, then positioning rules, then step types, then warnings. Dense but every sentence carries information; the step-type enumeration partially duplicates the enum and is the only marginally wasteful piece.

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 30-parameter destructive mutation with no output schema, it covers the workflow dependency (get_journey anchor), positioning modes, channel prerequisites and path-loss risk. It does not hint at which parameters are required per step_type, which is the main remaining gap for such a wide conditional schema.

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

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

Schema coverage is 90%, so the baseline is 3, but the description adds real meaning the schema lacks — the semantics of the position enum values and the shared-continuation rule after a split. It also enumerates the step types supported, though that largely restates the step_type enum.

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 ("Insert a step into a journey") and scopes the anchor requirement to ids from get_journey. The list of supported step types makes it immediately distinguishable from update_journey_step, move_journey_step and remove_journey_step.

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

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

Gives concrete insertion semantics (position defaults to after; before inserts before the anchor; path_start targets a named split path) and the post-split rule about inserting into the shared continuation. It also lists preconditions for SMS (verified sender, billing, consent). It never explicitly contrasts with update_journey_step or move_journey_step, so no explicit exclusion guidance.

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

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

Annotations only cover the safety profile (not read-only, non-destructive, not idempotent, closed-world); the description adds a real behavioral rule not present anywhere else: duplicate audiences already in the strategy are refused. It also signals a propose-then-approve workflow. It stops short of saying what is returned or where the audience lands in the strategy, 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?

Three tight sentences: what it does, when to use it, what it is not, plus the refusal rule. Front-loaded with the action and no filler or repetition of the title.

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

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

With no output schema, an agent still knows the inputs, the trigger, the sibling alternative, and the duplicate-refusal edge case. The only gap is what the call returns or where the new audience appears afterward, which is minor for a simple create tool.

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

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

Schema coverage is 100%, so name, jobs_to_be_done, vocabulary and site_id are already fully documented in the schema. The description restates the same field meanings at a high level without adding format, ordering, or limit guidance beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('Add ONE new audience (a marketing persona) to the site's strategy') and enumerates the concepts the audience consists of. It is immediately distinguishable from create_contact_segment and from strategy/idea tools like seed_marketing_strategy or update_marketing_idea.

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 trigger ('Use it when the owner wants to reach a new kind of customer'), explicit exclusion with a named alternative ('It is not a contact list or segment — for those use create_contact_segment'), and an interaction instruction ('propose the fields and let them approve'). Nothing is left to inference.

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

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

Annotations only supply readOnly=false, destructive=false, idempotent=false, openWorld=true; the description goes far beyond, disclosing credit consumption, a server-side job with a polling protocol (~10s, ~45-90s), that refusals write NOTHING, that the page isn't live until publish_site, version-history recording with `history_warning`, and the site_id/build_transition handoff on multi-design sites. Nothing contradicts 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 purpose and mode split are front-loaded and each bullet maps to a decision the agent actually makes. It is nonetheless long (~400 words) for a single tool, and a few clauses (the TSX authoring contract recap, reading read_design for imports) could be condensed or deferred.

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 14-parameter mutation tool with nested objects and no output schema, the description covers prerequisites, async job lifecycle, return shape (slug, file, content key, how_to_edit, version), failure semantics, and the multi-design edge case. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so 3 is the baseline, but the description adds real semantics the schema can't: `code` presence toggles the whole mode, `content` must use NEW top-level keys named page_<slug> and is read as content.page_marketing, `seo.title` defaults to "<name> | <site name>", and `variation_id` selection rules. That is well above what the structured fields convey.

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

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

The description opens with a precise verb+resource+scope ("Add ONE new inner page to an existing site that already has a design") and immediately splits behavior into two named modes. It also names the sibling tools it is not (update_variation_file, patch_variation_content, create_page_draft), so an agent can pick it apart from them without opening a schema.

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

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

It states the prerequisite (create_site / create_site_from_design first), the condition that selects each mode (pass `code` or not), and explicit exclusions — use update_variation_file/patch_variation_content to change an existing page, create_page_draft to try an alternative version. It even handles the ambiguous multi-design case with the `choose_design` fallback.

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 give generic flags; the description supplies the real behavior an agent needs: returns a `job_id` immediately, poll `get_job` every ~10s, bounded parallelism makes 10 pages take minutes, and a 'completed' job can still carry per-page failures in a `failed` array. It also discloses the non-obvious side effect that building can migrate the working site to a new `site_id` with a `build_transition` message to relay.

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?

It is front-loaded with purpose and batching before the edge cases, and nearly every sentence carries operational information. It is dense and slightly rambling in the design-transition paragraph, but that reflects genuine conditional complexity rather than 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?

There is no output schema, so the description carries return-value burden and does so: `job_id`, polling target and cadence, `failed` array, `site_id`/`build_transition` on unbuilt sites, and `choose_design` on ambiguous design. The menu-linking caveat closes the main remaining ambiguity.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema for `variation_id`: what happens when it is omitted, that Mondovo reuses the already-built or only-edited design, and that it otherwise returns `choose_design` so the agent must ask the user. It also clarifies the batch limit and per-page structure contextually.

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

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

The opening sentence states a specific verb and resource with scope ('Add multiple inner pages to an existing site in one call (up to 10)') and immediately distinguishes the batch case from the single-page sibling. An agent can tell what it does without reading 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?

It names explicit alternatives and the conditions that select them: use add_page per page when you need `nav_placement`, use patch_variation_content `navigation` to link pages, and pass `variation_id` only on a site that still holds several designs. The prerequisite ('The site must already have a design') is stated up front.

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

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

Goes well beyond the annotations: it discloses the 1,000-per-call cap, that re-adding an address replaces its destination (consistent with idempotentHint=true), and the propagation behaviour — live within a minute or two on a published site, otherwise applied at publish. That timing and overwrite semantics are exactly the kind of context 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?

The purpose is front-loaded and every sentence carries information — field semantics, limits, replacement rule, propagation timing. It is dense but not padded; a bulleted or line-broken layout for the per-field rules would have made it marginally easier to scan.

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

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

For a mutating bulk tool with annotations covering the safety profile, the description covers limits, defaults, overwrite behaviour and propagation. It does not say what happens on partial failure (e.g. one invalid entry among many) or whether the created redirects are returned, which matters for a 1,000-item batch.

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

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

Schema coverage is 67% and the nested `from`/`to`/`status` properties carry no descriptions at all, so the description does the heavy lifting: `from` accepts a full old URL and preserves an identifying query string, `to` may be a local path or an external URL, and 301 is the default with 302/307/308 as alternatives. That adds real meaning the schema cannot express (the default is not encoded anywhere).

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

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

The opening sentence states a specific verb+resource outcome ("Send old addresses to new pages so links ... keep working") and the body makes clear this is a bulk-add operation (up to 1,000 per call). It does not explicitly name the near neighbours it must be distinguished from (update_redirect, remove_redirects, map_old_site_links), so an agent still has to infer the split from 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 implied by the framing ("send old addresses to new pages") and one parameter-level rule is given ("use 301 unless the user asks otherwise"). There is no explicit statement of when to prefer this over update_redirect for an existing mapping, or how it relates to map_old_site_links.

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

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

Annotations are sparse (non-readonly, non-idempotent, non-destructive), and the description adds substantial context: media is processed in the background with content and usable-stretch analysis, the operation is FREE, up to 40 files per film, and files should be added before storyboarding. It also explains the returned media[].id for later pinning, which is not in the schema.

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

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

The description is long but front-loads the core action and cost, then layers workflow guidance in a logical order. Most sentences carry distinct operational value, though a couple of clauses could be tightened without loss.

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

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

Given no output schema and minimal annotations, the description covers the critical unknown: what happens after adding (background analysis and usable-stretch detection), how to use the returned ids, file limits, ordering advice, and the sibling alternative. An agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining that asset_ids come from list_brand_assets/upload_brand_asset and their order matters, and that project_id comes from create_motion_project. It does not mention the optional user_goal parameter, keeping it just shy of 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 precise verb and resource — putting brand Library files onto a film as its own media — and distinguishes itself from siblings like create_motion_project `from`, edit_studio_video_storyboard, and studio_video_message by naming when each is appropriate. The analogy to the Video tool's "Your media" makes the effect concrete.

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

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

Explicitly tells the agent where to get asset ids (list_brand_assets / upload_brand_asset), when to add media (before describing the film), how to direct usage (studio_video_message or edit_studio_video_storyboard place_media/insert_media_scene), and when to use a sibling instead (create_motion_project `from`). No inference 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 cover idempotency and non-destructiveness, but the description adds the material economics and behavior: credits are spent, each slide is billed individually at ~1 minute, failed slides are refunded in full, and a repeated idempotency_key never double-charges. It also explains that a character is drawn once, reused per slide, and persisted to the brand's characters — none of which is in the annotations.

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

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

Front-loaded with the highest-stakes fact ('SPENDS CREDITS') and organized as approval → character → cost/timing → polling → posting. It is a single dense paragraph, though, and the character paragraph could be split for faster scanning.

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 credit-spending, nested-parameter mutation with no output schema, the description supplies the full lifecycle: prerequisite preview, approval contract, character fallback logic, billing/refund behavior, polling tool, and the publish handoff. Nothing an agent needs to call this safely is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-call meaning the schema cannot: `slides` must match the quoted motions, `expected_credit_cost` must equal the quoted `credits`, and `idempotency_key` must be stable per approval. The `character` sub-fields are also tied to a source (`saved_characters` in the plan answer) that the schema only gestures at.

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 ('Start the animated carousel the owner approved') and immediately distinguishes itself from preview_carousel_animation, which must run first, and from get_carousel_animation, which polls results. An agent can route between these siblings from the description 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?

Explicit sequencing ('call preview_carousel_animation FIRST'), an approval precondition, an explicit follow-up ('Poll get_carousel_animation for the clips'), and a downstream route ('To post: attach_visual_to_post with the carousel job_id'). When-to-use and what-comes-next are both stated, not implied.

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

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

Annotations declare a non-destructive, idempotent write, and the description adds genuinely non-obvious behavior on top: that the answer can be recorded on a design before the site is built and is only applied at build time. It also discloses the `whatsapp_number_needed` return signal and the phone-number fallback, which the agent could not otherwise anticipate.

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

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

Front-loaded with the core action, then progressively drills into per-value edge cases; nearly every clause carries information. It is dense and reads as one long paragraph rather than separated guidance, which slightly hurts scanability.

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

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

For a 6-parameter mutating tool with no output schema, the description covers the deferred-application model, the conditional parameter rules, and the escalation path when a number is missing. Only the response shape and the optional `user_goal` field are left unaddressed.

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

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

Schema coverage is 100%, so the baseline is 3; the description still earns above baseline by explaining conditional parameter coupling — `phone` only matters with payment_account + whatsapp and defaults to the site's number, and `value`'s provider-id meaning triggers a subsequent key collection. It does not cover the optional `user_goal` parameter at all.

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

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

Names a specific verb and object ("Apply the owner's answer to one of the setup questions in `site_setup.ask`") and enumerates the three question domains the tool handles. It also implicitly separates itself from sibling mutators like configure_payments and set_store_currency by naming them as follow-on steps.

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?

Makes clear the input must come from the pending questions in `site_setup.ask` / `store_setup.ask` and routes the agent onward to configure_payments once a provider id is chosen. It stops short of explicit when-not guidance (e.g. for the currency path, where the sibling set_store_currency overlaps).

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 a non-read-only, non-destructive, non-idempotent mutation, and the description adds real context beyond them: the redraw is free, regenerated from accumulated notes, and pricing/buying happens later. It does not state what happens after approval (next pipeline stage) or that a repeated notes call redraws again, but the safety and cost profile is well covered.

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

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

A single tight paragraph that front-loads the trigger condition, then the user action, then the two response branches, then the cost note. Every clause carries information the agent needs; 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?

For a 4-param approval tool with no output schema, the definition covers trigger, user-facing step (show the picture), the two possible responses, the redraw consequence, and the cost framing. 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 100%, so all four parameters are already documented in the schema. The description reinforces the `approved` vs `notes` semantics and the cumulative-redraw meaning of notes, which is a small value-add, but it never mentions `user_goal` or the `project_id` format — baseline 3 is appropriate when the schema carries the load.

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

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

States a specific action (approve or send notes to redraw) on a specific resource (the film's look sheet) and anchors it to the `look_sheet.approved: false` signal from get_studio_video. An agent can distinguish this from approve_studio_video_plan or edit_studio_video_storyboard without opening either schema.

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

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

Explicitly names the triggering condition (get_studio_video shows look_sheet with approved: false) and the two branches: `approved: true` when it is right, `notes` when it needs redrawing. It also clarifies the redraw path reuses everything said so far, so the agent knows repeat notes calls are cumulative rather than a fresh start.

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

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

Goes well beyond the annotations by disclosing the credit spend, the free stand-in that plays until a commissioned clip arrives, the price-mismatch refusal with no charge, idempotency-key reuse to avoid double billing, version-history recording, and that publishing is required for visitors to see the result. These are exactly the side effects an agent needs before a mutating, credit-consuming call.

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

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

A single dense paragraph that front-loads the pattern taxonomy before the cost/precondition rules, with no filler sentences. The heavy use of capitalization and em-dashes makes it slightly harder to scan than a short bulleted structure would be.

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 18-parameter mutation with no output schema, the description covers the cost model, idempotency, the plan-then-apply workflow, and the publish step — enough to call it safely. It stops short of describing what the tool returns or how to verify success beyond 'recorded in version history'.

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 89%, so the baseline is 3; the description adds real meaning on top by linking expected_credit_cost to plan_hero_pattern, framing idempotency_key as retry-safety, and clarifying which video_source values are free versus paid. Minor gap: chapters vs chapter_title/eyebrow/subtitle mutual exclusivity is only implied by the schema field notes, not stated here.

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?

Opens with a specific verb+object ('Replace a design's hero section with a cinematic pattern') and then defines each of the four enum values in behavioral terms (scroll-driven, cursor-driven, pan/zoom, particles). This makes the tool unambiguously distinct from the sibling plan_hero_pattern, which only plans.

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

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

Explicitly states the prerequisite ('Call plan_hero_pattern first') and the cost/refusal contract (send expected_credit_cost, mismatch is refused with nothing charged). It explains which sources are free vs credit-spending, but never states when NOT to use this tool (e.g. theme-level changes belong to apply_theme or variation work to patch_variation_content).

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

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

Annotations already cover the write/idempotent/non-destructive/closed-world profile. The description adds genuinely new behavior: no credit cost ('Free'), changes are recorded in version history (hence recoverable), URLs must echo prior results, and the change is invisible publicly until published. It does not say what happens if a URL is rejected or what the response contains, keeping it below a 5.

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

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

Very short and front-loaded: the core action and its inputs come first, constraints follow. The telegraphic fragments ('Free.', 'Recorded in version history.') carry real information rather than padding, though the staccato style slightly costs readability.

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

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

For a mutation tool with full annotation coverage and no output schema, this covers the essentials: valid input sources, cost, reversibility via version history, and the publish requirement. Not fully complete because it omits failure behavior for invalid URLs and what the caller receives on success.

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

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

Schema coverage is 100%, so site_id, variation_id, user_goal and the replacements fields are already documented. The description only reinforces one nested field (concept_library_id) and the notion that original_url/new_url must be echoed from earlier results — useful but marginal over the schema, so the baseline 3 applies.

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

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

States a specific verb and resource — replace images on a design with user-chosen ones — and immediately disambiguates itself from the candidate-producing siblings (regenerate_images, explore_image_concepts). An agent knows this is the 'commit the choice' step, not the generation step.

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

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

Explicitly names the two upstream tools that produce valid input and the exact flag needed (apply: false, send concept_library_id), plus the condition that publishing is required for visitors to see the change. Missing only an explicit statement of when *not* to call (e.g. before any candidates exist), which is implied by the provenance rule.

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

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

Annotations already declare this is a non-destructive, idempotent write, so safety is covered. The description adds genuinely non-structural behavior: changes are partial by default and are not visible to visitors until the site is published. It does not discuss auth, rate limits, or whether a preset wipes prior custom values, which keeps it short of a 5.

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

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

Four tight sentences, front-loaded with the scope-defining clause in capitals, then the partial-update rule, the sibling exclusion, and the publish consequence. Nothing is redundant or padded.

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

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

For a 7-param nested write tool with no output schema, the description covers scope, partial-update semantics, the routing alternative, and the publish dependency. It omits what the tool returns and whether a preset overrides explicit colors/fonts sent in the same call, a real ambiguity but a minor one.

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

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

Schema description coverage is 100%, so both the field-level docs and the enum values are already spelled out, including that colors is partial and preset replaces everything. The description's 'send only what should change' and 'complete ready-made preset' largely restate that, adding little new syntax or format guidance. Baseline 3 is appropriate.

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

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

States a specific verb ('Change the look') with explicit scope ('across EVERY page of one design at once') and enumerates the dimensions affected: colours, fonts, corner radius, or a preset. It names the sibling it must not be confused with (refine_site), so an agent can pick correctly without inspecting schemas.

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

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

Explicitly routes the agent: use this for site-wide design changes, use refine_site for a single section or page. Adds a partial-update instruction ('Send only what should change') and a required follow-up ('Publish for visitors to see it'), leaving no ambiguity about when and how to use it.

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

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

Annotations already flag destructive=true and idempotent=false, but the description adds behavior those hints cannot express: Google is re-read before writing and a changed value yields `stale` with nothing written, plus a full outcome taxonomy including the deferred `pending_google_review` and the explicitly non-retryable `unknown`. That is real operational context, not a restatement of hints.

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

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

Front-loaded with the action, then the staleness guard, then the reporting contract; every sentence carries information. It is a single dense block with heavy backtick enumeration, which slightly hurts scanability but not content economy.

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

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

There is no output schema, so the description must carry the return contract, and it does by defining all five result states and the correct reaction to each. Combined with the prerequisite and the pre-write re-read, an agent has everything needed to invoke and interpret this destructive, non-idempotent 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 50%: site_id and user_goal are documented in the schema, while approval_id and payload_hash are bare. The description compensates by stating both come from prepare_google_change, giving the agent their provenance, but it never explains what payload_hash must match (a hash of the staged payload) or what happens if the pair is mismatched.

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 ('Apply exactly the staged change the owner approved') and ties it to the producing sibling 'prepare_google_change'. An agent can distinguish it from prepare_google_change, discard_google_change and get_google_business_status without opening any schema.

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

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

The prerequisite is explicit: approval_id and payload_hash must come from prepare_google_change, so the agent knows this cannot be called cold. It also gives per-outcome follow-up guidance ('unknown ... ask them to check the listing, do not retry'), though it never names discard_google_change as the alternative when the change should not be applied.

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

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

Annotations already flag this as non-read-only, open-world, non-idempotent, and destructive. The description adds valuable context beyond annotations: the reply is public, immediate, tied to the connected account, limited to one lead, and consumes the workspace's monthly X posts. It does not cover failure modes or whether a posted reply can be deleted.

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 scope are front-loaded in the first sentence. The remaining sentences add permissions, single-lead constraints, parameter guidance, and quota impact without unnecessary 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 public, destructive, open-world mutation, the definition covers authorization, scope, account context, and quota consumption. It stops short of explaining failure behavior or whether the posted reply can be edited or removed, but the safety-critical context is largely present.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters, including lead_id and brand_id sources. The description reinforces that text is for user-edited drafts and is capped at 280 characters, but adds little beyond the schema and says nothing about user_goal.

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

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

The description states a specific verb and resource: it POSTS a public reply on X under the connected account to ONE lead sourced from list_reply_leads. This clearly distinguishes it from sibling tools such as queue_post_for_publishing, update_social_post, or dismiss_reply_leads.

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

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

It gives explicit conditions: only after the user has read the lead and reply and said yes, never for several leads on one go-ahead, and never on the agent's own judgement. The prerequisite source tool and the single-lead scope are also named.

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

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

Goes well past the annotations: it discloses that approval spends Creative Credits against a daily cap, that a mismatched expected_credit_cost is refused, that free versus priced items differ, and that on request_failed the charge is refunded and the plan remains pending. That refund-and-retry detail is essential given idempotentHint=false, since it tells the agent a retry is safe.

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 the credit-safety warning are front-loaded, and every sentence carries operational information rather than filler. It is dense and a few clauses run long (the pack/shots sentence stacks three rules), but nothing is redundant.

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

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

For a 6-parameter, non-idempotent, credit-spending mutation with no output schema, the description covers the inputs, the failure contract, the refund guarantee, and the required next poll. An agent could call this correctly and recover from errors using the description alone.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds cross-parameter rules the schema cannot express: expected_credit_cost must equal pending_plan.quoted_credits or the call is refused, resolution must come from alternatives and changes which credit figure to send, and shots requires summing the chosen shots' credits and omitting unchosen ones.

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 ("Approve the plan") and immediately stakes out exclusive scope with "the only step that makes anything," which distinguishes it from the drafting siblings like plan_video, edit_studio_video_storyboard and get_studio_video. An agent knows exactly what this call does and what it does not.

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

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

Gives explicit preconditions ("NEVER approve one without the user's explicit go-ahead on that price"), names the alternative path ("resolution picks one of pending_plan.alternatives — then send that alternative's credits"), covers the partial-approval case via shots, and prescribes the follow-up ("Afterwards poll get_studio_video until ready"). 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=false, destructiveHint=false and idempotentHint=true, so the safety profile is covered. The description adds real value beyond that with the precondition that the customer must already exist as a contact, though it omits failure behavior and whether the operation can be undone.

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 only two sentences long. The inline visibility gloss is somewhat redundant with the enum descriptions and slightly bloats the sentence, but nothing is wasted overall.

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

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

For a 6-parameter mutation with no output schema, the description covers purpose and one precondition but leaves gaps: no precedence rule when both owner_email and owner_contact_id are supplied, and no statement of what is returned or how a bad contact id surfaces.

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

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

Schema coverage is 100%, so baseline is 3. The description does add one nuance the schema does not state plainly – that owner assignment and visibility setting are independent and combinable ("and/or") – but the visibility enum meanings it spells out are verbatim duplicates of the schema 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?

States a specific verb and resource ("Assign a collection record") plus the two effects it has: ownership and visibility. It is distinguishable from neighbors like update_collection_item, but it never names an alternative, so the agent has to infer the boundary itself.

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 prerequisite "The customer must already be a contact on this site" is a genuine usage constraint. However, there is no guidance on when to choose this over update_collection_item or set_collection_item_display, nor on what to do when the contact does not yet exist.

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 destructiveHint=true annotation is backed up with concrete semantics: the call REPLACES the post's existing media, and the already-set cover is kept unless keep_cover: false is passed. It also discloses the cost profile ("Free") and that media is attached "exactly as it is" (no reprocessing), which goes meaningfully beyond the annotations.

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

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

Front-loaded with the core action and accepted media shapes, then alternatives, then the cover caveat. Every clause carries information an agent needs; even the terse "Free." earns its place as a cost signal.

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

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

For a 5-parameter mutation tool with no output schema, everything needed to call it correctly is present: id provenance, cardinality limits, ordering, replacement/destructive semantics, cover behavior, cost, and sibling routing. Nothing material is left to inference.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description still adds derivable meaning: asset_ids order maps to carousel slide order, keep_cover's default-keep/clear-on-false behavior, and the provenance rule tying ids to list_brand_assets or list_creations. These are the two parameters most likely to be misused, and the description disambiguates both.

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 ("Attach the owner's OWN media from the brand Library to a planned post") and enumerates the exact accepted shapes: one picture, up to 10 as a carousel in order, or one video. It explicitly distinguishes itself from the two nearest siblings, attach_video_to_post and attach_visual_to_post, so an agent can route correctly without opening any schema.

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

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

Gives explicit when-not guidance by naming alternatives and the condition that selects them ("For a Video Studio film use attach_video_to_post; for a just-generated visual, attach_visual_to_post"). It also tells the agent where the ids must come from (list_brand_assets for uploads, list_creations for finished creations), closing the main pre-call question.

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

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

Adds substantial behavior beyond the annotations: media replacement, cover picture retention with keep_cover: false clearing it, that the old clip's cover moment is cleared, the pending outcome for in-progress films, the 80 MB / MP4-WebM-MOV constraint, and that url videos are stored in the Library first. It matches destructiveHint=true rather than contradicting it. Missing only what the response actually returns beyond the pending 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-loads the action and the exactly-one-of rule, then walks through the three sources in order. Dense but well organized; the bare 'Free.' at the end is terse and the parenthetical cross-references make it a bit heavy, yet nothing is filler.

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

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

For a 7-parameter destructive mutation with no output schema and open-world behavior, the description covers inputs, side effects, cover handling and one failure mode. It never describes the success response shape, so an agent still doesn't know what a successful attach returns — a minor but real gap.

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

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

Schema coverage is 100%, so the baseline is 3, but the description contributes real value the schema lacks: the mutual-exclusivity constraint across the three source parameters, the pending/retry semantics of project_id, and that asset_id refers to the owner's own Library video attached as-is. It doesn't explain the user_goal parameter or brand_id/post_id sourcing beyond what the schema already says.

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?

Opens with a specific verb+resource+effect: 'Attach a video to a planned post, replacing its media.' It clearly contrasts itself with create_motion_project for unchanged clips. However, it never names the near-identical sibling attach_library_media_to_post, so an agent comparing the two must still open both schemas to tell them apart.

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 routing rule — 'Send exactly one of' — followed by the condition for each of project_id, asset_id and video_url, including when to prepare a film first and what to expect while it is pending. It also states a negative rule: publish unchanged clips via asset_id/video_url, 'not create_motion_project'.

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

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

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), and the description adds real value on top: carousels attach all slides at once, and the operation is 'Free' (no credit cost). It doesn't say whether an attached visual replaces an existing one, which is the main remaining behavioral unknown.

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

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

Three short sentences, front-loaded with the action and its prerequisite chain, with the carousel and cost facts compactly appended. Nothing is redundant with the name or title.

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 no-output-schema mutation with full annotation coverage and 100% schema descriptions, the description supplies the workflow context an agent needs: where job_id and post_id come from, the completion gate, and the carousel/cost behavior.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds a meaningful constraint beyond the schema: the job_id must be one that get_job reports as completed, not merely created. The user_goal parameter is left entirely to the schema.

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

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

Specific verb and resource ('Put a finished visual ... on a planned post'), and the provenance chain (job_id from create_visual, post from get_calendar) implicitly separates it from sibling attach tools like attach_library_media_to_post and attach_video_to_post. It does not name a sibling explicitly, 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 a clear precondition gate: the job must be finished, confirmed via get_job, and the post must be an existing one from get_calendar. It does not state when NOT to use this (e.g. drafts vs scheduled posts, or what to do if the post already has a visual), so no explicit exclusions.

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

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

The description adds useful behavior beyond the annotations: `schedule` confirms immediately unless `confirm` is false, and `dismiss` closes the request without booking. The annotations already establish that this is a non-destructive mutation, so the description does not need to repeat safety details. It does not cover permissions, reversibility, or what happens if the chosen slot is unavailable.

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 a single compact sentence that front-loads the target audience and then gives the two possible actions. Every clause carries information about when to use the tool, the date/time format, confirmation behavior, or dismissal semantics. It has no redundant explanatory 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 moderate-complexity appointment mutation, the description supplies the request source, action meanings, date/time expectations, and confirmation behavior. The schema and annotations cover required identifiers, safety profile, and most parameter descriptions. Remaining gaps include return behavior and what happens if the requested slot is unavailable, but the definition is sufficient for correct tool selection and basic invocation.

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

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

The description adds meaning for the key action parameters by linking `schedule` to `date` and `time`, and by explaining the effect of `confirm`. It clarifies that the date/time are the owner's chosen values and that time uses the business clock. It does not add much for `notes`, but the schema already documents most other parameters.

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

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

The description states a specific verb and resource: it books a callback request at a chosen date/time or dismisses the request. It anchors the tool to the `list_appointments` view `needs_time`, clearly separating it from appointment listing. It does not explicitly distinguish itself from related appointment siblings such as `update_appointment` or `manage_appointments`.

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

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

It gives a clear usage context: only for requests waiting under `needs_time` in `list_appointments`. It explains that `schedule` books and `dismiss` closes without booking. It lacks explicit exclusions or guidance on choosing between this tool and related appointment-management siblings.

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

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

Annotations already cover safety, and the description adds important context: nothing goes live and no build starts, one AI call per page, batches take minutes, and the call counts toward the hourly AI limit. It also discloses skip reasons and the multi-design complication where a new site_id and build_transition appear and must be relayed, which is behavior an agent could not infer.

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

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

Purpose and the 10-per-call limit come first, then skip behavior, then side effects, and then the multi-design case. It is dense and long, but nearly every sentence carries operational information. The all-caps multi-design paragraph is heavy, yet it is justified by the complexity.

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

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

The definition covers side effects, rate limits, latency, skip and duplicate handling, response contents, and the site-rebuild transition with its site_id change. Together with a 100%-documented schema, an agent has everything needed to call it and handle the response.

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

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

Schema coverage is 100%, so the baseline would be 3. The description still adds meaning beyond the schema, including how combos map to pages and the fallback rules for variation_id ('uses the design already built or the only one edited, otherwise answers choose_design'), though it does not clarify target_keyword or cell_key beyond the schema.

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

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

States a specific verb and resource: 'have our AI write one local SEO page per service × location pair ... and save them as DRAFT pages', with a concrete example. This clearly separates it from siblings like add_page, add_pages, and generate_alternative_pages.

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 batch rule ('at most 10 per call; for more, call again with the next pairs'), explicit dedupe behavior ('pages that already exist are skipped, so a repeat never duplicates'), and explicit guidance for variation_id, including the fallback that returns choose_design so the agent can ask the user.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds valuable specifics: it explains exactly what is destroyed (queued sends not yet gone out), what is preserved (published posts), and that the post remains on the calendar and can be re-queued. This goes beyond the annotations without contradicting them.

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

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

Three tight sentences, front-loaded with the core action, followed by consequences for published posts and the post's reusability. Every sentence earns its place with no waste.

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

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

For a destructive mutation with full schema coverage and clear annotations, the description provides enough context: it states the action, the scope of cancellation, and the reversibility. No output schema exists, and the description does not need to explain return values.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the input schema. The description does not add any additional parameter meaning or usage nuance beyond what the schema provides.

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

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

The description uses a specific verb ('take back out') and resource ('publishing queue'), and clarifies scope by distinguishing queued sends from already-published posts. It does not name a sibling alternative explicitly, so it stays just below the top mark.

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

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

The description implies when to use it ('cancelling every send that has not gone out') and notes that published posts are unaffected, but it does not explicitly name alternatives such as reschedule_social_post or delete_published_post, nor does it state when not to use it.

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

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

Adds context beyond annotations: ~30-40 second cost, the caching behavior that a previously rendered design returns at once, and the `force: true` escape hatch after an edit. That latency and caching model is precisely what an agent needs to decide whether to call it now or wait.

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

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

Three sentences, front-loaded with the action, then cost, then routing guidance. No filler and no repeated title/schema content.

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

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

For a 5-param mutation-like render tool with no output schema, the description covers what is produced (an attached screenshot), how long it takes, when the result is instant, and how to force a refresh. No important gap remains 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 100%, so the schema already documents force, index, viewport and site_id. The description only reiterates the force-after-edit and default-index behaviors, adding marginal meaning rather than new syntax or constraints.

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

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

States a specific verb and resource ("Render one design variation ... and attach its screenshot") plus a scope qualifier ("one", "NOW"). It is unmistakable against siblings like generate_design_variation (creates variations) and get_render_diagnostics (read-only diagnostics).

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

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

Gives explicit when-to-use triggers: after importing or editing a design, before showing it to anyone, or when list_variations says thumbnails are pending and get_render_diagnostics has no screenshot. It also names the alternative behavior it replaces ("use this instead of waiting").

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 destructiveHint=false, so the safety profile is covered; the description still adds genuinely new behavior: volumes are cached for 30 days and force_refresh re-measures, and the result flags zero-demand keywords and names a better keyword from the page's suggestions. It does not mention cost/quota implications of a forced refresh, which would have pushed this to 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?

Three tight sentences, front-loaded with the core measurement and followed by the flagging behavior and the cache/refresh caveat. 'Changes no page' slightly restates readOnlyHint but works as a one-clause reassurance; no filler otherwise.

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

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

With no output schema, the description carries the burden of explaining returns, and it does so at a conceptual level (per-page demand, a 'none' flag, a suggested better keyword). It stops short of describing result shape or what happens for pages with no keyword at all, a minor gap for a 4-parameter read tool.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real semantics: `keywords` are *extra* terms measured on top of each page's primary keyword (a distinction the schema's 'candidates you are weighing' only partly conveys), site_id determines the country whose Google volumes are used, and force_refresh is framed as bypassing the 30-day cache.

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: measures monthly Google search volume for each page's primary keyword plus any extra keywords, scoped to the site's country. This is clearly distinguishable from siblings like suggest_keywords (which proposes terms) or get_growth_dashboard (which aggregates). The parenthetical about demand "none" makes the output concept concrete.

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

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

The description implies the use case (audit whether target keywords have measurable demand before optimising a page) and notes it 'Changes no page,' but never states when to call it versus suggest_keywords or update_page_seo, nor any precondition beyond site_id. Usage is inferable rather than explicit.

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

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

Annotations already declare destructiveHint=false and openWorldHint=false, so the safety profile is known; the description still adds real value by stating 'Changes nothing on Google' (this is a local mapping, not a Google-side mutation) and 'Free on every plan' (no credit cost). It does not say what happens to a previously linked location when a new one is set, which is the main behavioral question left open.

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

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

Three short sentences, front-loaded with the primary action, each carrying distinct information (action, unlink variant, no Google-side effect, cost). No filler or restatement of the title.

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 small mutation tool with annotations and no output schema, the description covers the source of the id, the unlink case, side-effect scope, and pricing. The only meaningful gap is the replace-vs-unlink-previous behavior when the site already has a location connected.

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

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

Schema coverage is 67% and connection_id itself carries no schema description, so the description usefully supplies its provenance and its null semantics. However, it says nothing about site_id or the optional user_goal parameter, leaving the description to add meaning for only one of the three inputs.

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?

Uses a specific verb ('Set') with a precise resource ('which connected Google location this site manages') and explicitly distinguishes the two modes (link by id vs. null to unlink). It is clearly differentiable from nearby siblings like list_google_locations, prepare_google_listing, and connect_data_source.

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

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

Tells the agent where to obtain the value ('connection_id from list_google_locations') and documents the alternate unlink path via null, which is exactly the branching an agent needs. There is no explicit statement about when not to use it (e.g. when no Google account is connected), but the context is otherwise clear.

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

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

Goes well beyond the annotations by disclosing concrete effects and failure modes: it replaces any existing domain (explaining destructiveHint), the domain is not live until DNS records exist and verify_domain succeeds, a paid plan is required, and a domain already bound elsewhere is refused. This is rich operational context an agent could not infer from the schema.

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

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

Four front-loaded sentences with zero waste: action, then DNS/verification consequence, then plan gate, then replace/refuse conditions. Each sentence carries distinct, decision-relevant information.

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

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

With no output schema, the description still tells the agent it returns DNS records to add, explains the async verification flow, plan constraints, and refusal conditions. An agent has everything needed to call it correctly and set user expectations.

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

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

Schema coverage is 100%, so the schema already documents all three parameters including the no-www/no-https guidance. The description adds only the 'domain the user owns' framing, not new syntax or semantics, so baseline 3 is appropriate.

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

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

States a specific verb (connect/claim) and resource (a custom domain a user owns) tied to a site. The sibling landscape (remove_domain, verify_domain) is implicitly disambiguated because the description explains this is the *start* of the flow and that verify_domain is a later step.

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 and prerequisites: paid plan required, free plan refused, and it starts a flow completed by verify_domain. It lacks an explicit 'use remove_domain to detach' style routing, so it falls just short of a full when/when-not statement.

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

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

Goes well beyond the annotations by disclosing the copied scope, that the original is untouched, that the copy has no address or custom domain, that it counts against the draft-site limit, and that the new site's id is returned. These are exactly the side effects an agent would otherwise have to guess at.

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 core action and scope, followed by constraints and return value. No waste or redundancy.

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

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

No output schema exists, but the description supplies the return value (new site's id) and the key side-effect limits. For a three-parameter mutation with full schema coverage, nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents site_id, name, and user_goal. The description adds no parameter-level detail beyond noting the return id; the schema is doing the heavy lifting, so baseline 3 applies.

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

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

Uses a specific verb (copy) plus explicitly enumerates what is copied — code, design, content, and every design — and the output artifact (a new draft site). This clearly distinguishes it from create_site, create_site_from_design, and rename_site among the 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?

States the conditions of the result (draft, unpublished, no address, counts toward the plan's draft-site limit) which tells the agent when this is the appropriate action. It does not, however, explicitly contrast with create_site or create_site_from_design, so the alternative selection is left implicit.

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 non-readOnly, non-destructive, non-idempotent, closed-world, so the safety profile is covered. The description adds real behavioral context beyond that: it acts as the connected person (identity of the actor), requires the post to be in review state, and is permitted for any brand member. It does not describe what happens to the review state or whether notes are editable/deletable, keeping it below a 5.

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

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

Four short sentences, zero filler, with the core action and the actor identity front-loaded and the sibling exclusion placed last. Every clause carries decision-relevant information.

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

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

For a simple non-destructive note-creation call with a fully documented 5-parameter schema and no output schema, this is nearly complete. The only gap is that it doesn't say what an agent gets back or that the note appears in the review thread visible to clients, which would help an agent confirm success.

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

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

Schema description coverage is 100%, so body, post_id, brand_id and reply_to are all documented in the schema already; baseline 3 applies. The description's mention of reply_to ('a note id to answer an existing note') essentially restates the schema's own wording rather than adding threading or ordering semantics.

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

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

Names a specific verb and resource ('Add a note to a social post's review') and anchors it to a familiar action ('the same as typing a note in the review screen'). It also explicitly distinguishes itself from the nearest sibling by stating it does not approve or request changes and redirecting to review_post.

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?

States the precondition ('The post must have been sent for review'), the permission model ('Any member of the brand may'), and the exclusion plus alternative ('Does not approve or request changes; that is review_post'). An agent has everything needed to route between this and review_post.

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 is non-read-only, non-idempotent, open-world, and destructive, so the description need not restate those traits. The description adds useful context that a verification must have been started and that the code comes from Google, but it does not explain what is destructive, what happens on a wrong code, or what state changes on success.

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

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

The description is a single front-loaded sentence with no wasted wording. It puts the completion action and the required Google-sent code immediately in view.

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 four-parameter mutation tool with annotations and no output schema, the description is adequate to identify the operation and prerequisite. It still leaves gaps around the verification parameter and the practical meaning of the destructive hint, so an agent lacks some detail needed to call it confidently in edge cases.

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

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

The description clarifies that the supplied code is the one Google sent the owner, which gives meaning to the otherwise undocumented pin parameter. However, the verification parameter remains unexplained, and the description does not add much beyond the schema's existing site_id and user_goal descriptions.

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

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

The description states a specific verb and resource: 'Complete a started verification' with the Google-sent code. The word 'started' distinguishes it from start_google_verification, and 'complete' distinguishes it from get_google_verification.

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

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

The phrase 'a started verification' clearly implies the prerequisite that start_google_verification must already have been called. It does not explicitly name alternatives or say when not to use this tool, so it falls short of full when/when-not guidance.

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

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

Annotations already declare readOnly=false, idempotent=true and destructive=false, so the description does not need to re-establish the safety profile. It still adds valuable context beyond them: changes affect future real messages, SMS requires approved setup, active billing and recipient consent, and unspecified fields are preserved. It does not state what happens to already-queued messages, but the gaps are minor.

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

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

The prerequisite read is front-loaded, followed by the patch semantics and the sending constraints. It is slightly dense with four separate caveats in successive sentences, but every clause carries real information 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?

For an 8-parameter mutation tool with no output schema, the description covers prerequisites, side effects on real customer messages, channel constraints and placeholder format. The main residual gap is response/rollback behaviour, which is not described but is a reasonable omission for an idempotent patch-style update.

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

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

With 100% schema description coverage, the baseline is 3, and the description genuinely adds meaning on top of the schema by explaining the template placeholders ({{first_name}}, {{business_name}}) and that variants must come from the overview. These are operational details not fully captured in the parameter descriptions alone.

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

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

The description opens with a specific verb and resource ('Change a built-in automation message, specific reminder/review variant, or supported SMS/email channel'), which lets an agent distinguish it from siblings such as set_automation_enabled or get_automation_overview. The scoping to messages/variants/channels rather than the on/off switch is explicit.

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

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

It gives a clear prerequisite ('Read get_automation_overview for actual templates, variants and available_channels first') and a key behavioural rule ('Omitted fields keep their current values'). It does not name the closest sibling (set_automation_enabled) as an alternative for toggling, leaving the enabled parameter overlap implicit.

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, idempotentHint=true and destructiveHint=false, and the description adds the non-obvious partial-merge rule: 'Omitted limits keep their current value', which is the key behavioral trait an agent needs to avoid clobbering existing limits. It does not address what happens to already-placed COD orders when disabling, or whether the change is reversible.

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

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

Three short sentences, front-loaded with the action and its effect, then the optional scoping, then the merge rule. Every sentence carries information an agent would otherwise have to infer.

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 idempotent, non-destructive mutation with full schema coverage and no output schema, the description covers purpose, prerequisite (no payment provider needed), limit semantics and merge behavior. The remaining gap is operational detail about disabling (effect on existing COD orders, required permissions), which is a smaller omission than the core coverage it provides.

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

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

Schema description coverage is 100%, so the schema already explains enabled, min_order, max_order, currency and the null-vs-omit distinction. The description reinforces unit semantics ('major currency units') and the merge rule, but adds little that the schema does not already carry.

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 ('Offer (or stop offering) cash on delivery at checkout') and adds the differentiator that it works with no payment provider, which separates it from configure_payments and configure_shipping. It stops short of naming those siblings, but an agent can route correctly from the text 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?

'Works with no payment provider at all, so it is the quickest way to let a store take orders' gives a clear condition for reaching for this tool over the fuller payment configuration flow. There is no explicit exclusion ('do not use if X' or a named alternative), so it falls short of a 5.

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

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

Goes well beyond the annotations: secrets are stored, masked to the last 4 characters and must never be repeated in chat; the response carries the `webhook` URL and events the merchant must register; demo-mode sites show a "test mode" bar when published and take no real money. It also warns never to invent or reuse keys. Only mild tension: `remove: true` deletes keys while destructiveHint=false, but that is a config disconnect rather than data destruction, so it is not a contradiction.

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

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

Purpose is front-loaded and every paragraph carries operational weight, but the single dense block with nested parentheticals ("(demo payments", "no real money moves; tell them so") is longer than needed and repeats test-mode wording that also appears in the schema.

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

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

For a 8-parameter, nested-object mutation with no output schema, the description covers the return value (webhook URL and events), side effects (test-mode bar, other providers switched off), secret handling, and the multi-provider constraint. Nothing an agent needs in order to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, and the description still adds real meaning: credentials must be the merchant's keys exactly as pasted, `use_test_payments` ignores `credentials`, and the default demo gateway is Razorpay for INR stores and Stripe otherwise. It does not re-explain per-key formats, but the schema already does that thoroughly.

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?

"Let a store take online payments" states a concrete outcome, and the description then spells out both operating modes (merchant's own gateway vs. demo/test payments) plus the disconnect action via `remove: true`. It is clearly distinguishable from siblings like configure_cash_on_delivery, which is explicitly named as the fallback when no provider is connected.

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

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

Explicit routing: use `provider` + `credentials` when the merchant has keys, use `use_test_payments: true` when they don't, and `remove: true` to disconnect. It also states the cross-tool rule (only one provider active at a time) and points to configure_cash_on_delivery for stores that want no gateway.

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, idempotentHint=false, readOnlyHint=false, so the mutation risk is structured. The description adds genuine value by disclosing downstream consequences: a store with no zones charges no shipping, and buyers outside every zone get no shipping option — an agent can reason about the blast radius of delete_zone. It stops short of stating whether deletes are irreversible or what happens to rates when a zone is deleted.

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

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

Front-loads what the tool does, then the preferred call shape, then the rate kinds and units. Dense but every clause carries actionable content; the parenthetical asides make it slightly harder to scan than a bulleted structure would.

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 18-parameter, action-discriminated mutation tool with no output schema, the description covers the action-to-parameter mapping, units, defaults, and where to obtain zone/rate ids. Remaining gap is update semantics: whether omitting a field on update_zone/update_rate clears it or leaves it unchanged.

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 94%, so the baseline is 3. The description does add cross-parameter logic the schema cannot express — kind is inferred from price/free_over when omitted, and which parameters belong to which action — plus unit conventions (major currency units, weights in grams, default store currency), which is real 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 set (create/change/delete) over two named resources (shipping zones and the rates within them), and immediately delimits the concept of a zone (which countries/regions it ships to). An agent can distinguish this from configure_tax, configure_payments and get_store_settings 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 concrete operating rules: 'One change per call', prefer create_zone carrying its rate, otherwise create_rate addressed by zone_id or zone_name. It routes between its own actions but never says when not to use this tool or who can call it (permission prerequisites).

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

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

Annotations already declare this is a non-read-only, idempotent, non-destructive operation. The description adds important behavioral context beyond annotations: only passed fields change, manual rates are percentages, and the agent must ask the user for tax registration details rather than inventing a GSTIN or rate.

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 decision and then enumerates the modes efficiently. Every sentence adds relevant detail, including the important constraint against inventing tax registration data.

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 8 parameters with full schema descriptions, annotations covering safety and idempotency, and no output schema, the description provides enough context to invoke the tool correctly. It covers mode selection, key GST behavior, partial-update semantics, and the critical warning about not fabricating tax details.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds useful domain meaning by explaining how modes relate to parameters: manual_rates are per country/region percentages, gst_in uses gstin, gst_business_state and gst_rate_percent, and prices_include_tax controls whether catalogue prices already include tax.

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

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

The description states a specific verb and resource: deciding how a store charges tax. It immediately distinguishes the four tax modes and their core semantics, so an agent can tell this apart from sibling configuration tools such as configure_payments or configure_shipping.

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 context for when to use the tool: setting up store tax behavior, with mode-specific guidance for manual, gst_in, and stripe_tax. It does not explicitly name when not to use it or compare it to adjacent configuration tools, but the intended usage is clear.

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

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

Annotations only declare the generic profile (openWorldHint=true, idempotentHint=false, destructiveHint=false). The description adds the non-obvious operational semantics: data is fetched at publish time and baked into pages, not live in the browser, so a republish or settings sync is required for changes to appear. It also discloses that an existing source blocks the connection, which is real behavioral context the 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?

Five short sentences, all load-bearing, with the scope constraint front-loaded before the prerequisites and the alternative route. Nothing is repeated from the title or the schema.

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

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

For a 9-parameter mutation with nested objects and no output schema, the description covers scope, prerequisites, ordering constraints and publish-time behavior well. The remaining gap is what the call returns (e.g. the created data source identifier or a mapping result), which the agent cannot learn from an output schema that does not exist.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds constraint semantics the schema does not state: endpoint_url must be public and key-free, and content_key must be exactly one path returned by list_bindable_content_keys. field_mapping, response_path and refresh_interval_minutes are left entirely to the schema.

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

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

States a specific verb and resource (connect a public endpoint/feed to a content section) and the effect (the section's items come from it). It explicitly scopes out key-based endpoints and points those to the site's Data Sources settings, which separates it from sibling data-source tools.

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

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

Gives ordered prerequisites (call list_bindable_content_keys and test_data_source_connection first), an exclusion (endpoints needing a key are connected in settings, not here), and a blocking condition (a section that already has a source must be disconnected first). An agent knows when and when not to call 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 non-read-only, non-destructive, idempotent and closed-world; the description adds real value beyond them by saying creation is free and that a retry with the same idempotency_key returns the same workspace. It also explains the downstream consequence — the supplied brief metadata drives every visual and film made under the brand. It stops short of covering permissions, failure modes, or what is returned on success.

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 eligibility, then the alternative, then the payload, then the follow-up and retry semantics — a sensible ordering with no filler. Dense but readable; a sentence or two on the required name or the return value could be folded in without bloat.

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-parameter creation tool with no output schema, the description covers purpose, eligibility, alternatives, the substantive brief fields, the asset follow-up and idempotency. The main gaps are the untouched user_goal parameter and what the caller gets back (e.g. the new brand identifier for later calls), which an agent may need to proceed.

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

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

With only 50% schema description coverage, the description compensates well on the brief fields: it explains what description, industry, audience, tagline and colors mean collectively ('these brief every visual and film made under it') and that colors are hex ordered by importance. It also pins down idempotency_key semantics beyond the schema. It says nothing about name, the optional user_goal, or max-item limits, so it is not fully complete.

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 standalone Creative Studio brand workspace') and immediately scopes it to a business with no website in the account. Explicitly names the sibling get_site_brand as the path for a website's brand, so an agent can distinguish the two without opening either schema.

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

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

Gives an explicit use case (client pitch, no website yet) and an explicit exclusion ('A website's brand is get_site_brand, not this'). It also routes the follow-up action — logo and photos — to upload_brand_asset, leaving nothing to inference.

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

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

Annotations already declare write, open-world, idempotent, non-destructive. The description adds the genuinely useful side effects: Google sends real invitations when attendees is non-empty, no attendees are invented, and retries require an idempotency_key. It omits prerequisites such as needing a connected/authorized calendar (cf. the get_calendar_connection sibling), which is the remaining behavioral gap.

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

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

Four short sentences, front-loaded with what is created and immediately followed by the scope exclusion, then parameters, then the invitation side effect. No sentence is filler and nothing important is buried.

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 open-world write tool with no output schema, the description covers the mutation's blast radius and retry story well. It never states what comes back (event identifier/link) or which connection/permission is required, which leaves a small but real gap for an agent planning a follow-up call.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds intent beyond the schema by telling the agent to pass the exact title, timezone-bearing start/end, and intended attendee emails, and by flagging idempotency_key as a hard requirement for safe retries. It does not explain the google_meet or user_goal parameters, but the schema already does.

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 one owner-authored Google Calendar event on the site's owned write calendar") and immediately scopes it against the obvious confusion: it is not a booking and does not consume appointment capacity. An agent can distinguish this from manage_appointments, book_callback_slot, or get_calendar 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?

Explicit exclusion is given ("does not create a booking or bypass appointment capacity") plus the precondition that attendees must be non-empty for invitations to go out. It stops short of naming the sibling to use when a real booking is wanted, so routing is implied rather than directed.

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 say non-read-only, non-idempotent, non-destructive, closed-world. The description adds real behavior beyond that: the link expires in 7 days and is returned rather than delivered, which directly shapes what the agent must do next. It does not explain whether repeat calls mint additional links or invalidate prior ones, which matters given idempotentHint=false.

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

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

Three short sentences: what it creates, its lifetime and delivery semantics, then a usage cue. The most decision-relevant facts come first and nothing is padded.

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

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

With only two params and no output schema, the description covers actor, lifetime, and delivery, which is sufficient to call and follow up correctly. The one gap is that the return value ('returned for you to share') is not characterized beyond that phrase, and re-invocation behavior is unstated.

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

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

Schema description coverage is 100%, including a pointer to list_brands for brand_id and guidance for user_goal, so the schema does the parameter work. The description mentions no parameter by name and adds nothing beyond that baseline.

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

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

States a specific verb and resource ('Create a private link a CLIENT opens to connect their own social accounts to this brand') and pins down the distinguishing constraint, 'with no Mondovo login', which separates it from ordinary OAuth/connect flows. An agent knows exactly what artifact this 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?

Gives a concrete triggering utterance ('send my client a link to connect their Instagram') plus the key exclusion that the tool does not send anything, so the agent knows the delivery step is on them. It stops short of naming an alternative or saying when not to use it versus get_social_connect_link or set_linked_social_accounts.

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

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

Goes well past the annotations (readOnly=false, idempotent=true): it discloses duration ("up to a few minutes"), cost ("costs no credits"), side effects (fields, detail-page template in every design, listing page, seeded items), the idempotent `already_existed` outcome, and that a multi-design build returns a new `site_id` plus a `build_transition` whose `tell_user` must be relayed.

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

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

Front-loads the core action and its cost/duration, then escalates to the edge cases; nearly every sentence carries unique operational information. The uppercase multi-design paragraph is dense and slightly run-on, but it is load-bearing rather than 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?

With no output schema, the description still documents the meaningful return signals (`already_existed`, new `site_id`, `build_transition.tell_user`, `choose_design`), which is exactly what an agent needs to handle the response correctly.

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

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

Schema coverage is 100%, so baseline is 3; the description earns above that by explaining variation_id omission behavior (use built/only-edited design, else answer `choose_design`) and the semantic shift of `site_id` after a multi-design build — neither of which the schema states.

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

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

States a specific verb and resource ("Create a new catalog collection") and enumerates concrete collection types, so the agent knows exactly what gets created. It does not, however, distinguish itself from the sibling `create_dynamic_collection` / `list_dynamic_collections`, which an agent could reasonably confuse with this.

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 real when/when-not guidance: it names the alternative path when the collection exists ("add items to it instead"), notes that publishing is a separate step, and explains the multi-design branch with a fallback to `choose_design`. The only missing routing is versus the dynamic-collection siblings.

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

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

Goes well past the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false) by disclosing side effects precisely: "Saving one emails nobody: contacts who already match are added silently and start no journey." It also documents the two refusal cases (values the site doesn't have, matching nobody unless allow_empty) — exactly the behavioral context the 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?

Four tight sentences, front-loaded with what the tool does, then the no-email side effect, then the prerequisite workflow and edge cases. Nothing repeats the schema or the title.

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 13-parameter mutation with no output schema, the description covers side effects, prerequisites and refusal rules well. It does not say what a successful call returns or how name collisions are handled (create failure vs. existing segment), which matters given update_contact_segment exists as a sibling.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: the default when no facets are supplied ("No facets = every contact") and the intent behind allow_empty ("an audience meant to fill up later"). The naming-values-must-exist rule also reinforces the schema's "use list_contact_filter_vocabulary" constraints.

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

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

States a specific verb+resource (save a contact filter as a named, reusable audience segment) and immediately scopes what the resource is for (campaigns and journeys target them). It also implicitly separates itself from preview_contact_segment, which it tells the agent to use for a dry run.

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

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

Gives concrete prerequisites ("Call list_contact_filter_vocabulary first and preview_contact_segment to check the size") and the rejection conditions that force allow_empty. It never addresses when to use create_contact_segment versus update_contact_segment, so the alternative for modifying an existing segment 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?

Beyond the annotations it discloses the credit cost (1 Creative Credit), a per-connection daily spend cap, that the call blocks for roughly two minutes rather than returning a job handle, and that the idempotency key should be reused after a timeout. That is exactly the operational context an agent needs before issuing a billable, long-running write.

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

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

Short and mostly front-loaded on cost and the required key, with the sibling routing at the end. The first clause is syntactically broken, which wastes one of the few sentences available.

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 billable generation tool with no output schema, it covers cost, blocking duration, idempotency and the correct alternative tool for ads. It does not describe what a returned pack contains or how large it is, which is a minor gap given there is no output schema.

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

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

Schema coverage is 71%, so most parameters are already documented, including expected_credit_cost and idempotency_key. The description reinforces the required pairing of credits and key but adds little that the schema does not already say, and it says nothing about brand_id, platform, persona_id or brief.

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 concrete verb and resource (write a social copy pack) and explicitly distinguishes it from siblings: pricing comes from quote_content_pack and ads belong to create_visual. The opening sentence is garbled ('Write the pack quote_content_pack priced'), which costs a little clarity, but the intent is still recoverable.

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 real when-to-use routing: use create_visual for ads, do not poll get_job after calling, and supply expected_credit_cost from quote_content_pack. It stops short of an explicit 'call quote_content_pack first' instruction and says nothing about when not to generate a pack at all.

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 non-readOnly, non-destructive, non-idempotent, but the description adds real behavioral context: links auto-update as matching pages are added, links are stored under `content_key`, and the change lands in version history (reversibility). It doesn't call out auth/permission needs, but the added mutation semantics are valuable beyond the annotations.

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

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

Front-loaded with the purpose and examples before drilling into `source_type` branching and the preview recommendation. It is dense (em dashes, inline enum references) but each clause carries information; 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?

For a 14-param, 5-required mutation with no output schema and thin annotations, the description covers mode selection, storage key semantics, auto-update behavior, version history, and the preview-first workflow. Layout/placement/columns defaults are left to the schema, which documents them, so the description is nearly complete.

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

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

With 93% schema coverage the baseline is 3, but the description goes further by explaining the branch semantics: `slug_pattern`/`page_types` only apply to `internal_pages` while `manual_items` apply to `manual`, and `content_key` is the render-time storage handle. That resolves the main ambiguity of a 14-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 concrete verb+resource ('Add a shared link block that fills itself') and immediately grounds it with examples (footer SEO links, 'Browse by area' card grid, category nav). It also distinguishes the two modes of building links via `source_type`, so an agent can separate this from `create_collection` or `add_collection_item` 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?

Explicitly routes the agent to run `preview_dynamic_collection` first, which is a real usage constraint. It also explains when to pick `internal_pages` vs `manual`. It does not contrast this with the sibling `create_collection` (static) or `add_collection_items`, which slightly limits routing clarity.

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 (which only declare non-readonly, non-destructive, non-idempotent), the description discloses that the created object has no code and does nothing until deployed, and that the slug is derived from the name — meaningful behavioral facts an agent would otherwise have to guess. It stops short of stating auth requirements or what happens on name collisions.

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

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

Three short sentences, front-loaded with the action, then consequences, then the slug detail. Every sentence carries information, though the parenthetical about owner editing is slightly more detail than strictly needed for tool selection.

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

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

For a 4-param creation tool with no output schema, the description covers what is created, its inert initial state, and the follow-up actions required, which is enough to call it correctly. It does not indicate what identifier is returned, but with no output schema that is a minor omission rather than a blocking gap.

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

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

Schema description coverage is 100%, so name, site_id, description, and user_goal are all documented at the schema level; baseline is 3. The description adds only the derived-slug note tied to name, which is marginal additional meaning beyond the schema.

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

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

States a specific verb and resource ('Create a new, empty function draft') and immediately scopes it as an empty scaffold, distinguishing it from generate_function_code and deploy_function which appear as siblings. An agent can tell this apart from the code-generation and deployment tools 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?

Explains the lifecycle context: the draft is inert until code is written (naming generate_function_code or manual owner editing) and then deployed, which effectively tells the agent this is the first step and what must follow. It does not explicitly state when NOT to use it or contrast with list_functions/get_function_details, so it falls short of a full when/when-not treatment.

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 it discloses two non-obvious behaviors: creation is retry-safe, and the listing remains unverified until verification completes (with an instruction to tell the user). Note the mild tension with idempotentHint=false — 'retry-safe' is not the same claim as idempotent, so this is clarification rather than a contradiction, but the agent could still wonder whether a retry yields the same listing.

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

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

Four short sentences, each carrying distinct information: the action, the prerequisite, the duplicate-confirmation gate, and the post-creation state. The critical gating rule is front-loaded right after the action statement, with no restatement of the name or title.

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, open-world, non-idempotent creation tool with a nested listing object and no output schema, the description covers the lifecycle (unverified until verification) and the safety gate. It does not say what identifies the created listing on return or what happens if a possible duplicate turns out to exist, leaving a small gap for the agent.

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

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

Schema coverage is 67%, and the description compensates where it matters most: confirmed_not_duplicate has no schema description at all, and the description supplies its exact semantics and safety condition. It also ties site_id to linking the listing, though setup_id and connection_id are left entirely to their schema blurbs.

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

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

The description states a specific verb and resource ('Create the NEW Google listing') plus the side effect ('link it to this site'), and it names the prerequisite sibling prepare_google_listing so the agent can place this call in the Google-listing workflow rather than confusing it with prepare_google_change or choose_google_location.

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

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

It gives a clear precondition ('after prepare_google_listing') and an explicit gating rule for confirmed_not_duplicate=true only after the owner confirmed none of the possible matches is theirs, which is exactly the when-to-use guidance an agent needs. It doesn't explicitly rule out alternative paths such as re-preparing a change or choosing an existing location, so it stops short of full when-not coverage.

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

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

Goes well beyond annotations: discloses that 301 is served uncached so every click is counted and edits take effect, that the on-domain address goes live within a minute or two (or at publish), that WhatsApp ignores URL tags so a ref is appended to prefill_text, and that phone defaults to the business number and must never be invented. Rich operational context for a mutation tool.

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

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

Dense but front-loaded: the core (what a tracked link is) comes first, followed by destination kinds, tracking, status, and lifecycle. Long single paragraph is efficient though packed; every sentence carries operational detail.

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

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

For a 13-param nested-object mutation tool, the description covers destination kinds, tracking, status, expiry/fallback, prefill, and live timing. With no output schema, it does not describe what is returned (e.g. the created link and short URL), which is the main remaining gap.

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

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

Schema coverage is 85%, so most params are documented, but the description still adds real meaning: destination.kind semantics (email requires email, page is a site path, web is full https), tracking tags behavior on page/web vs. WhatsApp, and status default logic. It does not cover every param (e.g. forward_query, tag_destination, user_goal) but adds value above 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?

Specific verb and resource: 'Create a tracked link' with a precise definition (on-domain address plus short address sending visitors to `destination` and counting clicks). It clearly distinguishes from siblings like add_redirects, suggest_link, and create_client_connect_link by describing both the on-domain path and short link behavior.

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

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

Explains conditions well: path is optional, status is 301 unless the user asks for temporary, expires_at pairs with fallback_url, and 'The path must not be a page, a redirect or another link' clarifies exclusion. It stops short of explicitly naming sibling alternatives (e.g. add_redirects vs. this tool) for an agent choosing between tools.

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

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

Goes well beyond the annotations: it discloses that Creative Credits are spent, that a mismatched price is refused with nothing charged, that a repeated key never double-charges, and that the result is asynchronous and lands in the brand library. This is exactly the economic and side-effect context the idempotentHint/destructiveHint flags 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-loads the action, then cost semantics, then the follow-up step — a sensible ordering with no filler. The middle sentence is long and packs three separate rules together, which slightly hurts scanability but every clause is load-bearing.

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 async, credit-spending, eight-parameter tool with no output schema, the description covers everything an agent needs: inputs sourced from plan_logo, cost guard, idempotent retry, and the fact that completion is observed via get_job rather than a direct return. No material gap remains.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns an extra point by tying `expected_credit_cost` to plan_logo's `credits`/`refine_credits` and explaining why `idempotency_key` must be stable. It does not add anything for `direction_prompt`, `logo_type`, or `direction_label` beyond what the schema already says.

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 ('Draw ONE logo direction'), names the upstream source (plan_logo), and the capitalization of ONE makes the one-direction-per-call scope unambiguous. An agent can distinguish this from plan_logo and from other creation tools without opening the schema.

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

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

Explicitly encodes the workflow: take the prompt and price from plan_logo, use `refine_credits` when refine is set, then poll get_job with the returned job_id. It also states the retry condition (reuse the idempotency key) and what happens on a price mismatch, so the agent knows when and how to call it versus its siblings.

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