Rebbel

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

Annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, so the safety profile is covered. The description adds real context beyond that: the downstream effect (the guide can then drive a strategy or campaign), the triggering condition, and the 'same trust level as clicking Approve in the dashboard' framing. It does not restate idempotency or reversibility, which keeps it off 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 action and its consequence, and every sentence contributes. The closing clause ('only call this once you actually want it approved') mildly overlaps the dashboard-trust sentence, a small redundancy that keeps it from 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?

For a two-param mutation with no output schema, the definition supplies the prerequisite chain, the trigger condition, and the stake (unblocks strategy/campaign generation). An agent has enough to decide correctly; only the exact return/post-approval state is left implicit, and no output schema exists to cover 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?

Schema description coverage is 100% — both brandId and guideId are documented with their source tools (list_brands, get_brand_guide) — so the schema carries the burden. The description adds no parameter detail, which is the baseline-3 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?

States a specific verb and resource ('Approves a draft brand guide') and immediately frames it as the human sign-off gate, which distinguishes it from sibling writers like generate_brand_guide, update_brand_guide, and regenerate_brand_guide_section. An agent can tell what this 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?

Explicitly states the condition for use ('only needed when generate_brand_guide didn't already auto-approve it, which happens on a thin/low-confidence website scan') and adds a strong gate ('only call this once you (the user) actually want it approved'). This is exactly the when-to-use / when-not-to-use guidance the dimension asks for.

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

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

Annotations already declare destructiveHint=false, idempotentHint=true, and readOnlyHint=false; the description adds real value beyond them by explaining the gating state transition, the no-op behavior on ineligible posts, and the 'same trust level as approve_post' bar for invocation. It does not, however, describe what a successful response looks like (no output schema exists), which keeps it short of a 5.

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

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

Two sentences, front-loaded with the core action before the eligibility and trust caveats. It is dense with parentheticals but every clause earns its place; slightly heavy packaging keeps it from 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?

For a mutating, gated tool with no output schema and no annotations covering eligibility, the description supplies the state precondition, the eligible/ineligible post distinction, the no-op guarantee, and the human-approval requirement — everything an agent needs to call it safely and correctly.

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

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

Schema description coverage is 100%, so all three parameters (brandId, campaignId, postId) already carry their provenance and constraints; the description adds no parameter syntax or format detail beyond restating the 'Read the words first' condition for postId. 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 and resource ('Releases a post's copy-approval gate... so its picture starts rendering') and explicitly distinguishes itself from approve_post by naming the shared trust level. An agent can tell it apart from approve_post, approve_strategy, and the other approve_* siblings 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 ('only on a post whose brief asked for AI-generated art or video'), explicit when-not ('a template ($0) or text post is never gated'), and names the correct outcome of misuse ('harmless no-op'). It also states a precondition ('only call once the user has actually read the words'), 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?

Goes well beyond the annotations: it equates the action's trust level to a dashboard click, discloses the format-specific side effect that a 'story' publishes only its photo/video (caption, hashtags, link are dropped), and describes the return payload (mediaLinks). Annotations only say destructive/non-idempotent; the description supplies the real-world consequences.

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 publish gate in the first sentence, then layers the story caveat and response note. Efficient, though 'Same trust level as clicking Approve in the Rebbel dashboard' is soft framing that could be tightened.

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

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

With no output schema, the description helpfully notes the response includes mediaLinks, and it covers the core side effects of a destructive, non-idempotent mutation. It stops short of saying whether approval can be undone (e.g. via remake_post/archive), which would round out the picture.

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 nested review object, including its enum values and the 'omit unless review_post ran' rule, is already fully documented in the schema. The description adds no additional parameter meaning, so the baseline 3 applies.

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

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

States a specific verb (approves) and resource (a draft post), plus the crucial consequence that publish_post/schedule_post will not accept the post otherwise. That downstream gate distinguishes it immediately from siblings like review_post and ask_for_changes.

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

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

Gives a clear calling condition ('only call this once you actually want this exact post approved') and ties it to the publish/schedule flow. It does not, however, name the sibling to use when the user wants to reject or revise (e.g. ask_for_changes), so the routing to alternatives is left implicit.

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

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

Annotations flag a non-read-only, non-idempotent, non-destructive mutation. The description adds value beyond that: it frames the call as an intent-gated trust action ('same trust level as clicking Approve in the dashboard'), which tells the agent not to invoke it autonomously. It does not cover reversibility or what the approval changes, so a 4 rather than 5.

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

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

Three front-loaded sentences that each carry signal: what it does, when it is needed, and the intent guardrail. The Rebbel-dashboard comparison is slightly verbose but earns its place by anchoring trust level.

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-param, no-output-schema approval action, the description covers purpose, prerequisites, trigger conditions, and the caller-intent constraint. A brief note on what changes after approval (and whether it can be undone) would close the remaining gap.

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

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

Schema coverage is 100% and both params carry source hints (brandId from list_brands, strategyId from get_strategy). The description adds no parameter detail, so the baseline of 3 is appropriate when the schema does the work.

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 ('Approves a draft strategy') and, crucially, distinguishes it from generate_strategy (which may auto-approve) and generate_campaign (which depends on approval). An agent can tell exactly what this does and how it differs from the many sibling approve_* tools.

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

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

Explicit when-to-use: only when generate_strategy failed to auto-approve on a thin/low-confidence website scan. It also states the downstream dependency (required before generate_campaign succeeds) and the intent gate (only call once the user actually wants it approved). This is a model routing instruction.

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 (destructiveHint=true, idempotentHint=true): it discloses that nothing underneath is deleted (campaigns, connections, billing history kept), that it is not reversible via any tool here, and that an archived brand publishes/schedules/promotes nothing, plus exactly what cancelScheduled does and that published posts are never touched. This is rich, invocation-relevant behavioral detail.

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

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

Front-loads the core action and hides/deletion distinction in the first two sentences, then details the cancelScheduled flag. Slightly redundant ('Doesn't delete anything underneath it' and 'campaigns... stay intact' restate the same point), but every sentence is otherwise load-bearing.

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

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

For a two-parameter mutation tool with full schema coverage and annotations covering safety, the description supplies everything an agent needs: what is affected, what is preserved, reversibility, and the optional side effect of cancelScheduled. No output schema exists, and the description explains resulting states adequately.

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 a concise restatement of the cancelScheduled effect ('cancel its scheduled posts now, they stay approved without a time') and the intent gating for brandId ('only archive one the user actually wants gone'). That reinforcement of the non-obvious flag semantics lifts it above baseline.

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

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

States a specific verb+resource ('archive_brand' hides a brand from list_brands) and explicitly distinguishes scope from siblings by naming list_brands and noting there is no unarchive counterpart here. An agent can immediately tell this apart from rename_brand or archive_campaign.

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 when-to-use context ('a brand the user is done with, or an accidental duplicate') and a prerequisite/limitation ('not reversible from here — the user restores it from the Rebbel dashboard'). It does not explicitly name a sibling alternative such as archive_campaign for comparison, so it stops short of a full 5.

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

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

Goes well beyond the annotations: discloses the side effects on scheduled posts (stay approved, lose their time, are not re-scheduled on restore), confirms published posts are untouched, notes the ad campaign is unaffected, and warns it is not reversible from this tool. The destructiveHint=true annotation is fully corroborated and enriched.

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, then layers side effects and caveats in tight clauses. No filler; every sentence carries distinct information an agent needs.

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

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

With no output schema, the description carries the full burden of outcomes and does so: what gets hidden, what happens to scheduled vs published posts, ad campaign impact, and reversibility 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 description coverage is 100%, so both brandId and campaignId are already documented, including the archive semantics in the campaignId field. The description adds behavioral color rather than new parameter syntax, 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 ("Hides a campaign from list_campaigns") and immediately scopes the intent (accidental duplicate or test run). An agent can distinguish this from archive_brand or pause_ad_campaign 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-to-use conditions (duplicate, test run cluttering the list) and when-not behavior (doesn't pause a live ad campaign attached to it), plus the restoration path. Routing is unambiguous even though sibling tool names aren't cited.

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, readOnly=false and non-idempotent, so the mutate/replace nature is covered structurally. The description nonetheless adds substantial context: it lands as a new version with the prior version retained and restorable, is never a silent no-op, and stays in review rather than publishing. That is meaningful added value beyond the annotations, but it stops short of documenting auth/permission requirements or the size/rate profile of generation work.

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

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

The core purpose is front-loaded in the first clause, followed by outcome and edge-case handling. It is dense and leans on long parenthetical asides and em-dash chains, so it reads as slightly rambling even though nearly every sentence carries distinct information.

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

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

With no output schema and a complex nested-object schema, the description carries the burden well: it covers the outcome (new version, old restorable), the no-op guard, failure handling for unfulfillable requests, approval/publish boundaries, and the inline-vs-async return behavior with a pointer to get_post. An agent has what it needs to call this correctly.

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

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

Schema description coverage is 100%, so the schema already documents every parameter including the nested review object and the verbose flag. The description's scoping discussion of `note` (classified into caption / one slide / all media / timing) adds meaning about how the input is interpreted, but the per-field mechanics are already covered.

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 (asks for changes to a post, from a plain-language note) and anchors it to a known UI affordance. It explicitly names the sibling it is not: 'For a post whose whole idea is wrong ... use remake_post instead,' so an agent can distinguish the two without opening either schema.

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

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

Gives explicit when-to-use (one scoped change) versus when-not (whole idea wrong → remake_post), plus routing for approved/scheduled posts (needs a fresh approve_post). It also explains what happens when the request can't be fulfilled and which sub-cases fail instantly.

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 (readOnly=false, destructive=true, idempotent=false), and the description adds real behavior: text is placed on image posts but not on video key frames, the image is auto-banked into the brand library, and the result surfaces via post.mediaLinks. It doesn't explain why the call is destructive or what gets overwritten on the post's existing media, leaving a small 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-loaded with the core action and input modes, then the conditional text behavior, then the exclusion and alternative. Dense and mostly waste-free, though the final sentence about showing the user mediaLinks drifts slightly into presentation guidance for a tool definition.

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

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

With no output schema, the description usefully explains what the response contains (post.mediaLinks) and how media is banked. Preconditions, exclusions, alternatives, and input modes are all covered, so 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 description coverage is 100%, so all six parameters are already documented, including the exactly-one-of constraint on the three media inputs. The description restates these modes but adds no syntax or format detail beyond what the schema provides, 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 (attaches) and resource (an image to an existing image_post or video_post awaiting media), plus the three accepted input forms. It distinguishes itself from create_adhoc_post and from the text_post/carousel case, so an agent can identify it without opening the schema.

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

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

Explicitly names when-not conditions (text_post/carousel, the user's own verbatim posts) and routes to the correct alternative, create_adhoc_post's mediaLibraryAssetId. The precondition that the post must be waiting on media is stated up front.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds the crucial non-obvious behavior: the confirm call is the owner's rights representation, equivalent to approve_post, and requires owner attestation rather than agent judgment. It doesn't explain what makes the operation destructive or idempotency behavior, but the rights/consent disclosure is exactly the kind of context annotations cannot 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?

Three sentences, front-loaded with the list-vs-confirm distinction and ending on the consent constraint. The first sentence carries some nested parentheticals, but each sentence earns its place and nothing is redundant.

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

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

With no output schema and four parameters, the description covers the calling modes, the consent precondition, and the downstream effect on posts. It does not describe the shape of the returned candidate list or how collections interact with the confirm step, leaving minor gaps that the 100%-covered schema mostly fills.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: the third calling pattern (neither assetIds nor all yields a list) is not stated in the schema, which only documents the mutual exclusivity of assetIds/all. The collections parameter is left entirely to the schema, which caps this at 4.

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 dual purpose with concrete verbs and resources: 'Lists real photos Rebbel found crawling the brand's own site' versus 'confirms them into the image library.' It also distinguishes the effect ('so posts use them instead of AI art') and anchors the semantics to a sibling (approve_post), so an agent can tell what this tool does and does not do 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?

Explicit when-to-use for both modes ('Call with neither assetIds nor all to see the list first') and an explicit when-not with a hard precondition ('only call it once the owner has actually said these are theirs, never on your own judgment'). The alternative route is named, and the consent gate is unambiguous.

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

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

Goes well beyond annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false) by disclosing that the result 'lands as a draft' rather than publishing, that it is filed under an auto-created 'your own posts' campaign, and that approval plus publish/schedule are required for the post to go live. It also explains the image is attached as-is with no text overlaid.

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 efficient throughout, but the heavy parenthetical nesting ('a campaign Rebbel keeps for these automatically — no campaignId needed') makes a single dense paragraph that is slightly harder to scan than it needs to be.

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

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

For a mutation tool with no output schema, it covers the full lifecycle: what gets created, its draft state, where it is stored, and the required follow-up steps. Combined with fully covered parameters, nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so every parameter is already documented — baseline 3. The description reinforces relationships (mediaLibraryAssetId comes from upload_brand_image, why there is no campaignId) but adds little syntax beyond what the schema already states.

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

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

States a specific verb and resource — 'Creates a post from the user's own exact copy' — and pins the differentiator ('used verbatim, never rewritten by an LLM'). It implicitly separates itself from create_post/draft_first_post by declaring no brand guide or strategy is needed, so an agent can route without opening schemas.

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

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

Gives a clear when-to-use condition (the user supplies their own exact copy) and then the full follow-up workflow: 'call approve_post, then publish_post or schedule_post to actually post it.' It also names the alternative path implicitly by noting no campaignId is required, so the agent knows it does not need create_campaign first.

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

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

Annotations only declare the safety profile (non-read-only, non-destructive, open-world, non-idempotent); the description adds substantially more: the scan is asynchronous and the derived name is upgraded once it completes, the response contains a real scan summary plus next steps, and connectSocialFirst returns a dashboard link because Claude cannot drive the Meta OAuth dialog. That last point is a genuine capability boundary an agent would otherwise discover only by failure.

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 mode decision, and every clause carries operational information (which mode, what the response contains, what to call next). It is a single dense paragraph with several very long clauses, so it is heavier to parse than it needs to be, but almost nothing is filler.

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

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

There is no output schema, so the description correctly compensates by describing what each mode returns (scan summary with name/palette/logo/voice sample, or a dashboard connect link) and what must happen next. For a multi-mode, async, chained-write tool with a nested guided object, this covers everything an agent needs to invoke and sequence 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?

Schema coverage is 100%, so baseline is 3, but the description adds cross-parameter meaning the schema states only per-field: that name is optional specifically when websiteUrl or connectSocialFirst is given and required for guided creation, and that connectSocialFirst is an alternative to both websiteUrl and guided rather than a complement. It does not add syntax detail beyond that, keeping it at 4.

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 (creates a new brand in Rebbel) and immediately enumerates the three mutually exclusive creation modes (websiteUrl scan, guided answers, connectSocialFirst). It also explicitly positions itself as 'First step for a brand that doesn't exist in Rebbel yet', which separates it from rename_brand/archive_brand and from the downstream generate_* siblings.

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

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

Explicit routing rules for every branch: use guided only when there's no website, use connectSocialFirst only when there's no site at all and the user wants to start from a connected Facebook/Instagram account. It also names the exact follow-up tools per branch (draft_first_post, approve_copy, generate_brand_guide, list_connections/list_brands) and when to call each.

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 mutation (readOnlyHint=false), non-idempotent and non-destructive; the description adds useful behavior beyond them: output is AI-generated concepts rather than deterministic content, and it requires a pre-existing campaign. It does not describe the returned batch shape, but the annotations plus the generation semantics leave little ambiguity.

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 action, followed by prerequisite and alternative routing. Every sentence carries distinct decision-relevant 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 2-param mutation tool with full schema coverage and annotations covering the safety profile, the description supplies the prerequisite and the sibling routing, which is what an agent needs to call it correctly. It stops short of describing the returned concept batch, a minor gap with no output schema present.

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

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

Schema description coverage is 100% and both parameters (brandId, campaignId) are documented with their sources (list_brands, generate_campaign). The description adds no parameter-level detail beyond what the schema already states, so baseline 3 applies.

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

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

States a specific verb+resource ('generates another batch of post concepts on an existing campaign') with a quoted user-intent gloss ('write more posts for this campaign'). It also explicitly distinguishes itself from create_adhoc_post, so an agent can route without opening either schema.

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

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

Gives an explicit precondition (call generate_campaign first if none exists) and names the alternative tool with the exact condition that selects it ('post this exact text I wrote' → create_adhoc_post). When-to-use and when-not-to-use are both 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 destructiveHint=true and idempotentHint=true, yet the description adds genuinely non-obvious behavior: the action is not reversible from here and the account must be reconnected from scratch in the Rebbel dashboard. That recovery path and the side effect on listing/publishing go beyond the boolean hints, though it stops short of covering auth or permission requirements.

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

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

Two sentences, zero waste. The high-value irreversibility warning is front-loaded right after the purpose statement rather than 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 two-parameter destructive action with no output schema, the definition covers purpose, trigger conditions, side effects, and the non-reversibility/recovery path. An agent has everything needed to decide and invoke correctly.

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

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

Schema description coverage is 100% and both parameters already document their source (list_brands, list_connections) plus the irreversibility warning. The description adds no parameter-level detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (Removes) and resource (channel connection) with precise scope: broken or wrong connections such as health="error"/"needs_reauth". It explicitly ties itself to the sibling list_connections, so an agent can separate it from list_connections and publish/schedule tools without opening a schema.

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

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

Gives a clear selection condition (only remove one that's actually broken/wrong, e.g. error/needs_reauth health) and the consequence that motivates it (stops cluttering list_connections, prevents accidental publishing/scheduling). It does not name a true alternative tool, but no sibling performs disconnection, so nothing is left ambiguous.

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

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

Annotations cover the write/safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), and the description adds real behavioral context beyond them: the multi-step external pipeline, non-duplication on re-run, and honest fallback when prerequisites are absent. The claim that it 'updates the existing set rather than duplicating it' sits in mild tension with idempotentHint=false, though this is not a flat contradiction.

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

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

Three sentences, front-loaded with the core action and pipeline, followed by re-run guidance and edge-case behavior. Dense and purposeful; no filler or restated name/title noise.

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

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

Despite no output schema, the description explains what is returned in normal and degraded cases ('gets back its existing set... and an honest reason instead of a new one'), which is exactly the return-value information an agent needs. Combined with the annotated safety profile, nothing material is missing 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 parameter (brandId) and the schema already documents it fully (100% coverage, including the 'from list_brands' provenance). The description references 'this brand' but adds no format, constraint, or sourcing detail beyond the schema, so the baseline of 3 applies.

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

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

The description names a specific verb+resource ('Finds or refreshes this brand's competitor set') and lays out the exact pipeline (site research → Google Places search → Instagram/Facebook handle resolution → scoring). It is clearly distinguishable from the sibling list_competitors, which is the read-only counterpart. An agent can tell what this does 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?

It gives explicit when/when-not guidance ('Meant to be re-run occasionally, not on every call') and discloses the non-duplicating re-run behavior, plus two failure modes (no site research, national/online brand) with the resulting fallback. It stops short of naming list_competitors as the alternative for simply viewing the set, so the routing is implied rather than stated.

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

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

Annotations only declare non-readOnly, non-idempotent, non-destructive. The description adds rich behavioral context: no second draft is ever started, the brand comes back as a caption with copy pending, an in-progress state means the reply says to call again in seconds, and publishing (not drafting) is where a real connection is required. This is substantial disclosure beyond the annotations.

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

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

The content is a single sprawling paragraph riddled with nested parentheticals, so the load-bearing distinction between count=1 and count=3-5 is buried mid-sentence rather than front-loaded. It is information-rich but hard to parse and poorly structured.

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

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

Given a two-parameter tool with no output schema and non-trivial two-mode behavior, the description covers the workflow, prerequisites, defaults, and downstream steps thoroughly. It is essentially complete, only slightly under-explained on how the returned draft/caption is shaped.

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 both params are documented, but the description adds interpretation beyond the schema: it explains what count=1 vs count=3-5 actually returns, and characterizes when a brandId has a usable voice sample (connected account or non-thin website scan). This goes past the schema's field-level wording.

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 (drafts) and resource (posts) and clearly splits the two modes: count=1 returns the brand's single auto-written first post, while count 3-5 drafts a batch from the brand's own voice. It is dense but an agent can distinguish this from create_post/create_adhoc_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?

It gives explicit when-to-use guidance for both modes (count 1 default; use 3-5 right after create_brand so there's a real batch) and names the concrete next-step alternatives: approve_copy, approve_post, then publish_post or schedule_post. It also names prerequisites (voice source) and the alternative paths (create_brand's connectSocialFirst, list_connections).

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 closed-world scope, so the safety profile is covered; the description redundantly restates 'Read-only' but usefully adds the concrete return shape {id, title, text, url} and what the payload contains per record type. That is real added context beyond the structured fields, though error/not-found behavior is still unspecified.

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 verb and the core mechanic, then a compact per-type breakdown, then the return shape and the 'not a web fetch' caveat. It is dense but well organized; the id-format patterns are repeated nearly verbatim from the parameter schema, which is the only real redundancy.

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

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

For a one-parameter lookup with no output schema, the description supplies what the structured data does not: the per-id-type payload contents and the exact return envelope {id, title, text, url}. Combined with annotations covering safety and a 100%-documented schema, 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 description coverage is 100% and the single id parameter is fully documented in the schema with the same three format patterns. The description reinforces the format but adds no syntax or validation detail beyond what the schema already gives, so the baseline 3 applies.

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

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

The description states a specific verb (fetches) and enumerates exactly what resource kinds can be retrieved (brand, campaign, help answer), each with its id shape and the fields it carries. It also explicitly disambiguates from a sibling concept ('Not a web fetch — ids come from search'), so an agent can distinguish it from 'search' and from the typed getters like get_brand_guide without opening a schema.

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

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

It clearly states the precondition for use — the id must come from a prior search — and rules out the most likely misreading (web fetch). What is missing is explicit routing versus siblings that also return brand/campaign data (get_brand_brief, list_brands), i.e. when to fetch by id rather than call a typed getter.

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 readOnlyHint=false, destructiveHint=true, idempotentHint=false and openWorldHint=true; the description adds genuinely new behavior beyond that — automatic approval of the guide on strong signal versus a draft on weak signal. It does not explain the destructive/idempotency implication (what happens to an existing guide if this is called again, or what the guide contains), which is the one gap for a mutation tool.

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

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

Dense but front-loaded: purpose first, then precondition, then the two outcome branches. The em-dash parenthetical and 'steering toward filling in the gaps' phrasing add slight verbiage, but nearly every clause carries actionable information.

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

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

With no output schema, the description does the work of explaining return/outcome states — auto-approved versus unapproved draft — and the next call an agent can make. It stops short of describing what the generated guide itself contains or how to inspect it (get_brand_guide), which would round it out for a 1-param generation tool.

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

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

Schema coverage is 100% and the single brandId parameter is already documented as coming from list_brands. The description restates the scan prerequisite, adding marginal context but no format or resolution detail beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Generates a brand guide') plus its input source ('from a brand's completed website scan'), which separates it from get_brand_guide, update_brand_guide, and regenerate_brand_guide_section. An agent can tell what is produced 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 an explicit precondition (create_brand's scan must have finished), spells out the auto-approval path and that generate_strategy can follow immediately with no approve_brand_guide click, and names the one case (thin scan) where the draft stays unapproved. This is when/when-not/alternatives in full.

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

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

Goes well beyond the annotations by disclosing the draft-only, never-publishes/never-schedules guarantee, the duplicate-objective/angle short-circuit with a user choice, and partial-failure behavior where unusable channels are dropped and named in the response (nothing created if none are usable). It does not cover permission/auth requirements or rate limits, keeping it just short of the top.

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

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

Front-loaded with the core action and the never-publishes guarantee, then layers in edge cases in a readable order. The inline channel id enumeration and the TikTok note are somewhat redundant against the schema enum, adding length without new information for that portion.

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 takes on the burden of explaining what comes back: the existing campaign on a duplicate match, the choice presented to the user, and channel names in the response. For an 8-parameter mutation tool it covers creation, duplication, and partial failure adequately.

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 semantics: it explains the plan-gated channel behavior, why some channels may silently be omitted, and reinforces generateAnyway's duplicate-detection meaning. The channel id list duplicates the schema enum, which caps the value slightly.

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 (creates a marketing campaign and its first batch of draft posts) with exact scope: copy plus image briefs per channel, landing as drafts. An agent can distinguish this from create_post, create_adhoc_post, and generate_strategy without reading further.

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 conditions throughout: pass generateAnyway:true only after the user asks for a second campaign on the same brief, and it states that an existing identical campaign is returned instead. It also carves out TikTok as dashboard-only and explains the plan-gated channel fallback, leaving little to inference.

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

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

Annotations flag destructiveHint=true, readOnlyHint=false, idempotentHint=false. The description adds meaningful context beyond them: it clarifies the regeneration source and that hand-edited briefs are never overwritten, which materially softens/qualifies the destructive profile. No contradiction with annotations.

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

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

Purpose is front-loaded and the sentences earn their place, but the first sentence nests a large parenthetical defining the brief, making it dense. Slightly heavy but not wasteful.

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

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

For a one-param mutation tool with full annotations and no output schema, the definition covers trigger, source, and preservation behavior. Nothing essential is missing, though return/result handling is left unstated.

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

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

Single parameter with 100% schema description coverage ('The brand's id, from list_brands'), so the schema already carries the semantics. The description adds nothing about the brandId parameter itself; baseline 3 applies for high coverage.

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

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

States a specific verb (regenerates) and resource (the brand's knowledge brief), then defines what that brief contains and where it comes from (the approved guide). It is easily distinguishable from siblings like get_brand_brief and generate_brand_guide.

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

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

Explicitly frames when to invoke it: 'Runs automatically on every guide approval; use this for an on-demand re-run.' That clearly positions the manual use case, though it does not name a sibling alternative to avoid.

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/side-effect profile (readOnlyHint=false, destructiveHint=true, idempotentHint=false). The description goes beyond that by disclosing the conditional approval behavior (auto-approved on confident scan vs draft on thin-scan) and the prerequisite dependency, which an agent cannot infer from the annotations alone.

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

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

Three sentences, front-loaded with the core action and its output, then the prerequisite, then the auto-mode behavior. No redundant restatement of the title or name.

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, yet the description conveys the resulting state (approved strategy vs draft) and the downstream tool. Combined with the prerequisite and approval flow, it covers everything an agent needs to invoke this correctly.

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

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

Schema description coverage is 100% and both parameters (brandId, goals) are well documented in the schema itself, so the baseline is 3. The description only echoes 'from the brand's goals' without adding format or constraint 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?

Names a specific verb (generates) and resource (organic-first marketing strategy) and enumerates its outputs — channel mix, content pillars, posting cadence — derived from the brand's goals. It clearly distinguishes itself from generate_brand_guide, generate_campaign, and approve_strategy by describing where it sits in the pipeline.

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

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

Explicitly states the prerequisite ('Requires an approved brand guide first'), describes the auto-approval path, and names the conditions under which a draft requiring approve_strategy results. It also routes the agent forward to generate_campaign once ready, so when-to-use and downstream sequencing are both covered.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description then adds genuinely non-redundant behavior: the output is 3-5 plain sentences, items are deduped across campaigns, and the report spans fixed +7/-7 day windows. It stops short of describing pagination or failure modes, but for a read-only summarizer this is solid added context.

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

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

Two sentences, front-loaded with the core purpose before enumerating contents. Efficient overall, though 'in one call' appears twice and could be tightened.

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

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

With no output schema, the description correctly takes on the burden of describing the return payload (sentence count, contents, link) and does so concretely. Combined with annotations covering the safety profile, an agent has what it needs; only the absence of explicit sibling routing keeps it from a 5.

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 (brandId) and schema description coverage is 100%, with the schema itself pointing to list_brands for sourcing the id. The description adds no further parameter semantics, so the baseline 3 applies.

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

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

The description names a specific resource (the brand brief) and spells out exactly what it contains: items awaiting the owner, upcoming/live content windows, failures with cause and next step, and one link. It signals brand-level scope distinct from campaign-level siblings, but never names a specific sibling it differs from (e.g. get_brand_guide), so differentiation is implied rather than stated.

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

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

Usage is implied rather than prescribed: 'covers every campaign in one call' suggests this replaces per-campaign listing, but there is no explicit when-to-use or when-not, and no alternative tool is named despite many close siblings (get_brand_guide, get_results_verdict, list_campaigns).

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 carry readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that: it discloses that it returns the approved guide or the latest draft, describes what the owner-facing view contains, and warns that verbose output is "several times larger." It stops short of noting auth/permission requirements or whether drafts are flagged.

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 front-loaded sentences with the verb and default behavior stated first and the verbose caveat last. The long enumerated content list is dense but justified as it tells the agent what to expect in the return. There is minor redundancy between the phrasing of the verbose caveat here and in the schema.

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

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

With no output schema, the description correctly carries the burden of describing returns, and it does so by enumerating the guide's sections and the compact-vs-verbose distinction. Nothing critical to invoking the read correctly is missing, though it could note pagination or trimming behavior.

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

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

Schema coverage is 100%, so both parameters (including the linked list_brands provenance for brandId) are already documented. The description's verbose explanation (full stored record, ids, provenance, storage refs) largely mirrors the schema's own description, so it adds marginal meaning rather than new semantics. 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 ("Fetches") plus the resource ("a brand's approved (or latest draft) brand guide") and enumerates the contents it returns (identity, voice rules, palette, logo links, etc.). The resource name cleanly separates it from siblings like get_brand_brief, get_strategy, and get_post, so an agent can select 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?

The description gives clear guidance on the verbose flag ("Compact by default... rarely needed"), which is genuine conditional usage advice. However, it never says when to reach for this tool versus get_brand_brief or get_strategy, nor states prerequisites. Usage is implied by the resource but not explicitly scoped against 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=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds real context beyond them: "reading a post never approves it" (important given the many approve_*/review_post siblings) and the size/side-effect profile of verbose. It stops short of permissions or rate-limit detail, but for a read-only fetch that is a minor gap.

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

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

Front-loaded with the core action and the routing signal, then details. It is a long paragraph, but since no output schema exists the return-field enumeration is largely load-bearing rather than filler; the dense field list costs some scannability.

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 the return value and does so thoroughly, field by field, including the `ask` concept. All three required ids are accounted for and the verbose mode is explained, so nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes slightly beyond the schema by naming what the verbose record actually contains ("brief, image prompt, version history"), which concretely helps an agent decide whether to pass verbose:true; the other three params are adequately documented in the schema itself.

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 ("Reads one post") and enumerates exactly what that read returns: caption/alternates, media with per-image text and mediaLink, scene plan, status, and `ask`. It also distinguishes itself from the sibling list_posts, so an agent can pick 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 names the condition for use ("review or critique what Rebbel actually wrote before approving it") and the alternative it supersedes (list_posts "only returns a headline, which isn't enough to judge copy against a brand's voice"). That is a clear when-to-use plus a when-to-use-something-else.

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

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

Annotations already cover read-only/idempotent/non-destructive, so the bar is low, and the description goes well beyond them by describing failure semantics ('any failure in plain words with a next step'), read timestamps, grouped ownership counts, and metric snapshots.

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 leading with the core fetch, followed by a dense but purposeful content list and the sibling routing at the end. No filler, though the list is packed tightly.

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-shape burden and does so thoroughly, covering results, timestamps, status breakdown, grouped counts, failures, and snapshots — enough for an agent to call and interpret confidently.

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

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

Schema description coverage is 100% and both params (brandId, campaignId) are documented in the schema with their sources, so baseline 3 applies; the description adds only 'one campaign's' scoping, no extra parameter meaning.

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

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

States a specific verb and resource ('Fetches one campaign's latest results') and enumerates the contents returned, so an agent can tell it apart from sibling getters like get_brand_brief 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?

Explicitly routes to the alternative: 'For the whole brand in one call, use get_brand_brief instead.' Clear selection condition, though no other when-not guidance (e.g., staleness or refresh expectations) is given.

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

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

Annotations already establish readOnly/idempotent/non-destructive, so the bar is lower. The description adds real value beyond them: it discloses that the strategy may still be a draft (not just approved), what the compact view contains, and that verbose is 'several times larger' — useful sizing context for a read call.

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

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

Two sentences, front-loaded with the verb and resource, followed by a dense but purposeful field list and the compact/verbose distinction. Nothing is wasted; every enumer item tells the agent what data comes back in the absence of an output schema.

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

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

No output schema exists, so the description carries the return-value burden and does so by enumerating the strategy's contents. Combined with the annotation-covered safety profile and the schema-covered parameters, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%; both brandId and verbose are fully documented in the schema, including the 'several times larger' warning. The description's verbose note largely restates the schema, so the baseline of 3 is correct — it adds no new syntax or format detail.

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

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

States a specific verb (Fetches) and resource (a brand's latest strategy), scopes it as approved-or-draft, and enumerates the exact payload the agent will receive. This clearly separates it from generation/approval siblings like generate_strategy and approve_strategy without needing to name them.

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

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

Usage is implied by the verb 'Fetches' and the 'as the owner reads it' framing, so an agent can infer this is the read path. But there is no explicit when-to-use guidance, no statement of when to prefer this over get_brand_brief or get_brand_guide, and 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 only declare the safety/idempotency profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the description adds real value beyond them: content is persisted verbatim rather than re-summarized, the artifact becomes permanent dashboard state, and it is silently injected into generate_strategy/generate_campaign prompt context going forward. It does not cover permissions, reversibility/cleanup of a saved brief, or rate limits, which keeps it short of a 5.

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

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

Three sentences, front-loaded with the core action and its persistence/visibility effects, then the when-to-use rule, then the revision alternative. The clause about 'summarizing it back to the user and losing it' is slightly rhetorical but still carries usage meaning; otherwise the text is 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 pointing to where the saved brief's id lives (dashboard Research page URL, or a prior call's result). Combined with the disclosed downstream effects and the verbatim-save guarantee, an agent has enough to call correctly, though it never states what the call itself returns.

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 kind, title, brandId, content and sourceNote are already fully documented in the schema, including the enum semantics and the domain-register example. The description adds no parameter-level detail beyond noting where an existing brief's id comes from, 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 (saves AI-synthesized research as a permanent document against a brand) and immediately names the downstream consumers, generate_strategy and generate_campaign, plus dashboard visibility. It distinguishes itself cleanly from update_research_brief and list_research_briefs, so an agent can pick 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?

Explicit trigger ('use this whenever a conversation produces real research worth keeping, instead of just summarizing it back to the user'), explicit anti-pattern (do not save a duplicate), and an explicit named alternative (update_research_brief) with the condition that selects it. Nothing is left to inference.

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

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

Annotations already declare the safe read profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds genuinely new context: the response carries each brand's id and status, and the empty-state behavior for a new account (a note for the owner plus their plan). It does not discuss auth or rate limits, but nothing an agent needs is missing.

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

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

Three tight sentences, front-loaded with the core action, then usage, then the empty-state caveat. No filler; every sentence delivers distinct information.

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

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

With no output schema, the description carries the return-value burden and does so reasonably (id, status, and the no-brands empty case). It is nearly complete for a trivial zero-param read tool, lacking only a note on ordering or scope if multiple accounts exist.

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

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

The tool takes zero parameters, so the baseline is 4. There is nothing schema-side to clarify, and the description correctly does not invent parameter semantics.

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

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

States a specific verb (Lists) and resource (brands/businesses), and scopes it precisely to 'this Rebbel account manages', which cleanly separates it from siblings like create_brand, archive_brand, and rename_brand. An agent can identify this as the read/discovery 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 names two use cases: resolving a brand name to a brandId, and seeing where each brand is. This tells the agent when the tool is the right pick (before calling id-based tools). It stops short of naming alternatives or exclusion conditions, so it falls just shy of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and a closed world, so safety is covered. The description adds meaningful read-shape context by enumerating the returned fields and the derived counts (posts working / waiting on owner / approved), which matters because there is no output schema. It stops short of noting result size, ordering, or pagination.

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 padding. The field enumeration comes first and the routing guidance second, so the most decision-relevant 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 read-only list tool with full parameter coverage and no output schema, the description supplies the return-field detail an agent would otherwise lack. The only gap is operational: no mention of ordering, result limits, or whether campaigns are paginated.

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

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

There is a single parameter with 100% schema description coverage ('The brand's id, from list_brands.'), so the schema already does the work. The description adds nothing about the brandId itself, so the baseline 3 applies.

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

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

The description states a specific verb (lists), the resource (a brand's campaigns), and enumerates the returned fields (id, objective, angle, channels, status, post counts). It also explicitly distinguishes itself from siblings by noting that no other campaign/post tool can look a campaign up by name.

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

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

It states the concrete use case ('find a campaignId for an existing campaign') and pre-empts the obvious alternative by asserting that no sibling tool supports name-based lookup. An agent knows exactly when to reach for this tool versus list_posts, get_post, or generate_campaign.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety bar is lower. The description adds real context beyond that: it does not trigger discovery (no side effects/rate-limit cost) and it names the return shape, which matters since 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 short sentences, each earning its place, with the core behavior and return fields front-loaded before the prerequisite. No filler or restated title.

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

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

For a one-parameter, non-nested read tool with no output schema, the description covers behavior, prerequisite, and the returned fields. Minor gap: no mention of ordering, pagination, or what an empty result looks like.

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

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

Only one parameter (brandId) and schema coverage is 100%, with the schema already stating it comes from list_brands. The description's 'this brand's' adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (Lists) and resource (this brand's current competitor set), and even enumerates the returned fields (name, handles, score). The clause 'without re-running discovery' cleanly separates it from the sibling discover_competitors.

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: call discover_competitors first if none exist yet, which tells the agent when this tool will return nothing useful. It lacks a general 'prefer X over Y' rule, but the empty-state routing is explicit and actionable.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's job is to add workflow context, which it does: it is the sole discovery path for connectionId and a verification step after brand creation. It does not mention pagination, empty-state behavior, or error cases, but the value-add beyond annotations is real.

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, zero filler, front-loaded with the resource and its returned fields before the workflow guidance. Every clause earns its place by tying the tool to specific downstream siblings.

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

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

With no output schema, the description compensates by enumerating the returned fields, and it fully covers the discovery and verification roles. An agent has everything needed to decide to call it and to interpret 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 100% and the single brandId parameter is already documented as coming from list_brands. The description adds no syntax, format, or edge-case detail about brandId, so it sits at the baseline for a fully-documented schema.

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

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

Specific verb (Lists) plus resource (a brand's connected channel accounts) with the returned fields enumerated (id, channel id and name, account name, health). This cleanly distinguishes it from sibling list_* tools that cover posts, campaigns, competitors, and briefs.

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 primary use case — finding the connectionId that publish_post and schedule_post require — and asserts there is no other way to discover one. It also names a second use (confirming a create_brand connectSocialFirst connection landed before draft_first_post or generate_brand_guide), giving concrete when-to-use conditions tied to named siblings.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description still adds real behavioral context beyond them: proposals have no effect on the brief until the owner approves, and they originate from two specific mechanisms, which tells the agent these are pending, non-applied suggestions.

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 in the first clause, and every subsequent clause carries information (source of proposals, approval gating, next tool). It is somewhat dense with em-dash asides, but nothing is redundant padding.

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

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

With no output schema, the description partially compensates by characterizing what the returned lines represent and where they come from. It is adequate for a single-parameter read tool, though it does not describe the shape or identity fields of the returned proposals.

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 there is only one parameter (brandId, already documented as coming from list_brands), so the schema does the heavy lifting. The description adds no additional parameter meaning, making the baseline 3 appropriate.

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

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

The description opens with a specific verb and resource ('Lists lines Rebbel suggests adding to a brand's knowledge brief') and immediately scopes what those lines are (reader's-world research the writer draws on). It clearly distinguishes this read tool from the sibling resolve_knowledge_proposal, which it names explicitly.

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

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

It clearly routes the agent onward: 'use resolve_knowledge_proposal to decide each one,' and explains the context that produces proposals (a fresh run against a hand-edited brief, and claims the writer kept making). It stops short of stating explicit preconditions or when not to call this listing tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: it describes the compact-vs-verbose payload tradeoff and what the status text conveys ('whose turn it is and why'). It does not mention pagination or result-size limits, keeping it short of a 5.

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

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

Front-loaded with the verb and return contents, then the usage routing, then the verbosity note. The field enumeration is dense but each item is meaningful. Slightly long in the first sentence, but nothing is wasted.

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

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

There is no output schema, so the description carries the burden of describing the return shape and does so thoroughly (id, channel, dashboard-worded status, headlines, mediaLink, ask). Combined with the usage routing and verbosity note, 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 nonetheless adds meaning beyond the schema for verbose ('Compact by default; verbose:true adds every status field'), clarifying what the flag actually changes in the response rather than just restating its type.

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 (Lists) and resource (a campaign's posts) and enumerates the returned fields, including the distinctive dashboard status framing and the `ask` field. An agent can immediately distinguish this from get_post, which fetches 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?

Explicitly states the intended use: 'Use this to find a postId before get_post, approve_post or schedule_post.' It names the concrete downstream siblings that consume the output, giving the agent a clear when-to-use signal.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false). The description adds genuinely useful context beyond them: the Research page is a flat read-only list whose markup/URL carry no ids, explaining why the tool must be used as an id lookup.

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

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

One front-loaded sentence with the resource, returned fields, and the reason-for-existence clause; it finishes by routing to update_research_brief. No filler or redundancy.

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

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

With no output schema, the description helpfully enumerates the returned shape (id, kind, title, content, dates), and annotations cover safety. Only minor gaps remain, such as list size, ordering, or pagination behavior, none of which block 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?

The single brandId parameter has 100% schema description coverage ('The brand's id, from list_brands'), so the schema carries the meaning. The description only implies the brand scoping via 'a brand's' and adds no format or sourcing detail, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('Lists a brand's saved research briefs') and enumerates the brief kinds (market, competitor, audience, domain, other) plus the fields returned, which cleanly separates it from siblings like list_knowledge_proposals or get_brand_brief.

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

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

Explicitly tells the agent when to reach for this tool: to find a brief's id before calling update_research_brief, since the dashboard exposes no ids. It names the downstream alternative rather than a rival list tool, so there is no explicit when-not guidance, but the context is clear.

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

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

Goes well beyond the annotations: it states the direction of effect (can only reduce spend, never start or increase it), discloses a side effect the annotations don't capture (cancels a queued ad launch pending Meta review), and describes the idempotent no-op response. This is genuinely useful behavioral context for a destructive write.

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

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

Three tight sentences, front-loaded with the core action and its spend-direction guarantee, followed by side effects and edge cases. 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 two-parameter mutation with no output schema and rich annotations, the description covers the safety profile, side effects, and the empty-result case. It stops short of explaining what a successful response contains, though the no-op behavior is addressed.

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 brandId and campaignId are already fully documented with their source tools. The description adds no parameter-level detail, which is the expected baseline when the schema does the work.

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 ('Stops real delivery on an active ad campaign') and reinforces it with a memorable metaphor ('the kill switch'). An agent can immediately distinguish this from siblings like archive_campaign or approve_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?

Clear context for when it applies and what happens in the no-op case (no ad running or already paused). It does not name a resume/alternative tool, but the operation is unambiguous in scope.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=true, but the description adds real behavior the annotations cannot convey: the refusal semantics for non-approved posts, the required call ordering, and the legal certification obligation for YouTube that must be shown to the owner beforehand. It does not address the destructive or idempotent traits, so a 4 rather than a 5.

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

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

Purpose is front-loaded in the first clause and every sentence is functional, including the prerequisite routing. The YouTube paragraph is long, but the quoted certification line is required verbatim, so the length is justified rather than padding.

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

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

With no output schema, the description still covers preconditions, refusal behavior, cross-tool dependencies, and the YouTube compliance gate, which is enough for correct invocation. It leaves the success response shape unstated, though that is a minor gap for a publish action.

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 that postId must be status=approved and that connectionId comes from list_connections. The description echoes these sourcing rules but adds no new 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 and resource (publishes an approved post through a connected channel) and explicitly distinguishes itself from schedule_post as the on-demand equivalent. It also carves out the second valid input state (a scheduled post being pushed early), so an agent can route correctly without reading the schema.

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

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

Gives explicit preconditions and exclusions: refuses posts that aren't approved or scheduled, directs the agent to approve_post first, and points to list_connections for the connectionId. It also names the case (missed slot, waiting on reconnect) where this beats waiting for schedule_post.

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

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

The description discloses that the whole section is rewritten from the website scan, which directly explains the destructiveHint=true annotation and warns the agent that prior section content is lost. It also notes the guide is a draft and that feedback steers output. It does not mention whether the operation is reversible or requires specific permissions, so it stops short of the highest bar.

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 section scope, followed by the two routing rules. No filler; every clause carries routing or behavioral information.

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

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

For a mutation tool with full schema coverage and annotations carrying the safety profile, the description covers purpose, alternatives, section scope, and behavioral impact. No output schema exists, so return-value explanation is correctly omitted. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description compensates by glossing the section enum (e.g., audiencePersonas = who it's for) and explaining that feedback steers the regeneration rather than being a generic field, adding intent the schema only flattens.

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 (Regenerates) and resource (one section of a draft brand guide), enumerates the relevant section values, and explicitly names the two siblings it can be confused with (generate_brand_guide, update_brand_guide). An agent can distinguish it from both 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 routing: use this instead of generate_brand_guide when the guide exists but the scan was thin and you have real detail to add, and use update_brand_guide when you only want to change specific lines. Both conditions and both alternatives are stated.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so irreversibility is signposted structurally; the description adds the scoping guarantee that only the named section changes and details version-dependent remapping of classic section names in strategyVersion 2. It does not describe the returned reply payload, but that is a minor gap given the rich behavioral context.

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

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

Dense but front-loaded: section list first, then the version-format caveat, then the feedback-parsing rule. Every clause carries information, though the middle sentence is long and could be split for readability.

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

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

For a mutation tool with no output schema, the description covers scope, version-dependent behavior, and feedback semantics well enough to call it correctly. The one omission is what the response contains beyond 'the reply says so' when feedback has no effect.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it glosses each section value, explains that classic names map onto their plan-format counterparts, and specifies exactly how numeric feedback is parsed for channelPlan/cadence ('X 3 to 5 a week' sets posts per week).

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 (regenerates) plus clearly bounded resource (one section of a draft strategy), with the enum members enumerated and glossed in plain language. It is immediately distinguishable from the sibling regenerate_brand_guide_section, which targets a different artifact.

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

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

It explains how to steer regeneration with feedback and when feedback is effective versus ignored ('expectations come from published sources, so feedback does not move them'). It stops short of stating prerequisites or alternatives, but the conditional guidance is concrete and actionable.

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

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

Annotations declare destructiveHint=true and non-idempotent, but the description adds substantially beyond them: the previous version is kept, images are redone, the result returns in review rather than being published, and there are explicit no-op outcomes (own verbatim posts, or a guide with no capabilities). The photo path also discloses what happens when a photo is unconfirmed or absent.

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, exclusion and the photo variant are front-loaded in a logical order, and most sentences carry load-bearing detail. It is dense and runs long, with the photo branch and the no-op caveats somewhat interleaved, but there is little outright 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 7-parameter mutation with no output schema, the description covers the return state ('comes back in review', 'one honest line'), the failure/no-op conditions, the reason-passing requirement, and the media variant. An agent has everything needed to invoke it and set expectations for 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 description coverage is 100%, so the schema already documents every parameter and the baseline is 3. The description still adds behavioral meaning the schema lacks: photoAssetId/useOwnerPhoto place the photo on the image or a carousel's first slide, and on the user's first post the photo is applied while the caption is kept.

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 ('Re-makes one post from the brand guide') and immediately scopes it as a fresh concept under the brand's current guide, landing as a new version with the previous one kept. It explicitly names the sibling it is not ('for a targeted edit use ask_for_changes'), 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 an explicit when-to-use ('when the idea itself was wrong — it describes a feature the product doesn't have, or the wrong audience — not just a line or an image') and an explicit alternative for the excluded case (ask_for_changes). It also names the caller's obligation to pass the user's reason and the hard boundary that this never approves or publishes.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, readOnlyHint=false and openWorldHint=false, so the safety profile is covered structurally. The description adds genuine context by explaining that URL correction is meaningless without re-running the website scan, which justifies the tool's narrow scope, but it never addresses the flags it is annotated with — notably why a rename is flagged destructive or what side effects occur.

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 action, and the routing note comes second where it can't obscure the primary purpose. The second sentence is slightly verbose in justifying itself, but no sentence is wasted.

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

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

For a simple two-parameter mutation with full schema coverage and annotations, the description is largely adequate and covers the main gotcha. It falls short of completeness by omitting rename side effects and any permission or state preconditions, which matters given the destructive and idempotent hints.

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

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

Schema description coverage is 100% (both brandId and name are documented, including the provenance hint "from list_brands"), so the schema carries the parameter burden. The description adds no format, validation, or uniqueness semantics for the new name beyond what the schema states, which is the expected baseline here.

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

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

The first sentence gives a specific verb and resource ("Renames a brand"), and the second sentence draws a boundary against a plausible but wrong use (correcting websiteUrl), naming the sibling that owns that job. It is clear and differentiable, though it doesn't describe the scope of what a rename affects (assets, guides, campaigns referencing the brand).

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

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

It supplies one explicit when-not rule — URL correction belongs to retry_brand_ingest — with a rationale. However, there is no positive guidance on when to call rename_brand, no prerequisites (e.g., brand must exist or be in a particular state), and no mention of other overlapping siblings like archive_brand or create_brand.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, but the description adds substantive context they don't carry: approve takes effect from the next campaign generated (not retroactively), and dismiss is permanent ('will not be proposed again'). It does not restate the safety profile, which is the right call, though it could be more explicit that a dismissal cannot be undone.

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

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

Three short sentences, front-loaded with the action and its outcome, then the human-approval precondition. No filler and nothing an agent needs is buried.

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

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

With no output schema, the description covers the outcome of both branches and the required precondition, which is sufficient for a 3-required-parameter decision tool. The only minor gap is not stating what the call returns or how to confirm which proposal was resolved.

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 enum values of decision and the provenance of brandId/proposalId are already documented in the schema. The description's timing note about 'the next campaign generated' adds marginal meaning but does not go beyond the schema's own enum descriptions in any material way.

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 decision verb (approve/dismiss) acting on a precisely scoped resource — one proposed knowledge-brief line — and names the sibling list_knowledge_proposals as the source of the proposalId. It is clearly distinguishable from the other approve_* siblings, which act on guides, copy, posts and strategy.

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

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

Gives an explicit precondition: only call it once the owner has said yes or no to that specific line, making clear this is a human-gated decision rather than an autonomous action. It also points to list_knowledge_proposals as the required upstream step to obtain the id.

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 rich context beyond annotations: exact side effects of each action (use → new version with current kept/restorable and re-enters review; keep → version untouched; both resume paused schedules), plus explicit refusal conditions. This meaningfully elaborates the destructiveHint/idempotentHint profile with what gets destroyed or preserved.

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 discovery step, then action semantics, then refusal conditions. Dense but every clause 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?

For a mutation tool with no output schema, the description covers preconditions, both action branches, post-conditions (review re-entry, schedule resumption, restorability), and error conditions. Complete enough to call correctly without further docs.

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 enum param is already documented in the schema, so baseline is 3. The description adds value by explaining the semantic distinction between 'use' and 'keep' in flow terms (fresh approval, paused schedule), which goes beyond the schema's terse enum descriptions.

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

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

States a specific verb (resolve) and resource (a proposed correction), and clearly names the sibling it depends on for discovery (get_post's `proposal` field). Distinguishes itself from approve_post/review_post by being the resolution step for a Rebbel-proposed correction.

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 call: after get_post shows a proposal and the user has picked. Also names the two alternative actions (use vs keep) and their outcomes, and lists refusal conditions. Leaves 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 declare destructiveHint=true, readOnlyHint=false, idempotentHint=false, and openWorldHint=true, and the description is consistent with them rather than contradicting them: it explains the merge-only-adds semantics and that forceFresh is the sole way to discard prior findings. However, it adds little beyond what the schema property descriptions already disclose about these behavioral traits, and it never addresses auth/permission requirements or failure/retry behavior on repeated scans.

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 a numbered "Two uses:" structure, so an agent can scan it quickly. It is on the verbose side and duplicates much of the schema text, but the redundancy reinforces the merge-vs-replace rule 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?

For a mutating, non-idempotent tool with no output schema, the description covers when it applies, the side effects (merge vs forceFresh discard), and the important non-effect (approved brand guide unchanged). Combined with the annotations and full schema coverage, 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 description coverage is 100% and the parameter docs are already rich and near-identical to the description's wording (e.g. the websiteUrl correction/omission semantics and the forceFresh "merging only ever adds" note are duplicated almost verbatim). The description adds the framing of the two modes but no syntax or edge-case detail the schema lacks, so baseline 3 is appropriate.

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

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

States a specific verb+resource ("Re-runs the website scan") and immediately enumerates the two distinct use cases (recovery after failure, refresh/correct an active brand). This clearly separates it from siblings like create_brand, generate_brand_guide, and regenerate_brand_guide_section, which an agent could otherwise confuse with a rescan.

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

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

Explicitly names when to use each mode with preconditions (brand status="failed" vs "active"), when to pass websiteUrl versus omit it, and draws an explicit boundary — "this does NOT by itself update an already-approved brand guide (call generate_brand_guide again for that)". No inference required to pick the right tool or the right path.

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, but the description adds substantive context beyond them: it never approves, changes or publishes anything, explains the review payload (up to three reasons, one fact to confirm, suggested change), and points at `position` as a countdown. This is far more than the annotations convey.

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

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

Front-loaded with the core purpose and routing, and every clause carries information. The first sentence is dense and long, but nothing is wasted and the read-only/routing guidance follows logically.

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 explain return values, and it does: the post content, the review reasons and their provenance, the confirmation fact, suggested change, position count, and assistantHint. 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 baseline is 3, but the description adds meaning for postId (omitting it selects the next post in Review order) and the `position` countdown that the schema does not describe. `verbose` and `brandId` meaning is left to the schema.

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

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

States a specific verb and resource ('walks the owner through ONE post waiting for their review') and specifies what is returned (images, caption, slide text, review reasons). An agent can immediately distinguish this from get_post, list_posts, and the approve_* siblings.

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

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

Explicitly says to omit postId for the next waiting post, names the dashboard's Review order, and routes downstream actions to approve_post and ask_for_changes with the `review` argument. It also tells the agent to follow assistantHint for the next step.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, and the description supplies the reasoning the annotations cannot: rescheduling retires the earlier attempt so it can never publish, which explains the destruction. It also discloses the approval gate, the YouTube attestation obligation, and that the call itself constitutes the owner's certification.

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

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

The core action and scope lead, followed by the reschedule case, the refusal rule, prerequisite lookups, and the YouTube requirement in descending priority. The quoted attestation line is long but is mandated verbatim text the agent must reproduce, so it earns its space.

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

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

For a destructive, non-read-only mutation with no output schema, the description covers prerequisites, the side effect on prior schedules, failure-to-publish recovery, and a channel-specific compliance step. Nothing an agent needs before calling is missing.

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

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

Schema description coverage is 100% and every parameter's meaning, source tool, and constraints (approved status, ISO-8601 future datetime, channel match) are already in the schema. The description reinforces list_connections for connectionId but adds no syntax or format detail beyond the structured fields, 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?

Names a specific verb+resource+scope: scheduling an already-approved post to a future time via a connected channel, plus the secondary reschedule case. It explicitly distinguishes itself from approve_post and denies doing approval itself, so an agent can separate it from the sibling tools without opening schemas.

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

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

Gives explicit preconditions (post must be approved; call approve_post first), an explicit prerequisite lookup (call list_connections for connectionId), an explicit refusal case ('refuses any other post'), and a conditional workflow requirement for YouTube posts. When-to-use and when-not-to-use are both stated.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, and with no output schema the description carries the return burden well: it discloses the {results: [{id, title, text}]} shape, that duplicate campaigns are collapsed, and that zero matches yield a plain note with a dashboard link rather than an empty array. It does not mention authorization or rate limits, and the closing line about ChatGPT/Claude research modes is context rather than behavior, so a 4 rather than a 5.

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

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

The key scoping fact (what is searched, and that it is not a web search) is front-loaded and the result/refetch contract is useful. However, the description duplicates the schema's parameter text almost word for word, stacks four example questions in-line, and ends with a promotional line about ChatGPT Deep Research and Claude research modes that does not help an agent decide or call correctly.

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

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

With no output schema, the description fully specifies what comes back, how duplicates are handled, what happens on a miss, and how to escalate to fetch. For a single-parameter read tool with strong annotation coverage, 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?

There is one parameter at 100% schema description coverage, and the schema's query description is essentially a verbatim copy of the tool description's first clause, so the description adds no meaning beyond the schema. The only marginal addition is that 'query' is the free-text entry point for both the keyword and question modes, which the schema already states.

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

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

States a specific verb (searches) over two named resource classes (this account's brands/campaigns, and product/help questions) with the matching fields spelled out in parentheses. It also differentiates itself from the rest of the catalog with 'Not a web search' and a handoff to fetch, so an agent can place it among ~50 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?

Explicitly covers both query modes with concrete example strings, states the boundary ('Not a web search'), and names the follow-up path ('Pass a result's id to fetch for the full record'). The no-match behavior is also described, which removes the main ambiguity an agent would have about whether a call failed.

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

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

Annotations already cover the safety profile (destructive, idempotent), and the description adds real context: it writes exactly the passed names, mirrors the dashboard's manual fields, and warns 'never invent one.' It stops short of spelling out what an overwrite destroys, but adds meaningful behavioral guidance.

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

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

Front-loaded with the action, then rationale, then the precondition. Slightly dense with parentheticals but every clause (website-sourced, dashboard parity, don't guess) 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?

No output schema, but for a mutation tool the description supplies the essential precondition workflow, the source-of-truth rationale, and cross-tool pointers. It omits success/failure behavior, which is a minor gap.

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

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

Schema description coverage is 100% and each parameter (brandId, guideId, headingFont, bodyFont) is already documented, including the 'exact font name... not a guess' note. The description reinforces but adds no new parameter-level semantics 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: 'Sets a brand guide's heading and body font directly.' It is readily distinguishable from sibling set_brand_logo and the broader update_brand_guide, and it clarifies it writes exact values rather than generating them.

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

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

Gives a clear precondition ('Have the actual correct font name in hand first') and names the routes to satisfy it (ask the owner, or read from a fresh get_brand_guide result after retry_brand_ingest). It doesn't explicitly contrast against update_brand_guide, but the context is clear.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds real context beyond them: the visible side effects (dashboard brand list, future post images) and the refusal mode for undersized images. It does not explain what becomes of a previously set logo, which matters given destructiveHint=true.

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

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

Three tight sentences, front-loaded with the core action, then prerequisite, then side effects and failure mode. No filler and no repetition of the title or schema.

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

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

With no output schema, the description carries return/behavior burden and does cover side effects, edge cases, and error behavior well. The remaining gap is replacement semantics for an existing logo on a tool annotated destructive, plus whether anything is returned on success.

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

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

Schema description coverage is 100% and both parameters are already documented, including the 'from upload_brand_image' hint. The description's mention of assetId only echoes the schema, adding no format, size, or validation detail beyond it. Baseline 3 applies.

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

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

States a specific verb and resource ('Sets a brand's logo from an existing image library asset') and immediately scopes the source of the asset, which distinguishes it from upload_brand_image and other brand-mutating siblings. The parenthetical clarifies the relationship to the sibling rather than restating the name.

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

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

Explicitly routes the agent: 'upload_brand_image first, then pass its assetId here', naming the prerequisite alternative and the ordering condition. It also declares the no-brand-guide case is acceptable, removing a plausible reason an agent might avoid 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?

Goes well beyond the destructiveHint=true annotation by disclosing all-or-nothing atomicity, that unnamed lines stay untouched, that it is a dry-run by default writing nothing unless apply is true, optimistic-concurrency refusal via expectedVersion, that an approved guide stays approved but is marked edited, and that the consistency check consumes generation budget. This is exactly the behavioral context the annotations cannot convey.

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

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

Front-loaded with the core action and scope, then behavior, then exclusions. It is a long single paragraph but nearly every clause carries distinct, non-redundant information; a light restructure into sentences would improve scanability.

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

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

For a destructive, non-idempotent mutation tool with no output schema, the description covers the workflow, safety guarantees, concurrency control, side effects on approval state, and budget cost — everything an agent needs to call it correctly and interpret 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 coverage is 100% so the baseline is 3, but the description adds real meaning beyond the schema: it explains the apply/expectedVersion interplay as a review workflow and frames the consistency check as advisory budget-consuming behavior. The nested operation semantics are left to the schema's already-rich descriptions.

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

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

States a specific verb and resource ('Edits specific lines of a brand guide') and enumerates exactly which sections/fields are editable, so the agent knows the scope precisely. It explicitly distinguishes itself from siblings by naming set_brand_guide_typography, set_brand_logo and regenerate_brand_guide_section as the tools for palette/logos/fonts/full rewrite.

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

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

Gives an explicit two-step workflow (call without apply, show the owner, then call with apply true) and states when NOT to use it (palette, logos, fonts, personas, full rewrite) with the alternative tool named for each. It also says to pass expectedVersion from get_brand_guide and when to set checkConsistency false.

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

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

Annotations declare destructiveHint=true and idempotentHint=true; the description goes well beyond that by disclosing that content is replaced in full and verbatim, the id is unchanged, the brief is visible in the dashboard and consumed as context by generate_strategy/generate_campaign, and that no delete tool exists so emptying content is the only retirement path. That is exactly the behavioral context annotations cannot convey.

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

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

Front-loaded with the core action and lifecycle consequences, and every sentence carries information. It is somewhat dense and repeats the empty-string retirement rule that the content parameter schema already states, which is a small 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, and the description covers what an agent needs for a destructive mutation: downstream consumers of the brief, the rename constraint, the retirement pattern, and the absence of a delete alternative. Nothing material is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning the schema only implies: briefId is preserved on update, title is the rename lever, and empty content is a semantic state (retired) rather than mere emptiness. It largely reinforces schema text (the empty-string rule appears in both), so it does not reach 5.

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

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

States a specific verb and resource (revises a research brief) and pins down its scope immediately: 'already saved via ingest_research_brief — replaces its content in place (id unchanged)'. This clearly separates it from ingest_research_brief, generate_knowledge_brief, and get_brand_brief without needing to open any schema.

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

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

Explicitly tells the agent when to reach for this tool (revising an existing brief, renaming via title) and gives the non-obvious alternative path for retirement: 'Pass an empty string as content to retire a stale brief... No delete tool exists; emptying content is the retirement path.' When/when-not guidance is complete.

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

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

Annotations already declare the write/network profile (readOnlyHint=false, openWorldHint=true, idempotentHint=false), so the bar is lower. The description still adds real context beyond the schema: server-side fetch semantics, the public-address/no-redirect constraint, and size ceilings, and it names the return value (assetId).

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

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

A single dense paragraph that front-loads the core action, then constraints, then return value. Every clause carries information (formats, limits, video exclusion, downstream use) 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?

There is no output schema, and the description supplies the missing return contract (assetId and where to pass it), the input-mode constraints, and the failure-relevant limits (size, video unsupported). Nothing an agent needs to invoke this correctly is absent.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters, including the base64 prefix requirement and URL size caps. The description largely restates those same format details rather than adding new semantics (e.g., tag usage or interaction between parameters), so the baseline 3 applies.

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

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

The description opens with a specific verb+resource ("Saves an image into the brand's image library") and immediately scopes what it accepts. It is clearly distinguishable from siblings like set_brand_logo or attach_post_media without opening either schema.

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

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

It states the two accepted input modes, rules out video, and routes oversized/video uploads to the Rebbel dashboard, plus names the downstream consumers (attach_post_media, create_adhoc_post). It stops short of an explicit contrast with set_brand_logo, which is the nearest ambiguous sibling.

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