Ignix

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

Annotations already flag destructiveHint=true, idempotentHint=true, and openWorldHint=true, but the description adds the crucial business behavior: the operation consumes AI credits on each run and is gated by an explicit user consent step, with a refusal path that returns the estimate. That is real added context beyond the structured hints, though it does not describe post-activation state or scheduling failure modes.

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

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

Two sentences: the action and its cost side effect first, the gating requirement second. No filler, no 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 write tool with no output schema, the description supplies the cost implication, the consent gate, and the refusal response, which is what an agent needs to avoid calling it prematurely. Minor gaps remain about what the returned estimate/confirmation looks like and any rate limits.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by explaining the failure semantics of confirm (request is refused with the estimate when absent) rather than merely restating the schema's 'true ONLY after the user agreed' wording. planId, workspaceId, and idempotencyKey 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 concrete verb+resource ('turn a plan on so it runs on its schedule') and the consequence ('spends AI credits on every run'), which cleanly separates it from deactivate_autopilot_plan, update_autopilot_plan, and create_autopilot_plan in the sibling list.

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

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

Gives the exact precondition for the required confirm flag ('after the user agreed to the estimated credits per run') and the outcome of omitting it ('refused with the estimate'). It does not name the sibling to use for the opposite action, but the paired names make that inferable.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new context beyond that: activating causes real people to receive messages, and it mandates user confirmation. It stops short of detailing timing/cancellation behavior.

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

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

Two tight sentences with the action and effect front-loaded, followed by the safety instruction. No wasted wording, though not exceptionally rich.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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, but the description conveys the state change and the confirmation requirement an agent needs to act correctly. Combined with full schema coverage and annotations, it is largely complete.

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

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

Schema description coverage is 100%, so the schema fully documents sequenceId (from list_sequences) and idempotencyKey. The description adds no parameter detail beyond this, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('Turn a drip sequence on') and clarifies the effect ('enrolled contacts start receiving its messages at their delays'). This implicitly contrasts with pause_sequence/deactivate siblings, but no sibling is named explicitly, so it falls 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?

Provides a conditional instruction ('confirm with the user first') that signals caution before invoking, but does not name alternatives such as pause_sequence or explain when-not to use it. Usage is implied rather than fully specified.

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

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

Annotations only say this is a non-read, non-destructive, open-world call; the description adds what they cannot: a hard cost of 2 AI credits from the monthly pool, that the org's own AI key is never used, that nothing runs or is charged without confirm: true, and what the unconfirmed call returns (the quote). That is exactly the behavioral context a cost-incurring mutation needs.

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

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

Purpose is front-loaded in the first two sentences, and the remaining sentences are load-bearing instructions rather than filler. It is long and repeats the 'nothing runs and nothing is charged' point already in the confirm schema description, which is the only waste.

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

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

With no output schema, the description still tells the agent what an unconfirmed call yields (the quote), what a confirmed call does, how credits are drawn, and how approval scope works. For a 6-parameter, credit-spending tool that is complete.

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

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

Schema description coverage is 67% and the schema already documents confirm, workspaceId, and idempotencyKey in detail. The description reinforces confirm's semantics (only after a clear yes) but adds no meaning for text, platform, or language beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb+resource+scope: rewrite existing text into a target network's native style and length, with the '(a LinkedIn post is not an X post)' parenthetical pinning down what 'native style' means. It implicitly separates itself from write_caption (new text) and translate_caption (language change), but never names a sibling to route the agent explicitly, which keeps it at 4.

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

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

Unusually explicit: call first without confirm to get a quote, tell the user in your own words what will run and what it costs, wait for a clear yes, then repeat with the same arguments and confirm: true. It also defines the boundary of a single approval ('one yes covers the plan they approved; anything new or different needs a new yes'), leaving no inference required.

Agents often have multiple tools that could apply. Explicit usage 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 (readOnly false, destructive false, openWorld false). The description adds genuinely useful behavior an agent cannot get from annotations: the note is never sent to the customer, does not pause the bot, and surfaces in the inbox and in get_conversation. It stops short of stating permissions or return shape, so 4 rather than 5.

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

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

Three sentences, zero filler, with the essential scope constraint ('private', 'NEVER sent to the customer') front-loaded ahead of the alternative-tool pointer.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 five-parameter mutation tool with no output schema, the description covers the critical unknowns: audience (internal only), side effects on the bot, and visibility surface. It could say more about where the note is readable programmatically, but nothing an agent needs to call it correctly is absent.

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

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

Schema coverage is 80% and the schema already documents note, platform, accountId, and idempotencyKey. The description adds nothing about parameters, and conversationId is left undocumented in both places. Baseline 3 is appropriate where 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?

The description states a specific verb and resource ('Leave a private note on a conversation') and immediately delimits its scope as team-internal. It is unmistakably distinct from reply-oriented siblings like send_message.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 supplies both when-to-use (team context, what was promised, what to check) and an explicit when-not with a named alternative: 'To answer the customer use send_message instead.' No inference is required to route between the two.

Agents often have multiple tools that could apply. Explicit usage 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 disclose non-read-only, open-world and non-idempotent behavior, so the bar is lower. The description adds a genuinely useful trait beyond them: 'It is public as soon as Google accepts it,' telling the agent the effect is externally visible and asynchronous/acceptance-gated. It stops short of describing auth or moderation constraints.

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

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

Three sentences, front-loaded with the core action and its input constraints. The middle sentence is promotional ('Listings with recent photos get noticeably more calls and route requests') — defensible as motivation but softer than the rest of the definition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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-param mutation with no output schema, the description covers the essentials: what is added, the URL requirement, the category, and the public visibility outcome. Remaining details (account/location resolution, idempotency retry semantics) are carried adequately by the 100%-covered 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 description coverage is 100%, so the schema already documents sourceUrl, category values, accountId provenance, locationId fallback, and idempotencyKey. The description's '(cover, logo, interior, product…)' merely mirrors the enum in looser case, adding no syntax or constraint detail beyond the schema, so baseline 3.

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

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

States a specific verb and resource ('Add a photo to the Google Business listing') plus the input constraint ('from a public https URL, in a category'). This clearly differentiates it from list_gbp_photos, remove_gbp_photo, and update_gbp_listing in the sibling set.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 phrasing — supply a public https URL and a category — but there is no explicit when-to-use, when-not, or alternative routing (e.g., replace vs add, or what to do if the photo already exists). The marketing sentence about more calls hints at motivation rather than 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 non-read-only, non-destructive, non-idempotent, open-world. The description adds genuinely new behavioral context: the block becomes public immediately on save, the user must be asked to confirm, and payments settle to the business's own Stripe account outside this chat. It does not cover failure modes or auth requirements.

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

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

Dense but front-loaded: the action is stated first, then the type/data reference block. Every line is load-bearing given the nested payload, though the opening store-administration framing sentence is slightly wordy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 annotations but no output schema, the description covers what is being created, the full payload vocabulary, and the public-visibility consequence. It stops short of stating permission prerequisites or the returned block identity, which an agent might want.

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

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

Schema coverage is 100%, but the schema explicitly defers to the description ('the data each type takes is described above'), so the per-type payload shapes (link, text, video, booking, socials, product, including style enums and network lists) are the real semantic content and exist only here. Only workspaceId/idempotencyKey details are left 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+resource: 'Append a block at the bottom of the public store page' names the exact mutation and its placement. It is clearly distinguishable from siblings like update_store_block (modify existing), reorder_store_blocks (reorder), and delete_store_block.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 frames the context (owner-managed link-in-bio store, no commerce in chat) and gives one operational rule ('It is public as soon as it is saved: confirm with the user'), but never explicitly routes the agent to alternatives such as update_store_block or reorder_store_blocks. Usage is implied rather than stated.

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

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

Annotations declare the write/not-readOnly and non-destructive profile, and the description adds meaningful context beyond them: 'Nothing here is ever published', short-text dropping, duplicate skipping, and the deduplication/palette caveats. It stops short of describing response or failure behavior, but adds real value over 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?

A single dense paragraph with no filler; the 'what to add' framing comes first, followed by constraints, routing, and the follow-up call. Slightly long, but nearly every sentence carries operational value.

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

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

For a 6-parameter, all-optional write tool with no output schema, the description covers sourcing rules, quantity guidance, targeting, deduplication behavior, and the required follow-up step. It leaves the return shape unstated, but with no output schema that is a minor gap.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds genuine meaning: accountId attaches to one account vs omitting for workspace-wide style, and imageUrls must be real posts (not screenshots, which poison the palette). It also explains why transcripts matter for video accounts, going beyond the schema text.

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

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

