oriiion

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

Annotations already declare the mutation profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false). The description adds real behavioral context beyond that: what accept actually triggers (a post idea starts generating, a connection card returns a sendable link) and a safety precondition requiring user confirmation for send/publish actions. It doesn't state whether accept can be undone once generation starts, so not a 5.

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

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

Three compact sentences, front-loaded with the core action and scope, then effect detail, then the conditional parameter note, then the safety rule. Every sentence carries useful information but the 'does what the card's button does' framing is slightly indirect for an agent with no card context.

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 describes the observable outcome of accept (generation starts, link returned) and the confirmation precondition. With annotations covering the non-destructive, non-idempotent mutation profile and full schema coverage, only minor gaps remain (e.g., what dismiss does to the item, whether accept is reversible).

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

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

Schema description coverage is 100%, so the schema already explains itemId (from list_todo), the action enum, and finalText. The description's mention of finalText and list_todo largely restates the schema rather than adding syntax, format, or edge-case detail. Baseline 3 applies.

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

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

States a specific verb pair (accept/dismiss) and resource (one todo item), scoped to a single item by id, and names list_todo as the source of that id. An agent can distinguish this from sibling mutation tools like publish_post or boost_post without opening another schema.

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

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

Gives clear conditions: accept vs dismiss semantics, and pass finalText when the user edited the draft first. It also states a strong operating rule ('always confirm with the user before accepting anything that sends or publishes'). It stops short of naming alternative tools for related workflows, so it lands at 4 rather than 5.

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

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

Adds real behavioral context beyond annotations: recipients can only be ADDED, removal is impossible, and trimming a draft requires deleting it and starting over. This irreversibility warning is critical and not captured by the idempotentHint/destructiveHint flags. It also confirms that adding does not send, which is not stated elsewhere.

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

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

Three short sentences, front-loaded with the primary action and its most important constraint (irreversibility). Every sentence carries distinct, useful information with no waste.

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

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

For a draft-mutation tool with no output schema, the description covers the essential behavioral traits: dual read/write modes, the no-removal limitation, and that nothing is sent. Minor gaps remain (e.g., no explicit return shape), but these are not required given the schema coverage and annotations.

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

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

Schema description coverage is 100%, so the schema already documents broadcastId, contactIds (max 500, from list_broadcast_contacts) and populate. The description reinforces the read-mode semantics of omitting both params but adds little 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 (add) and resource (broadcast recipients), and explicitly clarifies the write-vs-read duality, distinguishing it from send_broadcast ('Adding still sends nothing'). An agent can tell exactly what this does relative to siblings like list_broadcast_contacts and send_broadcast.

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

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

Gives clear context for both modes: call with neither contactIds nor populate to read, otherwise it adds. It explains the intent of each parameter but does not explicitly name alternative tools or exclusions beyond the read/add split.

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

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

Annotations already declare the mutation profile (readOnly=false, destructive=false, idempotent=false, openWorld=false). The description adds genuinely useful context: the image must be a public URL, the operation converts the post to a carousel, and there is a 10-slide cap. It does not say what happens when the cap is exceeded (error vs. silent failure) or what auth is required.

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

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

A single sentence that front-loads the action and packs the effect, medium constraint, and limit with zero 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 two-parameter mutation tool with full schema coverage and clear annotations, the description covers purpose, transformation effect, and the slide limit. The main gap is the cap-exceeded behavior and any post-type prerequisites, which are minor given the structured data already present.

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

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

Schema coverage is 100%, so both parameters are already documented in the schema, setting the baseline at 3. The description reinforces the 'public URL' constraint on imageUrl but adds no syntax, format, or validation detail beyond what the schema provides.

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

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

States a specific verb+resource ('Add an image ... to an existing post') and adds the meaningful effect: it becomes an extra slide, converting the post into a carousel with a max of 10 slides. It does not explicitly differentiate from close siblings like change_image or create_carousel, so an agent must infer the distinction.

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

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

The phrase 'to an existing post' implies a precondition, but there is no when-to-use vs. alternative guidance. It never tells the agent how this differs from change_image (replace) or create_carousel/create_photo_carousel, which is exactly the ambiguity a sibling-heavy toolset creates.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true and non-idempotent, so the safety bar is partly met. The description adds material context the annotations cannot convey: the call spends real money from a prepaid wallet, the service fee is charged on top of the stated budget, and user confirmation is mandatory — all valuable for a spend-incurring mutation.

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

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

Three tight sentences with zero waste. The money-spending warning is front-loaded in caps right after the one-line purpose, so the most consequential fact is read first, and the prerequisite tool is named last.

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

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

For a tool with eight parameters, nested targeting objects and no output schema, the description covers the essential workflow (recommendations → confirm budget → boost) and the spend risk. It leaves the managed-vs-own_account fee distinction and returning campaign details to the schema/annotations, which is acceptable but slightly under-explained.

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

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

Schema description coverage is 100%, so the schema already documents all eight parameters including budgetCents, mode, durationDays and the nested targeting fields. The description adds no parameter-level syntax or constraints beyond reiterating the budget-and-fee idea, 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?

Specific verb (boost) plus resource (a published post as a paid ad), and it distinguishes itself from sibling ad tools such as create_chatgpt_ad and google_ads_create_search_campaign by scoping to boosting an existing published post. An agent knows immediately what this does and on what object.

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

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

Gives explicit preconditions: confirm the budget with the user before calling, and call get_boost_recommendations first for suggested settings. It routes to a sibling tool by name, which is strong, but it doesn't contrast with other ad-creation tools or explain when the managed vs own_account path applies.

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

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

Goes well beyond the annotations by disclosing that prompt-based generation is async (~1-2 min), applied automatically, and how to poll it. Also surfaces a critical prerequisite and a failure mode (image shows a stranger without referenceImageUrls). Annotations only cover the safety profile, so this extra context is valuable.

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

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

Three dense sentences, front-loaded with the core action and split by the two operating modes. Every clause carries actionable information; no filler.

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

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

With no output schema, the description still covers the async lifecycle, status-check path, and identity prerequisite for a 4-param mutation tool. An agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: imageUrl is an instant swap, prompt triggers async generation, and referenceImageUrls must be paired with prompt and sourced from use_character_reference. This clarifies parameter interactions beyond the schema.

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

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

