SelieeAI

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

Annotations already declare destructiveHint=true and openWorldHint=true; the description goes beyond them by spelling out the real-world cost consequence (daily budget starts spending) and an approval requirement ('Requires human approval; never auto-approved') that appears nowhere in the structured fields. It doesn't cover failure behavior if the campaign isn't published, or what the response contains.

Agents need to know what a tool does to the 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 sentence with a bracketed tag prefix; the cost consequence and approval caveat land last where they read as the most important warnings. 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 money-spending mutation with no output schema, the description covers the key agent-facing facts: identifier options, the spending effect, the external-provider target, and the approval gate. Missing only the not-published failure case and any return-value expectation.

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

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

Schema coverage is 0%, so the description must carry the identifier semantics – it names both `ads_campaign_id` and `ads_campaign_uuid` and signals they are interchangeable ('or'). That is real added meaning, but it doesn't state that at least one is required (both default to null, 0 required params) nor any format detail for the UUID.

Input schemas describe structure but not intent. Descriptions should explain 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 ('Switch a published ad campaign ON at the provider') plus the concrete consequence 'it starts spending its daily budget'. This clearly distinguishes it from pause_ads_campaign and publish_ads_campaign, which occupy adjacent lifecycle stages.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 precondition 'published ad campaign' tells the agent the campaign must already be published (i.e. use publish_ads_campaign first), and the human-approval note sets the operational context. It stops short of explicitly naming pause_ads_campaign or publish_ads_campaign as alternatives, so it earns a 4 rather than a 5.

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

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

Annotations already flag this as a non-idempotent, destructive write, so the description adds real value beyond them: a hard cap of 10000 per call, and the non-obvious behavior that duplicates and invalid addresses are counted rather than rejected. It doesn't describe what the response contains or whether existing subscribers are modified.

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

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

One compact passage, front-loaded with the write marker and the core action, then the input modes. The nested parentheses and embedded JSON example make it denser than ideal, but no sentence 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 destructive write with no output schema and no parameter descriptions in the schema, the definition covers what an agent needs: target list, input shapes, batch limit, and duplicate/invalid handling. Missing only edge cases such as unsubscribe status and required permissions.

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

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

With 0% schema description coverage, the description carries the burden well: it documents the `items` element shape (bare address or `{"email","vars"}`), explains `source="customers"`, and notes that the two list identifiers are alternatives. It leaves open whether the id/uuid are mutually exclusive and whether both can be omitted.

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

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

The description opens with a specific verb and resource ('[write] Adds addresses to a saved list') and identifies the target by `email_list_id` or `email_list_uuid`. This clearly separates it from sibling tools like `remove_email_list_members` and `list_email_list_members`.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 explains the two input modes (explicit `items` vs `source="customers"`), which is useful usage context, but never states when to prefer this tool over siblings such as `import_email_campaign_recipients` or when not to call it. Usage is implied rather than explicitly 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 flag destructiveHint=true and readOnlyHint=false, but the description adds the real behavioral payload: the scope of effect spans pending recipients in every campaign plus all future sends. It stops short of saying what happens on a duplicate address or whether the action is reversible, which matters given idempotentHint=false.

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

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

Two tight sentences with the write tag and effect front-loaded; the second sentence carries non-redundant routing information. 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 single-parameter mutation with no output schema, the description covers the semantic consequence of the call well. Minor gaps remain around duplicate handling and error cases, but nothing an agent needs to select and 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 0%, so the description must compensate. Saying it 'puts an address' on the list implies the single required parameter is an email address, but no format, single-vs-multiple, or validation detail is given beyond that inference.

Input schemas describe structure but not intent. Descriptions should explain 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 ('Puts an address on the unsubscribe list') and immediately explains the effect (pending recipients skipped, future campaigns blocked). It doesn't name a sibling tool, but the closing line distinguishes it from removal, which is handled elsewhere.

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

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

'Removing an address stays in the panel' implicitly rules out the inverse operation and signals there is no delete counterpart in this toolset. However, there is no explicit statement of when to choose this over list_email_unsubscribes or how it relates to add_email_list_members; the guidance 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 already cover the safety profile (destructive=true, readOnly=false, idempotent=false), and the description adds genuinely new context: default match type BROAD, the enum of allowed match types, duplicate-skipping behavior, and a human-approval gate. The duplicate-skipping note sits in mild tension with idempotentHint=false, but it is not a direct contradiction since deduplication is about entries within the list, not repeated-call effects.

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

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

A single dense sentence with no filler; the action verb comes first, the `[publish]` category tag is front-loaded, and each parenthetical clause carries distinct information (identifiers, match type, dedup, approval). Nothing 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 destructive, approval-gated mutation with four parameters and no output schema, the definition covers identifiers, defaults, and dedup, but says nothing about the approval workflow (sync vs async, how to confirm), return values, or limits on how many keywords can be added. Adequate but with clear gaps an agent would likely hit.

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

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

With schema description coverage at 0%, the description carries the parameter burden and mostly does: it names the two identifier parameters as alternative list selectors, and gives the match-type values (EXACT / PHRASE / BROAD) plus the default. It leaves gaps — it never states that at least one list identifier is required, nor does it describe the required `ads_negative_keyword_texts` array or any batch-size limit.

Input schemas describe structure but not intent. Descriptions should explain 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 ("Add keywords to a negative keyword list"), which is unambiguous and clearly a write operation. It does not name or contrast with the read-side sibling `list_ads_negative_lists`, so sibling differentiation is only implicit via the name and the `[publish]` tag.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 rather than stated: it tells you the target list is identified by either `ads_negative_list_id` or `ads_negative_list_uuid`, and that a human approval step is required before committing. There is no explicit when-to-use/when-not guidance or pointer to alternatives.

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

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

Annotations already flag write/destructive/non-idempotent, and the description adds substantial context beyond them: the operation is queued, a worker downloads serially oldest-first, the merchant is notified, and the return includes both queued rows and rejected URLs. The gap is that with destructiveHint=true, it never says what is destroyed or whether an existing file at the same path/file_name is 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?

Front-loaded with the [write, queued] marker, then constraints, then async behavior, then return shape and follow-up tool. The extension list and size cap are verbose but each is load-bearing for a validation-heavy 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?