States a specific verb and resource: add customer-supplied style material (captions, transcripts, images) so the style can be learned from it. It is clearly distinguishable from siblings like import_style_from_link, learn_brand_style, and delete_style_examples, and it names the source constraint (accounts not connected to Ignix).

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 about when to use and what qualifies: content from unconnected accounts, ~10 texts minimum and 20 plenty, transcripts being the only way for video accounts. It also routes the agent to the next step ('call learn_brand_style so the style picks it up') and explains the accountId-vs-omit choice.

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

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

With annotations declaring readOnlyHint=false and openWorldHint=true, the description adds real context the annotations cannot: 10 AI credits (first per org free), a quote-then-confirm gate, and the fact that direct media links expire within hours so they must be downloaded immediately. It does not contradict the annotations — 'reference and analysis only' refers to content republishing, not to the credit spend that justifies readOnlyHint=false. What keeps it from a 4-5 is that 'its numbers' is left undefined despite there being no output schema, so the agent cannot tell the user what metrics they will actually get.

Agents need to know what a tool does to the 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 correctly front-loaded, but the body is one undifferentiated block that mixes return values, download guidance, transcription workflow, legal caution, pricing, routing, and a long confirmation protocol. The confirm rule is restated at least three times ('SPENDS AI CREDITS ONLY WITH confirm: true', 'Call it first without confirm', 'call again with the same arguments and confirm: true'), which aids safety but costs density.

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

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

With no output schema, the description usefully sketches the return shape (caption, duration, ordered media list with expiring links) and warns about link expiry, plus it covers cost, the approval gate, and the downstream transcription path via get_edit_playbook. The one real hole is that 'numbers' is never expanded into the actual metrics returned, which an agent needs to describe results to a user.

Complex tools with many parameters or behaviors need more documentation. 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 meaningfully extends the `confirm` parameter beyond its schema text by explaining the full quote-approval loop and that one yes covers only the approved plan. It also clarifies that `url` can be an Instagram /p/ carousel or a TikTok/YouTube link, which the schema does not. workspaceId and idempotencyKey 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 — fetch one public reel/post/video by URL — and immediately enumerates the platforms and the returned fields (numbers, caption, duration, media links). It names the sibling tools it is NOT (research_account, research_niche, get_research), so an agent can route without comparing 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 hands off to research_account for account-level posts, research_niche for topics, and get_research for previously run analyses (noting it is free). It also specifies the mandatory two-phase call pattern: call without confirm to get a quote, relay it to the user, then repeat with identical arguments plus confirm: true.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the useful 'already hosted' precondition and the video-job workflow, but omits what happens to existing media on the post and whether the post must be in a particular state.

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

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

Two tight sentences plus a docs link, with the core action front-loaded and the workflow hint second. Nothing is wasted, though the trailing docs URL adds little for an agent.

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

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

For a mutation tool with no output schema, the definition covers the action and a typical workflow but leaves behavioral gaps (media replacement semantics, post-state requirements, error behavior). Annotations cover the non-destructive/open-world profile, so this is adequate but not complete.

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

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

Schema coverage is 67% – url and idempotencyKey are documented in the schema, while postId has no description. The description adds no parameter-level detail beyond the schema, so the baseline 3 applies.

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

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

The description states a specific verb and resource (add a hosted image/video URL to an existing post), and the phrase 'already hosted' meaningfully separates it from upload_media and import_media. It never names those siblings explicitly, so the differentiation is inferred rather than stated.

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

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

It gives a concrete when-to-use scenario (create post, generate video, then attach) which is genuinely helpful sequencing for an agent. However it offers no exclusions or explicit pointers to alternatives such as upload_media for non-hosted files.

Agents often have multiple tools that could apply. Explicit usage 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 readOnly=false, destructive=true and idempotent=true, so the safety profile is known. The description adds genuinely new context by disclosing that bookmarks are private and that undo: true deletes the bookmark, which explains why destructiveHint is set for a nominally additive action.

Agents need to know what a tool does to the 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 ~20-word sentence, front-loaded with the primary action and the account scoping before the undo variant. No filler and nothing 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 simple 4-parameter tool with no output schema, the description plus annotations cover the safety profile, the privacy nuance, and the undo behavior. Minor gaps remain around confirmation of the resulting state or pagination-irrelevant return shape, but nothing essential is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes beyond the schema's terse 'true undoes the action' by clarifying that undo removes the bookmark, and it ties tweetId to 'a post' semantics. It adds real meaning on top of a fully documented 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 (bookmark) and resource (a post/tweetId on X) and names the account scope. It is clearly distinguishable from the other X-action siblings such as follow_on_x and retweet_on_x 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?

The description tells the agent how to perform the inverse operation ('remove the bookmark with undo: true'), which is useful routing information, but it never states when to prefer this tool over alternatives or any conditions/exclusions. Usage is implied rather than guided.

Agents often have multiple tools that could apply. Explicit usage 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, idempotentHint, non-destructive), and the description layers substantial extra behavior on top: empty sections are dropped so the report never shows blank pages, sentiment only appears on Inferno, filters are printed on the cover, researchIds are capped at 5 and never auto-included, and the top-conversations table is deliberately excluded for privacy. This is rich disclosure well beyond the annotations.

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

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

The output form is front-loaded in the first sentence and every following sentence carries a real constraint (skipped sections, Inferno-only sentiment, researchIds cap, excluded table). It is dense and slightly long, but no sentence 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?

With no output schema, the description fully carries the burden: it describes the artifact produced (document link with cover and sections, saveable as PDF), the inclusion/exclusion rules, and the filter constraints. 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 baseline is 3; the description still adds cross-parameter meaning, notably that sentiment is only valid on Inferno, that researchIds are limited to 5 and excluded unless listed, and that the report uses one account and one network. It reinforces rather than merely repeats 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 — it returns a link to an analytics report rendered as a document with cover, executive summary and per-page sections, PDF-ready. This clearly distinguishes it from data-returning siblings like get_analytics or get_engagement_trend, which return numbers rather than a formatted report artifact.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 strong context: pick sections, sections with no data are skipped, filters match the Analytics screen, competition analyses are appended only when explicitly listed, and sentiment is gated to Inferno. It stops short of naming an alternative sibling (e.g. 'use get_analytics if you only need raw figures'), so it is clear context without explicit exclusions.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), so the description only needs to add operational context. It does: undated items are 'spread across the free slots of the posting queue,' a non-obvious scheduling side effect that governs how the tool actually behaves.

Agents need to know what a tool does to the 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 core action and followed by the scheduling rule. The closing 'content plan for the month' sentence is softer framing than specification, but it is short and does carry batch-intent 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 batch-write tool with no output schema, the description covers batch semantics, account targeting, and queue filling. Idempotency and workspace resolution are delegated to the schema, which documents them fully, so only return/error expectations are left implicit.

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

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

Schema description coverage is 100%, so the baseline is 3; the description earns above that by clarifying cross-parameter semantics — undated items flow into free queue slots, and each item fans out to all accountIds. That is meaningfully more than the per-field text repeats.

Input schemas describe structure but not intent. Descriptions should explain 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 many posts') plus a scope qualifier ('for the same accounts in one call'), which cleanly separates it from the singular create_post and from schedule_post. An agent can identify the batch path 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?

'Ideal for loading a content plan for the month' gives one implied use case, so the tool's niche is inferable. However, it never names create_post or schedule_post as the alternatives, nor does it say when a single call is preferable — the when-not side is entirely absent.

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

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

Annotations declare destructiveHint/openWorldHint, but the description goes well beyond them: it enumerates the concrete side effects (deletes the Google Calendar event, emails the customer if an email exists, issues a full automatic refund when paid online) and explains the `refunded` outcome flag. This is exactly the side-effect disclosure a destructive tool needs.

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

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

Three tight sentences, front-loaded with what the tool does, followed by side effects and the confirmation requirement. No filler or repetition of 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?

With no output schema and only annotations covering safety hints, the description supplies the missing behavioral detail: destruction scope, notification, automatic refund, and the return flag. An agent has everything needed to call it correctly and warn the user.

Complex tools with many parameters or behaviors need more documentation. 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 by explaining where `id` comes from (list_appointments) and that the pre-cancellation refund behavior is tied to the payment state. It does not elaborate on idempotencyKey/workspaceId, which the schema already documents.

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

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