States a specific verb and resource ('Replace a post's image entirely'), which cleanly distinguishes it from siblings like add_image_to_post and edit_image. An agent can identify the operation 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 lays out the two modes (imageUrl for instant swap vs prompt for AI generation) and names the prerequisites: call use_character_reference first for named people, and check with get_task_status for async results. Clear when-to-use guidance with named alternatives.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: the gating condition on required steps and the recommendation to pre-verify state. It does not disclose what happens if the tool is called when prerequisites are unmet or when onboarding is already complete, which keeps it below 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 sentences with no filler; the state change is front-loaded, followed by the gate condition and the timing cue. Every sentence carries operational 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 zero-parameter, non-idempotent state-transition tool with no output schema, the description covers what to do before (verify status), when (end of conversation), and the precondition. What is missing is the failure/already-complete behavior, which matters for a non-idempotent 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?

Zero parameters are defined and schema description coverage is 100%, so the baseline of 4 applies. There is no parameter information for the description to add or omit.

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: 'Mark the user's onboarding as complete.' This tells the agent exactly what state change occurs. It falls short of 5 because the sibling set contains several other onboarding-completion tools (finish_agent_onboarding, onboarding_v7, log_agent_onboarding) that are not distinguished from this one.

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 prerequisites ('Only works once all required steps (payment + required social connection) are done'), an explicit verification step ('verify with get_onboarding_status first'), and an explicit triggering moment ('at the end of a successful onboarding conversation'). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, so the write-profile is covered by structured data. The description adds that generation is instant and driven by 'Agency Workforce v3', but it never clarifies whether the produced post is a draft or a live/scheduled post, nor whether the source idea is consumed — a meaningful gap for a non-idempotent creation tool.

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

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

A single front-loaded sentence that states the action and its input sources with no repetition. 'using Agency Workforce v3' is mild marketing filler that adds little decision-making value, which keeps it from 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?

With annotations present, a full-schema parameter set and no output schema, the description only needs to close the semantic gaps. It does not say what actually gets created (draft vs. published post), whether both source parameters are alternatives or mutually exclusive, or what happens if neither is supplied — real omissions for a generation tool with 0 required parameters.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters, giving a baseline of 3. The description contributes one genuinely useful signal — that ideaId and threadId map to two different source types (Idea Bank item vs. Sparring Angle Card) — but adds nothing about the platform or scheduledFor parameters.

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

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

The description names a specific verb (convert/turn into) plus both source resources (Idea Bank item, Sparring Angle Card) and the output (a finished single post), which separates it from siblings like generate_posts or create_from_trend. It stops short of explicitly comparing itself to those alternatives, so it lands at 4 rather than 5.

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

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

Usage is only implied: the agent can infer it needs a pre-existing saved idea or sparring card, and that publishing/scheduling is a separate step handled by publish_post or schedule_post. There is no explicit when-to-use, when-not-to-use, or named alternative, so this is minimum-viable 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 mark this as a non-read-only, non-destructive mutation but say nothing about side effects. The description supplies the key behavioral fact that 'Creating never sends anything' — the create is safe because it only makes a draft — plus a platform-availability constraint. It does not add auth/permission, rate-limit, or idempotency context beyond the annotations, 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?

Three tight sentences with zero filler. The most important constraint ('DRAFT ... never sends') is front-loaded, followed by the workflow and then the platform 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 6-param draft-creation tool with no output schema, the description covers purpose, sequencing with the two companion tools, the ID source, and platform limits. Nothing an agent needs in order to call this correctly is missing.

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

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

Schema description coverage is 100%, so every parameter (name, tags, text, accountId, description, isSubscribed) is already documented in the schema, including the note that accountId comes from list_broadcasts. The description's 'Use an accountId from list_broadcasts' merely repeats what the schema already says, 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?

Specific verb+resource ('Create a broadcast DRAFT') with an immediate gloss on what a broadcast is ('a DM sent to many contacts at once'). It clearly separates this from its siblings send_broadcast and add_broadcast_recipients, so an agent can select it 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 states the full workflow: create the draft, add people with add_broadcast_recipients, then deliver with send_broadcast. It also gives the prerequisite ('Use an accountId from list_broadcasts') and the exclusion ('Not available on WhatsApp or LinkedIn'). When-to-use, when-not, and alternatives 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?

With annotations only covering the safety profile (readOnlyHint=false, non-idempotent, non-destructive), the description carries the real behavioral load: background execution taking minutes, polling via get_task_status with the returned taskId, returning an ownerLink, and the downstream publish semantics (IG slide post, LinkedIn PDF document). It could still say more about duplicate drafts on repeat calls, but the disclosure is well beyond what the annotations provide.

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

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

Front-loads the core purpose and alternative routing, and nearly every sentence carries decision-relevant information. It is dense and the middle clauses chain several conditional rules together in one long sentence, which hurts scanability, but there is little pure 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 7 parameters, no output schema, and a genuinely complex tool, the description still covers initiation (background task), tracking (taskId + get_task_status), user-facing artifact (ownerLink), downstream destinations, and the source-dependent branching. Nothing an agent needs to call this correctly appears to be 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 baseline is 3, but the description adds cross-parameter behavior the schema cannot express: productId vs productIds interactions, the 'photos' vs 'template' design rule, the two-photo threshold, and the default designed deck for productIds. That is meaningful semantic value beyond the field-level docs.

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

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

Opens with a specific verb+resource+scope: 'Write and design a CAROUSEL from scratch — 4-10 branded slides', and explicitly names the conditions that separate it from siblings ('when there are no images and no PDF, only a subject'). It also names two siblings it is NOT for (create_carousel_from_images, redesign_document), so an agent can disambiguate 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 explicit when-to-use triggers ('make a carousel about X', 'a LinkedIn document carousel about X'), names the alternatives and the conditions that select them, and even states refusal conditions (AI images off with fewer than two photos; 'template' with no uploaded design). This is about as complete as routing guidance gets.

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

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

Annotations only supply the generic hint set (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false). The description adds non-obvious behavior the annotations cannot convey: images are cropped to portrait format, the operation yields a draft (not a published post) plus ownerLink and reviewLink, and the images must be publicly reachable URLs. The ownerLink warning about this chat's inability to render images is exactly the kind of context an agent needs.

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

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

Purpose is front-loaded, constraints follow, then return values, then the critical ownerLink instruction last for emphasis. Four sentences, all information-bearing, 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 carries the burden of explaining returns and does so concretely (draft post, ownerLink, reviewLink) while also explaining the required user hand-off. Combined with a fully documented input schema, nothing an agent needs to invoke and correctly relay results 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 imageUrls, caption and context are already documented, including the 2-10 bound and slide ordering. The description largely restates this (image count, public URLs, caption-or-context choice) rather than adding syntax or format detail beyond the schema; baseline 3 applies.

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

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

States a specific verb and resource ('Create a carousel post from 2-10 images (public URLs)') and adds scope constraints that make the tool's input contract immediately clear. However, it never distinguishes itself from the several other carousel-creating siblings (create_carousel, create_photo_carousel, create_facebook_product_carousel), so the agent must infer the routing from the input requirements 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 clear operational guidance: supply either a ready caption or a context for AI generation, and the emphatic 'ALWAYS give the user the ownerLink' instruction with its rationale (chat cannot display images). It stops short of explicit when-to-use/when-not-to-use guidance relative to the carousel siblings.

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

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

Annotations cover safety (readOnlyHint=false, destructiveHint=false, openWorldHint=true), and the description adds real value beyond them: it does not spend money, does not reserve funds, and returns a creative plus quote for review. It does not address idempotency despite idempotentHint=false and a requestKey parameter, which 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 core action and the non-spend constraint in the first two sentences. Mostly tight, though the garbled phrase 'oriiion shared advertiser identity' adds noise and slightly obscures the approval condition.

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

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

For a complex 11-required-param mutation with no output schema, the description usefully hints at the return value (creative and current quote) but leaves the parameter semantics largely unexplained. Adequate for routing, incomplete for correct invocation.

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

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

Schema description coverage is 0% across 11 required parameters, so the description must carry the burden. It gestures at budget, duration, and advertiser identity conceptually but never explains bidCents, goal, countries, requestKey, or the creative fields, leaving most inputs undocumented in both schema and prose.

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

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

States a specific verb and resource ('Save a ChatGPT ad DRAFT') and immediately bounds the scope with 'Does not launch, reserve funds or spend money.' It distinguishes itself from the sibling start_chatgpt_ad and edit_chatgpt_ad by making the draft-only nature explicit.

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

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

Explicitly routes the agent: 'Use start_chatgpt_ad only after the user approves the exact budget, service fee, duration and ... shared advertiser identity,' and adds the prerequisite 'No campaign-builder page is needed.' This is a clear when-to-use / when-to-escalate statement with the alternative 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 only say non-read-only, non-idempotent, open-world; the description adds the crucial fact that the automation goes LIVE immediately and sends real DMs to real people, which is the highest-stakes side effect here. It also mandates a human-approval gate before invocation, adding context annotations cannot express.

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

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

Two sentences, no padding: the first defines the tool and its live-fire effect, the second carries the approval requirement, the accountId source and the platform limit. The highest-risk information 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?

For a 14-parameter mutation with no output schema, the description covers the risk profile, prerequisites and platform scope adequately, and the rich per-field schema covers parameter detail. It does not indicate what the tool returns (e.g. the new automation's id) or what happens on duplicate/invalid keyword config, which an agent creating then referencing the object would benefit from.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns an extra point by telling the agent which values must be surfaced to the user for approval (dmMessage, keywords, accountId) and where accountId must come from. It does not add semantics for the remaining 11 optional parameters, which rely entirely on 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 precise verb and resource ('Create a comment→DM automation') and immediately characterises the resulting object's runtime behaviour plus platform scope. An agent can tell it apart from update_comment_automation, list_comment_automations and delete_comment_automation 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 a concrete prerequisite ('Use an accountId from list_comment_automations'), a platform restriction ('Instagram and Facebook only'), and a mandatory pre-flight step (get user approval after showing dmMessage, keywords and account). It stops short of naming a when-not condition or an explicit alternative for non-IG/FB accounts, so it is clear context rather than full routing guidance.

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

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

Annotations only flag destructive/openWorld/not-idempotent; the description adds the material facts an agent needs before committing — multi-minute runtime, roughly $0.30 of generation per account, and the reassurance that no customer-facing message is emitted. It also discloses side effects (writes a style guide, drafts posts, adds news sources/products) that explain the destructiveHint.

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

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

The staff-only warning and the capability summary are front-loaded, then cost/time, then the safety and follow-up instructions. The middle capability list is dense but each item maps to real work the tool performs and justifies the destructiveHint, so it earns its place despite the length.

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 redirects the agent to get_customer_onboarding for progress and explains that no customer contact happens here, covering the return-value gap. Staff-only scoping, cost, duration, and next steps are all present, so nothing needed to call this correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents all seven parameters including the small_business/thought_leader enum and the sv default. The description restates the website-vs-Instagram fallback, which the schema's instagramUrl description already covers ('used only when they have no website'), so it adds only marginal meaning. 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?

Opens with a specific verb+resource ('Set up a whole oriiion account for a customer') and then enumerates exactly what the setup entails — website/Instagram read, brand, images, news sources, products, style guide, first posts. This is clearly distinguishable from siblings like research_website, generate_style_guide, or complete_onboarding, which cover only slices of this workflow.

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

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

Gives explicit preconditions ('oriiion STAFF ONLY'), an explicit exclusion ('NOTHING is sent to the customer by this tool'), and names both the follow-up check tool (get_customer_onboarding) and the next action once satisfied (send_customer_welcome). The agent is routed through the full lifecycle, not just told when to fire the call.

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

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

Annotations declare a non-destructive write, and the description adds non-obvious behavior: if LinkedIn is not connected the tool returns a connect link the agent should hand to the user, and a single post covers both LinkedIn and later Instagram. It stops short of describing auth setup beyond the connect link or error conditions.

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

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

Front-loads the core action and format, then conditions (LinkedIn-only, connect-link fallback, Instagram-at-publish). Dense but each clause carries real information; slightly long 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 non-idempotent write with no output schema, the description covers the important edge behaviors (connect-link return, single-post model). What it does not cover is post-creation success output, which matters somewhat 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 coverage is 100%, so the baseline is 3. The description adds value by clarifying the caption/context relationship ('provide either a ready caption or a context for AI to write one'), which is a mutual-exclusion rule the schema descriptions only imply individually.

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 swipeable document post from a PDF) and pins the format and scope: the LinkedIn page-by-page carousel. It clearly distinguishes itself from PDF-less carousel siblings like create_carousel and create_photo_carousel by naming the PDF/LinkedIn constraint.

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

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

Gives strong when/when-not context: LinkedIn is the ONLY platform that renders a PDF, and Instagram is normally added at publish time rather than creation. It does not explicitly name alternative sibling tools (e.g. create_carousel) for when a PDF is not the right input, but the platform conditions are clear.

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

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

Annotations already mark this as a non-destructive write, but the description adds genuinely incremental behavior: the output is an *unpublished draft* (staging, not live content) and it must be reviewed before publishing/scheduling. That staging-versus-live distinction is not derivable from readOnlyHint/destructiveHint. It stops short of noting non-idempotency or auth requirements.

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

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

Three tight sentences with the core action front-loaded and the sourcing/next-step hints appended. No filler, though the draft-status fact is split across the first and last sentence rather than consolidated.

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, so the description would ideally say what the draft returns or how to retrieve its review link. It covers the creation flow adequately but leaves caption/campaign meaning and the return/lookup path unaddressed for a 3-required-param write tool.

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

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

Schema coverage is 0%, so the description carries full burden. It compensates well for productIds (source of IDs via list_products, 2–10 count, distinct images) but says nothing about caption or campaign semantics, leaving two of three required parameters undifferentiated from the raw schema types.

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

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

Specific verb+resource (create a Facebook link-carousel draft) with clear scope: unpublished, 2–10 owned products with distinct images. It distinguishes itself semantically from photo-carousel siblings, but never names the adjacent tools (create_carousel, create_photo_carousel, create_carousel_from_images, set_facebook_carousel) that an agent would need to weigh against it.

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

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

"Choose IDs from list_products" and "Review the draft before publishing or scheduling" give useful surrounding context – the sourcing step and the follow-on step. However there is no explicit when-not guidance and no routing to the sibling carousel-creation tools, so selection between them 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 establish a non-destructive write, but the description adds genuinely useful behavior: the link is read first (metadata, transcript, what it shows), it can take up to a minute for long video, the result is queued in the todo list rather than published, and posts use the user's own image rather than the creator's media. Only auth/permission expectations are unaddressed.

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, no filler, with the core action and its output options front-loaded before the latency and destination details. Sentences are long but each carries distinct information; nothing is repeated from the schema except the format list.

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

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

For a write tool with no output schema, the description covers what is produced, where it goes (todo list), how long it can take, and the media-ownership rule — enough for an agent to set expectations and follow up. Nothing essential is missing given full schema coverage.

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

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

Schema description coverage is 100%, so url, format, context, platform, and scheduledFor are already documented in the schema, including the format enum meanings. The description restates the format options and adds the media-ownership constraint for 'post', but contributes no additional syntax or default detail. Baseline 3 applies.

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

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

States a specific verb and resource ('turn a link the user shared ... into content') and enumerates the three concrete outputs (single post, phone-filmed script with teleprompter, Instagram carousel). The link-as-input framing cleanly separates it from siblings like create_from_trend, generate_from_news, generate_from_product, and create_post_from_image.

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

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

The three format outcomes are explained, which implies when each mode applies, and the 'lands in the user's todo list for review' note hints at the downstream workflow. However, it never names an alternative tool or states when to prefer this over create_from_trend or generate_from_news, so routing guidance 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 readOnlyHint=false already flagging a write/mutation, the description adds real behavioral context: the post uses the user's own image and never the creator's clip, the script is filmed on the phone via a teleprompter link, and it shares the create-from-link pipeline. It does not mention async generation or what the call returns, but the added traits go meaningfully beyond the annotations.

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

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

Three sentences, front-loaded with the core action and formats. Every clause is useful (source sibling, format outputs, pipeline equivalence, param guidance), though the parenthetical image caveat and pipeline note add slight length without new decision-relevant content.

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

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

For a 9-parameter mutation with no output schema, the description covers the source, outputs, and params sufficiently for correct selection and invocation. It stops short of describing the return value or asynchronous generation behavior, which an agent might want when this is one of many generate_* tools.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds intent beyond the schema by explaining that hook and idea from find_trends_for_business should be passed 'to keep the angle'. Its format enumeration is incomplete (omits reel), which the schema covers, so the lift is real but modest.

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 (turn one trend into content) and enumerates the concrete outputs: post, phone-filmed video script, or Instagram carousel. It explicitly ties the input to the sibling find_trends_for_business, so an agent can tell it apart from that listing tool and from create_from_link 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?

Usage is implied rather than stated: it is used after find_trends_for_business and consumes that tool's hook/idea. It notes 'Same pipeline as creating from a shared link' but never says when to prefer this tool over create_from_link or the other content-creation siblings, and there are no exclusions.

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

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

Annotations cover the mutation/safety profile (readOnly=false, destructive=false, idempotent=false), and the description adds real operational context beyond them: ~1 minute latency, a returned batchId checked via get_image_status, and mode-dependent behavior (new images use brand settings, edits preserve the original scene). It does not mention auth/permission needs, so 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?

Front-loaded with the core create/edit duality and packed with routing information; every sentence earns its place. It is a dense single paragraph with heavy em-dash use, which is slightly harder to scan but not padded.

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

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

For a 7-parameter async generation tool with no output schema, the description covers the workflow, the polling path (batchId -> get_image_status), prerequisites, mode behavior, and sibling alternatives. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds cross-parameter and cross-tool meaning the schema cannot — imageUrl switches the call into edit mode, and referenceImageUrls must come from use_character_reference to render the actual person. It does not explain count/imageType/aspectRatio defaults, which the schema already handles.

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

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

States a specific verb+resource ('Create a standalone image from a description, or EDIT an uploaded image') and explicitly distinguishes the two modes by the imageUrl parameter. It also names the siblings it is not (change_image, create_post_from_image), so an agent can route correctly without opening any schema.

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

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

Gives explicit when-to-use ('when the user asks for an image, a picture, a thumbnail or a graphic rather than a post'), names the alternatives for the post case, and states a prerequisite (call use_character_reference first for a named person). 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?

Beyond the annotations (write, non-destructive), the description discloses a lot an agent cannot infer: required entitlements, branding always coming from the owning account, transcription off unless requested, the 5-minute owner reminder behavior, no calendar sync/invites, and requestId reuse to avoid duplicates. The requestId dedup is a nuance against idempotentHint=false, but it is a client-supplied key rather than a claim that repeated calls are inherently idempotent, so it is additive rather than contradictory.

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

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

The purpose is front-loaded, but the body runs to roughly eleven sentences and mixes invocation guidance with output-presentation instructions (guestUrl/hostJoinUrl labels, 'do not call it a control panel'). Several defaults are restated from the schema, so the definition is information-dense rather than tight.

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, and the description compensates by describing the two returned links, their labels and language handling. Combined with prerequisites, defaults, reminder behavior, and CRM-linkage edge cases, an agent has everything needed to call this correctly and report the result.

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

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

Schema coverage is 67%, and the description covers most parameters contextually: explicit timezone-resolved startsAt, default 60-minute duration, transcription off by default, host reminder semantics, and the customer-vs-leadId resolution/ambiguity rule. Some content (duration default, transcription default) merely repeats schema defaults, and locale is only referenced obliquely via 'in the user's language'.

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

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

The opening sentence gives a specific verb, resource and scope: 'Create a branded oriiion video meeting in the authenticated user's My business workspace.' It further sharpens the boundary with 'This only creates the room: it does not invite anyone, sync calendars, start recording or join the meeting,' which cleanly separates it from siblings like prepare_meeting_link, get_meeting and list_meetings.

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

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

It states prerequisites (Business Suite, a customer instance, the Meetings grant), routes the agent between 'customer' and 'leadId' with a verification rule (leadId 'already verified with get_website_leads'), and instructs clarification on ambiguous matches. It stops short of explicitly naming the adjacent alternatives (e.g. prepare_meeting_link, link_meeting_customer), so the when-not-vs-sibling routing is only implied.

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

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

Goes well beyond the annotations (which only say non-read-only, non-idempotent, non-destructive) by disclosing the async lifecycle ('Returns generating, never finished'), the all-or-nothing success condition, the billing/accounting effect ('Counts as one post'), and the safety guarantee ('Never publish automatically'). These are exactly the behavioral traits an agent needs before invoking a generation tool.

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

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

Front-loaded with the core action and cardinality, and each subsequent sentence carries distinct information (routing, brief requirements, alternative tool, lifecycle, publish behavior) with no filler. It is dense and slightly list-like, but nothing is redundant.

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

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

With no output schema and thin annotations, the description supplies the return semantics, the draft-promotion condition, and the no-auto-publish guarantee. Remaining gaps are minor parameter explanations (topic, characters) rather than anything that would cause a misinvocation.

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

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

Schema description coverage is 0%, so the description has to carry the load and it does for the key nested fields: it explains that each slide needs a distinct complete brief preserving subjects and shared constraints, and instructs on productId and referenceImageIndex usage. It leaves 'topic' and the 'characters' array undocumented, so it does not fully close the coverage gap.

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

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

States a specific verb and resource ('Create ONE carousel post containing 2-10 separately generated photos, in the requested order'), including scope and ordering. It explicitly distinguishes itself from the closest sibling by naming create_carousel_from_images, so an agent can route correctly without opening either schema.

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

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

Gives explicit when-to-use ('when the user asks for an image/product/photo carousel') and when-not ('not separate posts or a text slide deck'), plus the alternative for the adjacent case ('Original photos without AI changes use create_carousel_from_images instead'). 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 the safety profile (non-read-only, non-destructive, non-idempotent, closed-world). The description adds real behavioral context beyond that: output is a rendering status rather than a finished video (async), existing photos are preserved, brand text inherits saved brand settings, and account defaults must not be changed. These are exactly the operational facts annotations cannot convey.

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

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

Front-loaded with the core action and constraints, and every sentence carries information. However, the trailing clauses about brand settings, fonts, and account defaults read as guardrail instructions rather than tool documentation, giving the text a slightly scattershot feel for its length.

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

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

With no output schema and 0% schema description coverage, the description does the heavy lifting, including clarifying the return value is a status. It omits how to retrieve the finished render (e.g., via the generation-status tool) and leaves one parameter undocumented, so it is strong but not fully complete.

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

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

Schema description coverage is 0%, so the description must compensate, and it largely does: it documents the 2-12 photo count, the ordering semantics (not expressed in the schema), the targetSeconds 5-60 range, and the music/text defaults. The 500-char 'description' parameter goes entirely unexplained, which is the main gap.

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

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

States a specific verb and resource ('Assemble 2-12 uploaded photos into a video') plus the key constraint that each photo appears exactly once in the supplied order. It also implicitly distinguishes itself from trend-based siblings ('uses the normal video renderer, not a trend sound') and from carousel tools, so an agent can route correctly.

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?

Clearly frames the tool as the non-trend renderer and notes the defaults (silent, text-free reel) and the 2-12 photo envelope, which tells the agent when this tool applies rather than create_from_trend or create_photo_carousel. It stops short of explicitly naming the alternative tools or stating when NOT to use it.

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

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

Annotations already declare this is a non-read-only, non-idempotent, non-destructive creation operation. The description adds useful behavioral context beyond annotations: the image becomes post media, AI writes captions, the operation runs asynchronously, and the user is notified when posts are ready.

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

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

The description is front-loaded with the core action, followed by relevant output behavior and async execution. It is concise and every sentence contributes useful information.

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

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

For a creation tool with rich schema coverage and annotations, the description covers the essential behavior, including AI caption generation and async notification. It does not mention status-checking mechanisms, but the notification statement largely covers what an agent needs to know.

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

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

Schema description coverage is 100%, so all five parameters are already documented in the input schema. The description adds meaning around the required image URL and AI captioning but does not further explain count, topic, enhance, or editPrompt 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?

The description states a specific verb and resource: creating posts from a user-provided image URL, with AI-generated captions. It is clearly distinct from generic post creation or image editing, though it does not explicitly name sibling 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?

The description implies usage when the user provides a public image URL and wants posts created from it. However, it gives no explicit when-not guidance or comparison to siblings such as create_post_from_video, create_from_link, or generate_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 declare the safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=false), so the bar is lower, and the description adds genuinely useful context beyond them: the operation is asynchronous and the user is notified on completion. It still doesn't say whether the tool returns immediately with a job id or how to poll, but the async disclosure is meaningful added value.

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

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

