XCut AI – Viral Content Research

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

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false), so the bar is lower. The description adds real context beyond them: Markdown is accepted, an unnamed canvas silently falls back to the user's 'From AI apps' canvas, and the call is free. It does not disclose what the response contains (e.g. created note id or target canvas), which is the remaining 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?

Three tight sentences with no filler, front-loading the trigger before the exception. Every clause carries decision-relevant information (accepted payload, default destination, cost, exclusion).

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

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

For a simple single-payload write with no output schema and full annotation coverage, the description supplies trigger, default behavior, cost, and routing to the alternative sibling. The only omission is any hint about what is returned (note id, canvas location) or whether repeat calls create duplicates, given idempotentHint=false.

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

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

Schema description coverage is 100%, so all three parameters are already documented, including the Markdown format and the 'From AI apps' default for canvas_id. The description's mention of Markdown and the canvas fallback therefore largely restates structured data rather than adding syntax or format detail. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Add a note to a canvas') and enumerates the content types it accepts (script, hook list, plan, other text), so the agent knows the intended payload. It also explicitly names the sibling it is not (xcut_add_to_calendar), removing ambiguity within a 36-tool family.

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 positive trigger ('when the user wants a script, hook list, plan or other text saved to XcutAI') plus an explicit exclusion with the correct alternative ('Do not use for calendar posts (use xcut_add_to_calendar)'). Nothing about tool selection is left to inference.

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

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

Annotations declare the safety profile (non-read-only, non-destructive, non-idempotent), and the description adds meaningful non-obvious behavior: the record is saved as a draft unless a status is supplied, setting status never publishes, and the call is free. It does not cover repeat-call/idempotency behavior or what identifying information comes back.

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 with the primary trigger front-loaded, followed by default behavior and the negative constraint. Every clause carries information; nothing is filler.

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

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

Covers purpose, triggering context, default state, and the publish misconception for an 8-parameter mutation tool whose schema is fully documented. Minor omissions remain, such as what happens to unspecified optional fields and whether a post identifier is returned (no output schema exists to answer that).

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

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

Schema description coverage is 100%, including enum meanings and the crucial clarification that status 'published' does not publish. The description's field list (title, platform, type, date, caption, hashtags) largely restates the schema and omits canvas_id, so it adds little beyond what the structured fields already say.

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 ('a planned post saved to their XcutAI content calendar') and enumerates the fields involved, so the agent knows this is a creation tool for calendar entries. The negative clause ('Do not use to publish') sharpens the boundary against posting, though no sibling tool (e.g. xcut_update_calendar_post or xcut_import_post) is named to fully disambiguate the create-vs-modify-vs-import choice.

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

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

Gives an explicit trigger ('when the user wants a planned post saved to their calendar') and an explicit exclusion ('Do not use to publish: XcutAI never posts to social media'), which is a common corner case for this kind of tool. It stops short of naming alternatives for modifying or importing existing posts.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and open-world behavior, so the safety profile is covered. The description adds genuinely new context beyond annotations: the call is free, requires no sign-in, and returns generic (non-personalized) output. It stops short of describing the actual score output structure.

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 usage trigger and each of the four sentences carries distinct information (capability, cost/auth, personalization alternative, exclusion). Slightly dense but no filler.

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

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

For a single-parameter, read-only tool with full annotation coverage, the description covers capability, cost, auth, personalization scope, and exclusions. The only gap is that no output schema exists and the description does not sketch what the returned score looks like.

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

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

There is a single parameter with 100% schema description coverage, including the 50-character minimum constraint. The description adds no syntax or format detail beyond what the schema already documents, so the baseline 3 applies.

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

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

The description names a specific verb (score/analyze) and resource (script) and enumerates the exact dimensions evaluated: hook, pacing, retention risk, and CTA. It distinguishes itself from the broader signed-in XcutAI toolset, though it does not call out a specific sibling like xcut_audit_content or xcut_find_hooks by name.

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

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