States a specific verb (cancel) and resource (appointment) plus the scoping mechanism (by id from list_appointments). Clearly distinguished from sibling create_appointment and list_appointments without needing to open 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 clear operational context: obtain the id from list_appointments, and 'Confirm with the user first' before invoking. No explicit when-not or alternative (e.g. reschedule) is offered, so it stops short of full routing guidance.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds real value beyond that by distinguishing plain cancellation from the more aggressive `remove: true` deletion, but it does not state irreversibility, effects on already-sent broadcasts, or auth requirements.

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

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

A single sentence, front-loaded with the primary action and immediately qualifying the alternate mode. Nothing is wasted and nothing 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 destructive, no-output-schema mutation tool, the description is thin: it omits what happens if the broadcast has already gone out, whether the action is reversible, and any required permissions. Annotations carry the danger signal, but the operational context an agent needs for a destructive call is only partially 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 coverage is only 33%, with the idempotencyKey documented and `remove` undocumented. The description compensates by explaining exactly what `remove: true` does, and broadcastId is self-evident from its name, so the meaningful semantic gap is closed.

Input schemas describe structure but not intent. Descriptions should explain 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 (cancel/delete) and resource (broadcast), and the remove flag makes the two modes explicit. It is readily distinguishable from siblings like list_broadcasts, create_broadcast and send_broadcast, though it does not name any of them.

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

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

The description implies use for a scheduled broadcast and clarifies the cancel-vs-delete choice via `remove: true`, which is genuine usage guidance. However, it gives no prerequisites (e.g., must the broadcast still be scheduled?), no exclusions, and no comparison to neighboring lifecycle 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?

Annotations already cover the read-only, idempotent, non-destructive profile, yet the description adds substantial behavioral context beyond them: that tokens require human reconnection, that restricted automations pause and auto-resume when Meta lifts the restriction, and that scheduled posts/automations will fail until resolved. This discloses consequences and required human actions that no annotation conveys.

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

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

The core purpose is front-loaded in the first clause, and every parenthetical earns its place by defining a status and its consequence. It is dense with nested parentheses, which slightly hurts scannability, but 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 zero-parameter read tool with no output schema, the description compensates by defining the status values it returns (reconnect/expiring/restricted) and their downstream effects. An agent has everything needed to interpret results and advise next steps.

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

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

The tool takes zero parameters, so per the baseline rule a 4 applies. The schema is trivially complete and the description correctly implies no input is required.

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

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

The description leads with a specific verb and resource: 'List connected accounts that need attention,' then enumerates the exact categories of attention (token expired/expiring, Meta-restricted pages). This clearly distinguishes it from the generic list_accounts sibling, which lists all accounts rather than problem accounts.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 strong context on what each returned state means and what action follows (reconnect in Ignix; automations paused and self-resuming for restricted). However, it never explicitly names when NOT to use it or points to sibling alternatives like list_accounts or sync_accounts, leaving routing inferences to the agent.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered structurally. The description adds valuable workflow context beyond the annotations: unconfirmed items are hidden from the assistant until this runs, and the bulk path (omitting itemId) affects every pending item. It does not explain idempotency behavior, though the idempotencyKey schema field does.

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

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

Two sentences, front-loaded with the reason unconfirmed items matter before stating the action. Every clause carries information; the parenthetical needsReview reference anchors it to list_catalog. Minor room for tightening but 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?

No output schema exists, and the schema fully covers all three parameters, so the description focuses on the state transition and workflow, which it does well. It omits any mention of return values or confirmation scope side effects, but annotations carry the mutation safety signal.

Complex tools with many parameters or behaviors need more documentation. 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 itemId, workspaceId, and idempotencyKey are fully documented in the schema. The description merely restates the itemId single-vs-all behavior already present in the schema, adding no new syntax or format detail. 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 (confirm) and resource (catalogue items), and explains the state being changed: items arrive UNCONFIRMED with needsReview: true until confirmed. This clearly separates it from siblings like create_catalog_item, update_catalog_item, and list_catalog.

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

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

Gives a clear condition for use ('after checking them with the user') and disambiguates the two modes: pass itemId to confirm one, omit it to confirm every pending item. It references list_catalog as the source of items but does not explicitly state when NOT to use it versus update_catalog_item.

Agents often have multiple tools that could apply. Explicit usage 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 context beyond the annotations: the token is single-use, valid for 30 minutes, scoped to this connection, and the execution is verbatim to the quote. What's missing is the failure surface — what happens if the token expired, was already consumed, or the underlying call fails — which matters for a money-spending path even with idempotencyKey documented 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?

Two sentences, front-loaded with the flow and ending on the safety prohibition, with zero filler. The first sentence is syntactically dense ('Runs what a quote was for' plus an embedded clause about needsConfirmation) and takes a second read, which costs it the top mark.

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

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