No output schema exists, and the description compensates by describing the return (queued storages_remote_upload_id rows plus rejected URLs) and the async follow-up path. It is nearly complete; only the overwrite/collision behavior implied by destructiveHint 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 coverage is 0%, so the description must carry the load and it does: path is the folder with empty meaning zone root, urls is capped at 20, file_name only applies when exactly one URL is given (otherwise the URL's own filename wins), and the two account identifiers are presented as alternatives. That is more than the bare schema conveys.

Input schemas describe structure but not intent. Descriptions should explain 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 files to a storage account — and immediately distinguishes the mechanism: 'from public https URLs instead of uploading bytes.' An agent can tell this apart from upload/create-folder siblings without opening the schema.

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

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

Gives explicit entry conditions (public https URLs only, not byte uploads), hard limits (max 20 URLs, 100 MiB each, enumerated allowed extensions), and routes the agent to list_storage_remote_files for progress tracking. Effectively an exclusion list as well as a use case.

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

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

Annotations already declare write, destructive, non-idempotent, so safety is covered. The description adds the genuinely useful operational constraint of a 100-number batch ceiling and clarifies the compliance meaning (do-not-call list), which the annotations cannot convey. It stops short of saying what happens on duplicates or whether re-adding an existing optout errors, 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?

Two short sentences, zero padding, with the write marker and the batch limit front-loaded before the parameter hint. Every clause 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, non-idempotent write with no output schema and zero schema coverage, the definition covers purpose, the batch cap and one parameter. Missing are duplicate/already-opted-out behavior, number formatting requirements, and what the call returns, which matter for a suppression-list mutation.

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

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

With 0% schema description coverage the description must carry all parameter meaning, and it only explains voip_optout_country (calling code that completes numbers starting with 0), implicitly hinting at number format. The required voip_optout_numbers format (national vs E.164, separators) and voip_optout_note are left undocumented anywhere.

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

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

States a specific verb and resource: putting numbers on the do-not-call list. The compliance effect is explicit, so an agent knows the outcome is a suppression list entry, not, say, a campaign target import. It does not name its natural sibling (list_voip_optouts) for verification, keeping it below a 5.

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

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

The '[write]' tag and the 'at most 100 per call' cap imply the context of use, but there is no explicit statement of when to prefer this over import_voip_campaign_targets or when to check list_voip_optouts first. No exclusion or prerequisite guidance is given.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's added value is the operational detail: results are sorted by spend and capped at 500 rows. That row cap is exactly the kind of limit an agent needs and cannot get from annotations. It does not describe what happens when the cap is exceeded or how the sorting tie-breaks.

Agents need to know what a tool does to the 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 sentence with no filler; the scope, filter convention, ordering and row cap all appear up front. The dense parenthetical is slightly compressed but every clause 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 10-parameter, all-optional reporting tool with no output schema, the description covers the core dimensions and the row limit. It leaves out date format expectations, valid provider values, and what the default behavior is when no filters are supplied, which an agent would need to call it confidently.

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

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

Schema description coverage is 0% across 10 parameters, so the description must compensate. It does partially: the parenthetical explains that website, account and customer filters accept either an id or a uuid, which disambiguates six of the ten parameters. But since/until formats, provider values, and campaign_key semantics are left entirely undocumented.

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

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

States a specific resource and granularity: ad performance broken out per provider campaign over a date range. The '[read]' prefix plus 'sorted by spend' makes clear it is a reporting read, and 'per provider campaign' distinguishes it from siblings like ads_insights_summary, ads_insights_timeseries and ads_insights_websites. It stops short of naming those siblings 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?

Usage is only implied by the scope phrase 'for a date range' and the listed filter dimensions. There is no statement of when to prefer this over ads_insights_summary or ads_insights_timeseries, and no mention of prerequisites or defaults when dates are omitted.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context about the default date window and the id-or-uuid filter convention, but it does not explain the return shape or whether results are grouped/paginated.

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

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

The description is a single compact sentence with the core purpose front-loaded, and every clause carries information. The nested parentheticals make it slightly dense but not wasteful.

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

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

For a tool with 10 optional parameters, 0% schema description coverage, and no output schema, the description is only partially complete. It covers the date default and id/uuid filter convention, but omits campaign_key semantics and does not describe the returned totals beyond saying they are per provider.

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

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

Schema description coverage is 0%, so the description has to carry parameter semantics. It compensates partially by explaining that website, account, and customer filters take an id or a uuid, and by specifying YYYY-MM-DD with a last-30-days default for the date range, but it leaves campaign_key and provider semantics under-specified.

Input schemas describe structure but not intent. Descriptions should explain 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 resource and scope: ad spend/result totals for a date range, plus the same totals per provider. It is clear enough to distinguish this as a summary aggregation tool, but it does not explicitly contrast itself with sibling tools such as ads_insights_campaigns, ads_insights_timeseries, or ads_insights_websites.

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

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

The description gives contextual details like the default last-30-days range, but it does not state when to use this tool versus the other ads_insights_* siblings or when not to use it. There is no explicit 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?

The annotations already declare write, destructive, and open-world behavior, and the description adds important context: the provider operation is read-only while local ads_insights rows are upserted. It does not spell out exactly what existing local data may be overwritten, but it identifies the mutated resource and clarifies the provider-side safety.

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

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

The description is a single front-loaded sentence with no wasted text. The [write] marker, account selector, provider read behavior, local upsert effect, and days default are all packed efficiently.

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

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

For an open-world, destructive sync tool with zero schema descriptions and no output schema, the definition covers the essential call behavior and side effects. It does not describe return values or error conditions, but the annotations carry the safety profile and the description covers the main operational semantics.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning; it identifies ads_account_id or ads_account_uuid as the account selector and explains that days defaults to the worker's sync window. It still does not clarify whether one account identifier is required or how id versus UUID should be chosen.

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

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

The description uses a specific verb and resource: pulling one ad account's recent insight window from the provider now, with local upserts. The provider-sync framing distinguishes it from sibling insight-query tools such as ads_insights_summary or ads_insights_timeseries.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 implies the tool is for refreshing data from the provider rather than querying local insights, but it does not explicitly say when to choose it over sibling insight-query tools or when not to use it. The usage context is clear enough but not fully routed.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds useful behavior beyond that: results are ordered by date and can be split per provider. It omits what happens when since/until are null (are defaults applied, or all-time?), and says nothing about result limits or pagination for a potentially large daily series.

Agents need to know what a tool does to the 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 bracketed sentinel ('[read]') plus one dense sentence with no waste; the core purpose is front-loaded and the filter semantics follow immediately.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 11-parameter tool with zero schema descriptions and no output schema, the description covers the ambiguous id/uuid duality and the split flag, which are the highest-risk unknowns. However, campaign_key is never mentioned, date formats and null-date behavior are unstated, and no hint is given about the returned point structure, leaving meaningful gaps.

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

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

Schema description coverage is 0% across 11 parameters, so the description must carry the load — and it does the most valuable part by explaining that the website, account and customer filters accept either an id or a uuid, which is otherwise completely opaque from param names alone. It also clarifies split_by_provider and the date-range pair. It leaves campaign_key entirely unexplained and gives no date format for since/until, so it does not fully compensate.

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

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

States a specific verb and resource — 'daily ad spend/result points for a date range' — plus ordering by date and an optional provider split, which distinguishes it from the summary and campaigns siblings by granularity. It does not name 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?

The phrase 'daily ... points' and 'ordered by date' implies this is the choice for trend-over-time analysis, but there is no explicit when-to-use, when-not-to-use, or pointer to ads_insights_summary / ads_insights_campaigns as alternatives. Usage must be inferred from the word 'timeseries'.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds useful behavior that annotations do not: results are sorted by spend and unmapped spend appears under a null website id. It does not cover pagination, result volume, or what the response rows contain.

Agents need to know what a tool does to the 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 sentence with the read marker and scoping first, then the sorting and null-handling caveats. Dense but every clause carries information; only the redundant "[read]" prefix against readOnlyHint is wasteful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 analytics tool with no output schema and no per-parameter descriptions, the description covers the core filtering semantics and the notable null-website edge case. It leaves gaps on the provider and campaign_key parameters, date formats, and result shape, which matter 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 description coverage is 0% across 10 parameters, so the description has to carry the load. It does meaningfully explain that the website, account and customer filters accept either an id or a uuid, which resolves the id/uuid parameter pairs, and it gives since/until meaning as a date range. However provider and campaign_key are unexplained, and no date format is given.

Input schemas describe structure but not intent. Descriptions should explain 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: reading ad performance per branch website for a date range, which distinguishes it from the campaign/summary/timeseries siblings. It stops short of naming those siblings or stating the boundary explicitly, so an agent must infer the distinction.

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

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

There is no when-to-use vs when-not guidance and no mention of the alternative ads_insights_* tools. The date-range scope implies a reporting use, but nothing tells the agent when to prefer this over ads_insights_campaigns or ads_insights_summary.

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

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

The description does add real behavioral context — chat costs the account's own provider spend and Seliee tokens, and it names the ERR_AI_ACCOUNT_* / ERR_TOKENS_INSUFFICIENT failure modes. But it prefixes the tool with '[read]' while annotations declare readOnlyHint=false and destructiveHint=true, signalling to the agent that this is a side-effect-free read when it is not.

Agents need to know what a tool does to the 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 well front-loaded: purpose and cost first, then the provider/account hint, then parameters and the return/error shape. The parenthetical-heavy parameter block is a little cramped, but no sentence 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?

No output schema exists, and the description compensates by naming the returned keys ({text, provider, account_id, account_uuid, model}) and the error codes for limit and balance failures. For an 8-parameter, cost-incurring tool this is complete enough to call 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 0%, so the description must carry all 8 parameters, and it does: it enumerates provider values, explains account_id vs account_uuid naming, distinguishes message (new turn) from messages (prior turns, oldest first, role user|assistant), and documents system, model default, and the max_tokens <= 8192 cap.

Input schemas describe structure but not intent. Descriptions should explain 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 ('Chat with one of the merchant's AI accounts ... and get the model's reply as text') and explicitly points to list_ai_accounts for account discovery, which separates it from the account-listing and send_chat_message 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 concrete usage context: continue a conversation by resending prior turns each call ('the caller keeps the history'), and use list_ai_accounts to find the account. It does not, however, say when not to use it or contrast with send_chat_message, so it stops short of explicit 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 write, destructive, open-world, and non-idempotent behavior. The description adds important context beyond that: it only queues analysis, returns trend_analyzer_ids for later retrieval, routes video vs. image posts, and caps calls at 5 items. It does not elaborate on destructive effects, auth, or broader rate limits, so it is strong but not 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?

The description is front-loaded with the write action and remains reasonably tight for the amount of workflow detail it covers. The semicolon-heavy parenthetical style makes it slightly less scannable, but no sentence is clearly 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 four-parameter asynchronous write tool with no output schema, the description covers the essential call behavior, inputs, batch limit, prerequisites, and follow-up retrieval. It could say more about the exact response shape beyond returned trend_analyzer_ids, but it is complete enough to invoke correctly.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It does so for all four parameters: source is the platform (today TikTok), media_ids are post IDs such as TikTok aweme_ids, language is the two-letter spoken language, and brief states the analysis purpose.

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

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

The description states a specific verb and resource: sending trend-source posts to content analysis, with video vs. image routing. It explicitly contrasts with the follow-up get_tt_trend_analysis tool, but does not name or differentiate the sibling analyze_tt_trend_media, leaving some ambiguity.

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

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

It clearly explains prerequisites (media_ids are TikTok aweme_ids from search_tt_videos) and the follow-up step (call get_tt_trend_analysis with returned trend_analyzer_ids). It also gives a batch limit of 5 per call, but does not explicitly state when to choose this over the sibling analyze_tt_trend_media.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the description's real added value is the asynchronous model: the call merely queues the job and results must be fetched separately with get_tt_trend_analysis. It also surfaces the batch cap of 5. It does not explain why destructiveHint is true for what reads as an analysis/queue operation, which is the one gap an agent might trip on.

Agents need to know what a tool does to the 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 [write] marker and the output-retrieval path front-loaded — no filler. Slightly dense with parentheticals, but every clause 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?

With no output schema, the description correctly compensates by naming get_tt_trend_analysis as the result path and flagging the async queue behavior. The only shortfall is silence on the optional brief/language controls, which affects output tailoring.

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

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

Schema description coverage is 0%, so the description must carry the parameters. It does well for aweme_ids (origin tool and max 5 items) but says nothing about the optional `brief` and `language` parameters, leaving two of three undocumented in both schema and description.

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

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

The description names a concrete verb and resource — send TikTok posts (aweme_ids) to content analysis — and explicitly scopes it as the TikTok specialization of analyze_trend_media. An agent can tell it apart from the generic analyze_trend_media and from list_tt_trends/list_tt_videos 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?

It states the prerequisite (aweme_ids must come from search_tt_videos), an explicit limit (at most 5), and the follow-up tool to call (get_tt_trend_analysis). The whole call sequence is spelled out, leaving nothing to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. Beyond that, the description adds real value by seeding the concrete stage identifiers (MAIN, SHEET, FACE, BIOMETRIC, LOOKS, OUTFITS, POSES, PROFILE, LOCATIONS) that a caller will need to pass elsewhere, plus the breadth of categories returned. It stops short of describing the response shape (keyed object vs. arrays).

Agents need to know what a tool does to the 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 sentence with the '[read]' tag first and the resource stated immediately. The list is long but each element is a distinct option family, so little is wasted; a slightly tighter grouping would improve it.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 input schema and no output schema, the description carries the burden of explaining what comes back, and it does so by enumerating the option families and stage constants. What is missing is the response structure (how categories map to keys) and any note on caching/staleness or size, which would make it fully self-sufficient.

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

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

The tool takes zero parameters, so the baseline is 4. The description's enumeration describes the returned option domains rather than inputs, which is appropriate for a no-arg catalog call.

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

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

The description clearly identifies the resource: the catalog of option values for the character form, enumerating styles, purposes, types, colours, body types, output formats, stages, providers and suggestions. It is specific about content but never names a sibling (e.g. create_character, get_character, list_characters) to distinguish when to fetch options versus fetch a character.

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

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

Usage is only implied: an agent can infer this is a discovery/enumeration call that precedes create_character or edit_character, but the description never states that, nor does it list any preconditions or exclusions. No alternative tool is mentioned.

Agents often have multiple tools that could apply. Explicit usage 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 real behavior beyond the annotations: it flips <platform>_chat_human=true, records the note and timestamp, and causes agents to leave the chat alone — the exact state mutation and its downstream effect. It does not address reversibility (how to hand a chat back to the bot), batch limits, or partial-failure behavior, which matters given destructiveHint=true and 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?

Two dense sentences with the write marker and payload shape front-loaded, and no filler. The inline pseudo-schema notation is efficient but slightly cryptic compared to plain prose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 a nearly empty input schema, the description supplies the payload contract, the state change, and the operational consequence — enough to call the tool correctly. Gaps remain around what is returned, whether a chat can be released back to the bot, and the destructive annotation's implications.

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

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

Schema coverage is 0% and the chats array is an untyped object, so the description carries the burden — it documents the platform enum (ig|fb|tw|wp) and the chat_id/chat_uuid alternative, which the schema does not. However, the top-level `note` parameter is left ambiguous: the prose mentions note only inside the chat item, so the agent cannot tell whether note is per-chat or a batch-level argument.

Input schemas describe structure but not intent. Descriptions should explain 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 — "Hand conversations over to a person instead of answering" — and the resource scope (chats) is unambiguous. An agent can immediately distinguish this from send_chat_message or comments_assign_to_human without reading 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?

"instead of answering" gives a clear selection condition: use this when a human, not the bot, should take the thread. It does not explicitly name the sibling alternatives (send_chat_message, comments_assign_to_human) or an exclusion, so it stops short of a 5.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered. Beyond that, the description adds real behavioral context: ordering (newest first), scope (per-platform, default all), what a complaint_hint means, and whether a human already took over the thread. That extra context justifies a 4.

Agents need to know what a tool does to the 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 dense sentences with the scope and ordering front-loaded and no filler. The middle sentence's field enumeration is long but earns its place by describing the return shape in the absence of an output 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 read-only listing tool with no output schema, the description enumerates the item fields (platform, chat_id, chat_uuid, account_id, name, last message, time, complaint_hint, takeover status), which is exactly what the missing output schema would have provided. Only `limit` and pagination behavior are 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?

With 0% schema description coverage, the description carries the burden and does most of it: it explains `days` (time window), `platforms` (ig|fb|tw|wp, default all) and `only_hinted` (filter to hinted items). Only `limit` is left unexplained, though its meaning is largely self-evident from the name.

Input schemas describe structure but not intent. Descriptions should explain 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 and resource: read conversations awaiting an answer within the last `days`, newest first, across ig|fb|tw|wp. It also clarifies the tool is not a classifier (the 'complaint_hint' is a match, not a verdict). It does not explicitly distinguish itself from siblings like chats_collect_sales_signals or list_chats, which keeps it from a 5.

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

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

Usage is implied through 'Read the texts yourself to decide which are complaints' and the only_hinted toggle, which tells the agent how to narrow results. However, there is no statement of when to prefer this over chats_collect_sales_signals or list_chats, and no prerequisites are mentioned.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, non-openWorld), and the description adds real behavior beyond them: default to all platforms, newest-first ordering, exactly which fields each item carries, null semantics for customer linkage, how hints are computed (words found in the message), and the caveat that hints are heuristic. It does not mention pagination or any cap behavior for `limit`.