Two tight sentences with zero filler, front-loading what the tool does and following with the async/notification caveat. 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?

With no output schema, the description correctly carries the return-behavior burden by disclosing the async notification flow. Combined with 100% schema coverage for inputs and clear annotations, little an agent needs is missing, though the polling/status path is left unspecified.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters, making 3 the baseline. The description reinforces that videoUrl must be a public URL and that topic drives the AI caption, but adds no syntax or format detail beyond what the schema provides.

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

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

States a specific verb+resource ('Create posts from a video') and adds the two behavioral facts an agent needs: the video becomes the post media and AI writes captions from the topic. It does not, however, differentiate itself from close siblings like create_post_from_image or process_video, which an agent must otherwise disambiguate by name alone.

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

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

Usage is implied rather than stated: the '(public URL)' qualifier tells the agent the video must already be hosted, but there is no explicit when-to-use or when-not versus siblings such as create_post_from_image, create_from_link, or process_video. Adequate but leaves routing 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 establish the mutation profile (non-readonly, non-idempotent, non-destructive), and the description adds real behavioral context beyond them: the product lands in the user's manual feed, a feed-{id} is returned, and image URLs are re-hosted on oriiion storage. The storage side effect is a genuinely useful disclosure not captured by 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?

Three short, front-loaded sentences with no filler; the core action comes first, followed by the actionable return value and one notable side effect.

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 explains the return value (feed-{id}) and its immediate reuse with generate_from_product, plus the storage side effect. It is complete enough to invoke correctly, though it could mention whether re-hosting is required or optional.

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 title, imageUrls, and description. The description only adds the re-hosting behavior for image URLs, which is marginal over the schema's baseline documentation.

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

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