For a two-parameter confirmation tool with no output schema, the description supplies everything an agent needs to call it correctly: the precondition, the token source, the alternative invocation path, the expiry window, the single-use scope, and the consent requirement. Return behavior is implied (the quoted tool's result) and the schema's idempotencyKey note covers retry handling.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes further by explaining the provenance of confirmToken (it comes from the needsConfirmation quote) and by presenting the argument-replay-plus-confirm:true alternative to the token. It does not restate the idempotencyKey contract, but the schema already covers 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?

Names a specific action (executing exactly the tool+arguments that were quoted) and anchors it to the needsConfirmation/confirmToken handshake, which no sibling tool does. An agent can immediately tell this apart from the spend tool it is confirming: one produces the quote, this one consumes the token.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 the exact trigger (a prior response returned needsConfirmation with a confirmToken and the user agreed), an explicit alternative route (re-call the original tool with the same arguments plus confirm: true), and a hard prohibition ('Never call it without the user's yes to that quote'). When-to-use, when-not-to-use and the alternative are all stated.

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

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

Goes well beyond the annotations by enumerating every side effect: slot availability check, person/room assignment, Google Calendar event creation, contact creation or update with custom fields and a 'booking' tag, and an outbound branded confirmation email with .ics attached. That outbound-email consequence is exactly the kind of externally visible effect an agent must know before invoking a non-read-only tool.

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

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

Front-loaded with the purpose and the partySize rule before the long side-effect sentence, so an agent can stop reading early. The side-effect sentence is a dense run-on that could be split, but every clause carries operational information rather than filler.

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

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

For a 10-parameter, no-output-schema mutation tool with nested 'answers', the description is nearly complete: it covers prerequisites, side effects, contact card persistence and notification behavior. It stops short of saying what is returned or what happens when the slot is no longer free, which an agent handling failures would want.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds conditional meaning by telling the agent to pass partySize for restaurant tables or activities and how diners/participants are counted, and by tying answers to the business's intake field keys. The remaining parameters (with, workspaceId, idempotencyKey) 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 ('Book an appointment') and immediately scopes it as 'on behalf of the business (for example one that came in by phone)', which separates it from the public booking page and from sibling tools like list_appointments and cancel_appointment. The purpose is unmistakable without opening the schema.

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

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

Explicitly names the trigger case (appointments taken by phone) and names an exclusion: paid services are not charged here because the business takes payment itself, only the public page charges online. It also adds a procedural precondition, 'Confirm the details with the user before calling it,' and points at get_booking_availability / get_booking_settings as 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 only mark it as a non-read-only, non-idempotent write; the description adds real behavioral context beyond that: the flow is ALWAYS created inactive, graph is validated on save, and certain node types are unavailable here. The inactive-by-default + mandatory review/enable cycle is exactly the kind of trait an agent cannot get from 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 the two modes, then the workflow. The middle sentence cataloguing what a flow can do (tag contacts, enroll in sequences, public comment replies) is dense and partly tangential to invoking this tool, costing some tightness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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-param tool with nested objects and no output schema, it covers creation modes, validation, inactive default, scope limitations, and the follow-up workflow. It never hints at what the call returns (e.g. the new automation id), 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 83% (baseline 3), and the description still adds meaning: 'Without graph it creates an empty one to fill in later; with graph it validates and saves the whole thing' clarifies the graph parameter's two contracts. Trigger semantics are largely left to the schema, which already documents them 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?

Specific verb+resource ('Create a chatbot flow for the connected accounts') and it spells out the two creation modes (empty vs. validated full graph). It never names the obvious sibling create_automation_from_template, so the agent must infer the difference from context rather than being told.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 post-creation workflow naming the alternatives to use next ('review it with preview_automation and enable it with set_automation_active after the user agrees') plus a clear exclusion ('Steps that call external services are not available here'). Both when-to-use-next and what-is-not-supported are stated.

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

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

Annotations only declare it is non-read-only, non-idempotent, and non-destructive. The description adds the critical non-obvious behavior that the flow is Created INACTIVE, plus the prerequisite call and the two follow-up tools needed to finish the job. This is behavioral context beyond what annotations convey.

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

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

Three sentences, purpose front-loaded, then parameter semantics, then the call sequence. No filler; each sentence carries distinct, actionable information.

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

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

Given a 6-param tool with nested objects and no output schema, the description covers prerequisites (list_automation_templates), post-creation state (inactive), and the activation path. 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 the baseline is 3, but the description adds meaning: overrides rewrites any field of any node (greeting, question, tags, buttons), and trigger replaces the trigger entirely, with the intent that "the flow comes out configured instead of generic." This is useful overlay beyond the schema's structural 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 precise verb+resource: "Instantiate a template as a new flow, adapted to this business." This clearly separates it from siblings like create_automation (blank flow) and duplicate_automation (copy of an existing flow). An agent knows exactly what the tool produces.

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

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

Explicitly prescribes the workflow: call list_automation_templates first for node ids/values, review the created flow with preview_automation, then enable it via set_automation_active. It names the exact alternatives at each step rather than leaving sequencing 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 annotations, it discloses that runs leave content as DRAFTS, send an email, never publish, and consume AI credits at specific rates. It also explains that confirm: true is needed to create the plan active and that without it the plan is saved PAUSED, plus when the first run occurs.

Agents need to know what a tool does to the 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 tool's purpose and key constraints, and every sentence carries useful information about credits, drafts, confirm, and first-run timing. It is dense with caps and parentheticals, making it less scannable than it could be, but not 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 complex 12-parameter creation tool with no output schema, the description covers the essential behavior: schedule, draft output, email notification, credit costs, confirm gating, paused default, and first-run timing. No important agent-facing call context is missing.

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

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

Schema coverage is 100%, so the schema already documents all parameters; baseline would be 3. The description adds behavioral meaning to confirm (paused without it, activation requirement) and withImages (biggest cost driver), plus notes accountIds come from list_accounts, which goes beyond the schema text.

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

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

The description states a specific verb and resource: saving a recurring Autopilot setup that runs daily, weekly, or monthly. It distinguishes this from run_autopilot by emphasizing recurring scheduling and draft-only output, so an agent can tell it apart from sibling autopilot 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?

It gives clear context for use: create a plan that runs on its own, get user agreement on credits before passing confirm: true, and otherwise the plan is saved paused. It does not explicitly name alternatives like run_autopilot or activate_autopilot_plan, but the condition for active versus paused creation is well specified.

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

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

Annotations already declare readOnly=false, openWorld=true, idempotent=false and destructive=false, so the mutation profile is known. The description adds a genuinely useful side effect — a Google Calendar is created when Calendar is connected — plus the business-time-zone interpretation of hours. It does not discuss duplicate-creation risk on retry or what is returned, leaving the idempotency story entirely to 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?

Front-loads the core action and packs semantics into five dense sentences with little filler. The trailing restaurant sentence is slightly tangential but earns its place as a domain-specific modeling rule rather than restating 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 nested mutation with no output schema, the description covers purpose, side effects, time-zone semantics and the restaurant variant well. It never states what a successful call returns (e.g. the new resource id needed for update/delete), which is the main remaining gap since no output schema exists.

Complex tools with many parameters or behaviors need more documentation. 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 does add meaning beyond the schema for 'spots' with concrete examples (1 for a person, 6 for a class) and ties spots/partyMin/partyMax to the restaurant table-type model, which is real added value, but the remaining parameters are left 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?

Opens with a specific verb and resource: 'Add a person or room that can be booked', and immediately scopes what the object carries (weekly hours, days off, spots). It implicitly separates itself from create_booking_service by noting services are assigned on the service (resourceIds), though it never names a sibling tool directly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 context for when this shape applies, including the restaurant modeling rule ('add one per table type') and the routing hint that service linkage belongs on the service object, not here. It stops short of explicit exclusions such as 'to change an existing resource use update_booking_resource'.

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

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

Goes beyond the annotations by warning that the service is public immediately and that the price/charge should be confirmed with the user first, and by disclosing that `charge` is refused unless Stripe is connected. Annotations already cover readOnly/openWorld/idempotency, so this added side-effect disclosure is the valuable layer.

Agents need to know what a tool does to the 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 required fields (name, durationMin) and then walks through the optional concepts; nearly every clause carries parameter-specific information rather than filler. It is a single dense paragraph, so it reads as a wall of text where light structuring would aid 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 19-parameter creation tool with no output schema, it covers the consequential fields — charge, partyMode, videoMode, resourceIds, buffers — and flags the user-confirmation requirement. Minor fields (active, imageUrl, workspaceId, idempotencyKey) are left to the schema, which is adequate since those carry their own descriptions.

Complex tools with many parameters or behaviors need more documentation. 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 genuine meaning: it groups 19 parameters into a coherent narrative (buffers, price as free text, who performs it, where, category/photo, online charge) and supplies examples such as 90-minute sittings for slotStepMin. Some of the partyMode/videoMode text duplicates the enum descriptions.

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

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

States a specific verb and resource — adding a bookable service that appears on the public booking page — which immediately scopes it to the booking domain. It never explicitly distinguishes itself from the closely-named sibling create_booking_resource, so sibling differentiation is only implicit (services vs. resources).

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 routing guidance for optional choices: use partyMode "seats" for tours/classes, "tables" for restaurants, resourceIds from get_booking_settings, and omit resourceIds for anyone. It does not say when to use this versus update_booking_service or create_booking_resource, so it stops 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?

The annotations declare destructiveHint=true, implying potentially destructive updates. The description directly contradicts this by stating the broadcast is created as a DRAFT and 'nothing goes out until send_broadcast', so the tool itself has no destructive effect. This is an annotation 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?

Three sentences, front-loaded with purpose, then draft status, then network limitations. Every sentence adds necessary context without repetition.

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

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

For an 8-parameter tool with no output schema, the description covers purpose, draft behavior, network constraints, and the next step (send_broadcast). It leaves individual parameter details to the rich schema, which is reasonable, but does not reconcile the contradictory destructiveHint annotation.

Complex tools with many parameters or behaviors need more documentation. 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 88%, so the schema already documents most parameters in detail. The description adds network policy constraints (Instagram/Facebook disallowed, WhatsApp template required), but these are usage-level rather than per-parameter semantics. Baseline 3 applies.

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

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

States a specific verb and resource: 'Create a mass message to the CRM contacts of one account.' It also distinguishes the output as a draft, setting it apart from send_broadcast and other creation 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?

Explicitly says nothing goes out until send_broadcast, naming the alternative. It also gives network-specific when-not conditions: Instagram and Facebook do not allow broadcasts, and WhatsApp requires an approved template.

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

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

Annotations cover the write/no-destroy profile, and the description adds genuinely useful behavioral context beyond them: prices here are the ones quoted to customers, so the value must be formatted for display. It doesn't mention permissions or what happens on duplicate names, but the customer-facing price impact is a real, non-obvious trait.

Agents need to know what a tool does to the 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 purpose, then the critical price caveat, then the pointer to list_catalog. No filler, though the price note slightly overlaps 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?

A 9-parameter creation tool with full schema descriptions, clear annotations, and no output schema — the description supplies the key semantic caveat (price is customer-facing) and a listing companion. Adequate 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 every parameter is already documented. The description's price-format advice duplicates the price schema description almost verbatim, adding little beyond the structured data — 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 a product or service to the catalogue") and clarifies the catalogue's role — it feeds answers to customers. It doesn't explicitly differentiate from the nearby create_store_product sibling, but the domain context makes the target clear.

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

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

"See list_catalog for the current items" hints at checking existing entries first, which implies a de-duplication workflow, but there is no explicit when-to-use vs. when-not, and no guidance against the lookalike create_store_product sibling.

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

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

Annotations declare destructiveHint=true and idempotentHint=false, and the description goes well beyond them: it discloses that the automation is created active, Meta's one-message-per-comment limit (text plus up to 3 buttons, no media), the Facebook personal-profile vs Page caveat, and that media or data requests require a prior reply/welcomeMessage. It does not spell out required scopes or error modes itself, deferring those to get_working_rules, which leaves a small gap but no contradiction with 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?

It is front-loaded with what the tool does and what to confirm before calling, which is right for a 29-parameter tool. It is dense but mostly earns its length; the only waste is repeating the get_working_rules pointer at the end after introducing it in the prior sentence.

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

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

For a high-stakes mutation with 29 parameters and no output schema, the description covers the creation lifecycle, platform constraints, the confirmation workflow, scope selection guidance, and where to look for deeper rules. An agent has everything needed to decide whether to call it and how to prepare the arguments correctly.

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

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

Schema description coverage is 93%, so the schema already documents nearly every parameter, including the message/buttons URL split and the scope enum meanings. The description mainly echoes that guidance ('message says what they get', buttons name the thing and carry the exact url) rather than adding new parameter semantics, so the baseline of 3 applies.

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

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

States a specific verb and resource ('comment-to-DM automation') plus the exact trigger and action: a keyword comment or story reply causes one private reply. It scopes the tool to Instagram and Facebook and distinguishes it from generic siblings like create_automation and create_welcome_message by describing the activation lifecycle ('created ACTIVE and answers every matching comment').

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 ('confirm with the user the accounts, the posts, the keyword and the messages first'), an explicit alternative for switching off ('turn it off with set_automation_active'), and a required reading step ('Before creating one, read get_working_rules("comment-to-dm")'). It even routes the agent among scope choices by recommending 'scheduled' first for unpublished posts.

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

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

Annotations only declare write/non-destructive/open-world; the description adds genuine context beyond them — the id is returned, network linking has downstream automation consequences, and "nothing is sent to the person" closes the obvious worry for a contact tool. It does not cover the fact that zero parameters are required, so an agent gets no guidance on the minimum viable payload.

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

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

Four sentences, none wasted: purpose first, linking rule and its consequence second, dedup/alternative routing third, side-effect reassurance last. Parentheticals carry useful qualifiers without derailing the front-loaded main clause.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 tool with no output schema, the description covers return value, side effects, linking semantics, and alternatives. The remaining gap is that every parameter is optional, so nothing states what a minimal valid call looks like or what happens with an empty payload.

Complex tools with many parameters or behaviors need more documentation. 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 per-parameter baseline is 3; the description earns above that by explaining the coupling between accountId and username and the behavioral consequence of omitting them, which the schema only states as terse "Needs accountId" cross-references. It does not address workspaceId or idempotencyKey, but the schema handles those adequately.

Input schemas describe structure but not intent. Descriptions should explain 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 a person to the CRM") with scope qualifiers — manual creation versus contacts auto-created by inbound writers. It also names the return value (created contact with its id) and explicitly distinguishes itself from update_contact, so an agent can separate it from siblings without opening a schema.

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

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

Gives explicit routing: check list_contacts first to avoid duplicates, use update_contact to modify an existing contact, and pass both accountId and username to link to a network. The when-not (without both fields the contact is CRM-only and unreachable by network automations) is stated as a consequence, not 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 openWorldHint=true, so the safety profile is covered. The description adds genuinely useful context beyond that: the coupon is replicated into the business's connected Stripe account (an external side effect), and 'Buyers type the code at checkout' explains the downstream behavior. It does not address error/duplicate-code handling, keeping it short of 5.

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

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

The action ('Create a discount code') does not appear until the third sentence; the two preceding sentences are domain preamble about the chat not selling anything. The content is not bloated overall, but it is not front-loaded and the opening framing is somewhat expendable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 create tool with full schema coverage and no output schema, the description supplies the domain, the two discount modes, and the Stripe replication side effect. It omits return-value behavior and what happens on a duplicate code, but the structured schema plus annotations carry the rest, leaving it nearly complete.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema, including the percentOff/amountOff exclusivity and the idempotencyKey semantics. The description restates the percentage-vs-fixed-amount choice but adds no format or constraint detail beyond what the schema carries, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Create a discount code for the store') and enumerates the two modalities (percentOff vs amountOff plus currency). An agent can tell it apart from list_coupons and set_coupon_active by inference, but the description never names those siblings explicitly, so it stops short of full differentiation.

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

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

The 'Store administration' framing and the note that buyers use the code at checkout give implied context for when this applies, and the scope is clarified as the business's own store rather than a marketplace. However, there is no explicit when-to-use/when-not guidance or routing against siblings like set_coupon_active or update-style alternatives.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, but the description adds real context beyond them: the operation is idempotent with respect to existing slugs and does not mutate contacts. It doesn't cover permission or auth requirements, 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?

Three sentences with no filler. Purpose and type enumeration come first, then the prerequisite check, then the scope clarification — appropriately front-loaded for an agent scanning candidates.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 covers the return value in one clause (all fields including the new slug) and explains how that slug feeds set_contact_field. Combined with the full schema coverage and annotations, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, so all five parameters are documented in the schema itself, including the enum values, options constraint, workspaceId fallback, and idempotencyKey format. The description restates the type list and the slug-derivation behavior but adds little that the schema doesn't already say; 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 ("Define a new custom field for contacts") and enumerates the five supported types with a parenthetical gloss on each. An agent can distinguish this from sibling tools like list_custom_fields or set_contact_field without opening any schema.

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

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

Explicitly routes the agent: "Check list_custom_fields first" and names set_contact_field as the downstream tool that writes values using the returned slug. It also states the no-op condition (existing slug is left as it was) and the scope boundary ("only adds the definition; no contact is changed").

Agents often have multiple tools that could apply. Explicit usage 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 write/non-destructive/non-idempotent/non-open-world, so safety is already covered. The description adds behavior the annotations cannot convey: keywords are normalized (stored without spaces, in capitals), URLs are validated as https, and file deliverables require a prior upload_media round-trip whose URL is reused. It does not describe the failure modes or what the created record looks like.

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

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

Roughly four sentences, purpose front-loaded, followed by validation and the file-upload workflow, ending with a docs link. Every sentence carries information; the parenthetical examples are slight padding but not wasteful. Tight enough for a 7-parameter tool.

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

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

With no output schema the description could say what is returned after creation, and it does not; it also says nothing about duplicate-handling beyond the schema's idempotencyKey. Otherwise it covers purpose, validation, the file workflow, keyword normalization, and workspace scoping is handled by the schema, so an agent has what it needs to call 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, but the description genuinely adds semantics: it explains the kind="file" branch and how url must be sourced from upload_media in that case, and it explains that keyword is transformed rather than stored verbatim. These are cross-parameter relationships the per-field schema text does not state.

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

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

Specific verb+resource ('Add a deliverable a DM can send') with concrete examples (guide, template, file, link) and an explicit framing of what this resource is for — the thing a keyword call-to-action promises. That framing cleanly separates it from list_dm_resources/update_dm_resource/delete_dm_resource and from create_comment_to_dm, which configures the keyword rather than the deliverable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 operational conditions: links must be https, and for a FILE the agent must first call upload_media and pass its returned url with kind "file". This is real when/how guidance tied to an alternative tool. It stops short of stating exclusions (e.g., use update_dm_resource to modify an existing resource instead of creating a duplicate), so it is not a full 5.

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

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

Annotations already declare the mutation and open-world profile, so the description's main contribution is 'It is public as soon as it is saved' — a genuinely non-obvious fact that there is no draft/review state and the change is immediately customer-visible. It leaves out limits on existing links and any auth/verification requirement, so it is good rather than exhaustive.

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

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

Two sentences, zero filler, with the core operation first and the visibility caveat second. Every clause carries information the agent did not already have. Nothing is buried or repeated from 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 5-parameter mutation with no output schema and full annotation coverage, the description covers what is created and the immediacy of the effect, which is what an agent most needs before writing. It is slightly thin on preconditions (verification status, existing-link limits) given this is an open-world, non-idempotent write.

Complex tools with many parameters or behaviors need more documentation. 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 earns an extra point by glossing the placeActionType enum in natural language ('book, order, reserve, shop online') and identifying uri as the destination, letting the agent pick a valid action kind without opening 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 (Add) plus resource (action link on the GBP listing), with the valid action kinds enumerated inline ('book, order, reserve, shop online…') and the required destination URL named. An agent can distinguish this from update_gbp_action_link and delete_gbp_action_link from the verb alone, though neither sibling is named explicitly.

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

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

There is no statement of when to use this versus update_gbp_action_link, no prerequisite (e.g. listing verification), and no note on how many action links a listing may hold. The only guidance-adjacent content is the visibility warning, which is a consequence rather than a selection 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?

Goes well beyond the annotations: it discloses the PENDING_APPROVAL outcome and who can approve, that each network is validated before sending and failures surface as explained errors, and the subtle comment-to-DM claim semantics (draft never claims, scheduled only when it actually publishes). These are exactly the non-obvious behaviors an agent needs.

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

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

Mode selection is front-loaded in the first two sentences, then approval, validation, and the automation caveat. Every sentence carries information, though the final comment-to-DM note is narrow enough that it slightly lengthens an already dense paragraph.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 tool with nested objects and no output schema, the description covers mode selection, approval side effects, validation errors, and idempotency is handled in-schema. It does not say what a successful call returns (post id/status), which is the main remaining 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 100%, so the baseline is 3; the description earns above that by explaining the interaction between scheduledFor, publishNow and suggestedFor (draft-only proposal, ignored when the others are set) — semantics not obvious from individual field docs. Remaining params 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 ('Create a post for one or more social accounts') and the title clarifies it also schedules/publishes. An agent can tell what it does, but the description never names its closest sibling (schedule_post) or explains why this tool already covers scheduling, leaving a small ambiguity against a very large sibling set.

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

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

Explicitly maps parameter states to outcomes: empty scheduledFor/publishNow means draft, scheduledFor means schedule, publishNow means immediate. That is clear when-to-use guidance for the three modes. It stops short of routing the agent to alternatives like schedule_post, bulk_create_posts, update_post, or validate_post when those would be more appropriate.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false, idempotentHint=false), so the description carries a lighter burden. It adds the shared/team-reuse context, but says nothing about duplicate handling, permissions, or length limits beyond what the schema documents.

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

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

Two short sentences, with the core action front-loaded before the parenthetical sibling reference. The second sentence is motivational rationale that is useful but not strictly necessary, so it falls just short of maximally lean.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 single-object create call with 100% schema coverage and no output schema, the description supplies enough: what it makes, where it is used (inbox), and a pointer to the listing tool. Return values need not be described, though duplicate/error behavior is unaddressed.

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

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

Schema description coverage is 100%: title, text (with 5000-char cap), and idempotencyKey retry semantics are all documented in the schema. The description adds no parameter-level meaning, so the baseline 3 applies.

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

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

The description states a specific verb and resource ('Save a reply the team can reuse in the inbox'), which clearly maps to creating a reusable reply template, and it points at the related read tool list_saved_replies. It does not explicitly contrast with the sibling write tools (update_reply_template, delete_reply_template), but those distinctions follow from the names.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 through the rationale ('turning a good answer into a template'), and list_saved_replies is offered as a companion read. However, it never says when to use this versus update_reply_template or delete_reply_template, nor any prerequisites, so the guidance is suggestive 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 only cover the safety profile (not read-only, not idempotent, not destructive). The description goes further: it explains that the AI classifies into topics, that only a well-written topic description makes classification work, and that unassigned rules are silently ignored. That is genuine operational context beyond the annotations.

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

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

A single front-loaded paragraph that opens with the core action, then the mechanism, then the caveat. Dense but every sentence carries information; 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 mutation tool with no output schema, the description covers the action, the classification behavior, the assignee requirement, and points at list_team for valid IDs. The idempotency behavior is handled in the schema, so little 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 meaning by tying assignUserId/assignTeamId to list_team as the source and by stressing that the topic description drives classification quality. This is light but real value on top of the schema's own parameter docs.

Input schemas describe structure but not intent. Descriptions should explain 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: adding a topic and its assignee for automatic handoff routing, and even explains the classification mechanism. It is clearly separable from siblings like update_routing_rule, delete_routing_rule, and list_routing_rules, though it never names them explicitly.

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

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

It gives the scenario context ('when a handoff is set to assign automatically') and notes that a rule with no assignee is ignored, which implies a prerequisite. However, it never states when to reach for this tool over update_routing_rule or list_routing_rules, leaving the when-to-use choice 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?

Beyond the annotations (readOnlyHint=false, openWorldHint=true) it discloses substantial runtime behavior: X polled every 6 hours, news once a day, no account connection required, news sourced via Google News with the brand's own site excluded, and that 'opportunity' mode only drafts replies for user approval and never posts on its own. That is exactly the mutation-safety context an agent needs and cannot get from the structured fields.

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

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

Purpose and platform scope are front-loaded, and the dense single paragraph carries mostly load-bearing detail (cadence, plan gating, approval-only drafting). A few nested parentheticals and the Reddit-API aside add length without helping the call decision, but nothing is badly out of order.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 creation tool with no output schema and full schema description coverage, the description covers what is created, where it runs, how often, and the plan prerequisite. It stops short of saying whether the search is active immediately on creation and whether duplicate searches or a count limit are handled.

Complex tools with many parameters or behaviors need more documentation. 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 platform, query operators, kind and idempotencyKey, setting the baseline at 3. The description adds real meaning on top — X queries are passed through untouched and only word-containing posts are kept, and the brand's own site is excluded from news — though it restates the operator list from the schema.

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

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

The description states the effect concretely — watching for brand/competitor/topic mentions on X and NEWS — with explicit scope limits (no own website, Instagram/TikTok/YouTube not watched) that distinguish it from list_saved_searches or list_mentions. The creation verb itself is implied by the name/title rather than stated in the body, which keeps it just 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?

It gives clear conditions for use (watch brand, competitor or topic on the two supported platforms) and explicit exclusions — Instagram, TikTok, YouTube unwatched, Reddit paused — plus the 'Inferno plan only' prerequisite and that no connected account is needed. It never names a sibling tool as an alternative or says when to prefer an existing search over a new one.

Agents often have multiple tools that could apply. Explicit usage 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, openWorld), the description adds real behavioral traits: it is created PAUSED, nothing is delivered until enrollment plus activation, and it auto-stops for unsubscribers. It also discloses an API limitation (no media) that would otherwise cause silent failures.

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

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