Agents need to know what a tool does to the 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 filter and ordering, then the item shape, then the hint caveat. The field enumeration is dense but earns its place given no output schema. Minor waste in the inline line break and the unrelated 'answer in the language of the message' 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?

There is no output schema, so the description carries the return shape itself and does so field by field, including nullability. With annotations covering safety and three of four parameters explained, an agent has everything needed to call it and interpret the result; only `limit` semantics are missing.

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

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

Schema coverage is 0%, so the description must compensate and largely does: `days` is defined as the recency window on the customer's last message, `platforms` enumerates the allowed codes and states the default-all behavior, and `only_hinted` is defined as keeping items with any hint. Only `limit` is left entirely unexplained.

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

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

States a specific verb and resource with tight scope: conversations whose last message came from the customer within `days`, newest first, across ig|fb|tw|wp. The 'sales signals' idea is made concrete through the returned hints (quote/accept/reject), so an agent can tell it apart from plain listings like list_chats. It stops short of naming the sibling it displaces (list_chats, chats_collect_complaints).

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 sales-signal framing and the `only_hinted` explanation, plus the explicit instruction to read the message and decide rather than trust hints blindly. There is no explicit when-to-use / when-not / use-instead-of guidance relative to list_chats or chats_collect_complaints.

Agents often have multiple tools that could apply. Explicit usage 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 annotations: messages are delivered to real contacts (matching destructive/openWorld), a 50-reply batch cap, the 24h Meta messaging window, the send_wp_template fallback, and a per-reply result shape. This is exactly what an agent needs to avoid failing a bulk send.

Agents need to know what a tool does to the 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 compact sentences, front-loaded with the action and the payload shape, then the delivery constraint and return value. 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?

Covers payload shape, batch limit, delivery semantics, the WhatsApp template escape hatch, and the return granularity despite no output schema. Minor gaps remain on error/partial-failure behavior and auth/permission requirements for publishing to real contacts.

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

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

Schema coverage is 0% and the schema only declares an untyped array of objects, so the description carries the full burden and does it well: it documents the item keys (platform enum ig|fb|tw|wp, chat_id or chat_uuid, message) and the max-50 batch size.

Input schemas describe structure but not intent. Descriptions should explain 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 (send replies) applied to a specific resource (complaint conversations), and the [publish] tag signals the write scope. It is clearly distinguishable from chats_collect_complaints, though it does not explicitly rule out comments_send_complaint_replies or send_chat_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?

The 24h Meta window plus the note that WhatsApp messages outside it require send_wp_template gives an explicit conditional routing rule to a sibling tool. No explicit exclusion against the comments-based sibling, but the context is clear.

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

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

Annotations already establish idempotentHint=true and destructiveHint=false. The description adds real value beyond them: which caches are touched, that the nginx purge only applies once published, and the specific error code raised for slug-less advertisements.

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

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