States a specific verb+resource ('Create a new product in oriiion') and clarifies the destination scope ('added to the user's manual product feed'). This distinguishes it from create_product_video and from feed-generation tools, though it doesn't explicitly name a sibling to avoid.

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

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

It implies downstream usage by noting the returned feed-{id} can be used with generate_from_product, which helps position it in a workflow. However, it gives no explicit when-to-use/when-not guidance or comparison against list_products or other creation tools.

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

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

Adds substantial behavior beyond the annotations: it runs in the background for minutes, lands in the Todo list, returns a post id and task id, and must be verified via get_task_status ('never say it is done'). It also discloses the cost/quality tradeoff between 'designed' and 'simple' looks, which no annotation conveys.

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

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

Front-loads the outcome ('Make a short vertical video...') before the option lists. The dense parenthetical enumerations make the middle heavy and slightly run-on, but nearly every clause carries operational 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 an async, open-world creation tool with no output schema, the description covers what is produced, how long it takes, where it lands, what identifiers it returns, and how to confirm completion. An agent has everything needed to call it 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 coverage is only 60%, and the description compensates by explaining the semantics of the enum values — sound options and their meaning, 'look' default (designed) with a concrete description of the cheaper 'simple' mode, and the first-photo rule for multi-product runs. 'steer' and 'targetDuration' are left to the schema, but the description clearly adds meaning over the raw enums.

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 ('Make a short vertical video (Reels/TikTok) out of one or more products from list_products') and pins the source of the inputs. This clearly separates it from siblings like create_photo_reel or create_post_from_video, which are not product-based.

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 useful preconditions ('Needs at least 2 product photos in total', productIds come from list_products) and post-invocation guidance, but never states when to prefer this tool over create_photo_reel, generate_from_product, or create_video_shoot. Usage is implied rather than routed.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false; the description adds real behavioral context beyond them — scripts are stored verbatim, auto-cut into takes, nothing is rewritten, filmed, or published, and the user consumes it later under Shoots on their phone. It does not disclose what happens on repeated calls (idempotentHint=false) or any permission requirements, 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?

Front-loaded with the primary action, then scope, then the sibling alternative, then behavioral constraints. Four sentences is slightly more than needed — the final sentence about the teleprompter/camera experience is nice context but not essential to invoking the tool.

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

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

For a two-parameter mutation tool with full annotation coverage and no output schema, the description covers purpose, trigger conditions, alternatives, and side effects. The only gap is what the call returns (e.g. project identifier or status), which the agent must discover elsewhere.

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

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

Schema coverage is already 100%, so the baseline is 3. The description still adds meaning over the schema: 'Every script is stored word for word and cut into takes automatically' clarifies the script-vs-segments relationship, and 'nothing is rewritten' constrains how the input text is handled downstream.

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

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

Opens with a concrete verb+resource ('Set up a whole video project at once') and immediately enumerates what that means: every script for a client or campaign, filed into folders. It explicitly contrasts with sibling 'create_video_shoot', so an agent can distinguish the two 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 explicit trigger conditions ('when there is more than one video to make — a product launch, a client's month of content, a shot list someone sent over') and names the alternative tool for the single-video case. The schema further routes to list_shoot_folders for folder reuse. 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?

Goes well beyond the annotations: it discloses that the returned link is short-lived, that the USER must open it in a browser and drop files (human-in-the-loop), and that a second call is required to obtain stored URLs. It also exposes the API key requirement for the alternative path. Annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false) are consistent with a link-generating, non-destructive operation.

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

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

Front-loads the purpose and the routing decision before the mechanical detail, and every sentence carries decision-relevant content. The embedded curl block makes it longer than typical, but it is high-value guidance rather than filler.

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

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

For a tool with no output schema and a single optional parameter, the description supplies everything an agent needs: what the link is, who consumes it, its lifetime, and the exact next call to make. No meaningful gap remains for correct invocation.

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

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

Only one optional parameter ('note') and the schema already documents it at 100% coverage, so the baseline of 3 applies. The description adds no extra meaning about the note parameter (e.g. that it is only shown to the agent, not the user).

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

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

States a concrete verb+resource (create an upload link for the user's own files) and immediately scopes it to files that exist only inside the conversation. It cleanly separates itself from siblings upload_file and list_uploaded_files by describing the browser-drop workflow rather than a direct upload.

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

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

Explicitly says when to use it ('when you cannot make HTTP requests or the file only exists as an attachment in the chat') and when not to ('IF YOU CAN RUN SHELL COMMANDS, skip this and upload directly'), including the alternative command. It also names the required follow-up call (list_uploaded_files) and the downstream tools that consume the result.

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 safety profile (not read-only, not idempotent, not destructive); the description adds the real behavioral payload: a link opens teleprompter+camera on phone, QR code on desktop, per-take filming, 1-3 min auto-render, output lands on the same page, and critically that this chat cannot be notified on completion.

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

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

Front-loads what the tool does and keeps every clause functional (mode selection, device behavior, render timing, the notification caveat). It is a dense single paragraph, but no sentence is filler.

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

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

With no output schema and no annotation detail, the description carries the full burden and does: it explains what is returned (a page/QR link), what happens after filming (auto-render), where the result appears, and the async notification gap. Nothing an agent needs to set expectations with the user is missing.

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

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

Schema coverage is 100%, so 3 is the floor, but the description goes further by explaining that `script` is filmed verbatim and only cut into takes, that `topic` triggers oriiion writing, and that sourceShootId re-records the original take order. folderPath, productIds and targetSeconds are left entirely to the schema.

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

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

States a concrete verb+resource transformation ('Turn a script into a talking-head video the user films on their phone') and names the two input modes. An agent can distinguish it from render_video_shoot, process_video, and create_shoot_project without opening any schema.

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

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

Explicitly routes between `script` (user's exact words, nothing rewritten) and `topic` (oriiion writes it), and tells the agent to call get_video_shoot_status when the user returns. It does not, however, say when to prefer this over adjacent siblings like create_shoot_project or render_video_shoot.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is partly covered. The description adds real value beyond them: it discloses the cascading effect (recipient list is also deleted), the mid-send precondition, and the user-confirmation requirement — all material for a destructive operation.

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

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

Three tight sentences, front-loaded with the action and its scope, followed by the precondition and confirmation requirement. 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 single-parameter destructive tool with no output schema, the description covers the essential agent needs: what is destroyed, the precondition, and the required confirmation. Return-value explanation is unnecessary without an output schema.

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

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

Only one parameter and schema coverage is 100%, with the schema itself pointing to list_broadcasts as the source. The description adds no syntax or format detail beyond what the schema already 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+resource ('Delete a broadcast') and even scopes the blast radius ('and its recipient list'). This distinguishes it cleanly from sibling destructive tools like delete_post or delete_comment_automation, which operate on different resources.

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

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

Provides a clear precondition ('a broadcast that is mid-send must be cancelled first') and a required workflow step ('confirm with the user before deleting'). It stops short of naming an explicit alternative tool, but no sibling performs broadcast deletion, so routing ambiguity is minimal.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is partly covered; the description adds the irreversibility framing ("Permanently") and a required user-confirmation step, which is real operational context. It does not describe any cascade effects (e.g., what happens to existing DM history) or error behavior, so it stops short of full disclosure.

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

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

Three short sentences, each earning its place: what it does, the safer alternative, and the confirmation gate. The destructive nature is stated first, which is the correct ordering for a delete tool.

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

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

For a single-parameter delete with no output schema and annotations that already declare destructiveness, nothing essential is missing: permanence, the non-destructive alternative, and the confirmation requirement are all covered.

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 carries a pointer to list_comment_automations as its source. The description adds no format, validation, or sourcing 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 ("Permanently delete a comment→DM automation") with the permanence qualifier front-loaded. It is clearly distinguishable from update_comment_automation, which the description itself names, so an agent can route correctly without opening a schema.

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

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

Gives explicit when-not guidance ("To stop it temporarily, use update_comment_automation with isActive:false instead") naming the exact alternative and the parameter value to use. It also states a procedural prerequisite ("Confirm with the user before deleting"), 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 destructiveHint=true, non-idempotent, non-read-only, so the safety profile is covered. The description adds genuinely new behavioral context beyond that: a state-based precondition that some posts are undeletable. It does not state irreversibility, required permissions, or failure behavior beyond the implicit refusal.

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

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

Three short sentences, front-loaded with the action before the constraint. The third sentence restates the second in inverse form ('only drafts can be deleted' / 'published cannot'), a small redundancy that could be trimmed.

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 no output schema, the description covers the critical decision input (deletability by post state). It omits what happens on success/failure and whether deletion is permanent, which would round it out.

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 postId parameter, so the schema already documents the argument fully. The description adds no ID format, sourcing, or lookup guidance, so baseline 3 applies.

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

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

States a specific verb and resource ('Delete a post') unambiguously, so an agent immediately knows the operation. It does not explicitly distinguish itself from other delete siblings (delete_broadcast, delete_comment_automation), but the resource is named precisely enough to avoid confusion.

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

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

The description gives an explicit eligibility rule: only draft and scheduled posts can be deleted, and published posts cannot. This is a clear when-not condition that prevents a failed call. It stops short of naming an alternative path (e.g., unpublishing first), so it isn't a full 5.

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

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

Annotations already declare the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower. The description adds real value beyond them: a cap of 'up to 24' results, that it is an interactive show-to-user step, and that a separate save tool completes the flow.

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

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

Two tightly packed sentences with zero filler, front-loading the collection action and cap before the follow-up save step. Every clause earns its place.

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

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

For a single-optional-param discovery tool with no output schema and annotations already covering safety, the description covers sources, cap, and the next step well. It could say more about behavior when no candidates are found or how the selection step is triggered, but nothing essential is missing.

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

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

With 1 parameter at 100% schema description coverage, the schema already documents instagramHandle fully, including its default. The description only obliquely references Instagram as a source, adding no syntax or override 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 ('Collect candidate brand images') plus the three sources (website, Instagram posts, earlier research), so the agent immediately understands the resource and scope. It is clearly distinguishable from siblings like search_my_images (search a library) and recommend_images_for_post (recommend for a single post).

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

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

The description embeds the workflow context: collect candidates, show them to the user, then save via select_brand_images, explicitly naming the follow-up tool. It gives clear when-to-use context but does not explicitly contrast with alternatives such as search_my_images or recommend_images_for_post.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), and the description adds substantial context beyond them: it replaces any earlier draft on the message, adds it to the to-do list, surfaces it under E-post › Utkast, returns stored draft text and replyArgs, and documents character limits and MAIL_NOT_FOUND/MAIL_DRAFT_TOO_LONG errors.

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

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

Purpose and the 'sends NOTHING' caveat are front-loaded, and most sentences earn their place (side effects, error codes, send handoff). It is still a dense single block, and the send-path instructions could be tightened since they describe a different tool's invocation.

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-param write tool with no output schema and no param descriptions, the definition covers everything an agent needs: scope, side effects, replacement behavior, return payload, language rule, size limit, and the two failure codes — all before the agent calls it.

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

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

With 0% schema description coverage the description must carry the load, and it does for two of three params: 'one received message' plus 'MAIL_NOT_FOUND means the id is not a received message' scopes the id, and the ~3,500-character cap constrains text. The locale parameter is only indirectly addressed via 'Write in the language of the conversation,' so its enum values remain undocumented.

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

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

States a precise verb+resource: 'Save a reply draft on one received message in the authenticated business mailbox, for the owner to review,' and explicitly clarifies it 'sends NOTHING.' This clearly separates it from the send path and from list/get siblings in the business-email 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 explicit when-to-use (drafting for owner review), when-not (not authorization to send), and the exact alternative path: show the owner the draft, get explicit approval, then call send_business_email with replyArgs, new requestId and approved:true. It even names the sibling tool, 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=false and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavioral detail beyond that: omitting platform rewrites the main caption everywhere, whereas supplying platform scopes the change and explicitly leaves other platforms' variants intact.

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, purpose front-loaded, then the branching behavior. No filler; every clause carries operational meaning.

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

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

For a mutation tool with no output schema and full annotation coverage, the description supplies the operation, its scope, and the platform-conditional behavior an agent needs to call it correctly. Nothing essential is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: it clarifies the default behavior when the optional platform is omitted (update the main caption everywhere) versus its scoped effect. This resolves the ambiguity the bare 'Only update the caption for this platform' schema note leaves.

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 (update) and resource (caption/text of an existing post), which cleanly distinguishes it from generation siblings like generate_platform_captions and from add_image_to_post. An agent can identify the operation without opening the schema.

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

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

The description implies the use case (editing an existing post's caption) but never names an alternative tool or states when not to use it. The with/without-platform sentence is really parameter behavior, not selection guidance.

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

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

Goes well past the annotations by disclosing that a replacement creates a new DRAFT and 'leaves the original unchanged', that the original is only ended as authorized, and that a fresh requestKey is required. This clarifies the destructiveHint=false claim (the original is preserved) and adds prerequisite and workflow context the structured fields do not carry.

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

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

Front-loaded with the core action and constraint, and the sentences are dense with distinct information rather than filler. The trailing authorization instruction is slightly process-heavy for a description but still earns its place for safe replacement handling.

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 nested, multi-step mutation tool with no output schema, it covers the flow, prerequisites, and the replacement semantics an agent needs. It stops short of enumerating editable fields or failure modes, so it is strong but not exhaustive.

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

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

With 0% schema description coverage, the description must carry the load and it explains three of the five top-level params well: revision ('latest revision from get_chatgpt_ads'), replacement, and requestKey. However, campaignId and the entire nested 'changes' object (10 sub-fields such as body, headline, countries, budgetCents) get no semantic explanation anywhere, which is a real gap.

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

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

States a specific verb and resource ('Edit selected fields of a ChatGPT ad draft') and immediately scopes the object type (draft vs launched ad). It explicitly distinguishes itself from the sibling update_chatgpt_ad_budget, so an agent can route without opening either schema.

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

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

Gives explicit when-to-use rules: drafts are edited directly, while launched ads require replacement=true plus a new requestKey, and budget-only live edits must go to update_chatgpt_ad_budget. Alternatives and their selecting conditions are named outright.

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

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

Annotations already declare the mutation/safety profile (readOnly=false, destructive=false, idempotent=false), so the bar is lower. The description adds real value beyond them: it discloses the asynchronous nature, the ~1-2 minute duration, that the edited image is applied to the post automatically, and how to track progress via get_task_status.

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

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

Two tightly written sentences with zero filler; the core purpose is front-loaded and the async/tracking details follow. Every clause earns its place.

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

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

For an async, no-output-schema tool, the description covers the essentials an agent needs: what it does, that it runs in the background, that the result is applied automatically, and how to poll. It stops short of describing what get_task_status returns or whether the edit is reversible.

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

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

Schema coverage is 100%, so the baseline is 3 and the schema already documents both params. The description adds meaning by giving concrete examples of valid instruction content ('make the background blue', 'remove the text'), clarifying the expected free-form input beyond the schema's terse 'What to change in the image'.

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 ('AI-edit a post's image') and clarifies the interaction mode with a natural-language instruction, backed by two concrete examples. It is distinguishable from manual siblings like open_image_editor, but it never names or contrasts with alternatives such as change_image, so it falls short of full sibling differentiation.

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

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

The scenario in which this tool applies is implied by the purpose (edit a post's image via instruction) and the note to check get_task_status gives operational context. However, there is no explicit when-to-use/when-not guidance and no mention of when to prefer change_image or open_image_editor 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 flag destructiveHint=true, but the description adds material context they cannot express: the action is irreversible (cannot be resumed), unspent reservations settle only after the final daily report and at least 48 hours after ending, and no instant refund occurs. This is exactly the kind of consequence disclosure a destructive tool needs.

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

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

Three short sentences, front-loaded with the action and its two modes, then the irreversible consequence, then the settlement/refund timing. Every sentence adds decision-relevant information with no padding.

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

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

For a one-parameter tool with no output schema, the description covers the important unknowns: destructiveness, non-resumability, and delayed fund settlement. The remaining gap is the provenance/format of campaignId, which the schema does not supply.

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

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

Schema description coverage is 0% for the single required parameter, so the description carries the full burden of clarifying campaignId — and it says nothing about it. It neither identifies the ID's source (e.g., from get_chatgpt_ads or list_ad_campaigns) nor whether it must reference a draft versus a live campaign, which matters given the tool's dual behavior.

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 ('End a ChatGPT draft or archive a launched campaign') and distinguishes its two operational modes by campaign state. An agent can tell it apart from edit_chatgpt_ad or update_chatgpt_ad_budget at a glance.

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

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

The description conveys the operative condition for choosing this tool — permanence ('It cannot be resumed.') — which implicitly steers an agent toward pause_chatgpt_ad for reversible stopping. However, it never names that alternative or states an explicit when-not condition, so the routing is only implied.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, but the description adds genuine context beyond them: the sourcing method and the crucial fact that results are non-authoritative candidates requiring user confirmation before saving. It stops short of describing result volume, confidence, or failure behavior when no website exists.

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

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

Two sentences, zero filler. The capability and its scope come first, and the confirm-then-save handoff is front-loaded as the closing imperative.

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

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

For a zero-parameter, no-output-schema discovery tool, the description covers what it does, how it does it, what it returns conceptually (candidates), and the required follow-up step. Nothing needed to invoke it correctly is missing.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. It correctly avoids inventing parameter guidance that would not apply.

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

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

Specific verb (find) plus resource (social media profiles), with the exact platforms enumerated and the mechanism (website link harvesting + web search) named. It is clearly distinguishable from the sibling set_social_profiles, which it references 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?

Explicitly states the workflow: this tool returns candidates only, the user must confirm, and then set_social_profiles is the tool that persists them. The agent is routed to the correct sibling with the condition that selects it.

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

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

Annotations already declare readOnly/idempotent/non-destructive and closed-world, so the safety profile is covered; the description adds useful behaviour beyond that — the supported markets (US, GB, SE, GR), the source platforms behind each feed type, that audio is 'commercially cleared', and that Creator Only trends are excluded by default. It does not mention latency, rate limits, or whether the business profile is auto-resolved (only implied by the country default).

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

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

Two sentences, front-loaded with the agent's role and output, then the invocation cue. The long em-dash enumeration of feed types is dense but earns its place by mapping sources to content formats. Minor redundancy with the schema enums keeps it off a 5.

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

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

With no output schema, seven optional parameters, and 100% schema coverage, the description supplies the missing pieces: what the tool returns per trend (a hook and a content idea), the supported markets, and the intended pre-authoring workflow. Not fully complete since it omits whether results are deduplicated or how the business profile is used, but that is a small gap for a read-only discovery 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% with three enum parameters that all carry their own descriptions, so the schema does the heavy lifting. The description largely mirrors that information — 'Markets: US, GB, SE, GR' restates the country enum, and the feed-type enumeration repeats the feedType description. Baseline 3 is appropriate; almost no meaning is added 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?

The description names a specific actor and output: a 'Trend Agent' that 'picks today's trends' and 'returns a tailored hook and content idea for each', with concrete source types (Google/X surges, TikTok/Instagram videos, memes, cleared sounds). That is far more specific than a tautology. It stops short of 5 because it never distinguishes itself from adjacent siblings such as search_trending_audio, get_trend_details, create_from_trend or google_ads_discover_trending_keywords, whose scopes overlap visibly.

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 before writing a trend-based post, meme or video script' gives an explicit triggering context, which is more than most siblings offer. However, it names no exclusions and no alternative tool, so an agent still has to infer when to call get_trend_details or search_trending_audio 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?

Adds substantial context beyond the annotations: the customer-facing page behavior (message shown with a dashboard button), that staffSummary is stored in the support log and never shown to the customer, and that unanswered items persist as a to-do. The 'call once' instruction aligns with idempotentHint=false, reinforcing non-repeatable behavior.

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

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

Front-loads the audience restriction and core action, then covers the customer page effect and the timing condition. It is dense and the parenthetical clauses make it slightly meandering, but every sentence carries usable 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 mutation tool with no output schema, the description explains the downstream effects an agent cannot otherwise infer: the message is displayed to the customer with a dashboard button, the staff summary goes only to the support log, and unaddressed items remain as to-dos. Combined with annotations and full param docs, nothing essential is missing.

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

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

Schema coverage is 100%, so all three parameters are already fully documented in the schema. The description only reinforces this by mentioning 'Pass staffSummary for support' and the language requirement for the message, adding marginal 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: 'Mark your work on the onboarding as done and give the customer your closing message.' Combined with the 'STAFF ONLY' restriction and the distinction from siblings like start_agent_onboarding_build and complete_onboarding, an agent can identify what this tool does without opening the schema.

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

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

Gives explicit when-to-use conditions ('when the build is done and the website and brand are settled') plus an edge-case fallback ('or the customer stopped answering'), and a 'call once' constraint. It stops short of naming sibling alternatives (e.g. complete_onboarding) to disambiguate, so it is clear context but not full when/when-not routing.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false and destructiveHint=false, so the mutation profile is covered. The description adds real value beyond that: it discloses that execution is asynchronous and that the user is notified on completion, which the annotations cannot express and which changes how the agent should behave after calling it.

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

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

Three short sentences, front-loaded with purpose, then the key parameter rule, then the async behavior. No filler and nothing buried.

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

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

For a 3-parameter tool with no output schema, the description covers purpose, the one non-obvious parameter rule, and the async completion path. The only meaningful gap is that it doesn't point the agent at a status/retrieval tool (get_generation_status, get_post) for the generated results.

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

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

Schema description coverage is 100% and the schema already states the count default, the max of 5, the platform enum, and 'Article id from list_news. Omit to auto-pick the most relevant one.' The description largely restates the articleId omission rule rather than adding syntax, format, or constraint detail beyond it.

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 (generate), an output type (thought-leadership posts), and the source resource (a news article). The news-article source is the key differentiator from the many sibling generators (generate_from_product, create_from_trend, create_from_link, generate_posts), so an agent can route to it 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 one concrete usage condition — omit articleId to auto-pick the most relevant recent article — which is genuinely useful routing guidance. However, it never says when to prefer this tool over the other content-generation siblings (e.g. generate_from_product or create_from_trend), so alternative 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 cover the safety profile (not read-only, not destructive, not idempotent), so the description's added value is what it contributes beyond that: it discloses the async execution model and the user-notification behavior, plus the 'no new picture is drawn' constraint. It stops short of stating permissions or rate limits, so a 4 is warranted.

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

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

Two tight sentences: the positive scope first, then the routing rule to the sibling. Every clause earns its place and no filler is present.

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

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

For an async generation tool with no output schema, the description covers the key facts an agent needs: the input constraint, the async/notification behavior, and the sibling routing. It could note how to check generation progress (e.g. via get_generation_status), but the notification statement largely closes that gap.

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

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

Schema coverage is 100%, so all three parameters (productId, count, topic) are already documented with examples in the schema. The description reinforces the single-product constraint but adds no syntax or format detail beyond what the schema provides; baseline 3 is appropriate 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 (generate) and resource (a plain post from one product), and pins the exact constraint: exactly ONE product, built on that product's own main photo. It explicitly distinguishes itself from generate_posts, so an agent can route correctly 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?

Spells out both when to use this tool (one product, no new image) and the exact conditions that select the alternative — two or more products, product+person, or a new picture — naming generate_posts and even the relevant arguments (productIds, characters). 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 readOnlyHint=false, destructiveHint=false, and idempotentHint=false. The description adds real behavioral context beyond that: the base caption is preserved and each platform publishes its own variant, clarifying this is a non-destructive additive write. It doesn't explain what happens on re-generation (non-idempotency) or platform-connection prerequisites, 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 tightly written sentences, front-loaded with the core action and scope, with the second sentence delivering the key mutation semantics. 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 one-parameter generation tool with no output schema, the description covers what is produced, the platform scope, and the effect on the base caption. It stops short of describing the return shape (e.g., whether variants are returned or stored per platform) or the need for connected platforms, leaving a small gap.

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

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

Schema coverage is 100% and there is a single parameter (postId) already documented in the schema. The description's 'for one post' merely restates the schema semantics without adding format or constraint detail, so the baseline 3 applies.

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

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

States a specific verb (generate) and resource (platform-specific caption variants) with an explicit scope ('for one post'). It is clearly distinguishable from siblings like edit_caption (edits the base caption) and generate_posts (generates whole posts), and it names the target platforms.

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

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

The phrase 'for one post' and the mention of 'each connected platform' imply the context of use, but there is no explicit when-to-use/when-not guidance or routing to alternatives such as edit_caption. Usage is inferable rather than stated.

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

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

Adds substantial behavior beyond the annotations (which only declare non-read-only, open-world, non-idempotent, non-destructive): product photos come from the user's catalogue or the web, scheduling reserves the date and creates an idea review card, approval is required before publishing, and it returns a task ID and group ID immediately with the explicit instruction not to claim it is already scheduled. This is exactly the context an agent needs to set expectations.

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

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

Front-loaded with the core purpose, then flows through product detection, scheduling/approval, platform targeting, and return semantics. It is dense and long, but nearly every sentence carries actionable instruction; only minor tightening would be possible.

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

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

For an 11-parameter mutation tool with no output schema, the description covers the key gaps: that it returns a task ID and group ID, that approval is required, that the user is notified when ready, and where to check progress. Nothing an agent needs to invoke and report on this tool correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description maps natural user phrasing onto parameters ('only TikTok', 'LinkedIn and Instagram', 'everywhere' -> platforms; 'a post about A and B' -> productIds in one call) rather than merely restating schema text. That mapping adds real selection value on top of the schema.

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

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

States a specific verb and resource ('Generate new social media posts using AI'), and the body clarifies the scope (auto product detection, scheduling, platform targeting). It does not, however, name the siblings it is distinct from (e.g. generate_from_product, create_post_from_image, generate_from_news), so an agent must infer routing.

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

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

Gives concrete conditional guidance: pass scheduledDate/scheduledTime only when a date is explicitly requested, pass platforms when the user names networks, pass instagramPlacement 'story' for a story, and 'Check get_generation_status if they ask for progress' names an alternative. It stops short of stating when this tool should be avoided in favor of image/video-specific siblings.

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

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

The 'Nothing is saved' clause directly reinforces the readOnlyHint=true annotation and tells the agent the result is ephemeral until save_style_guide is called — useful workflow context beyond the annotations. It does not, however, describe return format or any generation constraints, so it adds value but is 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?

Two sentences, zero waste. The core action and its contents come first, with the non-persistence caveat and next-step handoff following. Every clause earns its place.

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

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

For a single-optional-param generation tool with no output schema, the description covers what is produced, that nothing persists, and the follow-up path. The only minor gap is that it doesn't hint at the return shape of the generated guide.

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 only one optional parameter (toneHint) with 100% schema description coverage, so the schema already carries its meaning. The description mentions generating from the business profile but does not clarify how toneHint influences output, so it adds nothing beyond the schema — baseline 3.

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

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

States a specific verb (generate) and resource (content style guide), then enumerates the outputs it contains (tone of voice, dos, don'ts, emoji & hashtag policy). It also names the sibling save_style_guide as the persistence counterpart, so an agent can distinguish it from that tool immediately.

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

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

Explicitly describes the workflow: generate, show the user, apply edits, then persist with save_style_guide. This names the alternative tool and the condition that routes to it, 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, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered by structured data. The description adds one useful behavioral fact — that the lookup is implicitly scoped to the authenticated account rather than an arbitrary target — but says nothing about what is returned or whether the call can fail when no account is authenticated.

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

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

A single eleven-word sentence with zero filler and the subject (authenticated user's data) front-loaded. It is appropriately sized, though it is arguably too terse to be maximally useful given the absence of an output schema.

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

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

With no output schema, the description is the only place an agent could learn what comes back, and it stops at the vague phrase 'profile and business information'. It is otherwise adequate for a zero-parameter read whose annotations already cover the safety profile.

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

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

The tool takes zero parameters, so there is no parameter semantics burden to carry; the baseline for a no-param tool is 4. The description correctly implies no input is needed by framing the call around 'the authenticated user'.

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 (get) and resource (account info), scoped to the 'authenticated user' so the agent knows it is not a target-selectable lookup. It does not, however, distinguish itself from near-neighbours like get_customer_profile, get_brand_identity, or get_connected_platforms, which overlap with 'profile and business information'.

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

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

There is no when-to-use guidance at all: no indication of when this should be preferred over get_customer_profile, get_brand_identity, or get_billing_status, and no prerequisites mentioned. The agent must infer usage purely from the name.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered without the description's help. The description adds the useful unit convention ('Amounts are in cents') but says nothing about auth scope, staleness, or how far back 'recent transactions' extends.

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

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

A single sentence, front-loaded with the resource, followed by the returned fields and the unit convention. No filler and nothing that needs to be read twice.

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

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

With no output schema, the description carries the burden of explaining the return shape, and it does list the key fields plus the currency unit. It stops short of describing transaction count, pagination, or ordering, which would help for the 'recent transactions' portion.

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

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

The tool takes zero parameters, so the baseline of 4 applies. The description correctly describes a no-argument read of the caller's own wallet, and the cents convention is the only semantic detail that could be conveyed.

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 ('Get the user's prepaid advertising wallet') and enumerates the contents returned (balance, reserved funds, service fee, recent transactions). It does not distinguish itself from nearby siblings like get_billing_status or get_pricing, so an agent must infer which one is wanted.

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

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

The description contains no when-to-use guidance, no prerequisites, and does not name any alternative tool. Nothing tells the agent when this wallet view is preferable to get_billing_status or get_pricing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. Beyond that the description adds genuine context: staff-only authorization, the delta semantics of newFromCustomer relative to the last read, and the long-poll wait behavior. It stops short of describing failure modes or cursor staleness handling, 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?

It is a single dense paragraph, front-loaded with the access restriction and the scope, then the return contents, then the call pattern. Every sentence carries information, though the long inventory of returned fields runs close to list-dumping rather than tight prose.

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

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

With no output schema, the description must carry return-shape information and it does: it names the customer-progress signals, build log, brand, sent cards, and the newFromCustomer delta. What is missing is any sense of the response structure or how large these sections can get, but for a 3-parameter read tool this is close to sufficient.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema already documents all three parameters. The description still adds value by explaining the intent behind two of them — the cursor round-trip for since and using waitSeconds to wait rather than poll — which is rationale the schema text does not supply.

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 ('Everything about one agent onboarding in a single read') and enumerates the concrete payload it returns (customer progress, build progress/log, brand, cards, newFromCustomer). That enumeration meaningfully separates it from generic onboarding readers, though it never names the adjacent siblings like get_customer_onboarding or get_onboarding_status.

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

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

It gives real operational guidance for the cursor/wait pattern ('Pass back the returned cursor as since; pass waitSeconds to wait for the customer instead of polling') and a hard access constraint (oriiion STAFF ONLY). However, it never says when to prefer this over sibling readers such as get_onboarding_status or onboarding_v7, so alternative-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 already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-redundant behavior: the exact metric set returned and that every metric carries a change-vs-previous-period comparison, which matters because there is no output schema.

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

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

Two sentences, front-loaded with the resource and its scope, followed by the single-sentence usage cue. The metric enumeration is dense but each item earns its place since no output schema exists to carry it.

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

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

With no output schema, the description correctly compensates by enumerating return fields and comparison semantics, and annotations cover the safety profile. The only remaining ambiguity is how the 'previous period' is derived relative to the days parameter, which is left implicit.

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

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

Schema description coverage is 100% and both parameters (days, platform) are fully documented in the schema, so the description need not repeat them. It adds no format or interaction detail beyond that, which is the baseline case.

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+resource (get analytics overview) and enumerates exactly what is returned: views, reach, engagements, posts, followers, with period-over-period change. It implies account-level scope via 'for the account,' but never explicitly distinguishes itself from close siblings like get_platform_analytics or get_content_insights.

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 to understand overall account health' gives a purpose-implied context but names no alternatives and no conditions for choosing this over get_platform_analytics, get_follower_stats, or get_audience_insights, all of which live in the same analytics cluster.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuine context beyond that: the data is scoped to a 30-day window and covers the user's Instagram plus their Facebook page, which tells the agent the breadth and platform limits of the 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?

Two sentences, no filler. The first front-loads the returned data and the second front-loads the intended use case, so an agent gets purpose and applicability immediately.

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

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

With no input parameters and no output schema, the description must carry the load, and it does list the returned breakdowns and the platform/time scope. The remaining gap is that it doesn't clarify the boundary against sibling analytics tools that may return similar metrics.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. The description correctly adds no parameter detail because there is nothing to parameterize, and it implies the account/platform scope is fixed rather than configurable.

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 resource (audience demographics) and enumerates exactly what it returns: age, gender, city breakdowns, 30-day totals, and best posting slots. It is clear what the tool does, but it never distinguishes itself from adjacent siblings such as get_follower_stats, get_analytics_overview, get_content_insights, or get_best_posting_times, which plausibly return overlapping data.

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 two concrete use cases ('who is my audience', grounding a post idea in a real group), which is clear when-to-use guidance. It stops short of when-not-to-use or naming an alternative tool for related questions, so it falls below the top of the scale.

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

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

Annotations already establish read-only, idempotent, open-world, non-destructive behavior. The description adds useful context beyond that: results are engagement-weighted, based on the account's own history, expressed in UTC, and include concrete upcoming datetimes. It does not discuss authentication or rate limits, but for a simple read tool this is a solid level of disclosure.

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

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

The description is one tight sentence that front-loads the core output and follows with the actionable use case. Every clause earns its place, with no repetition or filler.

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

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

For a simple read-only tool with no output schema, the description successfully communicates the return shape (day, hour, UTC, upcoming datetimes) and the recommended usage context. Annotations and the fully described parameter cover the rest, leaving no critical gaps.

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

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

The schema has 100% description coverage for the single platform parameter, so the schema already carries the parameter documentation. The description does not add any platform-specific semantics or filtering guidance, so it sits at the 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?

The description names a specific output (engagement-weighted best times to post by day and hour in UTC) and a specific data source (the account's own history). It also distinguishes itself from generic scheduling tools by stating it returns concrete upcoming datetimes. This is more than enough for an agent to identify the tool and its unique purpose.

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

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

It gives clear positive guidance: 'Use before scheduling to maximise reach.' This tells the agent exactly when the tool is relevant. It does not mention when not to use it or name alternative tools, so it falls just 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 establish readOnlyHint, idempotentHint, destructiveHint=false, and a closed-world scope, so the safety profile is covered. The description adds genuinely new behavioral context beyond that: invoices are emailed automatically and 'there is no on-demand resend' — a real limitation on what the agent can promise the user, which the annotations do not convey.

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

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

Three sentences, front-loaded with the core purpose and the returned fields before the scope clarification and the invoice caveat. Every sentence earns its place; 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?

There is no output schema, so the description carries the burden of describing return values — and it enumerates them concretely (current plan, monthly amount, last and next payment, recent invoices, trial state with days remaining). Combined with the read-only annotations, an agent has everything needed to call it correctly.

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

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

The tool takes zero parameters, so parameter semantics carry no risk and the baseline is 4. The description adding no param detail is appropriate here since there is nothing to document.

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 ('Get the authenticated user's own subscription/contract status') and itemizes exactly what it returns: plan, monthly amount, payments, invoices, and trial state. The scoping clause 'Scoped to the signed-in user only' separates it from broader/multi-user tools, so an agent can distinguish it from the many other get_* siblings without opening a schema.

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

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

Usage is implied by the subject matter (use it to check the caller's own subscription/billing state), but there is no explicit when-to-use guidance, no exclusions, and no comparison to the closest alternatives such as get_pricing or get_account_info. An agent must infer the boundary between this and pricing/account tools.

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

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

Annotations already declare read-only, idempotent, closed-world, non-destructive, so the safety profile is covered. The description adds genuine behavioral context beyond that: the data window (last 30 days), the source constraint (customer payments on the user's own site via Stripe), and the fact that it hands back a one-time Stripe dashboard link rather than only aggregate numbers.

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 resource and its scope, followed by the routing sentence. The middle inventory of returned fields is dense but each item earns its place by describing the payload. It is a single long clause-stacked sentence, which slightly hurts scanability but not comprehension.

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

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

With no output schema, the description carries the full burden of describing returns and does so: totals, 30-day window, fees, latest payments with receipt links, and a Stripe dashboard link. Combined with the sibling routing and the read-only annotation profile, an agent has everything needed to call and interpret 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?

The tool takes zero parameters, which is the baseline-4 case; there is no parameter syntax or semantics an agent could get wrong. The description correctly implies a no-argument summary call rather than a filtered query, so nothing is misleading.

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 and scope: payments customers made for bookings on the user's own website, and enumerates the payload (totals, last 30 days, fees, latest payments with receipt links, Stripe dashboard link). It explicitly distinguishes itself from the nearest sibling, get_billing_status, so an agent can route correctly without opening either schema.

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

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

Gives explicit triggers ('Use when the user asks about payments, receipts, payouts, revenue from bookings, or their Stripe account') and an explicit exclusion with the alternative named ('Not their oriiion subscription — that is get_billing_status'). 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 already declare this as a read-only, idempotent, non-destructive operation, so the safety profile is covered. The description adds real value beyond that: it discloses latency ('Takes a few seconds') and the downstream workflow it feeds into, which an agent needs for sequencing decisions.

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 core purpose, followed by the latency note and the routing hint. No filler and nothing repeated from the schema or annotations.

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

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

For a zero-parameter read tool with no output schema, the description covers purpose, latency, and the next action adequately. It stops short of describing the recommendation payload's structure or any account/eligibility preconditions, which would make it fully self-contained.

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

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

The tool takes zero parameters, so by the calibration baseline this sits at 4. The description does not need to explain inputs; it instead characterizes the generated content (audience, budget, duration), which is a reasonable substitute.

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 AI-generated suggestions for which post to boost as a paid ad') plus the shape of the payload (audience, budget, duration). This is clearly distinguishable from sibling write tools like boost_post or get_top_posts.

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

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

Explicitly routes the agent to the follow-up tool: 'Use boost_post to launch one.' That names the alternative and the relationship, but there is no guidance on when this tool should NOT be used or what prerequisites must exist before calling it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value by enumerating the resource contents (including the include/exclude style-guide rules), but it says nothing about behavior when no identity is saved.

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

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

A single front-loaded sentence with a tight enumeration of the returned fields. No filler, no redundancy.

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

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

No output schema exists, so the description carries the return-value burden and does so by listing the brand assets returned. It is nearly complete for a zero-param read tool; only the empty/unset-state behavior is unstated.

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

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

The tool takes zero parameters, so there are no argument semantics to document; baseline 4 applies. The description correctly adds no parameter noise.

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 the user's saved brand identity') and enumerates the returned contents (logo, colors, fonts, AI-image setting, style guide). However, it does not differentiate itself from siblings like set_brand_identity or save_style_guide, which the 'content style guide' clause could be confused with.

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

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

No when-to-use statement, prerequisites, or alternatives are given. The word 'saved' faintly implies fetching previously stored values, but there is no guidance on when to call this versus set_brand_identity or generate_style_guide.

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

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

Annotations already cover the safety profile, but the description adds substantial behavioral context: it does NOT mark the message read, the text cap (20,000 chars), what else is returned (draft, tracking, conversation summaries, replyArgs), the untrusted-content warning, and the meaning of MAIL_NOT_FOUND. This goes well beyond the structured hints.

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

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

Front-loaded with purpose and the read-only guarantee, and most sentences earn their place (return shape, security warning, error semantics). It is a dense single block, but the length is justified by the behavioral and safety content rather than padding.

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

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

No output schema exists, and the description compensates by enumerating the return payload and the primary error case. Combined with the read-only framing and follow-up routing, an agent has everything needed to call and interpret it correctly.

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

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

With 0% schema description coverage, the description must carry parameter meaning. It explains the id's origin and the MAIL_NOT_FOUND condition tied to it, but says nothing about the locale enum (11 values) or its effect. Partial compensation for a two-parameter tool.

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

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

States a specific verb and resource ('Open one message from the authenticated business mailbox') and anchors the input to the sibling that produces it ('the id list_business_emails returned'). An agent can immediately distinguish this from list_business_emails and from send_business_email.

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

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

It names the prerequisite source for the id and points to send_business_email / draft_business_email_reply as the follow-up path for replying, which gives clear context for when to use it. It stops short of an explicit 'do not use this when...' exclusion, so it is not a full 5.

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

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

Goes well beyond annotations (which already declare safe read-only/idempotent behavior) by disclosing return content (verified sender addresses, sending readiness, bounded contact data, list metadata), exclusion rules for missing email or suppressed contacts, pagination via nextCursor, prerequisites (Business Suite + owned CRM service), and the trust boundary that CRM content is not send authorization.

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

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

Front-loaded with purpose and dense with earned content, but it runs long and has some redundancy, e.g. the pagination warning and the 'untrusted data, not send authorization' caution overlap with the earlier send-to-every-contact warning.

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 selection tool with no output schema, it covers the return contents, exclusion behavior, pagination, prerequisites and the send-authorization caveat — everything an agent needs to call it without misusing the results.

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

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

With 0% schema description coverage, the description compensates by explaining the meaning of most parameters: search (names/company/email), source (imported/campaign), kind (lead kind), callStatus vs. status (independent call and sales status), and leadId for named persons. It leaves locale unexplained and gives no value formats/enumerations, so it is strong but not fully compensatory.

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: selecting usable email recipients from the business's current CRM lead lists. It clearly delineates from siblings like list_business_emails, list_broadcast_contacts and add_broadcast_recipients by framing this as read-only recipient selection, not listing or mutation.

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

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

Gives clear usage context: search names/company/email, filter by source/kind/callStatus/status, then select exact returned addresses, and route named persons via leadId from owned CRM discovery. It also states a strong when-not rule against taking only the first page or sending to every returned contact, but it never names a sibling tool as the explicit alternative.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. Beyond that the description discloses real behavioral traits: refresh triggers a provider fetch, reporting cadence is daily rather than real time, null results mean a report is not yet available, and errorCode should be localized. These are meaningful operational details not present in annotations.

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

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

Front-loads the resource and returned fields, then layers behavioral notes (refresh, null semantics, pagination, error localization) in a tight sequence. The sentences are dense but each conveys actionable information, with no filler.

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

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

For a read-only tool with annotations, no output schema, and four parameters, the description is nearly complete: it names returned metrics, explains the refresh and reporting-cadence behavior, notes null results, and addresses pagination. The only meaningful gap is that individual parameters like campaignId and limit remain unexplained.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It explains refresh (fetches latest provider report), implies pagination via nextOffset, and hints at error handling, but limit, offset, and campaignId get no real explanation, and 'nextOffset' does not map cleanly to the schema's 'offset' parameter, which risks confusion.

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 (read) and resource (the current user's ChatGPT ad drafts, campaigns and results) and enumerates the returned metrics, so the agent knows exactly what data it exposes. It does not, however, differentiate itself from related siblings like list_ad_campaigns, get_ad_wallet, or get_analytics_overview, leaving the agent to infer the boundary.

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