Two tightly written sentences: the first front-loads what the tool is and its delivery model, the second packs the paused state, activation requirement, and media limitation. 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 mutation tool with no output schema, the description covers the lifecycle, enrollment dependency, activation step, and a key limitation, which is nearly everything needed to call it correctly. It does not mention the response shape, though with no output schema declared that is a minor gap.

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

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

Schema description coverage is 80%, so the schema already carries most parameter meaning (accountId, idempotencyKey, stopIfTheyReply, steps). The description only adds the semantic that each step fires after its delay, which loosely maps to delayMinutes; the baseline 3 is appropriate.

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

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

States a specific verb (Create) and resource (timed message sequence / drip) plus its scope (for subscribers of one account). It distinguishes itself from the closest sibling by explicitly naming create_broadcast as the tool for media, so an agent can route without opening either schema.

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

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

Gives explicit when-to-use context: created PAUSED with nothing sent until contacts are enrolled and it is activated (activate_sequence), and a clear when-not alternative (use a broadcast when media is needed). The lifecycle and the follow-up activation tool are both named.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, non-idempotent), so the burden is light. The description adds meaningful behavioral context beyond them: products start unpublished, payment flows to the business's own Stripe account, and files/lessons must be added by a human in the Ignix app.

Agents need to know what a tool does to the 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 draft state in the first clause, then layers type semantics. The opening store/billing framing is slightly verbose but earns its place by defining the domain boundary; every sentence carries 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 15-parameter, no-output-schema tool this is close to complete: it describes the draft lifecycle, the type taxonomy, pricing caveats for memberships/lead magnets, and where files/lessons get attached. What is absent (response shape, per-param formats) is largely carried by the 100%-covered 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 100%, so baseline is 3, but the description goes further by explaining the semantics of the type enum (download = digital files, lead_magnet = free in exchange for email, bundle = combined downloads/courses, membership = recurring) and noting that price is per-period for memberships. This meaningfully augments the terse schema field descriptions.

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

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