Two compact sentences, the cache targets front-loaded and the parameter/error detail following. Dense but every clause carries information; 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 cache-invalidation tool with no output schema, the description covers targets, triggering conditions, and the error case. It omits what a successful response looks like and whether elevated permissions are needed, minor gaps given annotation coverage.

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

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

Schema coverage is 0% and neither parameter has a schema description, but the description compensates by telling the caller the two are alternatives ('Pass advertisement_id or advertisement_uuid'). It does not address what happens if both or neither are supplied, which matters since required parameters count is zero.

Input schemas describe structure but not intent. Descriptions should explain 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 (clear), resource (advertisement cache), and scope (every website it runs on), plus the exact cache layers affected: Redis slave list cache and nginx proxy cache of /s/<slug>. This is clearly distinguishable from purging a website-wide nginx cache or a page cache.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 invocation guidance ('Pass advertisement_id or advertisement_uuid') and a failure condition (ERR_ADVERTISEMENT_NO_SLUG when the advertisement has no slug). It does not explicitly name purge_website_cache_all or clear_page_cache as fallbacks, so sibling routing 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 already declare this as a non-read-only, idempotent, non-destructive operation. The description adds useful behavioral context by identifying the specific cache layers affected and the published-state condition for nginx cache clearing.

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

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

The description is compact, front-loads the action and affected caches, and then states the accepted identifiers. Every clause contributes useful 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 relatively simple cache-clearing operation with annotations covering idempotency and safety, the description provides enough context about what is cleared and under what condition. The main remaining gap is the lack of clarity around the optional parameters and whether one identifier is required.

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

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

With 0% schema description coverage, the description partially compensates by saying to pass either article_id or article_uuid, implying the two are alternative identifiers. It does not clarify whether at least one is required, whether both may be supplied, or which takes precedence.

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

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

The description clearly states the verb and resource: clearing an article's cache, including Redis slave-list cache and nginx proxy cache for published articles. This is more specific than the tool name alone, though it does not explicitly contrast itself with similar sibling tools like clear_page_cache or purge_nginx_cache.

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

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

The description implies when the tool applies by naming the caches involved and noting that nginx cache is only cleared once the article is published. However, it gives no explicit guidance on when to choose this tool over alternatives such as clear_page_cache, clear_collection_cache, or purge_nginx_cache.

Agents often have multiple tools that could apply. Explicit usage 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, the description discloses concrete effects: the Redis slave list cache, the nginx proxy cache (AMP included), and the collection's own article/advertisement lists are all invalidated, plus the publication-state condition that governs the nginx purge. It stops short of stating permissions, whether caches repopulate, or what the response looks like. No contradiction with idempotentHint/destructiveHint.

Agents need to know what a tool does to the 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 progressively narrowing to the specific caches, with the parameter hint last. No filler, though the parenthetical '(AMP included)' is the only marginally expendable 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 two-parameter cache-invalidation tool with no output schema, the description covers what is purged and under what condition, which is the information an agent needs to call it safely. The main remaining gap is the absence of usage context relative to sibling purge tools.

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

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

Schema coverage is 0%, so the description carries the burden, and it partially does by telling the caller to pass either collection_id or collection_uuid, implying they are alternatives. It gives no format detail for the UUID, no precedence rule if both are supplied, and no clarification given that neither parameter is technically 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?

States a specific verb+resource ('Clear the cache of a collection') and itemizes exactly which caches are targeted (Redis slave list, nginx proxy, article/advertisement lists), which clearly distinguishes it from page/article/advertisement cache tools. It does not, however, name any sibling alternative 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 explicit when-to-use or when-not-to-use statement, and no routing to the many closely named siblings (clear_article_cache, clear_page_cache, purge_nginx_cache, purge_cache_group). The only conditional given ('once it is published') describes behavior rather than selection guidance.

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

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

Annotations already declare idempotent=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description still earns credit by naming concrete side effects (Redis slave list cache + nginx proxy cache, AMP included) and the conditional 'once it is published' behavior, which the annotations do not convey. It stops short of describing the response or what happens if the page is unpublished.

Agents need to know what a tool does to the 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 primary action and target front-loaded, followed by the identifier requirement. No filler. The parenthetical 'AMP included' is compact and informative rather than noise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 cache-purge mutation with no output schema and zero parameter documentation, the description covers what is cleared and how to identify the page, but omits when to prefer it over the many overlapping purge/clear siblings, what the result looks like, and the behavior when the page is not yet published.

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

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

Schema coverage is 0% and both parameters are optional with null defaults, so the description carries the burden. It does usefully signal that page_id OR page_uuid is acceptable (an either/or identifier choice not expressed in the schema), but it doesn't state precedence when both are given, nor the expected format of page_uuid, nor what happens if neither is supplied.

Input schemas describe structure but not intent. Descriptions should explain 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: 'Clear the cache of a page', with the concrete caches named (Redis slave list cache, nginx proxy cache, AMP included). This clearly identifies the target resource as a page, which implicitly separates it from clear_article_cache and clear_collection_cache, but it never explicitly distinguishes itself from purge_nginx_cache, purge_cache_group, or flush_website_slave_list, which overlap heavily.

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

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

'Pass page_id or page_uuid' is a parameter instruction, not usage guidance. There is no statement of when to call this versus the numerous sibling cache tools (purge_nginx_cache, purge_cache_group, purge_website_cache_all, flush_website_slave_list, get_cache_targets), nor any prerequisite such as needing the page to exist or be published first.

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

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

Beyond the annotations (destructiveHint=true, idempotentHint=false), the description discloses exactly what is modified: the comment rows get <collection>_human=true plus the note and timestamp, and downstream collection skips them. That is real behavioral context a caller could not infer from the structured fields, though it does not say what happens on re-assignment or what permissions are needed.

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

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

Two dense sentences, front-loaded with the write action and the payload shape before the side effect. The parenthetical flag syntax is terse but earns its place; nothing is redundant.

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

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

For a 2-parameter mutation with no output schema and annotations already covering the safety profile, the description supplies the payload structure, the exact side effect, and the downstream consequence — enough for an agent 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?

With 0% schema description coverage, the description supplies the critical payload shape — comments = [{platform: ig|fb|yt, comment_id, note?}] — including the enum values and the meaning of comment_id. It is ambiguous whether 'note' is the per-item field or the top-level note parameter, which is the main 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 action and resource — leaving complaint comments to a person — and immediately clarifies the interaction with the sibling comments_collect_complaints (which will skip them afterwards). An agent can distinguish this from chats_assign_to_human and the other comment tools without opening the schema.

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

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

The '[write]' tag and the note that comments_collect_complaints skips flagged rows imply the workflow position, but there is no explicit statement of when to choose this over e.g. comments_send_complaint_replies or reply_comment, nor any prerequisite 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?