It states when to use ('when the user wants a script scored on...'), an explicit exclusion ('Do not use for writing unrelated to social media or marketing content'), and the alternative ('for work based on the user's own posts, canvases or brand, use the signed-in XcutAI tools'). Both the when-to-use and when-not conditions are present, leaving little to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds behavior the annotations cannot: 'Free; no sign-in' and the fact that output is generic versus personalized signed-in tools. That auth/cost and output-fidelity context is genuinely useful beyond structured fields.

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

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

Three short sentences, front-loaded with the 'Use this when...' trigger, then cost/scope, then the exclusion. No redundant or filler text; every sentence carries a distinct routing or behavioral fact.

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

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

No output schema exists, but the description tells the agent the output is 'generic,' which sets return-value expectations. With only two fully-documented params and full annotation coverage, the definition supplies everything needed to invoke the tool correctly, bar a named alternative sibling.

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

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

Schema description coverage is 100%, so both parameters (titles_or_captions, platform) are already documented with defaults, lengths and item bounds. The description only restates the 3-to-10 count already encoded as minItems/maxItems, adding no new parameter meaning. Baseline 3 is appropriate when the schema carries the load.

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

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

States a specific action and resource: a 'consistency check across 3 to 10 of their past titles or captions.' An agent can distinguish this from writing tools like xcut_write_caption or xcut_write_content. It stops short of naming a near-neighbor analysis sibling (e.g. xcut_analyze_script), so it is clear but not fully differentiated.

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

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

Gives an explicit trigger ('Use this when the user wants a consistency check...'), a scope bound (3 to 10 titles/captions), and a negative rule ('Do not use for writing unrelated to social media or marketing content'). It routes own-brand work to 'the signed-in XcutAI tools' but names no specific sibling, leaving the agent to infer which one.

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

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

Annotations already declare readOnly, idempotent, open-world and non-destructive, so the safety profile is covered. The description adds context annotations cannot carry: it is free, requires no sign-in, and its output is 'generic' rather than personalized. The one remaining gap is that 'generic' is never made concrete, so the agent cannot predict the shape of the result.

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 with no filler; the purpose clause leads, followed by cost/auth facts, then routing and exclusion. Every sentence carries information the agent needs.

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, no-sign-in evaluative tool with no output schema, the description covers cost, auth, scope and the key exclusion. The only shortfall is that it never characterizes the return — a viability score, verdict, or suggestions — leaving the agent to guess what comes back.

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?

Only one parameter, and the schema already documents it at 100% coverage ('The niche to check, described in a sentence or two'). The description adds nothing about format, length, or what makes a good niche_description value, so the baseline of 3 applies.

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

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

The description states a concrete outcome — determining whether a niche is viable before committing — which is more specific than the title 'Check niche'. It also names the class of sibling it is not (signed-in XcutAI tools for the user's own content). It stops short of saying what the tool actually returns, so it is clear but not fully self-contained.

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

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

Explicit when-to-use ('when the user wants to know whether a niche is viable before committing'), explicit when-not ('Do not use for writing unrelated to social media or marketing content'), and an explicit alternative ('for work based on the user's own posts, canvases or brand, use the signed-in XcutAI tools'). This is close to ideal routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so safety is covered. The description adds context those fields cannot express: 'Free; no sign-in' (auth requirement) and 'Output is generic' (return quality). It stops short of describing pagination or result shape, but the additions are meaningful.

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

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

Three short sentences, front-loaded with the primary use case and free of filler. Each sentence carries a distinct constraint: use case, auth/output, and exclusion.

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 notes that output is generic, and it covers auth, scope and exclusions for a simple 2-parameter read tool. Only minor gaps remain (no hint about result granularity), so it is close to complete.

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

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

Schema description coverage is 100%, so the schema already defines 'niche' and 'competitor_names' with constraints. The description references niche and named competitors but adds no format or syntax detail beyond the schema, making the baseline 3 appropriate.

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

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

The description states a specific verb and resource — content gaps versus named competitors in a niche — and contrasts it with the signed-in XcutAI tools that operate on the user's own assets. An agent can distinguish this from siblings like xcut_check_niche or xcut_find_outliers by scope alone.

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

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

It gives explicit when-to-use ('when the user wants content gaps versus named competitors'), an alternative route ('for work based on the user's own posts, canvases or brand, use the signed-in XcutAI tools'), and a when-not ('Do not use for writing unrelated to social media or marketing content'). Routing is unambiguous.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false), so the bar is lower. The description still adds two non-schema facts: the call is 'Free' (cost behavior) and it 'Returns its id' (result side, which matters because no output schema exists). It does not cover auth requirements or whether repeated names create duplicates, so it stops short of a 5.

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

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

Three short, front-loaded sentences: trigger, return value, exclusion. No filler, no repetition of the title, and the most decision-relevant information (when to use it) comes first.

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 create tool with no output schema, the description covers the trigger, the negative case, the cost, and the return value. Annotations cover the mutation/safety profile, so nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100% for the single parameter, including examples ('Q4 launch', 'Client: Glow Skincare'), so the schema already carries the semantics. The description adds nothing about the name beyond what the schema states; baseline 3 is appropriate.

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

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

States a specific verb and resource ('Create a canvas' / 'a new, separate XcutAI canvas') and scopes the use case to a project, client or campaign. It also implicitly distinguishes itself from the read siblings by noting that import/write tools pick a canvas automatically, so an agent can tell it apart from xcut_get_canvas, xcut_list_canvases, xcut_import_post and xcut_write_content.

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 gives the triggering condition ('when the user asks for a new, separate ... canvas for a project, client or campaign') and an exclusion ('Do not use just to import or write: those tools pick a canvas automatically'). This routes the agent away from the import_* and write_* siblings without needing to open their schemas.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: deletion should only occur on an explicit user request, which functions as a confirmation/permission gate. It stops short of stating permanence or recoverability, so it is not a full 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?

Two short sentences, zero filler. The positive usage condition comes first and the exclusion/redirect second, which is the right front-loading order for an agent scanning for a decision.

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 one-parameter destructive tool with rich annotations and no output schema, the description covers the essential runtime decision (when to fire it) and the sibling routing. It omits any statement of what happens after deletion or what the call returns, which is a minor gap given no output schema exists.

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

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

Schema description coverage is 100% — the single post_id parameter is documented with a UUID pattern and even names the source tool (xcut_list_calendar). The description adds no parameter information beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb ('remove/delete') and resource ('a post from their XcutAI content calendar'), and explicitly names the sibling it is not — xcut_update_calendar_post. An agent can distinguish this from update/list calendar tools without opening any schema.

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

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

Gives both a positive trigger ('when the user explicitly asks to remove a post') and an explicit exclusion with the redirect ('Do not use to reschedule or edit (use xcut_update_calendar_post)'). This is the exact when/when-not/alternative pattern.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true, so the safety profile is covered structurally. The description adds the prerequisite sourcing chain ('Needs the fact's id from xcut_get_brand'), which the annotations cannot express. It stops short of stating irreversibility or what happens if the id is stale, keeping it at 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 short sentences, zero padding, with the triggering condition front-loaded before the prohibition and alternative. Nothing is redundant with the title or 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 two-parameter destructive delete with full annotation coverage, a rich schema, and no output schema, the description supplies the trigger, the exclusion, the alternative, and where to obtain the required id. Only edge behavior (deleting a non-existent fact, post-delete response) is unstated, a minor gap.

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

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

Schema description coverage is 100% — both canvas_id and memory_id are documented with their UUID pattern and source tool. The description echoes the memory_id provenance but adds no format or constraint detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('remove a saved brand memory fact from XcutAI') and implicitly routes to the right sibling by naming xcut_update_memory as the wrong tool for edits. An agent can distinguish it from xcut_save_memory and xcut_update_memory without opening any schema.

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

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

Gives an explicit trigger ('when the user asks to remove a saved brand memory fact'), an explicit exclusion ('Do not use to change a fact'), and names the alternative tool (xcut_update_memory). This is the full when/when-not/alternative triad.

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

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

Annotations already declare read-only, idempotent, closed-world and non-destructive, so the safety profile is covered. The description adds genuinely new context: it is free, requires no sign-in, the library and topic search are English-only, and the library size (~1,000 proven hooks). That English-only constraint is material and not derivable from structured fields.

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

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

Front-loads the trigger condition, then the return behavior, then the exclusions in a single dense paragraph with no filler. Slightly long but every sentence carries routing or behavioral 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?

There is no output schema, so the description must explain what comes back, and it does: proven hook templates matched to topic, each with slots for the user's subject. Combined with the when-to-use, language constraint and exclusions, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, with topic, limit and category all documented in-schema, so the schema carries the parameter burden and baseline 3 applies. The description only loosely echoes 'matched to the topic' and mentions slots, adding no format or syntax detail beyond what the schema already provides.

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

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

States a specific verb+resource (find/return hook templates) with scope ('opening lines or first sentences') and even lists the supported output formats. It draws a clear boundary against xcut_get_playbook and xcut_write_caption, so an agent can tell it apart from the closest 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?

Explicit when-to-use ('when the user wants hooks...') plus explicit when-NOT with named alternatives ('Do not use for formats... use xcut_get_playbook', 'for a finished caption use xcut_write_caption'). Strong, but it does not differentiate from the near-identically named sibling xcut_hook_ideas, which is the most confusable 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?

Goes well beyond the annotations by disclosing credit costs (3-4 for 30 posts on Instagram/TikTok, none on YouTube, more on Facebook), the asynchronous job_id behavior for longer runs and the follow-up tool (xcut_get_job), and the non-obvious canvas_id side effect ('results are returned here, not placed on the canvas'). No contradiction with readOnlyHint=false, idempotentHint=true, or destructiveHint=false.

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

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

Four tight sentences: purpose and trigger first, then scoring behavior, then cost and async behavior, then exclusions. Every sentence carries non-redundant information an agent needs to decide or call correctly.

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

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

Despite no output schema, the description conveys what the result looks like ('says by how much each beat it'), the cost side, the async/job_id path, and the canvas side effect. For a four-parameter read-style analysis tool with openWorld and idempotent annotations, this is complete enough to invoke 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 already 100%, so baseline is 3. The description adds value by tying the posts enum to a cost model and by clarifying that canvas_id only supplies thumbnails and does not receive results, a nuance the schema's 'Canvas that owns the thumbnails' does not fully convey. It does not add syntax detail for profile or platform, but those are adequately covered in-schema.

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

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

States a specific verb and resource ('Find a profile's outlier posts') and immediately explains the mechanism: scoring the latest 20-100 posts against the account's own median and reporting the margin. It also names the exact sibling tools it is not (xcut_profile_analytics, xcut_search_viral), so an agent can disambiguate without opening a schema.

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

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

Explicit when-to-use ('when the user asks which of a creator's, competitor's or their own posts performed best... or what works for an account before writing') plus two explicit when-not-to-use cases with the correct alternative named for each. Nothing is left to inference.

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

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

Annotations already declare openWorldHint=true, non-idempotent, non-destructive, non-read-only, so the mutation/safety profile is covered. The description adds genuinely new context the annotations cannot: a Starter-plan gating requirement and a cost of about 14 credits per image. It stops short of describing the return value or any async/job behavior, which is the remaining 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?

Three sentences, front-loaded with the usage trigger, then caveats. Every clause earns its place — use cases justify the tool's scope, the plan/credit line sets expectations, and the final sentence bounds misuse.

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

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

With no output schema, the description still gives an agent the trigger conditions, inputs, cost and plan gate — enough to call it correctly. It does not say what the call returns (image URL, asset, or job handle), which is the one thing an agent must recover elsewhere, likely via xcut_get_job.

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

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

Schema coverage is 100%, so prompt, aspect_ratio (with per-value guidance) and reference_image_urls are fully documented in the schema. The description only references 'a prompt and optional reference image links' and adds no syntax or constraint detail beyond it. Baseline 3 is correct when the schema does the heavy lifting.

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

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

States a specific verb (made or edited) and resource (social media image), then enumerates concrete outputs — post graphic, carousel slide, thumbnail, ad visual — and names the inputs (prompt plus optional reference image links). An agent can distinguish this from every text-oriented sibling (write_caption, write_content) without opening the schema.

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

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

Explicitly opens with 'Use this when the user wants a social media image made or edited' and closes with a when-not ('Do not use for images unrelated to the user's content or marketing'). No alternative tool is named, but no sibling performs image generation, so there is little routing ambiguity left.

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 and closed-world, so the safety profile is covered. The description adds genuinely new context: the call is 'Free' (no credit cost) and usage-history scoping is unavailable here. It stops short of describing return shape or pagination, but with annotations doing heavy lifting that is a minor 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?

Front-loads the usage trigger, then adds the pre-cost-check use case and the exclusion. Two sentences, no filler, every clause earns its place.

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

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

There is no output schema, so the description usefully names the fields returned (plan, credit balance, allowance, refill date, trial). It does not detail response structure, but for a zero-argument read tool this is nearly complete.

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

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

Zero parameters, so the schema carries no semantics to compensate for; baseline is 4. The description properly focuses on behavior and triggers rather than inventing parameter detail.

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

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

States a specific verb ('Get') and resource ('account and credits') and enumerates the concrete fields surfaced (plan, credit balance, monthly allowance, next refill date, trial), which lets an agent distinguish it from siblings like xcut_get_breakouts or xcut_get_content.

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

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

Explicit triggers ('when the user asks about their XcutAI plan, credit balance...'), a proactive trigger ('before starting an import or analysis that costs credits'), and an explicit exclusion ('Do not use for usage history'). This is a textbook when/when-not specification.

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. The description still adds value beyond them: the return shape (brand profile plus saved memory facts with ids) and the cost signal ('Free'). It does not mention auth or rate limits, but those are less relevant for a free read.

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

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

Three sentences, each earning its place: trigger, return shape, and exclusion. The purpose is front-loaded and 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?

With no output schema, the description still states what is returned (brand profile and saved memory facts with ids), and the trigger plus exclusion make the routing complete. Nothing an agent needs to call it correctly is missing.

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

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

Only one parameter (canvas_id) at 100% schema description coverage, so the schema fully documents the UUID source (xcut_list_canvases) and its purpose. The description adds no meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get brand memory' / returns the canvas's brand profile) with the exact payload (voice, niche, audience, offer, memory facts with ids). It explicitly names the siblings it is not (xcut_find_outliers, xcut_search_viral), so an agent can differentiate 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?

Gives an explicit trigger ('when you are about to write for the user's brand', or the user asks what XcutAI knows about their brand) and an explicit exclusion ('Do not use for public creators the user does not own') with named alternatives. When/when-not and alternatives are all present.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely useful non-annotation context: the data source (watchlist accounts), the freshness boundary ('from the last scan'), and that it is free. It stops short of describing the shape of a breakout alert, but the added operational context is strong.

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 triggering condition, then the data scope, then the negative routing. 'Free.' is a single word that earns its place; there is no filler.

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

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

For a read-only, single-optional-param list tool whose annotations cover safety, the description supplies everything needed to select and invoke it. The only minor gap is that no output schema exists and the description does not characterize what a returned alert contains (fields, count 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 100% for the single 'limit' parameter, including range and default, so the schema carries the semantics. The description adds no interpretation of the limit or what counts as a breakout, which is the expected baseline when the schema is fully documented.

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 ('get breakout alerts' plus 'trending keywords') and scopes them to the user's own watchlist accounts and last scan. An agent can distinguish this from xcut_search_viral 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?

Explicit when-to-use ('user asks what is breaking out or trending in their own niche right now') and explicit when-not, naming the alternative and the selecting condition ('topic or creator outside their watchlist -> use xcut_search_viral'). Nothing is left to inference.

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

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

Annotations already cover read-only/idempotent/non-destructive, so the description's added value is 'Free' (cost) and the shape of the payload (ids, counts, previews), which is genuinely useful given there is no output schema. It stops short of noting what a canvas with zero items returns or any rate/limit caveats.

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

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

Three sentences, front-loaded with the trigger condition, followed by the return contents and the disambiguation. 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?

With no output schema, the description compensates by describing the return payload (items, ids, counts by type, short previews) and the filtering/paging model. Combined with complete schema coverage and full annotations, an agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so every parameter (limit, offset, canvas_id, item_type) is already documented in the schema. The description only restates the item_type filter and offset paging, adding no syntax or semantics beyond it — the correct baseline of 3.

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

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

States a specific verb ('get') and resource ('canvas') and enumerates exactly what is returned: items with ids, counts by type, and short previews. It explicitly distinguishes itself from xcut_get_content, which reads a single item in full.

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?

Names the triggering user intent ('asks what is on one of their XcutAI canvases') and gives an explicit exclusion with the alternative tool to use instead ('Do not use to read an item in full (use xcut_get_content)').

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

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

With annotations already declaring destructive=false, idempotent=true and openWorld=false, the description adds real context: cost ('Free'), pagination behavior for chats, and the range of item types returned. It never clarifies the tension between the intuitive read-only nature of 'get content' and the readOnlyHint=false annotation, nor return size/limits, so it earns a 4 rather than a 5.

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

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

Front-loads the usage trigger and closes with the exclusion, with no filler sentences. The middle enumeration of item types is long but each entry carries selection-relevant information, so it is appropriately sized rather than padded.

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

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

There is no output schema, so the description usefully enumerates what content forms come back and how to page chats. It does not cover permission/auth needs or any limits on how much content is returned, which is a minor gap for a read tool whose sibling xcut_get_canvas handles listing.

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

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

Schema description coverage is 100%, so canvas_id, item_id and before are already documented in the schema, including the ordering provenance ('from xcut_get_canvas') and the chats-only pagination semantics. The description's 'by canvas id and item id (from xcut_get_canvas)' and 'paginate with `before`' largely restate that, so the baseline 3 applies.

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

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

States a specific verb (get the full content), the resource (an item on the XcutAI canvas), and enumerates the content variants it returns (transcript/stats, note, chat, website, analytics table, Meta ad, group). It explicitly distinguishes itself from xcut_get_canvas, so an agent can route without opening either schema.

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

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

Gives an explicit trigger ('Use this when you need the full content of an item') and an explicit exclusion with the alternative ('Do not use to list a canvas (use xcut_get_canvas)'). Nothing about when to select this tool versus its closest sibling is left to inference.

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

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

With annotations present, the description still adds real context: cost ('Free'), the polling contract (status 'running' plus a suggested wait), and the shape of a finished payload. It does not explain what readOnlyHint=false implies (i.e. whether fetching consumes or mutates the job), which is the one behavioral gap left.

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 trigger condition and the outcome contract, with no filler. Every clause carries information an agent needs before calling.

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 enumerating the possible return states and their meanings. It leaves the polling cadence and job-expiry behavior implicit, but for a one-parameter read-and-check tool this is largely complete.

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

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

Schema coverage is 100% and the single parameter already documents that the job_id must be the one an XcutAI tool returned, unchanged. The description reinforces the provenance but adds no syntax, format, or example beyond what the schema already carries.

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 ('check a job' via job_id) and immediately names the entry condition plus the two possible outcomes ('running' with a suggested wait, or the finished result with concrete result types). An agent can distinguish it from every sibling because it is the sole polling/retrieval companion to the async tools.

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

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

Both the when ('use this when another XcutAI tool returned a job_id') and the when-not ('Do not use without a job_id from an XcutAI tool') are stated explicitly. No alternative tool exists for this purpose, so no alternative needs to be named.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety and repeat-safety are covered structurally. The description adds genuinely new behavioral context: cost/access ('Free; no sign-in') and the shape of the response ('a short summary of each matching ... format, principle, hook family, ad framework or platform fact'). It omits rate limits or result-count caveats, but adds real value beyond the annotations.

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

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

Front-loaded with the usage trigger, then return shape, then the exclusion; every sentence carries information. It is slightly dense with enumerations, but there is no filler or repetition.

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

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

For a read-only, no-output-schema tool, the description supplies the trigger, the return content, the access cost, and the routing exclusion. 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 100%, so all three parameters (goal, kind, limit) are already documented, including examples and bounds. The description's 'Describe the goal in plain English with platform and format' essentially restates the goal field's schema description rather than adding syntax or constraints, so the baseline 3 applies.

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

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

States a specific verb+resource ('get' a 'content playbook') and enumerates exactly what families it covers (Reel/TikTok/Short structure, principles, hashtags, ad frameworks, platform facts). It also names what it is not (hook templates), so an agent can separate it from xcut_find_hooks without opening either schema.

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

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

Gives an explicit trigger ('when the user asks how to structure ... or how a platform's algorithm, hashtags or profile setup work'), a timing rule ('Call it before writing'), and a negative case with the correct alternative ('Do not use for hook templates (use xcut_find_hooks)'). This is textbook when/when-not/alternative guidance.

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

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

Annotations already cover read-only, idempotent, non-destructive, and open-world traits. The description adds real value beyond them: it discloses the access model ('Free; no sign-in'), that output is generic rather than personalized, and that signed-in tools exist for brand-specific work. It stops short of describing rate limits or exact return formatting.

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

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

Four sentences, front-loaded with the primary trigger, followed by the alternative, the access model, and the exclusion. Every sentence earns its place, though it is slightly dense with multiple conditionals packed together.

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

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

No output schema exists, so the description carries the return-value burden and does reasonably well, stating the count (10), the nature (generic vs. personalized), and the free/no-sign-in access. It leaves the exact output format unstated, but the essentials for correct invocation 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?

Schema description coverage is 100%, with self-documenting parameters and a platform enum. The description restates niche/topic/platform at a high level but adds no syntax, format, or constraint detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('10 new hook variations written for their niche and topic') plus the platforms involved. It explicitly differentiates itself from sibling xcut_find_hooks, letting an agent route without opening a schema.

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

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

Gives both positive triggers (user wants new hook variations for a niche/topic) and negatives ('Do not use for writing unrelated to social media or marketing content'), and names the alternative tool for proven templates. This is explicit when/when-not/alternative guidance.

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

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

Annotations only declare the generic safety profile (readOnlyHint=false, openWorldHint=true, non-destructive). The description adds non-obvious behavior: an 18-credit hold charging the real cost, and that it may return a job_id to be polled via xcut_get_job. It stops short of describing retry/idempotency behavior or failure modes, so a 4 rather than 5.

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

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

Three sentences: the trigger first, the cost/return behavior second, the exclusion last. No filler, and the important routing constraint is front-loaded.

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

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

With no output schema, the description compensates by disclosing the possible job_id return and the polling tool. Combined with 100% schema coverage for both params, an agent has what it needs; only deeper detail on the job flow or credit-failure behavior is missing.

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

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

Schema description coverage is 100% and both parameters are documented in the schema, including the canvas_id fallback behavior and the xcut_list_canvases id source. The description only restates the Meta Ad Library link requirement, so it adds no meaning beyond the schema; baseline 3 is appropriate.

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

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

States a specific verb and resource ('Import a Meta ad') plus what is extracted (copy, media, video transcript) and names the sibling it is not (xcut_import_post). An agent can distinguish it from xcut_import_post and xcut_import_profile without opening any schema.

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

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

Gives an explicit trigger condition ('user shares a Meta Ad Library link') and an explicit exclusion with the correct alternative ('Do not use for organic Facebook posts (use xcut_import_post)'). Both when-to-use and when-not-to-use are covered.

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

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

Annotations only declare the mutation/idempotency profile; the description adds the operations behind the call (transcription, caption/visual/stat reading), the credit cost and its variability, the default canvas destination, and the async contract via the returned job_id resolved by xcut_get_job. This goes well beyond what the structured fields disclose.

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 use case, then cost, return contract, and exclusions in a tight sequence with no filler. The opening sentence is long, but every clause carries routing or behavioral 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?

Despite having no output schema, the description explains the return value (job_id) and the follow-up tool needed to get the transcript. Combined with cost and canvas defaulting, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so both parameters are already documented, but the description adds decision-relevant nuance: leaving canvas_id out silently routes to the user's "From AI apps" canvas rather than erroring. That is more than a restatement of the schema default.

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 (import) and a narrowly scoped resource (Instagram/TikTok/YouTube/Facebook post or video link), plus the outcomes it enables (transcript, breakdown, own version). An agent can distinguish it from xcut_import_website and xcut_import_meta_ad without opening any schema.

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

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

Gives an explicit trigger condition (user shares a social post/video link wanting transcript or breakdown) and explicit exclusions with named alternatives for website links and Meta Ad Library links. It also preempts the canvas question, telling the agent not to ask when no canvas is named.

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

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

Annotations already flag readOnlyHint=false, idempotentHint=false and openWorldHint=true, so the write/external nature is covered. The description adds real value on top: cost ('About 1-15 credits plus transcription') and async behavior ('Returns a job_id while the profile is read'). It stops short of saying how to poll the job (xcut_get_job) or what the analysis output 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?

Three sentences, front-loaded with the triggering condition, and every clause earns its place — scope, platforms, cost, return value, and the exclusion all arrive in the first pass.

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

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

For a 4-param async mutation with no output schema, the description covers trigger, platforms, cost, side effects, and the key return (job_id). The one omission is the follow-up step for retrieving results once the job completes, which the job_id implies but does not state.

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

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

Schema description coverage is 100%, so profile, platform, posts, and canvas_id are all documented in the schema, including the canvas_id default behavior. The description adds only the implicit canvas-placement effect and the credit cost, not syntax or format details beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb+resource (import a profile's recent posts), the four supported platforms, and the side effects (adds them to a canvas as a group, transcribes and analyses each). It also names the sibling it is not (xcut_find_outliers), so an agent can distinguish it 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?

Explicitly gives the when ('user wants to study a creator's or brand's recent posts in depth') and the when-not with a named alternative ('Do not use just to rank posts (use xcut_find_outliers)'). Nothing is left to inference.

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

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

Annotations already declare the write/open-world/non-idempotent profile, so the bar is lower. The description adds real behavioral context beyond them: it stores text on a canvas, costs 'up to about 3 credits', and returns a short preview. It could say more about failure behavior (e.g. unreachable URLs), but the cost and storage disclosure is genuinely useful.

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

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

Three sentences with the use-case front-loaded, then behavior/cost, then the alternative. Every sentence carries distinct information and there is no filler.

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

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

With no output schema, the description correctly notes the return is a short preview, and it covers storage destination and cost. Combined with the safety annotations and full schema coverage, an agent has what it needs, though error handling is left unmentioned.

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

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

Schema coverage is 100% and the canvas_id description already explains the default 'From AI apps' canvas and points to xcut_list_canvases. The description adds no additional parameter meaning beyond what the schema provides, so the baseline 3 applies.

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

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

The description names a specific verb and resource ('imports' a 'web page') and explicitly lists the page types covered (product page, landing page, article). It distinguishes itself from the sibling xcut_import_post, so an agent can route without opening either schema.

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

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

It states the triggering condition ('when the user shares a web page... to use as context for writing their content') and an explicit exclusion with the alternative named ('Do not use for social media post links (use xcut_import_post)'). This is exactly when-to-use, when-not, and the sibling to use instead.

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, openWorldHint=false and destructiveHint=false, so safety and repeatability are covered structurally. The description adds genuine behavioral context beyond that: the call is free (no credit cost) and enumerates the status taxonomy the listing spans. It stops short of noting pagination/ordering behavior beyond the schema's limit, so not a 5.

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

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

Two sentences, zero waste, and the trigger condition and scope constraints are front-loaded ahead of the exclusion. Nothing is repeated from the schema.

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

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

There is no output schema, so the description carries return-shape burden, and it partly discharges this by naming the status taxonomy the posts carry. All parameters are optional and documented, and the alternative route is given. What is still missing is any hint of default ordering or result-volume behavior, which matters slightly for a list tool with a 200-item cap.

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

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

Schema description coverage is 100%, with formats, defaults and the 1-200 limit range documented inline, so the structured data does the heavy lifting and the baseline is 3. The description echoes date range and the optional single-canvas scoping but adds no syntax or semantics beyond the schema, and its mention of status values risks reading as a filter that does not exist among the four parameters.

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

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

States a specific verb+resource (list posts on the XcutAI content calendar) and pins the scope precisely: between two dates, optionally one canvas, with defined status values. It also names the sibling it is not (xcut_profile_analytics for live posts), so an agent can separate it from other listing/analytics tools without opening a schema.

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

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

Opens with an explicit trigger ('Use this when the user asks what content is planned or scheduled') and adds an explicit exclusion with a redirect ('Do not use for posts already live on social media (use xcut_profile_analytics)'). This is the when/when-not/alternative pattern at full strength.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds genuinely new context beyond them: 'Free' (cost), 'newest first' (ordering), and shared-canvas inclusion. It does not describe return format or pagination, but for a read list that is minor.

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

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

Two tight sentences, front-loaded with the trigger condition, then the exclusion. No wasted words.

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

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

For a zero-required-param list tool with full schema coverage and annotations, the description supplies everything needed: what it returns, ordering, scope, cost, and routing to siblings. No output schema is required for this operation.

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

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

Schema description coverage is 100%, with both limit and include_shared documented in the schema, so the baseline is 3. The description's 'including ones shared with them' loosely maps to include_shared but adds no syntax or format detail beyond the schema.

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

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

States a specific verb+resource ('list canvases (projects)'), plus scoping details ('including ones shared with them, newest first'). It also distinguishes itself from siblings by noting that import/write tools use the 'From AI apps' canvas instead.

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

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

Explicit when-to-use ('when you need a canvas id or the user asks what canvases they have') and when-not-to-use ('Do not call it just to import a post or write'). It names the alternative behavior those other tools use, 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 readOnlyHint, idempotent, and non-destructive, so safety is covered; the description adds genuinely new context: 'text plan only', 'Free; no sign-in', and 'Output is generic'. It stops short of describing the output shape or any length/rate constraints, 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?

Front-loaded with the trigger ('Use this when...'), and each subsequent clause carries distinct routing or scope information rather than filler. Slightly dense with four separate directives, but none are 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 read-only, four-parameter text-generation tool with no output schema, the description covers trigger, scope, cost/auth posture, and alternatives well. It could say more about the output format, but the annotations and complete schema carry most of the remaining burden.

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

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

Schema description coverage is 100%, so the schema already documents every parameter. The description names three of the four inputs (omitting platform) but adds no format or syntax detail beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

States a specific verb and artifact ('posting plan drafted') plus the inputs that drive it (niche, posting frequency, content pillars). It explicitly distinguishes itself from xcut_add_to_calendar and the signed-in XcutAI tools, so an agent can route without reading either schema.

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

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

Gives explicit when-to-use, when-not-to-use ('Do not use for writing unrelated to social media or marketing content'), and named alternatives for adjacent needs (xcut_add_to_calendar for scheduling, signed-in tools for personalized brand work). Nothing is left to inference.

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

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

Annotations only declare safety/idempotency flags, so the description's added context is valuable: credit cost varies by platform and post count, and longer runs return a job_id to be polled via xcut_get_job. That async behavior is exactly the kind of trait annotations cannot express. It does not, however, say when the sync path ends and the job path begins (no threshold), leaving a practical unknown.

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

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

Three sentences, front-loaded with the trigger condition, then cost/async behavior, then the exclusion. Every sentence carries distinct information and nothing is repeated from the schema.

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

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

With no output schema, the description partially compensates by naming the metric fields returned and disclosing the job_id handoff for long runs. What remains unstated is pagination/volume limits on the returned table and the exact credit formula, but the essentials for correct invocation 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?

Schema description coverage is 100%, so every parameter is already documented, including the days-vs-posts choice and the default of 20 posts. The description restates the same notion ('last N posts or days') without adding syntax or exclusivity rules beyond the schema, so the baseline 3 applies.

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

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

The description names a specific verb+resource — per-post metrics (views, likes, comments, shares, engagement) for an account's last N posts or days — and enumerates the supported platforms. It also explicitly separates itself from the nearest sibling by naming xcut_find_outliers, so an agent can route without opening either schema.

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

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

It states the triggering intent ('when the user wants... for a performance review or to compare accounts') and gives an explicit exclusion with the alternative tool ('Do not use to find standout posts (use xcut_find_outliers)'). Both the use case and the negative case are covered.

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, openWorld and non-destructive, so the safety profile is covered elsewhere. The description adds genuinely new context the annotations cannot express: no sign-in/auth requirement, free cost, and a quality caveat that output is generic versus brand-aware signed-in tools. It stops short of describing return format, but that is a minor gap against an already-covered safety profile.

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 trigger condition. Every sentence carries distinct information: trigger, cost/auth plus quality caveat, and exclusion. 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 two-parameter, read-only generation tool with no output schema, the description covers everything an agent needs: when to invoke, auth/cost posture, output quality expectations, routing to alternatives, and scope boundaries. Nothing material is missing.

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

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

Schema description coverage is 100% with only two parameters, so the schema already fully documents 'title' and 'description'. The description mentions 'one piece of content' but adds no syntax, format, or length guidance beyond the schema. Baseline 3 is appropriate.

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

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

Names a specific transformation ('one piece of content turned into TikTok, Reel, LinkedIn, X and email angles'), not just a verb+resource. It also distinguishes itself from the signed-in XcutAI tool family, so an agent can tell it apart from siblings like xcut_write_content 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?

Gives an explicit trigger ('when the user wants one piece of content turned into...'), an explicit alternative ('for work based on the user's own posts, canvases or brand, use the signed-in XcutAI tools'), and an explicit exclusion ('Do not use for writing unrelated to social media or marketing content'). All three of when/when-not/alternative are present.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description adds genuinely new behavioral context beyond them: it is free, requires no sign-in, and its output is 'generic' versus signed-in tools that use the user's own data. This is useful for setting expectations, though it could say more about what the output looks like.

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

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

Three tight sentences with zero redundancy, and the trigger condition is front-loaded before the alternatives and exclusion. Every sentence earns its place.

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

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

For a 3-parameter generation tool with no output schema, the description covers trigger, exclusion, alternative routing and the nature of the output. Parameter-level detail is fully handled by the schema (including maxLength and enum). Only a richer sense of what the returned bio looks like is missing, which is minor since no output schema exists.

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

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

Schema description coverage is 100%, so platform, current_bio and niche are already documented in the schema. The description repeats the platform list but adds no format, length or syntax guidance beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb (rewrite) and resource (profile bio) and enumerates the exact platforms covered (Instagram, YouTube, TikTok, X, LinkedIn). It also positions itself against the signed-in writing tools, so an agent can distinguish it from xcut_write_caption or xcut_write_content.

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

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

Provides an explicit trigger ('when the user wants their profile bio rewritten'), an explicit exclusion ('Do not use for writing unrelated to social media or marketing content'), and routes to the correct alternative ('for work based on the user's own posts, canvases or brand, use the signed-in XcutAI tools'). All three when/when-not/alternative elements are present.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the bar is lower. The description adds meaningful non-schema behavior: token billing with a concrete cost estimate (a month plan ~60-90 credits) and that longer runs return a job_id (async). It stops short of noting that re-running bills again (relevant given idempotentHint=false) or failure 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?

Purpose and scope are front-loaded and the exclusion is last, which is a sensible order. The first sentence is a long comma-list of deliverables that is dense but earns its place by conveying the tool's breadth; still, it could be tightened.

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 costly, non-idempotent generation tool with no output schema, the description supplies the essentials: what it produces, when to use it vs a sibling, the billing implication, and that longer runs return a job_id (implying polling via xcut_get_job). An agent has enough to call and follow up correctly.

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

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

Schema description coverage is 100%, so every parameter is already documented, and the baseline is 3. The description restates the playbook values rather than adding syntax or format meaning beyond what the schema's own playbook description provides.

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

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

States a specific verb+resource (run a playbook) and enumerates the concrete deliverables the playbooks produce (month/week plan, hooks, scripts, teardown, audit, etc.). It distinguishes itself from siblings by naming xcut_write_content as the alternative for single requests, so an agent can route 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?

Explicit when-to-use (user wants a ready-made deliverable from canvas content) and explicit when-not ('Do not use for a single custom request (use xcut_write_content)'). The alternative tool is named, 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 cover the safety profile (non-read-only, non-destructive, non-idempotent), and the description adds real context beyond them: the operation is append-only ('never changes or removes one'), it is free, and its effect is persistent and global ('every XcutAI agent uses it from now on'). It stops short of covering edge behavior such as duplicate facts or write 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?

Three tight sentences with no filler: purpose is front-loaded, then the additive guarantee, then cost and the alternatives. Even the one-word 'Free.' carries a decision-relevant fact.

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?

All three parameters are schema-documented, alternatives are named for both conflicting operations, there is no output schema to explain, and the append-only semantics are explicit. An agent has everything needed to select and call this correctly.

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

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

Schema description coverage is 100%, so the schema already documents text, category (with a 20-value enum), and canvas_id including its UUID source (xcut_list_canvases). The description's parenthetical list (voice, audience, offer, constraint, posting schedule) loosely maps to some categories but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource ('Save a brand memory fact') and immediately scopes it as additive: 'Adds a new fact; never changes or removes one.' This lets an agent distinguish it from xcut_update_memory and xcut_delete_memory without opening any schema.

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

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

Gives an explicit trigger ('when the user states a lasting fact about their brand') plus concrete examples of qualifying facts (voice, audience, offer, constraint, posting schedule). It also names two exclusions with the correct alternative for each: use xcut_update_memory to change an existing fact, and don't use it for one-off current-request instructions.

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

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

Annotations only declare readOnly=false, openWorld=true, idempotent=false, destructive=false. The description adds the traits that actually govern invocation: a once-per-hour rate limit, a cost ceiling (~1 credit or less), and an estimate-only dry-run mode. Those are exactly the facts an agent needs to avoid burning quota on a redundant scan.

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 trigger condition, then constraints, then the exclusion. No filler and the most decision-relevant information comes first.

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 one-optional-param tool with no output schema, the definition covers trigger, cost, rate limit, and routing to the read tool. The only gap is what a scan returns or whether it is synchronous versus job-based, which would help an agent set expectations after the call.

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

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

Schema coverage is 100% and the sole `estimate` parameter is already described there ('true returns the credit cost without scanning'). The description restates that almost verbatim, adding only the workflow framing of cost-checking before spending credits, so it does not materially extend parameter meaning.

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

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

States a specific verb and resource ('Rescans the accounts on their XcutAI watchlist') and names the sibling it must not be confused with (xcut_get_breakouts). An agent can pick it apart from get_breakouts 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?

Explicit trigger ('when the user wants fresh breakouts now instead of waiting for the next scheduled scan') plus an explicit exclusion and alternative ('Do not use to read the latest results (use xcut_get_breakouts)'). This is the when/when-not/alternative triad in full.

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

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

Goes beyond annotations by disclosing return contents (views, engagement, links, captions), pagination via next_cursor, and cost behavior ('a fraction of a credit per page, cached pages free'), which usefully explains why readOnlyHint is false (cache writes). It does not cover auth requirements or rate limits, so it falls short of a 5.

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

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

Front-loads the use case, then mode, then returns, then cost, then exclusions – a sensible priority order with no wasted sentences. Slightly dense, and the inline platform enumeration ('Instagram, TikTok, YouTube or Facebook') duplicates the platform enum, costing a perfect score.

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 fields and the pagination cursor. Combined with the explicit exclusions and cost note, an agent has everything needed to select and invoke this correctly.

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

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

Schema coverage is 100%, so the schema already documents every parameter including the mode enum semantics and the Facebook profile-only constraint. The description's mode sentence largely restates the schema, adding no syntax or format detail beyond it; baseline 3 applies.

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

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

States a specific retrieval action (find what's going viral/trending/performing) across named platforms and both operating modes (keyword vs profile), and explicitly names the sibling it is not (xcut_find_outliers). An agent can distinguish it from xcut_get_breakouts or xcut_check_niche from the description alone.

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

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

Gives explicit trigger scenarios ('when the user asks what is going viral... what a creator posts that works, or what ads run in the Meta Ad Library') and explicit exclusions ('do not use for general web or news search, or for one profile's outliers versus its own normal') with the correct alternative named. Nothing is left to inference.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true; the description goes beyond them by explaining partial-update semantics ('Only the fields given change') and what is destroyed ('their old values are not kept'), plus a cost signal ('Free') and a no-publishing guarantee. It omits error behavior and any permission/auth requirements, 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?

Three short sentences, front-loaded with the use condition, then the mutation semantics, then the negative constraint. No filler; every sentence carries distinct information.

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

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

For a 7-parameter mutation tool with full schema coverage and safety hints in annotations, the description covers when to use it, partial-update behavior, cost, and the publishing caveat. The only gap is that with no output schema the agent gets no hint about what a successful response contains or how to confirm the change.

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

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

Schema description coverage is 100%, so per the rubric the baseline is 3. The description names the updatable fields and matches the schema properties, but adds no format or syntax detail beyond what each property description already provides.

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

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

States a specific verb (change/update), the resource (a post on the XcutAI calendar), and enumerates the mutable fields: date, caption, hashtags, title, type, status. This clearly separates it from xcut_add_to_calendar and xcut_delete_calendar_post without requiring 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 a concrete triggering condition ('when the user wants to change a post on their XcutAI calendar') and an explicit exclusion ('Do not use to publish: XcutAI never posts to social media'). It does not name a sibling alternative for the add/update boundary, so it stops short of a full 5.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds what the annotations cannot: the old text is discarded rather than versioned, the fact must be resolved first via xcut_get_brand, and the call is free. It stops short of describing the response or any side effects on dependent content that referenced the fact.

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

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

Four short sentences, front-loaded with the trigger and followed by the destructive effect, prerequisite, cost and exclusion in descending order of importance. Slight redundancy between 'Replaces that fact's text and category' and the parenthetical '(the old text is not kept)'.

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, annotation-backed mutation tool with no output schema, the definition covers trigger, exclusion, alternative, prerequisite and irreversibility. What remains unstated is the return payload and whether callers of the fact elsewhere are affected.

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

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

Schema description coverage is 100%, so the schema already documents text, category (with the full enum and 'omit to keep current'), canvas_id and memory_id including their source tools. The description adds no syntax or constraint detail beyond that, so the baseline 3 applies.

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

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

States a specific verb+resource (update a saved brand memory fact) and explicitly contrasts itself with the two nearest siblings: not xcut_save_memory (add) and implicitly not xcut_delete_memory. An agent can route between the three memory tools without opening a schema.

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

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

Gives an explicit trigger ('when the user asks to change a saved brand memory fact'), an explicit exclusion ('Do not use to add a new fact'), and names the alternative tool that handles the excluded case. Prerequisite chain (id from xcut_get_brand) is also stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds value annotations cannot: the call is free, requires no sign-in, and its output is deliberately generic rather than brand-personalized — a meaningful expectation-setting detail. It stops short of describing output shape or any limits on repeated calls.

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

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

Three sentences with no filler: the primary trigger comes first, then the free/no-sign-in qualifier, then the personalized-alternative routing and the exclusion. Every clause carries selection-relevant information.

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

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

For a three-parameter, read-only generation tool with no output schema, the description covers trigger, platforms, delivered output components, cost, authentication state, output genericity, and the sibling to route to for personalized work. Nothing an agent needs to select or invoke it correctly is missing.

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

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

Schema description coverage is 100%: concept, platform (with enum) and tone (with default and examples) are all documented in the schema itself. The description adds no syntax, format or length guidance beyond that, so the baseline 3 is appropriate.

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

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

States a specific verb (write) and resource (caption) and enumerates the delivered parts — hook, body, CTA and hashtags — for three named platforms. It also distinguishes itself from the signed-in XcutAI tool family, so an agent can tell it apart from xcut_write_content without opening either schema.

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

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

Explicitly frames the trigger ('when the user wants a finished caption ... from a short concept'), names the alternative for personalized work ('for work based on the user's own posts, canvases or brand, use the signed-in XcutAI tools'), and adds an exclusion ('do not use for writing unrelated to social media or marketing content'). Use, alternative, and non-use cases are all covered.

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

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

Annotations cover only the safety profile (non-read-only, non-idempotent, non-destructive, closed-world). The description adds genuinely new behavioral context: token-billed at typically 1-26 credits, the conversation is persisted to the user's canvas, and longer turns return a job_id instead of the content directly. These are exactly the traits an agent needs before invoking a billed generative write.

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

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

Front-loaded with the use condition, then deliverable scope, then picks, then billing/return behavior, then the exclusion. The deliverable list is long but each item earns its place by defining scope precisely, and there is no filler.

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

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

With no output schema, the description correctly compensates by explaining that a canvas conversation is created and that long turns return a job_id (resolvable presumably via xcut_get_job). Billing cost is also disclosed. Minor gap: it does not say what the short-turn return value looks like, but it is otherwise complete for a 4-parameter mutation tool.

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

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

Schema description coverage is 100%, so all four parameters (including the agent enum and the canvas_id lookup source) are already documented in the schema. The description's "Pick `agent` for the platform, or auto" largely restates the enum, and item_ids is not addressed at all, so baseline 3 is appropriate.

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

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

States a specific verb+resource (XcutAI agents writing brand social content) and enumerates the concrete deliverables (Reels/TikTok/Shorts scripts, YouTube scripts, Facebook posts, Meta ad copy, hooks, captions, plans). This clearly separates it from siblings like xcut_write_caption (single narrow output) and xcut_rewrite_bio or xcut_repurpose_content.

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?

"Use this when the user wants XcutAI's agents to write for their brand" plus an explicit exclusion ("Do not use for writing unrelated to the user's social media or marketing content") gives clear when/when-not guidance. It does not name an alternative sibling for the overlapping caption-writing case, 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?

Annotations already cover the safety profile (readOnly, non-destructive, idempotent, openWorld), so the description's added value is that it is free, requires no sign-in, and produces generic rather than personalized output. These are genuinely useful behavioral disclosures an agent cannot get from the annotations. It stops short of describing how many options come back or any rate/limit behavior, hence not a 5.

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

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

Three sentences, front-loaded with the usage trigger and with zero filler. The trailing exclusion sentence is slightly redundant given the earlier alternative-tool guidance, which keeps it out of 5 territory.

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 does carry the burden of telling the agent what comes back, and it does state that the result is title options with thumbnail ideas, free and unauthenticated. It is missing only detail on volume/format of the returned options, a minor gap for a two-parameter generation tool.

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

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

Schema coverage is 100% – both 'topic' and the optional 'niche' are documented in the schema with constraints. The description adds only the loose notion of a 'video topic' and never mentions the niche parameter or how it shapes output, so the baseline 3 is correct.

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

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

Names a specific verb-and-resource combination (YouTube title options, plus thumbnail ideas) for a video topic, which is more informative than the tool name alone. It cleanly separates this free/generic tool from the signed-in XcutAI content tools that work off the user's own posts, canvases or brand.

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

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

Gives an explicit trigger ('when the user wants YouTube title options... for a video topic'), an explicit alternative ('for work based on the user's own posts, canvases or brand, use the signed-in XcutAI tools'), and an explicit exclusion ('do not use for writing unrelated to social media or marketing content'). Nothing is left to inference.

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