States a specific verb and resource ('Create a store product') and adds crucial scope: it is created as a DRAFT that nobody can buy. It also fixes the domain ('the business's own link-in-bio store in Ignix'), which separates it from the many generic create_* siblings.

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

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

Gives clear context for when this applies (store administration, drafts only) and names the follow-up tool publish_store_product as the gate before anything is purchasable. It does not contrast against update_store_product or list_store_products, so an agent must infer update-vs-create for existing products.

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

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

Annotations already declare this is a non-read-only, non-destructive, open-world write, so the safety profile is covered. The description adds that the ticket carries a number, subject and priority, and that the note is private to the team, but says nothing about permissions, whether the originating conversation is modified, or what is returned. It is also silent on idempotent retry behavior beyond what the schema already documents.

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

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

Two sentences, front-loaded with the core action and resource, no repetition. The clause 'so it stops living only in the inbox' is motivational flavor rather than actionable detail, but it is short enough not to be a real cost.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 five-parameter mutation with no output schema, the description plus the annotation block covers the essentials: what is created, the notable fields, and the safety profile. The gaps — required conversationId semantics, priority levels, and the fact that 'number' is a result rather than an input — are modest but real.

Complex tools with many parameters or behaviors need more documentation. 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 40%: only note and idempotencyKey are documented, and the description reinforces the note's private-to-team nature. It names subject and priority, which partially compensates, but the required conversationId has no description in either place, and 'number' is mentioned as if it were an input when it appears to be a generated value.

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

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

The description states a specific verb and resource ('Promote a conversation to a support ticket') plus the fields it carries, so an agent can distinguish it from generic creation tools like create_post or create_contact. It does not name a sibling it is not, so it stops short of full differentiation.

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

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

Usage is implied by 'promote a conversation to a support ticket' — you use it when an inbox conversation needs to become tracked work. There is no explicit when-not guidance and no routing away from the closely related sibling add_conversation_note, which is a plausible alternative when the agent only wants to annotate a thread.

Agents often have multiple tools that could apply. Explicit usage 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 writability and open-world scope but say nothing about consequences; the description supplies the critical side effect that the message is "switched on at once, so it reaches real people from then on" and names the return payload (id, active). It also discloses the uniqueness failure mode, so the agent knows a second call will be rejected rather than silently overwritten.

Agents need to know what a tool does to the 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 riskiest fact (it goes live immediately, confirm with the user first) is placed early, and every sentence carries distinct information. Slightly dense with nested parenthetical sibling references, which costs a little readability for an otherwise four-sentence block.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 three-parameter mutation with no output schema, the description covers consequence, uniqueness constraints, return values, and sibling alternatives. Nothing needed to invoke it 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; the description still adds constraint-level meaning by tying accountId to the one-per-account rule and the rejection behavior. It says nothing about idempotencyKey, but that parameter is fully documented in the schema with retry guidance, so no real gap.

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

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

States a specific verb and resource ("Create the message one account sends automatically to each person the first time they write to it") and defines the exact trigger semantics of a welcome message. This is clearly separable from update_welcome_message, delete_welcome_message, and create_reply_template among the many sibling create_* 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?

Explicitly routes the agent: check list_welcome_messages because a second one is rejected, use update_welcome_message to change an existing one, and use send_welcome_to_existing_contacts to reach existing contacts. It also adds a procedural precondition — confirm the text with the user first — which is an actual when-to-use gate.

Agents often have multiple tools that could apply. Explicit usage 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 the write/non-idempotent/open-world profile, lowering the bar. The description adds one genuinely useful fact beyond them: the flow is created as a draft, not published. It says nothing further about permissions, limits, or what happens to the created object.

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

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

Two short sentences: the action first, then the workflow chain and a docs link. Every clause earns its place with no filler.

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

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

For a create tool with no output schema, the agent gets the action, the draft state, the follow-up sequence, and a docs URL — enough to invoke and chain correctly. It lacks any note on what the call returns or failure modes, so it is not fully complete.

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

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

Schema description coverage is 100% and the parameter docs are detailed (categories examples, idempotencyKey retry semantics), so the schema carries the load. The description adds no parameter meaning of its own; baseline 3 applies.

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

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

States a specific verb and resource ('Create a WhatsApp Flow') and scopes it with 'as a draft', which separates it from publish_whatsapp_flow and send_whatsapp_flow. It does not explicitly name a sibling it is not, so it stops short of the top band.

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

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

'Next steps: upload_whatsapp_flow_json, preview_whatsapp_flow, publish_whatsapp_flow' tells the agent where this tool sits in the flow-building sequence, which is strong implicit when-to-use context. It does not state any exclusions or contrast with alternatives such as create_whatsapp_template, so it is not a full 5.

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

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

Annotations declare the write/open-world/non-idempotent profile, and the description adds genuinely new behavior: a new template is created as PENDING and is unusable until APPROVED via an external Meta review. That lifecycle and the delay it implies are not derivable from annotations or 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?

Three tight sentences, front-loaded with the action and destination, then the approval constraint, then placeholder syntax. Every sentence carries distinct information with no filler.

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

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

For a 6-parameter creation tool with a fully documented schema and no output schema, the description covers the approval lifecycle, placeholder rules, and the follow-up tool for checking status. Return shape is unspecified but no output schema exists to anchor it, making this a minor gap.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds ordering semantics for placeholders ('{{1}}, {{2}} in the body, in order') and notes they are filled at broadcast send time — detail the schema's bodyText description does not 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?

States a specific verb+resource+destination: 'Submit a WhatsApp message template to Meta for approval.' This clearly separates it from list_whatsapp_templates, delete_whatsapp_template, and the unrelated flow tools among the many 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?

Explains the condition that makes templates necessary ('WhatsApp requires to write to someone outside the 24h window') and points to list_whatsapp_templates for status. It does not explicitly compare against adjacent creation tools like create_whatsapp_flow or create_reply_template, so it stops short of full when/when-not routing.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds domain context (what a workspace owns) but says nothing beyond the schema about rename side effects, name conflicts, or permissions. With annotations carrying the mutation semantics, this is an adequate but not rich disclosure.

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

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

A single sentence that front-loads the primary verb and folds the secondary operation and domain definition into one compact clause. No filler or redundancy.

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

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

For a low-parameter mutation tool with no output schema, the description covers purpose but leaves behavioral questions open: what the created/renamed workspace returns, whether names must be unique, and what a rename affects. It is minimally viable rather than complete.

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

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

Schema description coverage is 67%: workspaceId and idempotencyKey are documented in the schema, while the required 'name' parameter has no description anywhere. The description restates the rename purpose but does not clarify which parameter drives it or add format/uniqueness constraints, so it contributes little 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 clear verb (create) plus an alternate operation (rename) on a specific resource, and parenthetically defines what a workspace contains (accounts, library, knowledge), which removes ambiguity about the domain object. It does not name or distinguish itself from the closest sibling list_workspaces, but the operation is distinct enough to identify 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?

The create-vs-rename fork is implied but not operationalized in the description; the agent must read the schema to learn that supplying workspaceId triggers rename. No when-not guidance or reference to alternatives is given, though the tool's role is fairly self-evident from its name.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true, so the safety/idempotency profile is covered. The description adds genuine behavioral context beyond that: the state change halts execution and spending, and it is non-destructive ('Nothing is deleted'). It does not explain what happens to already-queued work, which would be the next useful detail.

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

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

Two short clauses, zero waste, with the core effect front-loaded and the non-destructive reassurance second. Nothing to trim.

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

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

For a state-changing mutation tool with no output schema, the description is adequate but thin: it does not say whether the plan can be resumed (activate_autopilot_plan) or what happens to in-flight or scheduled items. Annotations cover safety and idempotency, which limits the gap, but more operational context would help.

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

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

Schema description coverage is 100%, and planId, workspaceId, and idempotencyKey are each documented in the schema (including the idempotency retry semantics). The description adds no parameter-level detail, 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 (pause) and resource (plan) and describes the effect: 'it stops running and spending.' The closing 'Nothing is deleted' distinguishes it from the destructive sibling delete_autopilot_plan. It does not, however, explicitly name activate/delete/update as the sibling set, so the differentiation is inferential rather than spelled out.

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

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

There is no explicit when-to-use guidance or named alternative; the agent must infer that this is the reversible counterpart to delete_autopilot_plan. The 'Nothing is deleted' clause implies when NOT to use delete, which is useful context, but no direct routing statement is present.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds real value on top by stressing the operation is permanent and by steering the agent to a non-destructive alternative, which is exactly the context an agent needs before an irreversible call. It does not cover what happens if the automation is still running or whether dependent nodes are affected.

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

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

Two short sentences, zero filler, with the destructive scope stated first and the safer alternative second. Every sentence earns its place and the ordering matches the agent's decision order.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 permanent-delete tool with no output schema and annotations covering destructuring and idempotency, the definition is nearly sufficient: it states the effect, its permanence, and the preferred alternative. It could still mention recovery impossibility or required scope/permissions, and it leaves flowId provenance 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 50%: idempotencyKey is thoroughly documented in the schema, while flowId has no description at all. The description adds nothing about parameters, so it neither compensates for the undocumented flowId nor explains where to obtain one. Given the single undocumented parameter is largely self-explanatory from context, a baseline 3 is appropriate.

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

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

States a specific verb and resource plus the permanence qualifier: 'Delete a flow permanently.' It also names the softer alternative (set_automation_active), which helps discriminate from sibling delete_* tools. Minor ambiguity: it calls the resource a 'flow' while the tool and siblings use 'automation', and delete_whatsapp_flow exists in the same sibling set, so a small amount of terminological clarification is missing.

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

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

Explicitly tells the agent when NOT to use this tool and names the alternative that should be preferred: 'Turning it off with set_automation_active is usually enough.' That is a concrete routing rule, not implied usage, and it is the most decision-relevant sentence in the definition.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is partly covered. The description adds genuinely useful context beyond that: existing drafts survive the deletion, the action is irreversible, and user confirmation is required. It does not say what happens to future scheduled runs, which would have completed the picture.

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

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

Three short sentences, front-loaded with the action, then the non-obvious side effect, then the safety prerequisite. No filler and every sentence carries 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 destructive tool with no output schema, the description covers irreversibility, the survival of existing drafts, and the confirmation requirement. The remaining gap is the effect on future/scheduled plan output and the relationship to deactivate_autopilot_plan.

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

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

Schema description coverage is 100% and all three parameters are documented in the schema, including idempotencyKey retry semantics. The description adds no parameter-level information, 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 (delete) and resource (a plan), and the title disambiguates it as an Autopilot plan. It is clearly distinguishable from delete_sequence/delete_automation by the plan resource, though the description body itself just says 'a plan' and relies on the title.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 one real usage rule: confirm with the user first before invoking. However, it never addresses the key alternative, deactivate_autopilot_plan (and update_autopilot_plan), so the agent gets no guidance on when deletion is preferable to merely deactivating.

Agents often have multiple tools that could apply. Explicit usage 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=false, so the safety profile is given. The description adds genuinely new behavioral context: the linked Google calendar is NOT deleted, the action cannot be undone, and user confirmation is required. These details go beyond the annotations and materially affect the decision.

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

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

Two tight sentences with no filler; the core action leads and the two critical caveats (calendar preservation, irreversibility/confirmation) follow. Every clause earns its place.

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

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

For a destructive delete with full annotation coverage and a fully documented schema, the description supplies the crucial side-effects an agent needs (what is preserved, irreversibility, confirmation). No output schema exists but return values are unimportant for a delete, leaving little 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 resourceId, workspaceId and idempotencyKey are all fully documented in the schema itself. The description's 'person or room' loosely reinforces resourceId but adds no syntax or sourcing detail beyond what the schema already states, 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?

The description names a specific verb and resource ('Remove a person or room') and scopes it ('take it off every service'), which clearly separates it from delete_booking_service and update_booking_resource. An agent can distinguish what this deletes without opening the schema.

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

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

The 'confirm with the user first' instruction implies the tool's place in a workflow, and the irreversibility note signals caution. However, it never names an alternative (e.g. update_booking_resource for edits) or states when to prefer it over siblings, so routing guidance is only implied.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: existing booked appointments are preserved, and the action is irreversible and requires user confirmation.

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

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

Three short sentences, each earning its place, with the destructive action and its side effect front-loaded before the confirmation instruction.

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

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

For a single-required-param delete with full schema coverage and no output schema, the definition covers the key unknowns: what is removed, what survives, and irreversibility. Only the return shape (whether anything is returned) is unaddressed, which is a minor omission.

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

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

Schema coverage is 100%, so serviceId, workspaceId, and idempotencyKey are all documented in the schema itself. The description's mention that serviceId comes from get_booking_settings only repeats the schema text, adding no new semantic detail. 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 ('Remove a service from the booking page'), scoping it to booking services rather than resources or settings. It does not explicitly distinguish itself from the nearby delete_booking_resource or update_booking_service, but the resource and target are unambiguous.

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

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

Gives a real prerequisite ('serviceId from get_booking_settings') and a procedural guardrail ('confirm with the user first'). It stops short of naming alternatives, e.g. deactivating or updating the service when the user actually wants to hide rather than delete it.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, so the irreversibility is structured data. The description reinforces 'cannot be undone' and adds the confirmation step, which is genuinely useful, but it does not explain side effects (e.g. whether posts referencing the item break) or why idempotencyKey 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?

A single tight sentence with the identifier source front-loaded and the danger warning attached; no filler or repetition.

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

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

For a destructive, three-parameter tool with full schema coverage and no output schema, the description covers the essentials: what it does, where the id comes from, and the irreversible/confirm-first requirement. Only the downstream impact of deletion is left unstated.

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

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

Schema description coverage is 100% and the schema already says itemId comes 'from list_catalog', so the description's parenthetical duplicates structured data. No extra syntax, format, or workspace-id guidance is added, 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 (Remove) and resource (catalogue item), and identifies where the required identifier comes from (list_catalog). An agent can distinguish it from update_catalog_item and create_catalog_item without opening any schema.

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

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

Gives a clear procedural precondition — retrieve itemId from list_catalog and confirm with the user before deleting — but never names an alternative tool or explains when deletion is the right choice versus updating or deactivating.

Agents often have multiple tools that could apply. Explicit usage 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=false, so the safety profile is partly covered. The description still adds real context beyond that: irreversibility ('Cannot be undone'), a required user-confirmation step, and the downstream effect of stopping automations that send the resource.

Agents need to know what a tool does to the 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, zero filler, and the ordering is well chosen: what it deletes, what it affects, then the irreversible-action warning. Each sentence carries distinct 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 single-target delete with no output schema and full annotation coverage, the description plus schema covers everything an agent needs to call it safely. The only residual note is that the schema's idempotencyKey retry mechanism sits slightly at odds with idempotentHint=false, which the description does not reconcile.

Complex tools with many parameters or behaviors need more documentation. 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% – resourceId's origin, workspaceId's default, and the full idempotencyKey retry semantics are all documented in the schema. The description repeats the list_dm_resources origin of resourceId but adds nothing new about the other two parameters, 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 ('Delete a deliverable') and identifies the source of the required ID (list_dm_resources), which separates it cleanly from create_dm_resource/update_dm_resource by verb. It stops short of explicitly naming a sibling alternative, but the action is unambiguous.

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

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

Gives an explicit precondition ('confirm with the user first') and signals the consequence that makes deletion a deliberate choice ('Automations that send it stop having it'), implying when this is the right call. It does not state when NOT to delete or point to a non-destructive alternative such as update_dm_resource.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true, so safety and replay semantics are covered. The description adds genuinely new behavioral context - that editing reverts to default behavior until a new style is saved - rather than repeating the annotations. It stops short of saying whether the deletion is reversible or what happens if no style exists.

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

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

Two short sentences, action front-loaded before the consequence. The parenthetical "(when the user asks)" is slightly redundant with the imperative voice, but nothing else is wasted.

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

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

For a simple destructive delete with no output schema and annotations already carrying the safety profile, the description supplies the key post-condition. It omits error/not-found behavior and reversibility, which are minor gaps for this complexity level.

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

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

Schema coverage is 50%: idempotencyKey is fully documented in the schema, while workspaceId has no description. "this workspace's" lightly implies the workspaceId parameter's meaning but adds no format or constraint detail beyond the schema. Baseline 3 with partial coverage 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?

Specific verb+resource ("delete... saved edit style") scoped to the workspace, and clearly distinct from its nearest siblings get_edit_style, save_edit_style and delete_style_examples. An agent can select 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?

The parenthetical "(when the user asks)" gives a trigger condition, which is more than most delete tools offer, but there are no exclusions or named alternatives (e.g., distinguishing it from delete_style_examples or from simply not using a style). Usage is implied rather than fully specified.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, so the danger profile is covered structurally; the description's added value is the human-confirmation requirement, which annotations cannot express. It never states whether removal is permanent or recoverable, and it does not reconcile the idempotencyKey parameter with the idempotentHint=false annotation.

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

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

Two tight clauses with zero filler; the destructive action is stated first and the safety instruction second. It is appropriately sized for the operation, though front-loading "Confirm with the user first" before the parameter hint would read even better.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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-parameter destructive mutation with full schema coverage, no output schema, and annotations carrying the safety profile, the description covers purpose, parameter provenance, and the required human-in-the-loop step. The only real gap is not saying whether the removal is irreversible or how to restore the link.

Complex tools with many parameters or behaviors need more documentation. 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 all four parameters (including idempotencyKey's retry semantics and locationId fallback) are documented in the schema itself. The description only repeats the source of "name" already noted in the schema, adding no new parameter meaning. 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?

Specific verb and resource ("Remove an action link") plus a scope qualifier ("from the listing"), which cleanly separates it from create_gbp_action_link and update_gbp_action_link in the sibling list. It does not explicitly name those siblings, so it falls just short of 5.

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

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

"Confirm with the user first" gives an explicit precondition for invocation, and "(name from get_gbp_listing)" routes the agent to the sibling tool that supplies the identifier. There is no statement of when NOT to use it or what to do instead if the link should only be modified, so it stops short of 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?

Although annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=true, the description adds the substantive behavioral facts: exactly what is destroyed (every learned passage), that website/social/profile sources are re-learned on the next refresh or profile save, and that human confirmation is required. This is context an agent cannot infer from the annotations.

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

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