Goes well past the annotations by disclosing exclusions (hidden/held/account's own comments), sort order (newest first), platform default (all), and the full shape of each returned item. The main omission is pagination/limit behavior and the cost of the 100-item default, which matters for a read over social APIs.

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

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

Effects are front-loaded in the first clause, the return shape is a compact enumerated list, and the two closing sentences are operational advice. No sentence is redundant or padding.

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

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

The missing output schema is fully compensated by the inline item enumeration, and the annotations already cover safety. The gaps are the undocumented `limit`/`only_hinted` arguments, which leave the agent guessing about paging and whether hint filtering is available.

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

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

Schema description coverage is 0%, so the description carries the burden and only partly discharges it: `days` ('last `days`') and `platforms` ('ig|fb|yt (default all)') are explained, but `limit` and `only_hinted` are never mentioned, and `only_hinted` is genuinely non-inferable despite `complaint_hint` appearing in the item list.

Input schemas describe structure but not intent. Descriptions should explain 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 with precise scoping: top-level, unanswered comments, newest first, across ig|fb|yt. The word '[read]' plus the explicit filters make it trivially distinguishable from siblings like comments_send_complaint_replies and list_comments_inbox.

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

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

Gives a concrete prerequisite ('Run sync_post_comments first for fresh data') and sets the expectation that the tool does not classify ('Read the texts yourself to decide which are complaints'). It does not name an explicit alternative for the adjacent jobs (e.g. list_comments_inbox vs chats_collect_complaints), so the guidance is strong but not complete.

Agents often have multiple tools that could apply. Explicit usage 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, openWorldHint=true, and idempotentHint=false, so safety context is covered. The description adds useful behavioral detail: replies are visible on the real platform, batches are capped at 50, and one result is returned per reply.

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

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

The definition is front-loaded with '[publish]' and packs the entire nested reply shape, platform enum, batch limit, and return behavior into one dense sentence with no wasted text.

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

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

For a destructive, open-world send tool with no output schema, the description gives the essential input contract and notes that one result is returned per reply. It stops short of describing result fields or permission/rate-limit requirements, leaving a small gap.

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

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

Schema description coverage is 0%, so the description carries the full burden and does so well. It defines the replies array elements: platform enum, post_id or post_uuid, comment_id, message, max 50, and the source of ids.

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

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

The description uses a specific verb and resource — 'Post public replies to complaint comments' — and names the exact platforms (ig|fb|yt). An agent can distinguish this from comments_collect_complaints and unrelated reply tools without opening the schema.

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

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

It clearly ties usage to ids returned by comments_collect_complaints and marks this as a public publish action. It does not explicitly state when to avoid this tool versus siblings like reply_comment or comments_assign_to_human, but the intended workflow is clear.

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

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

Beyond the annotations, the description discloses important behavior: the provider publish is PAUSED, spend requires activation, and a failed publish preserves the draft for retry. It does not cover auth or rate limits, but adds substantial operational context for a write/destructive tool.

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

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

The description is dense but front-loads the core action and paused-publish behavior before platform details. The platform and creative lists are lengthy, but they carry necessary invocation guidance for a multi-provider campaign 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?

For a complex 12-parameter write tool with no output schema, the description covers the main behavioral and parameter requirements across providers. Remaining gaps around a few simple parameters and auth context are minor given the rich annotations.

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

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

With 0% schema description coverage, the description compensates well for the complex parameters by explaining account/website identifiers, goal enums, daily budget currency, platform-specific creative requirements, and META creative variants. It leaves title, start/end date, and custom URL implicit, but the major ambiguities are addressed.

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

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

The description states a specific verb and resource: create an ad campaign draft and publish it paused. It distinguishes this tool from activate_ads_campaign and publish_ads_campaign by explaining the paused state and retry flow.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 clearly explains that the campaign is created paused and cannot spend until activate_ads_campaign, and that a failed publish should be retried with publish_ads_campaign. Platform-specific goal and creative requirements further guide use, though explicit exclusions are not stated.

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

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

Annotations already declare that this is a non-readonly, destructive, non-idempotent mutation. The description adds useful behavior beyond that: new advertisements start as UNPUBLISH, customers may be identified by id or uuid, and tags are lowercased, de-duplicated, and capped at 20. It does not cover authorization, side effects, or response behavior.

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

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

The description is compact and front-loads the core action and initial status. The parameter notes are terse and there is no filler, though the structure could more clearly group required versus optional fields.

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

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

For a 14-parameter mutation with no output schema and 0% schema description coverage, the description is materially incomplete. It gives initial status and a few field formats, but does not explain most parameters or enough of the required fields to let an agent call this confidently.

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

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

Schema description coverage is 0% across 14 parameters, so the description must carry the burden. It explains customer_id/customer_uuid, the FAQ entry shape, and tag constraints, but leaves most parameters undocumented, including required advertisement_title and advertisement_sort plus note, group, poster, country, options, language, and start/end datetime.

Input schemas describe structure but not intent. Descriptions should explain 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, 'Create', and resource, 'advertisement', and adds the important initial status UNPUBLISH. It is distinguishable from edit_advertisement and publish_advertisement by implication, though it does not explicitly name those 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?

There is no explicit when-to-use guidance or named alternative, but 'starts as UNPUBLISH' implies that publishing is a separate step likely handled by publish_advertisement. It does not clarify when to choose this over edit_advertisement or broader campaign creation 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 declare write/destructive/idempotent=false, so the safety profile is covered. The description adds meaningful behavioral context beyond that: end defaults to start + 30 min, status defaults to PENDING with the full allowed set, and `appointment_chat_key` uses a `<platform>:<account>:<chat>` format. It doesn't mention side effects (e.g., customer notifications) or auth requirements, which would push this higher.

Agents need to know what a tool does to the 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 '[write] Create a calendar appointment' core, and every subsequent clause adds a concrete fact (datetime format, default duration, status values, chat key format). Dense but efficient; the parenthetical '(the customer by `customer_id` or `customer_uuid`)' is slightly awkward phrasing.

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

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

For a mutation tool with 8 parameters and no output schema, the description covers the most consequential behaviors (defaults, formats, status values). It omits what happens on success (return value) and the semantics of `appointment_note`/`appointment_title`, and does not address whether creating an appointment triggers any external effect.

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

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

Schema coverage is 0%, so the description must carry the load. It documents the customer identifier choice, ISO 8601 datetime format, default end time, status enum, and chat key format, but leaves `appointment_title` and `appointment_note` completely unexplained. Partial compensation for an 8-parameter schema.

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

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

The description opens with a specific verb+resource ('Create a calendar appointment') and clarifies that the appointment is tied to a customer via `customer_id` or `customer_uuid`. It is clearly a creation tool distinct from `list_appointments`, though it doesn't explicitly name alternatives.

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

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

Usage is implied by 'Create a calendar appointment' and the required start datetime, but there is no explicit when-to-use/when-not guidance or reference to alternatives like `list_appointments` or `edit_*` tools. The agent can infer the purpose but must decide on its own when this tool is appropriate.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, openWorldHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior: the record is created in UNPUBLISH state and setting publish_datetime causes an automatic future publish. It does not mention slug-collision handling or whether website id/uuid is mandatory, which would complete 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 dense sentences, front-loaded with the creation and its resulting state, then parameter semantics. No filler; nearly every clause conveys information. The parameter list is packed into two long sentences, which is efficient though slightly cramped.

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

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

For a 12-parameter mutation with no output schema, the description covers creation state, scheduling side effects, and several parameter groups, which is solid. Still missing are the required fields and any note on whether a website identifier is needed, both of which an agent needs to call this correctly on the first try.

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

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

With 0% schema description coverage across 12 parameters, the description carries the burden and does substantial work: it defines the date format for publish_datetime, explains that website is supplied via id OR uuid, that collections accept ids and/or uuids, and gives the FAQ entry shape {summary, text}. Title, content, slug, keywords, language and description are left undocumented, so some gap remains.

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

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

States a specific verb and resource ('Create a new seliee_article') plus the resulting initial state (UNPUBLISH), which clearly separates it from edit_article or publish_article. It never names those siblings explicitly, so the differentiation is implied 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?

The scheduling sentence ('the article is published automatically on that date') gives useful context about when this tool's behavior extends past creation. However, there is no explicit guidance on when to pick create_article over edit_article/publish_article, nor any statement of prerequisites such as requiring a website identifier.

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

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

Annotations already declare write/non-idempotent/destructive, so the safety bar is lower; the description adds genuinely new behavioral context: the resource is created as a DRAFT, the call is priced (consumes credits), and it returns character_id/character_uuid. The description does not explain why it is flagged destructive (presumably credit consumption), which is the one gap.

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

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

The first sentence is well front-loaded, but the body collapses dozens of field names, enum values and object shapes into one semicolon-chained run-on paragraph with no list structure. Every field arguably earns its place, yet the presentation makes scanning and correct field selection harder than it needs to be.

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

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

For a three-parameter, no-output-schema, draft-creating mutation, the description covers creation requirements, the payload vocabulary, provider/storage wiring, return identifiers, and the follow-up call. It remains slightly incomplete about what DRAFT implies for visibility or publishing downstream.

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

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

Schema description coverage is 0% and the schema is nearly opaque (`character` is an untyped additionalProperties object), so the description carries the full burden — and it does: 2000-char limit on character_description and its mapping to character_prompt, plus field-by-field documentation of character_style, character_type with allowed values, source object shape, AI account keys, and storage keys. Without this text the tool would be unusable.

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

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

Opens with a specific verb+resource ("Create a character") and immediately qualifies it with state ("DRAFT"), which distinguishes it from edit_character, get_character, and the asset-generation siblings. The [write, priced] tag signals the cost dimension up front, so an agent knows this is a billable mutation without opening the schema.

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

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

Gives explicit next-step routing: "Next: queue_character_assets with stage MAIN," which is the key workflow dependency an agent would otherwise miss. It also points at character_options for storage/account selection. It does not explicitly say when to prefer edit_character over this tool, so it stops short of full alternative 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 write/destructive/non-idempotent, but the description adds real context beyond them: the work is queued for a background worker, it must be polled, it is priced, and it returns image_id and image_uuid. The '[write, queued, priced]' tags front-load the cost and async nature, which annotations cannot express.

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

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

The lead clause states the action, scope, and output before any parameter detail, so it is well front-loaded. The optional-parameter block is a dense semicolon-chained run-on that is harder to scan than it needs to be, but each clause 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?

A 9-parameter, high-complexity mutation with no output schema still gets everything an agent needs: required inputs, enums, nested object shapes, default AI-account resolution, the async polling successor to call, and the identifiers returned. Nothing material is missing for calling 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?

With 0% schema coverage the description carries the full burden, and it delivers: image_prompt's 1500-character cap and placeholder syntax, image_aspect's complete enum, and the shape of every opaque nested object (character_assets, image_environment, image_product, image_ai), including the default fallback for image_ai. Only image_title and character_uuids go unremarked, and their meaning is self-evident from the surrounding prose.

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

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

The description names a concrete verb+resource ("One picture of 1-3 READY characters") and scopes it tightly by subject matter, source material ("drawn from their main pictures"), naming conventions in the prompt, and allowed aspect ratios. That makes it distinguishable from generic image siblings like create_image or create_promo_image, though no sibling is explicitly named as an alternative.

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

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

It states prerequisites ("1-3 READY characters"), what to do after the call ("poll get_character_image"), and how to override defaults via character_assets or image_ai. It does not state when to use a different creation tool instead, so the routing guidance is implicit rather than explicit.

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

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

The bracketed '[write, queued, priced]' adds real signal beyond the annotations: this is an asynchronous job that consumes credits. It also discloses a non-obvious behavioural trait — no text is drawn, so the title must be added in an editor afterwards — plus the polling target. It does not explain the destructiveHint=true cost/irreversibility angle beyond the single word 'priced'.

Agents need to know what a tool does to the 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 the operation class front-loaded in brackets and the poll target at the end. Nearly every clause carries information, though the run-on parenthetical about framing is heavier than it needs to be.

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

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

For a 7-parameter mutation with no output schema, it covers the core prompt semantics, aspect handling, the async polling loop and the returned image_id/image_uuid. The remaining gap is the family of optional nested-object parameters, which are delegated rather than described.

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

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

Schema description coverage is 0%, so the description must carry the load: it defines thumbnail_prompt (meaning plus a 1100-character limit), image_aspect (all four values plus the 16:9 default) and constrains character_uuids to 1-3 READY characters. However, image_title, image_ai, character_assets and image_environment are left entirely to a pointer at create_character_image, so several parameters remain undocumented here.

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

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

States a specific verb and resource (create a thumbnail picture for a character) and scopes it precisely: a video/post cover framed with 1-3 ready characters. It differentiates itself from create_character_image by deferring 'other options' there, so an agent can tell the two apart.

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

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

Explicitly says to poll with get_character_image and points to create_character_image for the shared option set, which routes the agent correctly through the workflow. It stops short of stating when NOT to use it (e.g. a plain image with no thumbnail framing) — that is only implied by the framing language.

Agents often have multiple tools that could apply. Explicit usage 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-idempotent, destructive write, so the description's job is to add beyond that — and it does: initial status UNPUBLISH, default publish date is tomorrow, and the website is resolved from either an id or a uuid. It does not say what happens if both website params are omitted, nor how duplicate slugs are handled, which are the main remaining behavioral unknowns.

Agents need to know what a tool does to the 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 dense sentences that front-load the operation and status, then move to the parameters most likely to be misused. No filler, though the parameter notes read as a flat list rather than being ordered by importance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 11-param, no-output-schema create tool, the description covers the non-obvious fields and defaults that an agent could not infer from the bare schema. The gaps (slug constraints, what the call returns, behavior when the website selector is omitted) are real but secondary.

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

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

Schema description coverage is 0% across 11 parameters, so the description carries the full burden and only partially pays it: it explains publish_datetime format/default, the website id/uuid alternatives, and the FAQ object shape. Required params title and slug, plus icon, content, keywords, language, and description, get no explanation (slug's URL/format expectations in particular are left unclear).

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

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

The description opens with a specific verb+resource ("Create a new seliee_collection") and immediately states the initial state (UNPUBLISH), which tells an agent exactly what the call produces. It does not differentiate itself from the many create_* siblings (create_page, create_article, create_template) or point to list_collections/get_collection for verification, but the resource is unambiguous.

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

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

There is no explicit "use this when..." guidance and no named alternative. However, "starts as UNPUBLISH" implicitly signals the follow-up flow (publish via publish_collection, modify via edit_collection), which is useful inferred context. Usage remains 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 already declare destructiveHint=true, openWorldHint=false and idempotentHint=false, so the agent knows this is a non-idempotent write. The description adds the useful fact that creation does not trigger a crawl and that it returns id and uuid, but says nothing about required permissions, whether referenced ids must already exist, or what happens on duplicate creation.

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

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

Two tight sentences, front-loaded with the core action, with the constraint and return value in parentheses and a trailing sentence. No filler, though the second sentence is a flat enumeration that could be clearer.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 mutation tool with no output schema and no parameter documentation, the description is far too thin. It covers the uuid alternation and the return shape but leaves most required inputs—url_list, lengths, research flags—undefined, which an agent cannot infer.

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

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

With 15 parameters and 0% schema description coverage, the description carries the full burden but only explains the id/_uuid pairing for four fields. The four required parameters (url_list, has_research, article_length, research_length) plus language, pass_path_list and pass_domain_list get no explanation at all.

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

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

States a specific verb and resource ('Create a new seliee_crawl_keyword_analyzer entry'), and the parenthetical about running `extract` separately clarifies that this is only the creation step. The resource name is internal jargon and isn't distinguished from list/get/delete siblings explicitly, keeping 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?

The note that crawling requires running `extract` separately in the panel is genuinely useful context about what this tool does *not* do. However, there is no explicit guidance on when to use this versus the list/get siblings or what prerequisites (e.g., existing customer/gservice records) must exist first.

Agents often have multiple tools that could apply. Explicit usage 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, destructiveHint=true and idempotent=false; the description usefully adds that the created record begins in an UNCRITICAL state. It does not explain why creation is flagged destructive, whether duplicates are rejected, or what identity/identifier comes back, so the destructive flag is left uncontextualized. No contradiction with annotations.

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

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

Two tight sentences with the action front-loaded and the dense parameter expansion relegated to second position, which is the right ordering. The '[publish]' bracket tag is ambiguous overhead, but otherwise nothing 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 five-parameter mutation tool with no output schema and rich annotations, the definition covers the billing payload but omits whether the response returns the new customer id, duplicate-name behavior, and the required customer_title. Adequate to call it, not complete enough to call it confidently.

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

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

Schema coverage is 0%, so the description must carry the load. It does well on the hardest parameter, expanding customer_billing's free-form object into the twelve invoice keys it accepts — information available nowhere in the schema. However, customer_title (the only required field), customer_note, customer_email and customer_phone are left to the bare schema titles.

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

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

Specific verb + resource ('Create a new customer') with a distinguishing behavioral note that the record starts as UNCRITICAL. It is clearly separable from edit_customer, delete_customer and lead_submit_to_customer by name, though the description does not explicitly contrast with them. The '[publish]' prefix is cryptic and unexplained.

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

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

No statement of when to use this versus alternatives such as edit_customer (for existing customers) or lead_submit_to_customer (converting a lead). The UNCRITICAL status hint implies a follow-up review step but never says what the agent should do next. Usage must be inferred entirely from the tool 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 write behavior, non-idempotence, and destructiveHint=true. The description adds important context beyond those annotations: the operation creates a DRAFT, requires an ACCEPTED offer, populates fields from the proposal, and does not send anything. It does not explain what destructive aspect the annotation is warning about, but there is no clear contradiction.

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

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

The description is two focused sentences, front-loaded with the write operation and its key precondition, then immediately names the alternative send action. There is no wasted prose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 and no parameter descriptions, the description covers the main creation flow, precondition, and send-vs-draft distinction. However, it leaves the optional note, expire_date, and title-override semantics unexplained, which is a meaningful gap 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 description coverage is 0%, so the description must carry parameter meaning. It explains proposal_id/proposal_uuid as the accepted-offer source, but it does not clarify note, expire_date, or how the optional title parameter interacts with the title apparently copied from the offer.

Input schemas describe structure but not intent. Descriptions should explain 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: prepare a customer contract as a DRAFT from an ACCEPTED offer. It also distinguishes the operation from sending by naming send_customer_contract, so an agent can tell it apart from sibling tools without opening 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?

It explicitly gives the condition for use: the offer must be ACCEPTED, and non-ACCEPTED offers are refused. It also names the alternative action when the goal is to send: use send_customer_contract.

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

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

The description effectively manages the severity indicated by the `destructiveHint: true` annotation by clarifying that the action is merely creating a DRAFT. It also explains complex calculations (totals computed here) and default behavior (currency, dates, template copying).

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

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

The description is extremely dense but highly effective, packing the necessary structural, logical, and operational details into a concise block without 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 complex financial tool involving templates, customer IDs, and calculation logic, the description is complete, covering both the input requirements and the resulting state (draft, non-sent).

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

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

Since schema description coverage is 0%, the description excels by explaining the required object structure of the `items` array. It also clarifies logic for defaults (e.g., tax rate, currency, issue_date).

Input schemas describe structure but not intent. Descriptions should explain 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 tool clearly states its purpose: to prepare an invoice draft for a specific customer. It distinguishes this creation action from the eventual delivery action, directing the agent to the sibling tool `send_customer_invoice`.

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

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

It provides critical guidance on usage by stating explicitly that it only prepares a DRAFT and that no actual communication is sent. This prevents misuse and directs users towards the appropriate workflow.

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

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

Beyond the annotations, it adds that the proposal is created as a DRAFT and that nothing is sent, which is important side-effect context. It also notes that the title defaults from the advertisement, though it does not clarify the destructiveHint=true or idempotentHint=false behavior.

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

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

The description is compact and front-loaded: it starts with the write action and draft status, then explains the key inputs. Every sentence carries relevant information 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 a 9-parameter create tool with no output schema, it covers the core purpose, draft behavior, identifier options, and several field semantics. It could still say more about the note field, required identifier combinations, and what is returned, but the essentials are 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?

With 0% schema description coverage, the description compensates well by explaining the identifier alternatives for customer and advertisement, the amount/currency meaning, the expire_date format, and the title default. It does not explain the note parameter, so it stops short of full parameter coverage.

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

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

The description states a specific verb and resource: preparing a customer offer as a DRAFT, tied to a customer and an advertisement/listing. It clearly distinguishes this from sending by saying 'Nothing is sent: use send_customer_proposal.'

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

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

It explicitly says this creates a draft and that sending is handled by send_customer_proposal. That gives the agent a concrete when-to-use and when-not-to-use rule relative to a sibling tool.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true; the description adds real value on top with the '[write]' marker, the owner-account authorization requirement, the verified-address validation on forward_to, and the explicit return identifiers. It does not cover failure modes (duplicate mailbox, unverified zone) or irreversibility, which keeps it from a 5.

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

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

A single tight paragraph, front-loaded with the write marker and the verb, with each clause carrying distinct information. Slightly dense back-to-back parentheticals cost it the top score but nothing 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 no-output-schema mutation tool, the description covers authorization, key validation, all inputs and the returned identifiers, which is close to sufficient. Missing only error/conflict behavior for a non-idempotent create.

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

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

With 0% schema description coverage, the description must carry all six parameters, and it does: local_part, email_zone_id/email_zone_uuid, display_name, forward_to and signature each get meaning (sender name, copy destination, plain-text signature). The one gap is that it never explains whether the id and uuid forms are alternatives or mutually exclusive.

Input schemas describe structure but not intent. Descriptions should explain 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 (mailbox) plus the exact resulting address shape `<local_part>@<zone domain>`, plus the scope constraint of a single connected e-mail zone. This clearly distinguishes it from list_email_accounts or send_email 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?

Gives prerequisites ('Owner accounts only', forward_to must be a verified Email Routing address) which imply when the call can succeed, but never names alternatives or says when to create a new mailbox vs. reuse/forward an existing one. Usage is inferable 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?

Beyond annotations, the description discloses important behavior: the campaign is created as a draft, nothing is sent until manually started, recipient confirmation is required, variable placeholders are substituted per recipient, scheduling is interpreted after start, and an unsubscribe link is automatically added. These details materially help an agent understand side effects and prerequisites.

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

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

The description is front-loaded with the core draft-creation behavior and then organized around account, body, scheduling, and unsubscribe semantics. It is appropriately sized for an eight-parameter tool, though some sentences are dense and could be slightly tighter.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 eight parameters, the description provides the needed context: it mentions the returned id and uuid, the draft lifecycle, account prerequisites, body/content requirements, variable replacement, scheduling behavior, and unsubscribe handling. This is sufficient for an agent to invoke the tool correctly without additional schema 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 description coverage is 0%, so the description must carry parameter meaning. It explains email_account_id/uuid as the sending account with a connected-mail-zone requirement, covers HTML/text body options, describes {variable} substitution in subject and bodies, explains schedule datetime in ISO 8601 with empty meaning immediate send, and notes the unsubscribe label. It leaves email_campaign_title mostly implicit, but the required title is self-evident from its name.

Input schemas describe structure but not intent. Descriptions should explain 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: 'Creates a DRAFT e-mail campaign', and immediately clarifies that it returns an id and uuid. It also distinguishes the action from sending by explaining that nothing is sent until the campaign is started in the panel, which makes it clear this is a draft-creation tool rather than a send tool.

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

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

It gives clear usage context: the sending account must be active and in a connected mail zone, and the merchant must confirm recipient consent before the campaign is started. It does not explicitly compare against siblings such as edit_email_campaign or send_email, so it stops short of full when-to-use/when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the write nature is structured data, but the description still adds unannotated context: the new list starts empty, and the response carries id and uuid. It says nothing about permissions, duplicate-title handling, or limits, which would be the remaining behavioral gaps.

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

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

A single front-loaded sentence plus a semicolon clause; the write marker, the created state, the return fields, and the follow-up tool all appear before any padding. Nothing 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?

With no output schema, the description usefully discloses that the result contains id and uuid, and it names the follow-up tool, which is what an agent needs to chain calls. The only meaningful hole is the total absence of parameter detail for a tool whose schema has 0% description coverage.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, yet it never mentions email_list_title or email_list_description. An agent gets no guidance on title length, uniqueness, or whether description is optional from the description 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 names a specific verb and resource ('creates an empty saved recipient list') and immediately bounds the scope by saying the list is empty, which is not obvious from the name alone. It distinguishes itself from siblings like add_email_list_members and edit_email_list by stating what state the created object is in.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 an explicit next step ('fill it with add_email_list_members'), routing the agent to the correct follow-up tool instead of leaving it to guess. It lacks an explicit exclusion (e.g. use edit_email_list to rename an existing list), so it's strong but not complete when/when-not guidance.

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

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

Annotations already declare destructive=true, idempotent=false, readOnlyHint=false and openWorldHint=true, so the mutation/safety profile is covered. The description adds real context the annotations don't: a persistent backlink record is created for a specific website and verification requires a separate tracking step. It still omits whether the call is reversible, what happens on duplicate hrefs (relevant given idempotent=false), and permission 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 compact sentence with the resource and scope front-loaded and no filler. The trailing parenthetical about the panel is slightly awkward but carries genuine information about a follow-up verification step.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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, non-idempotent creation tool with zero schema description coverage and no output schema, the description should clarify the required backlink fields and duplicate behavior. It covers the website targeting only, leaving an agent unable to tell what `href_follow` expects or what the call returns upon success.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it explains only 2 of 5: it clarifies that the website is identified by either id or uuid (an either/or relationship not expressed in the schema). It says nothing about `seliee_external_backlink_href` (the sole required parameter), `href_text`, or `href_follow` — the latter being a string whose values (follow/nofollow?) are entirely undisclosed.

Input schemas describe structure but not intent. Descriptions should explain 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 ('Register a new external backlink') and names the scope target (the website given by `seliee_website_id` or `seliee_website_uuid`). It does not explicitly differentiate from list_external_backlinks / delete_external_backlink, but the create semantics plus the website scoping make the operation unambiguous.

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

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

The only usage note is '(run `track` separately in the panel to verify it)', which describes an out-of-band manual step rather than when to choose this tool over siblings like semrush_backlinks or list_external_backlinks. There is no statement of prerequisites (e.g., that a website identifier is effectively needed even though only the href is required) or when not to use it.

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

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

Annotations already flag non-readOnly and destructiveHint=true, but the description adds genuinely non-redundant behavior: the job is queued and priced (costs money, returns an ID rather than a finished asset), and it shares the UGC pipeline. What it does not do is explain what the destructiveHint encompasses or what happens to prior renders.

Agents need to know what a tool does to the 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 the action and the bracketed tags are efficient metadata, and there is little outright filler. But the single run-on sentence with deeply nested parentheticals makes the key constraints hard to parse, and much of the nested-field detail arguably belongs in the schema rather than the description.

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

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

For a 7-parameter, nested-object, no-output-schema write tool, the description covers the core payload and the returned IDs, which is more than most. It is still incomplete for a required nested argument (video_render_target) and for the six supporting parameters, leaving the agent unable to assemble a fully valid invocation from this definition alone.

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

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

Schema coverage is 0%, so the description carries the full burden; it does a strong job on video_ugc, enumerating nested keys, constraints (6000 chars, 30-120s default 60, 1-12 scenes) and even the backing enums. But video_title, video_output, video_keywords, video_language, video_description and especially the REQUIRED video_render_target receive no shape or meaning at all, which is a hard blocker for constructing a valid call.

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

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

States a specific verb and resource ('Create a film from characters and a scenario') and identifies the pipeline relationship ('same pipeline as the UGC video'), which orients the agent among create_ugc_video/create_video siblings. It also states the return identifiers (video_id, video_uuid). It stops short of telling the agent when to pick a film over a UGC video or a plain video, so differentiation is only implicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 '[write, queued, priced]' tags and the reference to plan_film_storyboard as the upstream producer of storyboard scenes imply a workflow and its ordering. However, there is no explicit 'use this instead of X when...' guidance against the several sibling video-creation tools, and no prerequisites (e.g., character must be READY) beyond a passing parenthetical.

Agents often have multiple tools that could apply. Explicit usage 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, openWorldHint=true, idempotentHint=false and readOnlyHint=false, so the agent knows this is a non-idempotent mutating call with external effects. The description adds the useful fact that a tracking record is created, but says nothing about duplicate-URL behavior, what permissions are needed, or what side effects the external Google submission has.

Agents need to know what a tool does to the 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: the action and effect come first, then the identifier-flexibility note. No filler and nothing 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 12-parameter destructive mutation with no output schema, the description covers the action and the id/uuid duality but omits optionality rules, duplicate handling, and any indication of what the call returns (the created indexer's id, presumably). Adequate but with clear gaps.

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

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

With 0% schema description coverage across 12 parameters, the description earns real credit by explaining that website, article, collection, page and customer are each addressable by id OR uuid — that covers 10 of the 12 params. It still leaves open whether those links are optional, whether both id and uuid may be sent, and what the two required string fields mean beyond their names.

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

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

States a specific verb and outcome: "Register a new URL to track for Google indexing." That is clearly distinct from the read/delete/send siblings (list_gservice_indexer, delete_gservice_indexer, send_gservice_indexer), though the description never names those alternatives to reinforce the contrast.

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

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

There is no explicit guidance on when to call this versus send_gservice_indexer or submit_gservice_sitemap, nor any stated prerequisite (does the URL need to exist first? does it need a parent website?). Usage is only inferable from the verb "register."

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the write/destructive bar is covered structurally; the description echoes it with a "[write]" tag and adds genuinely new behavior: the document is created as a DRAFT and requires a separate render_image call to queue rendering. It does not state permissions required, whether an unreferenced draft is garbage-collected, or what a failed create does — meaningful gaps for a destructive write. No contradiction with annotations.

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

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

Front-loaded with the action and DRAFT status, then the project/output split, then the next step and the return identifiers. Dense and largely waste-free, though the parenthetical key list inside the image_output clause is a run-on that is harder to scan than a short list would be.

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

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

For a 6-param destructive write with no output schema, the description supplies what matters most: what the two opaque object params contain, the mandatory follow-up render step, and the returned image_id/image_uuid. The remaining gap — semantics of the keywords/language/description fields and any title-uniqueness constraint — is modest given the free-form object 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 0% and both object params are additionalProperties:true, so the description has to carry the load. It does well on image_output, enumerating width/height/format/quality/background_color/storages_account_id/path keys, and sketches image_project's shape. But image_title, image_keywords, image_language, and image_description get no mention at all, so half the parameter surface remains undocumented.

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

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

Specific verb+resource: "Create an image editor document (DRAFT)", followed by a precise disambiguation of the two nested payloads (image_project = editor document with layers/text/images/effects; image_output = canvas/export settings). That makes the tool's output conceptually clear. It does not, however, differentiate from near-name siblings like create_promo_image, create_infographic_image, or create_character_image, which an agent would need to choose between.

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

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

It gives one clear workflow cue — "Call render_image to queue the server render" — which tells the agent this tool alone does not produce a rendered asset. Beyond that there is no when-to-use guidance, no prerequisites, and no exclusion telling the agent when a different image-creation sibling is the right call. 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 declare readOnlyHint=false and destructiveHint=true; the "[write]" prefix is consistent and reinforces that. Beyond that, the description adds only the lifecycle context (albums get filled by other tools) and nothing about permissions, whether kind is immutable after creation, or what happens on duplicate titles. Adequate but thin given this is flagged destructive.

Agents need to know what a tool does to the 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 write-nature flagged first, then purpose, then valid kind values, then downstream usage. Nothing is padded. Minor cost: the phrasing "Pass the answered images_album_uuid as images_album_uuid" is awkward and refers to a parameter this tool does not have.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 3-parameter tool with no output schema, the description covers the essentials: what it produces, the valid kind values, and how the return value is consumed downstream — which compensates for the missing output schema. It lacks scope details (account/workspace ownership, uniqueness constraints) but nothing that would cause a mis-invocation.

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

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

Schema description coverage is 0%, so the description must carry the load — and it does supply the meaningful part: `images_album_kind` takes MANUAL or STORYBOARD, values that appear nowhere in the schema (no enum is defined). Title and description params are self-evident from their names and go unmentioned, which is acceptable.

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

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

States a specific verb+resource ("Create an album") and immediately defines the resource as "a named group of pictures," so an agent knows exactly what object is produced. It also names the downstream consumers (create_character_image / create_promo_image), which implicitly separates it from plain create_image. It stops short of contrasting with near-siblings like create_storyboard, which is why it isn't 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?

Gives real ordering context: create the album first, then pass the returned images_album_uuid into create_character_image / create_promo_image to populate it. That tells the agent where this tool sits in a workflow. There is no explicit "when not to use" (e.g., vs create_storyboard), so it falls short of a 5.

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

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

Adds materially to the annotations: 'queued' reveals asynchronous execution, 'priced' reveals a credit cost, and the description names the poll target and the returned identifiers. It stops short of explaining what destructiveHint=true means here (e.g. whether image_output_path gets overwritten) or what authorization/account context is required.

Agents need to know what a tool does to the 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 operation profile tags, then the core input semantics, then side effects and intros. Dense but wastes little; only the deferred-parameter clause reads as compression rather than clarity.

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

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

Given 9 parameters including a nested passthrough object and no output schema, the description covers the workflow, async model, and return values adequately. It is still incomplete for correct invocation: the required image_title has no semantics, the image_ai object shape is entirely deferred, and cost/overwrite behavior is only a tag.

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

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

Schema description coverage is 0%, and the description compensates well for topic, layout, language, image_aspect and image_source_url (including enum values the schema itself omits). But it leaves the required `image_title` unexplained and disposes of image_ai, storages_account_id and image_output_path with a bare 'as in create_promo_image', forcing a lookup in another tool's definition.

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

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

States a specific verb+resource (create an infographic) and immediately scopes it: 'An infographic about `topic`... The picture at `image_source_url` is the subject it is about.' This distinguishes it from the many sibling image tools (create_image, create_promo_image, render_image) by defining the two inputs that shape the output.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 bracketed tags [write, queued, priced] plus 'Poll with get_character_image' give an explicit async workflow and point at the companion polling tool. It does not, however, say when to pick this over create_promo_image or create_image, so the routing decision is left partly to inference.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=false, so the mutation profile is covered. The description adds value by naming the return values (lead_id, lead_uuid) and the shape of lead_faqs, but says nothing about defaults (lead_type defaults to DRAFT), whether the lead is published or draft on creation, or permission 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?

Three short sentences, front-loaded with the action and the scoping field, with no filler. Slightly terse given the parameter surface, but well-structured.

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

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

For a 12-parameter create tool with 0% schema coverage and no output schema, the description covers only the FAQ payload and website selectors. It omits the draft-vs-published semantics implied by lead_type's DRAFT default and the meaning of the JSON/content/slug fields, leaving the agent without enough to populate the call confidently.

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

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

Schema description coverage is 0% across 12 parameters, so the description must carry the burden. It explains only lead_faqs ({"summary", "text"} entries) and the two website selector params; nine parameters including lead_type, lead_json, lead_slug, lead_poster, lead_content, and lead_keywords are left entirely undocumented.

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

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

States a specific verb+resource ("Create a new lead (deal form)") and clarifies the website scope via seliee_website_id/seliee_website_uuid. It doesn't explicitly differentiate from near-neighbors like create_lead_submit_event or publish_lead, but the object created is unambiguous.

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

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

No when-to-use or when-not-to-use guidance, and no alternative tool is named. The only contextual cue is that the lead belongs to a website identified by id or uuid, which does not tell the agent when to pick this over edit_lead, publish_lead, or create_lead_submit_event.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=false, so the write/irreversible profile is covered. The description adds real value by specifying the accepted id forms and the ISO-8601 datetime format with a concrete example, but says nothing about whether repeat calls duplicate events or what happens on invalid ids.

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

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

Two short sentences, front-loaded with the action and the target resource, followed by the one format detail an agent would otherwise get wrong. 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?

A destructive write tool with six undocumented parameters and no output schema needs more: the description omits the required title field, the note field, optional end time, and any return/confirmation behavior. The id and datetime guidance helps but leaves the caller to guess at half the 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 0%, so the description must carry the burden. It documents the leads_submit_id / leads_submit_uuid alternative and the datetime format, but leaves leads_submits_event_title (required), the note field, and end_datetime entirely unaddressed in both schema and description.

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

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

The description gives a concrete verb+resource: put a calendar entry (call, meeting, follow-up reminder) on a lead submission. That is far more specific than the tool name alone. It does not, however, distinguish itself from the sibling create_appointment, which plausibly overlaps in function.

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

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

Usage is implied by the framing — attach a calendar entry to a submission identified by id or uuid — but there is no explicit when-to-use statement or exclusion relative to create_appointment or the lead-submit stage tools. An agent must infer the choice from the resource name.

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