Rebbel

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the write-safe profile is covered. The description goes beyond by characterizing the action's weight ('Same trust level as clicking Approve in the Rebbel dashboard'), which is valuable non-redundant context for an irreversible-looking sign-off, though it doesn't discuss whether approval can be reverted.

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, then necessity, then trust-level caveat — a logical progression. Slightly dense with three clauses in one sentence, but no filler sentences.

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 safety, the description supplies the missing decision context (when approval is needed, trust level). No output schema exists, so return values needn't be explained; only minor gap is reversibility.

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, guideId) are described in the schema with their provenance (list_brands, get_brand_guide). The description adds no parameter-level detail, so the baseline 3 applies.

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

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

States a specific verb ('Approves') and resource ('draft brand guide') and clarifies scope: the human sign-off required before a guide can drive strategy or campaign. This clearly distinguishes it from sibling approve_* tools (approve_copy, approve_post, approve_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?

Explicitly says when it's needed ('Only needed when generate_brand_guide didn't already auto-approve it, which happens on a thin/low-confidence website scan') and includes a strong when-not caveat: 'only call this once you (the user) actually want it approved.' This is precisely the alternative/condition guidance a 5 requires.

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?

Annotations only supply the generic safety profile (readOnly=false, destructive=false); the description goes well beyond by characterizing the trust level ('same as clicking Approve in the dashboard'), requiring real user intent, disclosing the story-format side effect (caption/hashtags/link won't publish), and describing the response (mediaLinks stable https links) despite there being 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?

Four sentences, each load-bearing — the gating constraint, the user-intent requirement, the story-format caveat, and the response note — with the prerequisite relationship front-loaded ahead of nuance.

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

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

For a non-read-only mutation tool with no output schema, the description covers the safety/authorization model, the caller obligation to confirm intent, a format-specific edge case, and the return value, leaving no gap an agent would need to guess at.

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

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

Schema description coverage is 100%, so the baseline is 3: the schema already documents all four parameters, including the nested review object and its enums. The description adds no syntax or format detail beyond what the schema carries, so it neither compensates nor detracts.

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 post') and immediately situates it against siblings by declaring it a prerequisite for publish_post/schedule_post. An agent can distinguish it from approve_copy, approve_strategy, and approve_brand_guide 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 gating: only call once the user actually wants this exact post approved, and it is required before publish/schedule will work. It also names the review_post precondition for supplying the review object, so both when and when-not are covered.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false. The description adds meaningful context: it is required before generate_campaign succeeds, it may be skipped by auto-approval, and it carries the same trust level as clicking Approve in the dashboard. It does not mention required permissions or error behavior, but the annotation coverage lowers the burden.

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

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

The description is a single tight paragraph that front-loads the action, then adds dependency and conditional-use details. Every sentence contributes relevant guidance without filler.

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

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

For a two-parameter mutation tool with full schema coverage, no output schema, and useful annotations, the description covers why the tool exists, when it is needed versus auto-approval, and user-consent expectations. An agent has enough context to invoke it correctly.

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

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

Schema description coverage is 100%, and the schema already explains that brandId comes from list_brands and strategyId from get_strategy. The description adds no additional parameter meaning, so the baseline of 3 applies.

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

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

States a specific verb (approves) and resource (draft strategy), and explains the dependency on generate_campaign. It distinguishes itself from generate_strategy, which may auto-approve the 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?

Explicitly says when the tool is needed ('only needed when generate_strategy didn't already auto-approve it'), gives the condition that triggers that path ('thin/low-confidence website scan'), and states the user-consent requirement. Alternatives are clearly implied via the auto-approval 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?

Adds substantive behavioral context beyond annotations: what is *not* destroyed (campaigns, connections, billing history all stay intact), that the action is not reversible from this tool, and that restoration happens in the Rebbel dashboard. This nuances the destructiveHint=true annotation (visibility removed, data retained), which the annotation alone 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?

Three short sentences, front-loaded with the core effect, then scope of damage, then reversibility. No filler; each sentence carries a distinct, decision-relevant fact.

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

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

For a single-parameter mutation with no output schema, the description covers everything an agent needs: what changes, what survives, and that undoing requires the dashboard. No gaps remain for correct invocation.

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

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

Schema description coverage is 100% and the brandId description already explains provenance (from list_brands), the hide-not-delete semantics, and the restore path. The description adds no parameter-level detail beyond what the schema states, 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 effect ('Hides a brand from list_brands') plus the resource, and immediately distinguishes itself from a hard delete. An agent can tell exactly what happens to the brand without opening the schema, and the reference to list_brands ties it to the sibling that surfaces the change.

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 selection context — 'a brand the user is done with, or an accidental duplicate' — and clarifies it is not a delete. It stops short of naming an alternative tool or exclusion (there is no unarchive sibling), so routing is inferred from the effect rather than from an explicit alternative.

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

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

Annotations already mark this destructive and idempotent, but the description adds critical context annotations cannot convey: it does not cancel scheduled posts or pause an attached live ad campaign, and it is not reversible from here (restore happens in the dashboard). That is exactly the side-effect and reversibility information an agent needs before a destructive 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?

Three short sentences, zero filler, with the primary effect front-loaded and the caveats ordered after. Every clause carries decision-relevant information.

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

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

For a two-parameter destructive mutation with no output schema, the description covers purpose, trigger conditions, side-effect boundaries, and reversibility. Nothing an agent needs to call it safely is missing.

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

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

Schema description coverage is 100%, so brandId and campaignId are already fully documented in the schema (campaignId's schema text even repeats the archive caveats). The description adds no new parameter-level meaning such as formats or edge cases, 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 ('hides/archive') and resource ('a campaign') and immediately clarifies the concrete effect: it disappears from list_campaigns. This distinguishes it from siblings like pause_ad_campaign and archive_brand without the agent needing to open any schema.

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

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

Gives an explicit when-to-use ('an accidental duplicate or a test run the user doesn't want cluttering the list') and explicit when-not boundaries ('doesn't cancel scheduled posts or pause a live ad campaign attached to it'). The agent can route between archive_campaign and pause_ad_campaign from the description alone.

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

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

Annotations only declare the mutation/safety profile; the description adds substantial behavioral detail beyond them — previous version retained and restorable, never a silent no-op, unfulfillable requests return an honest line with nothing changed (some decided instantly pre-generation), and the response's `note` (owner-facing) vs `assistantHint` (for the agent) distinction.

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 each clause carries real information (versioning, error behavior, note/assistantHint). It is dense and long, with several sentences that could be tightened, but little is pure filler.

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

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

With no output schema, the description supplies the return behavior (inline caption before/after for quick changes, get_post for media work, note vs assistantHint) and the review-gating context for a 6-param tool with a nested object. An agent has what it needs to call and interpret it correctly.

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

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

Schema coverage is 100%, so every parameter including the nested `review` object is already documented. The description's note guidance ('pass the user's own words, don't rewrite the copy') largely duplicates the schema's own note description, so it adds little beyond the 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+scope: it changes exactly one thing about a post via a plain-language note, and enumerates the classification scopes (caption, one slide/image, all media, add/remove slide, timing). It explicitly distinguishes itself from remake_post for when the whole idea is wrong.

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

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

Names the alternative (remake_post) and the exact condition that selects it, notes it never approves/publishes and that an approved/scheduled post needs a fresh approve_post, and routes the agent to get_post to see media work land. Clear when-to-use and when-not.

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, non-idempotent, and open-world. The description adds unique behavior beyond that: image posts receive auto-generated headline/subhead/cta text, video key frames get no text, and the response's post.mediaLinks should be shown to the user. This is rich behavioral context that structured data does not provide.

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

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

Four sentences, each earning its place: purpose, text-placement behavior, exclusions with alternative, and response handling. The purpose is front-loaded and there is no redundant restatement of the name or 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?

No output schema exists, but the description explains the response shape (post.mediaLinks) and directs the agent to show the user the result. Combined with annotations and full schema coverage, the definition gives an agent everything needed to invoke the tool correctly and handle its output.

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 parameters are documented in the schema. The description restates the three input options (base64, public https URL, existing assetId) but adds no syntax, format, or constraint details beyond what the schema already provides. 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 (attaches) and resource (an image to an existing image_post or video_post waiting on media), and explicitly distinguishes from siblings like create_adhoc_post and non-applicable post types. An agent can identify the exact operation and its scope without opening any schema.

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

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

Explicitly states when not to use it (text_post/carousel, user's own verbatim posts) and names the alternative (create_adhoc_post's mediaLibraryAssetId). Also specifies the precondition that the post must be waiting on media, leaving no ambiguity about selection.

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

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

Annotations mark this as a non-readonly but idempotent, non-destructive write; the description adds the crucial behavioral semantics annotations cannot carry — that passing all:true constitutes the owner's rights representation, that it mirrors approve_post, and that the agent must not confirm on its own judgment. It also discloses the list-vs-mutate behavior and the downstream effect on AI-art usage.

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-load the what, then the how-to-call, then the critical caution, in descending order of urgency. Every sentence carries actionable content 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 four-parameter, dual-mode tool with no output schema, the description covers both primary paths and the rights constraint well. It omits any reference to the collections/facts grouping capability, relying entirely on the schema for that, and only loosely implies the shape of the returned list.

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 genuine operational meaning beyond the schema by clarifying that 'neither assetIds nor all' triggers a pure list call and by emphasizing the rights weight of all:true, though it never mentions the collections parameter.

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-mode purpose: listing unconfirmed candidate photos crawled from the brand's site, or confirming them into the image library so posts use real photos instead of AI art. The verb+resource is concrete and the effect on downstream post generation is spelled out, so an agent can distinguish it from siblings like upload_brand_image 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?

It gives explicit when-to-use and when-not guidance: 'Call with neither assetIds nor all to see the list first,' and for the mutation path, 'only call it once the owner has actually said these are theirs, never on your own judgment.' It even names approve_post as the analogous rights step, 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 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 negative hints (not read-only, not idempotent, not destructive, closed-world). The description goes well beyond them, disclosing what the scan actually does (pulls logo/colors/copy tone), that name is derived and later upgraded, and crucially that connectSocialFirst cannot complete OAuth itself and hands off a dashboard link.

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 most sentences carry workflow value. It is dense with nested parentheticals and follow-up guidance that makes it a heavy read, but little of it is truly wasted for a branching multi-path tool.

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

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

With no output schema, the description compensates by describing the return value ("a real summary of what the scan actually found (name, palette, logo, a voice sample)") and the divergent connectSocialFirst response. Given a branching, zero-required-param, nested-object tool, nothing essential is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds real cross-parameter logic the schema states only per-field: name being optional/required depending on which other path is chosen, and connectSocialFirst being an alternative to websiteUrl/guided rather than a complement.

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") and then enumerates the three mutually exclusive creation paths (website URL scan, guided answers, connectSocialFirst). It explicitly positions itself as "First step for a brand that doesn't exist in Rebbel yet," distinguishing it from sibling read/approve/generate 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?

Gives explicit when-to-use conditions per path: websiteUrl when a site exists, guided "if there's no site yet," connectSocialFirst "if there's no website at all." It also routes to follow-up siblings (draft_first_post, generate_brand_guide) and names list_connections/list_brands as the way to check readiness.

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 declare destructiveHint=true and readOnlyHint=false, but the description goes beyond them by stating the operation is not reversible from here and specifying the recovery path (reconnect from scratch in the Rebbel dashboard). This is exactly the kind of consequence detail an agent needs before a destructive 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 tightly packed sentences with the irreversibility warning front-loaded second, no filler. 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?

For a 2-parameter destructive tool whose annotations already cover the safety profile, the description supplies the missing consequence and recovery context. No output schema is needed, and nothing required to call it correctly is absent.

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

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

Schema description coverage is 100%, so both brandId and connectionId are already fully documented, including the warning not to remove healthy connections. The description adds no new parameter syntax or format 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?

Specific verb (removes/disconnect) plus resource (channel connection), and it scopes the operation to broken or wrong connections with concrete examples (health="error"/"needs_reauth"). It also implicitly distinguishes itself from list_connections by explaining it removes clutter from that list.

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

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

States the trigger condition clearly (only remove a connection that is actually broken/wrong, with health-state examples) and warns of the downstream effect (can't be used to publish/schedule). It stops short of naming an explicit alternative tool or a when-not-to-use path, but the usage context is unmistakable.

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 the mutation profile (readOnly=false, destructive=false, idempotent=false); the description adds substantive behavior beyond that: output is drafts, a voice source must be real, a confident website scan defaults the target platform to Facebook until a channel is connected, and publishing is where a connection is actually required. No contradiction with annotations, and the state-transition chain (draft → approve → publish/schedule) is disclosed.

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

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

Purpose and key constraint are front-loaded, but the description is a single dense sentence with three stacked parentheticals and repeats the count guidance already present in the schema. It earns most of its length but could shed the duplicated count advice and one nested aside without losing information.

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

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

With no output schema, the description correctly explains what comes back (drafts under 'your own posts') and what to do next, plus the prerequisites and the default-platform fallback. It is nearly complete for this tool's complexity; only failure modes (e.g., thin website scan blocking a draft) are implied rather than stated.

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

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

Schema coverage is 100%, so both parameters are already fully documented in the schema, including the 1-5 range and the brandId voice-source requirement. The description restates the '3-5 for a real first-run batch' guidance rather than adding new syntax or constraints. Baseline 3 is appropriate when the schema carries the 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 and resource ('AI-drafts 1-5 posts') with explicit scope (1-5, from the brand's own voice) and clearly separates itself from create_post/create_adhoc_post by noting output lands as drafts, not published posts. It also names the downstream siblings (approve_post, publish_post, schedule_post), so an agent can place the tool in the workflow 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 conditions ('no brand guide or strategy required', 'no connected channel required') and states the alternative path when a real connection is needed (publish_post / schedule_post, see create_brand's connectSocialFirst path or list_connections). It also names the required precondition (a real voice source: connected account bio/recent posts or a non-thin website scan), which is exactly the routing information an agent needs.

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, destructiveHint:false and openWorldHint:false, so safety is covered and the bar is lower. The description still adds non-obvious behavior: it discloses the return shape '{id, title, text, url}' despite there being no output schema, and notes ids must originate from search rather than arbitrary URLs. It does not cover error behavior for unknown/malformed ids, which keeps it from a 5.

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

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

The core action is front-loaded in the first clause, and every subsequent clause adds distinct information (the three id types, read-only status, return shape). The three-part parenthetical is dense but information-bearing rather than filler, so it stays within a reasonable size for the amount of routing it does.

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?

One required parameter with full schema coverage, rich annotations, and no output schema — and the description fills the output gap itself by naming the returned fields and the per-type content. Nothing an agent needs to select or correctly invoke this tool 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 id format is already documented and the baseline is 3. The description goes slightly beyond the schema by mapping each prefix to the specific content it yields (brand fields, campaign fields, full help answer plus source page), which tells the agent what to expect from the single parameter rather than just its syntax.

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 (the full record behind a search result id), then enumerates the three id namespaces and exactly what each returns. The closing 'Not a web fetch — ids come from search' explicitly separates it from any web-fetch interpretation and from the sibling search tool, so an agent can identify 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?

It gives clear usage context by tying the tool to ids produced by 'search' and explicitly rules out web URLs ('Not a web fetch'). That is a real when-to-use and when-not signal. It stops short of a 5 because it never routes the agent among the overlapping getters (get_brand_brief, get_brand_guide, get_post) for the same underlying data.

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

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

Beyond the annotations (which only flag non-read-only, non-idempotent, non-destructive), the description discloses the actual state machine: strong-signal scans auto-approve while thin/low-confidence scans persist as an unapproved draft. That outcome behavior is exactly what an agent needs and is not derivable from the structured fields.

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

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

Front-loaded with the core action and precondition, then the auto-mode nuance. Dense but each clause carries routing value; it runs slightly long, but no sentence is wasted given the branch logic being conveyed.

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 covers the key return outcome (approved guide vs unapproved draft) and the dependency chain. It could say more about the guide payload itself, but for a one-param generation tool the workflow completeness is strong.

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 param is already documented in the schema, including the 'from list_brands' provenance and scan-completion precondition. The description restates this rather than adding syntax or format detail, 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 (generates) and resource (a brand guide) with its source input (a brand's completed website scan). This cleanly separates it from get_brand_guide, update_brand_guide, and regenerate_brand_guide_section without opening any schema.

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

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

Explicitly states the prerequisite (create_brand's scan must have finished) and the downstream routing: in auto-mode call generate_strategy directly, while a thin scan routes toward fill-in-gaps or an explicit approve_brand_guide. The when/when-not conditions and alternative branches are all named.

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

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

Annotations only declare the generic safety profile (readOnlyHint false, destructiveHint false, idempotentHint false). The description adds substantial context beyond that: posts land as drafts awaiting approval, this tool never publishes or schedules, an existing campaign may be returned instead of creating a new one, and ineligible channels are silently dropped with a note rather than erroring unless none qualify.

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, then layered with dedup and channel rules. It is a dense single paragraph, so slightly heavy, but each clause (draft-only, dedup, generateAnyway, channel gating) carries distinct information.

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

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

For a 7-param mutation tool with no output schema, the description covers the essential behavior an agent needs: no publishing/scheduling side effects, draft output, dedup handling, and channel fallback semantics. 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 real meaning beyond the schema: the dedup/return behavior tied to objective+angle, the concrete channel-eligibility rules (meta_facebook/meta_instagram always available; linkedin/threads/x gated), and confirmation that unmatched channels are dropped not errored.

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 campaign and generates a first batch of draft posts) with explicit scope detail (copy + image briefs per channel). It clearly separates itself from siblings like create_post, create_adhoc_post, and draft_first_post by describing the campaign-level bundle it produces.

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

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

Explicitly says when to pass generateAnyway:true (only after the user asks for a second campaign on the same brief), explains the dedup path (existing campaign with same objective+angle returns instead), and details channel eligibility. The agent has clear when-to and when-not-to guidance.

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

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

Annotations declare this is a mutation (readOnlyHint=false) but not destructive, and the description adds a genuinely non-obvious behavioral trait: 'Never overwrites a brief you've hand-edited.' That protects the agent from assuming a clobber, which annotations alone do not convey. It does not cover idempotency or the no-guide-exists case.

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 resource; the long parenthetical definition of the brief earns its place by grounding an otherwise jargon term. Three sentences, all load-bearing, though the parenthetical is dense enough to slow reading.

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 mutation with no output schema, the description covers purpose, trigger context, and the hand-edit safeguard adequately. Return behavior and failure modes are left implicit, which is the only meaningful 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 the single brandId parameter is fully documented in the schema (including provenance from list_brands), so the description adds no parameter meaning. Baseline 3 for a high-coverage schema where 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?

Uses a specific verb (regenerates) plus a precisely scoped resource (the brand's knowledge brief), and even defines what that brief contains. It is clearly distinguishable from get_brand_brief (retrieval) and generate_brand_guide (guide creation) without opening either schema.

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

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

Explicitly states the default behavior ('Runs automatically on every guide approval') and the condition that selects this tool ('use this for an on-demand re-run'), which is exactly the when-to-use guidance an agent needs. It stops short of naming sibling alternatives, but the routing condition 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?

With annotations declaring readOnlyHint=false and idempotentHint=false, the description adds meaningful behavioral context beyond them: the auto-approval behavior and the branch to draft status. It doesn't quantify cost, latency, or rate limits, so it falls just short of full transparency.

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, followed by prerequisite and outcome branches, and every sentence carries information. It is slightly dense with the auto-mode explanation 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?

With no output schema, the description adequately covers the inputs, the prerequisite, and the resulting state (auto-approved vs draft). It doesn't describe return payloads, but the workflow context is sufficient to call the tool 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 both parameters (brandId, goals) are already documented. The description reinforces that goals drive the strategy but adds no format or syntax 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?

States a specific verb ("Generates") plus the resource and its contents ("organic-first marketing strategy (channel mix, content pillars, posting cadence)") and the source input ("from the brand's goals"). It is clearly distinguishable from siblings like generate_brand_guide and generate_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?

Names the prerequisite explicitly ("Requires an approved brand guide first") and splits the outcome into two cases: a confident-scan brand that auto-approves and readies generate_campaign, versus a thin-scan brand that lands as a draft needing approve_strategy. This tells the agent both when it can proceed and which sibling to call next.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description goes further by disclosing the aggregate behavior (deduped across every campaign), failure reporting with cause and next step, and the unusual consumer instruction 'Read `brief` to the user as-is' — genuinely useful context beyond structured data.

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 front-loaded with the payload description before the usage triggers, and nearly every clause carries distinct information. It is dense and slightly long, but not padded.

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

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

With no output schema, the description fully carries the burden of what comes back: sentence count, the four content categories, and the single link. An agent knows exactly what it will receive and how to present 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% and the single parameter already documents that brandId comes from list_brands. The description adds no parameter-level syntax or format detail, so the baseline 3 applies — 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?

The description states a specific verb and resource ('brand-level check-in in one call') and precisely enumerates the content: pending owner actions deduped across campaigns, next-7-day schedule, last-7-day activations, failures with cause and next step, and one link. It distinguishes itself from siblings by noting it replaces calling list_campaigns + get_results_verdict per 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?

Explicit triggers are given ('how's it going', 'what do I need to do', 'what's happening this week') plus an explicit alternative it supersedes (list_campaigns + get_results_verdict). Nothing about when or when-not to use it is left to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so safety is covered. The description adds genuine context beyond that: it falls back to the latest draft when no approved guide exists, and it characterizes the size/contents difference between compact and verbose responses.

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

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

Two tightly written sentences: the first front-loads what is returned, the second handles the compact/verbose decision. No filler or repetition.

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

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

With no output schema, the description carries the burden of describing return content and does so thoroughly for both compact and verbose modes. For a read-only tool whose annotations cover the safety profile, 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?

Schema coverage is 100%, so both parameters are fully documented in the schema, including the verbose tradeoff ('several times larger', internal fields/ids/provenance). The description largely restates that same tradeoff rather than adding new 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 (fetches) and resource (brand guide) and enumerates the exact content returned (identity, voice rules, palette, logo links, do/don't rules). This clearly separates it from siblings like update_brand_guide, generate_brand_guide, regenerate_brand_guide_section, and 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?

The verbose toggle gets explicit guidance ('Pass true only when you need the full stored record... rarely needed'), which is useful. However, nothing tells the agent when to reach for get_brand_guide instead of get_brand_brief, list_brands, or get_strategy; tool-level selection guidance is only implied.

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

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

Annotations already declare readOnlyHint/destructiveHint=false, so safety is covered; the description adds real value beyond that by disclosing the returned payload shape (stable mediaLink, refused request, dashboard-worded status) and the semantic that 'reading a post never approves it,' clarifying the read/approve workflow boundary. It could add more on pagination/size limits beyond the verbose note.

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

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

Purpose and the key when-to-use/alternative routing are front-loaded in the opening sentences, and the verbose note is sensibly placed last. The middle enumeration of returned fields is dense but each item is informative; slightly long but not padded.

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

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

With no output schema, the description carries the return-value burden and does so by listing the major fields and the verbose variant. Combined with full schema coverage and read-only annotations, an agent has what it needs to call correctly; only large-response handling is left implicit.

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

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

Schema description coverage is 100%, so all four parameters are already documented — the baseline is 3. The description reinforces verbose (full stored record: brief, image prompt, version history) but does not add syntax or constraints the schema lacks, so no credit 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 and resource ('Reads one post') and then enumerates the concrete payload — caption, slide list with mediaLink, scene plan, last change, status. It explicitly distinguishes itself from list_posts ('only returns a headline'), 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 when-to-use ('review or critique what Rebbel actually wrote before approving it') and names the alternative plus its limitation ('list_posts only returns a headline, which isn't enough to judge copy against a brand's voice'). The condition that selects this tool is unambiguous.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds real context beyond that: it reports freshness ('when they were read'), distinguishes what needs the owner from what the department is still working on, and surfaces failures with a next step. It does not cover auth requirements or pagination, which keeps it from a 5.

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

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

It is one dense return-contract sentence plus a short routing sentence, with the verb and scope front-loaded. Every listed element maps to a real output section, though the single long clause chain is harder to scan than a short bulleted list would be.

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

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

There is no output schema, so the description effectively serves as the return-value contract, and it enumerates the payload sections an agent would need to reason about results. Combined with the sibling routing hint and the fully documented parameters, nothing needed to invoke and interpret this tool 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% – both brandId and campaignId are documented in the schema, including where to source them (list_brands, list_campaigns or generate_campaign). The description adds nothing about the 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 names a specific verb (fetches) and resource (one campaign's latest results) and then enumerates the exact payload sections: plain-English results with read timestamp, post status breakdown, owner-needed vs. in-progress items, failures with next steps, and metric snapshots. It also names the sibling it is not (get_brand_brief), so an agent can distinguish 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?

It states the scope condition implicitly by saying 'one campaign's' and gives the routing rule explicitly: 'For the whole brand in one call, use get_brand_brief instead.' That is a concrete when-to-use-this vs. when-to-use-the-alternative statement.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that: it discloses that both approved and draft strategies are returned (a non-obvious state), enumerates the returned sections, and explains the default-compact vs. verbose-full behavior including the size tradeoff.

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, both earning their place: the first front-loads what is fetched and its contents, the second front-loads the default behavior. Dense and skimmable, though the long enumeration of fields could have been grouped more 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?

There is no output schema, so the description correctly compensates by enumerating the returned sections (goals, budget, channels, cadence, pillars, calendar, expectations, rationale). Combined with the disclosed approved-or-draft state and the compact/verbose distinction, an agent has enough to call and interpret this tool 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 brandId's provenance ("from list_brands") and the verbose semantics are already documented in the schema. The description's "compact by default; verbose:true returns the full stored record" largely restates the schema rather than adding syntax or format detail. Baseline 3 is appropriate.

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

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

States a concrete verb ("Fetches") and resource ("a brand's latest strategy") and pins the scope to the newest version, whether approved or draft. It also enumerates the payload contents, so an agent knows exactly what comes back. It stops short of explicitly contrasting itself with generate_strategy or approve_strategy, but the resource and version scoping are specific enough to tell it apart.

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

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

Usage is implied rather than stated: "as the owner reads it" and "latest (approved or still draft)" suggest a read of the current effective strategy, and the verbose flag carries its own condition ("pass true only when you need the full stored record"). However, there is no explicit when-to-use vs. alternatives guidance, e.g. whether to prefer get_brand_brief or list_campaigns for adjacent information.

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

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

Annotations declare destructiveHint=true and idempotentHint=false; the description adds that content is saved verbatim and is consumed as context by generate_strategy/generate_campaign, which explains downstream effects. It does not explicitly warn against duplicate creation being non-idempotent as a risk, but the 'instead of saving a duplicate' line covers the practical hazard. Minor gap: no mention of permanence/undo limits beyond wording 'permanent document'.

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 effect, then routing guidance. Slightly dense with a parenthetical enumeration of content kinds, but every clause earns its place.

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

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

For a save-mutation tool with no output schema, the description covers what is stored, how it is used downstream, and when to use an alternative. It does not describe what the tool returns (e.g., an id), which would help the agent chain to update_research_brief, but the dashboard-URL fallback mitigates this.

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 each parameter is already documented in the schema, including the 'domain' enum semantics. The description adds nothing about individual parameters beyond what the schema states, which is the expected baseline when 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 (Saves) and resource (AI-synthesized research brief), and enumerates the content domains (market sizing, competitor analysis, audience/persona notes). It explicitly distinguishes itself from update_research_brief by naming that sibling and the condition that selects it.

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

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

Explicit when-to-use ('whenever a conversation produces real research worth keeping') and when-not (to revise an existing brief, use update_research_brief instead of saving a duplicate). It even tells the agent where to find the existing brief 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds that results include id and status and that it acts as the prerequisite resolution step, which is useful behavioral context beyond annotations.

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

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

Two tight sentences with zero waste; the resource description comes first and the routing instruction ('call this first') is placed prominently. Every clause earns its place.

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

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

With no output schema, the description partially compensates by naming id and status, and it establishes the tool's role as the entry point for resolving brandIds. Nothing critical is missing, though a note on ordering or pagination 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?

The tool takes zero parameters, so per the rubric the baseline is 4. The description correctly signals a parameterless call and instead describes the returned identity fields, adding meaning without inventing inputs.

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) this Rebbel account manages') and names the fields returned (id, status). It is clearly distinguishable from siblings like create_brand, archive_brand, and rename_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?

Explicitly says 'Call this first to resolve a brand name to a brandId before calling any other tool' – a precise when-to-use directive with the condition that motivates it. No alternative tool ambiguity remains.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds meaningful context about the returned data (field list including post-status counts), though it omits pagination, ordering, or rate-limit behavior.

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

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

Two tight sentences, front-loaded with what the tool returns followed by the precise use case. Every phrase carries information and nothing is redundant.

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

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

With no output schema, the description compensates well by listing returned fields and the lookup purpose. Minimal gaps remain around pagination or default result limits, but the core information needed to invoke and interpret the tool is 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 the single parameter (brandId) is fully documented in the schema as coming from list_brands. The description does not add any parameter-level detail, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Lists a brand's campaigns'), enumerates the returned fields, and explicitly distinguishes itself from other campaign/post tools by noting none can look up a campaign 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?

Provides an explicit use case ('find a campaignId for an existing campaign') and rules out alternatives by stating that no other campaign/post tool can perform a name lookup, leaving no ambiguity about when to choose this 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 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 declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so safety is covered. The description adds meaningful context beyond that: the exact fields returned and the fact that no alternative tool exposes connectionIds, which shapes how the agent should reason about the 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 tightly written sentences: the first declares what is returned, the second covers the two usage scenarios with named downstream tools. No filler, and the most important routing information (only source of connectionId) is front-loaded.

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

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

With no output schema, the description compensates by enumerating the returned fields, and with a single fully-documented parameter and annotations covering the safety profile, nothing an agent needs to select or call this tool 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% and the single brandId parameter is fully documented in the schema (including its source, list_brands). The description adds no syntax or format detail beyond the schema, 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 (Lists) and resource (a brand's connected channel accounts) and even enumerates the returned fields (id, channel id/name, account name, health). An agent can distinguish this immediately from siblings like list_brands or list_posts.

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

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

Explicitly states the primary use case (obtaining the connectionId that publish_post and schedule_post require) and asserts it is the only discovery path, plus a second use case (confirming a create_brand connectSocialFirst connection landed before draft_first_post or generate_brand_guide). This is when-to-use guidance with named consumers.

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, destructiveHint=false and closed-world, so safety is covered. The description adds useful behavioral detail beyond that: the default compact output and the fact that verbose:true expands to the full record with every status field, plus the guarantee of 'one stable mediaLink per post.'

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

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

Front-loads what is returned, then the usage guidance, then the compact-vs-verbose note. Two dense sentences with no filler; every clause carries 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 correctly carries the burden of describing the return shape by enumerating the fields. Combined with the usage routing and the verbosity control, nothing material is missing for calling this tool 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 baseline is 3 and the schema already documents brandId, campaignId and verbose. The description still adds value by tying verbose to the returned field set ('adds every status field'), reinforcing the tradeoff between the compact owner view and the full record.

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 id, channel, status, headline, and mediaLink. An agent can distinguish this from get_post (singular retrieval) 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 workflow: 'Use this to find a postId before get_post, approve_post or schedule_post,' routing the agent to concrete downstream tools. It stops short of stating when not to use it or what it is a poor fit for, so it falls just below the top tier.

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?

Beyond the annotations, the description discloses important behavior: it stops real delivery, it cannot start or increase spend, it is available directly in chat, and it refuses when no ad campaign exists or the campaign is already paused. These details meaningfully explain the safety profile and failure conditions.

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

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

The description is front-loaded with the core action and purpose, then adds the risk rationale and refusal conditions in a tight, useful way. Every sentence contributes to selection or invocation.

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

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

For a two-parameter mutation tool with full schema coverage and annotations covering read/write, idempotency, and destructiveness, the description provides enough context to call it correctly. No output schema exists, so return-value details are not needed.

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 explains both brandId and campaignId with their sources. The description adds no parameter-specific syntax or format details, so the baseline of 3 is appropriate when the schema carries 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?

The description states a specific verb and resource: 'Stops real delivery on an active ad campaign — the kill switch.' It also distinguishes this action from riskier campaign actions like creating, activating, or scaling, so an agent can identify it clearly.

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 when to use the tool: pausing is monotonically risk-reducing and therefore available directly in chat. It also gives when-not conditions ('refuses if the campaign has no ad campaign, or it's already paused'), though it does not explicitly name an alternative tool such as archive_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 destructive/non-idempotent/open-world behavior, but the description adds genuine behavioral context beyond them: it refuses when status!=approved, and it imposes a YouTube-specific obligation to display a certification line before calling. That compliance/precondition detail is not derivable from structured fields.

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

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

Three tight sentences, front-loaded with the core action, then preconditions, then the special-case YouTube requirement. Every sentence carries load; nothing is redundant.

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

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

For a write action with full schema coverage, no output schema, and annotations covering the safety profile, nothing an agent needs to invoke it correctly is missing. The approval precondition and YouTube certification requirement close the important gaps.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters, including that postId must be approved and where connectionId comes from. The description reinforces ordering but adds little syntax or meaning beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Publishes an already-approved post') and explicitly distinguishes itself from the sibling schedule_post by calling itself 'the on-demand equivalent of schedule_post.' The scope ('already-approved,' 'immediately') is unambiguous.

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

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

Gives explicit prerequisites and routing: call approve_post first, call list_connections first for connectionId, and use schedule_post instead when scheduling. Both the when-to-use and the alternative are named.

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

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

Annotations already declare the mutation profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), and the description adds real behavioral context beyond that: the whole section is rewritten from the website scan and the rest of the guide is untouched, and feedback can steer the output. It does not discuss whether regeneration is costly, requires auth scopes, or is reversible, but with annotations covering the safety profile this is solid.

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

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

Front-loads what the tool does before the routing guidance, and the three sentences are dense with decision-relevant content. There is mild redundancy: the 'feedback vs generate_brand_guide' rationale appears both in the description body and repeated in the feedback parameter description.

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

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

For a non-idempotent mutation with no output schema, the description covers when to choose it, the overwrite semantics (whole section rewritten, rest untouched), and the steering parameter. It does not describe what the call returns or any cost/time implication, but 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?

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: it clarifies that feedback steers regeneration (with example content such as what the brand sells or a tone correction) and that the rewrite is scoped to the named section. The section enumeration in the description names a subset of the schema enum (missing imagery, capabilities, limitations), a minor inconsistency.

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

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

States a specific verb+resource+scope ('regenerates one section of a draft brand guide') and enumerates the section names, so an agent knows exactly what unit of work this performs. It also explicitly separates itself from generate_brand_guide and update_brand_guide by naming the alternative 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?

Gives explicit routing rules: use this instead of generate_brand_guide when the guide exists but the scan was thin and real detail is available, and use update_brand_guide instead when only specific lines should change. When-to-use, when-not, and the alternative for each condition are all named.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so safety semantics are covered. The description adds only the mild context that the target is a 'draft' strategy; it does not state whether regeneration overwrites prior output, whether approval is required first, or what a repeat call produces despite the non-idempotent hint.

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 core action stated first and the section glossary after it. The parenthetical glosses add length but each earns its place; no filler or repetition.

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

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

For a non-idempotent mutation with no output schema, the description covers purpose and section meaning but omits governance context: whether it works only on unapproved drafts, whether feedback is free-form, and whether existing content is lost. The missing 'rationale' entry in the section list is a further completeness gap.

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

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

Schema coverage is 100%, so the schema carries the parameter documentation and baseline 3 applies. The description goes beyond it by translating opaque enum values into plain language (channelMix = 'where to post', cadence = 'how often', calendarSkeleton = 'the week-by-week calendar'), which materially helps the agent pick the right section.

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 ('Regenerates one section of a draft strategy') and enumerates the section values with short glosses, which clearly differentiates it from generate_strategy. However, the enumeration lists only seven sections while the enum includes eight ('rationale' is missing), leaving a small ambiguity about what is actually regenerable.

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 'draft strategy' and 'steered by feedback', so an agent can infer this is for revising an existing draft. But there is no explicit when-to-use vs. generate_strategy or regenerate_brand_guide_section, and no stated prerequisite (e.g. the strategy must exist and not be approved).

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=false), the description discloses the full mutation profile: a new version is created with the previous one kept, images are redone, output goes through a quality check, and the post returns in review rather than published. It even documents the no-op edge case (user's own verbatim post, or no capabilities in the guide) returning one line with nothing changed.

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, scope, and the sibling alternative, then the behavioral caveats. It is dense and long, but nearly every clause carries decision-relevant information; the em-dash-heavy style is slightly harder to scan than a clean sentence-per-idea structure.

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

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

For a 5-param mutation tool with no output schema, it covers everything an agent needs: what is regenerated, what is preserved, the review state of the return, and the exact conditions under which nothing happens.

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 real value by telling the agent to 'pass the user's reason if they gave one' and explaining that it is folded in as critic notes, which is semantic guidance not present in the schema field text.

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

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

Opens with a specific verb+resource ('Re-makes one post from the brand guide') and immediately scopes it as a fresh concept for THIS post under the current guide. It distinguishes itself from ask_for_changes by contrast, so an agent can separate it from sibling editing 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?

Explicit when-to-use ('when the idea itself was wrong — it describes a feature the product doesn't have, or the wrong audience'), explicit when-not ('not just a line or an image'), and names the alternative ('for a targeted edit use ask_for_changes'). It also states the boundary with approval/publishing tools.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, giving the safety profile. The description adds only a cross-tool note rather than behavior of this call itself (e.g. side effects on scans/ingestion), so the added value beyond structured data is modest.

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

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

Two tight sentences, front-loaded with the core purpose and followed by a useful routing caveat. Nothing redundant, though the second sentence leans toward justifying a sibling rather than this tool.

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

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

For a two-parameter rename with full annotations and no output schema, the definition covers purpose, key scope boundary, and the sibling to use instead. Return-value behavior is not described, but no output schema exists and the annotation set is adequate.

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?

Both parameters (brandId, name) are fully documented in the schema at 100% coverage, so the baseline is 3. The description adds no additional format or constraint detail beyond what the schema already provides.

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

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

States a specific verb+resource ('Renames a brand') and immediately bounds the scope by contrasting it with the sibling retry_brand_ingest for websiteUrl correction. An agent can tell exactly what this tool mutates without inspecting 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?

Provides explicit negative routing: websiteUrl correction 'lives on retry_brand_ingest instead,' naming the alternative and giving a rationale. It lacks broader when-to-use guidance (e.g. prerequisites for renaming), but the key exclusion 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, 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?

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false): it explains that 'use' lands the correction as a new version while keeping the current one restorable, that it re-enters review for fresh approval, that a paused scheduled publish resumes after approval vs. immediately on 'keep', and lists three refusal conditions. This is exactly the reversibility, side-effect, and error context an agent needs.

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

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

A single dense paragraph that is front-loaded with the core action and its two outcomes; every clause (restorability, review re-entry, schedule resumption, error behavior) carries distinct information. It is slightly packed with em-dash asides but not padded.

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

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

For a four-parameter mutation tool with no output schema, it covers outcomes, reversibility, side effects on schedules, and failure conditions. There is no output schema to explain, and nothing an agent needs to call it correctly appears to be missing.

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

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

Schema coverage is 100% and the action enum values are already documented in the schema, so the baseline is 3. The description nonetheless adds semantics about each action's downstream consequences (re-entry into review, schedule resumption), giving extra meaning beyond the enum labels.

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 ('Answers a correction Rebbel support proposed on one of your posts') and ties it to get_post's `proposal` field, so the agent knows exactly what triggers it. It is clearly distinguishable from siblings like approve_post and resolve_knowledge_proposal.

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

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

Gives a clear precondition ('call this once the user has picked') and routes the agent to get_post's `proposal` field to see both versions first. It does not explicitly name an alternative tool or state when-not-to-use, but the trigger condition is unambiguous.

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

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

Annotations only say it is a non-read-only, non-idempotent, non-destructive write; the description goes well beyond by disclosing the merge-not-replace semantics, that a normal re-scan can never remove findings, that forceFresh discards prior findings, and that an already-approved guide is not touched by this call. These are exactly the behavioral traits an agent needs and cannot infer from annotations.

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

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

Front-loads the core action, then numbers the two use cases in order of likely need. Some clauses (e.g. restating merge behavior in both the prose and the schema) are redundant, but every sentence carries operational weight.

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

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

A mutation tool with no output schema and three fully documented parameters; the description covers prerequisites, defaults, destructive-ish side effects, and the downstream call needed to propagate changes. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds mode-dependent meaning for brandId (recovery vs refresh) and stresses the safe default for forceFresh, plus a bare-domain hint for websiteUrl. It largely parallels the schema text, so it does not fully escape the 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 ('Re-runs the website scan') and immediately distinguishes the two modes from sibling operations like create_brand and generate_brand_guide. An agent can tell what this does and when it differs from a first-time ingest 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 enumerates two use cases with the prerequisite brand statuses ('failed' for recovery, 'active' for refresh), states when to omit websiteUrl, warns that most retries should NOT set forceFresh, and names the follow-up action (generate_brand_guide) when an approved guide must be updated. This is close to a complete routing spec.

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 by disclosing the approved-only precondition, the refusal behavior, that it never approves, the required list_connections prerequisite, and the YouTube certification requirement (a compliance constraint not expressible in annotations). Does not explicitly restate destructive/idempotent semantics, but the approval and certification context substantially compensates.

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, then conditions and routing in efficient order. The embedded verbatim compliance sentence is necessarily long but earns its place by being a required disclosure. Slightly dense with parentheticals, but no filler.

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

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

Covers preconditions (approved status, connection exists, future time), failure mode (refusal), prerequisites (list_connections, approve_post), and the critical YouTube legal/compliance certification. Complete for a mutation tool with no output schema.

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

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

Schema coverage is 100%, so the schema already documents all five parameters including the approved precondition and future-datetime constraint. The description adds the connectionId sourcing (list_connections) and confirms the approval constraint, but largely overlaps the schema. Baseline 3 is appropriate.

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

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

States a specific verb (schedules), resource (an already-approved post), and target (a connected channel at a future time). This clearly differentiates it from publish_post (immediate), approve_post (approval), and create_post (creation).

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 preconditions and routing: refuses if status != approved, directs to approve_post or the dashboard first, directs to list_connections for connectionId, and gives a YouTube-specific pre-call requirement. Covers when-to-use, when-not, and alternatives thoroughly.

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

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

Annotations cover only the safety profile (readOnly, non-destructive, closed-world), so the description carries the rest and does it well: it discloses the return shape {results:[{id,title,text}]}, the dedup behavior (identical campaigns collapsed into one row), and the non-obvious empty-result behavior (a plain note with a dashboard link rather than an empty array).

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 verb and scope, and most sentences carry distinct information (query kinds, return shape, empty case, fetch handoff). The example questions and the closing line about ChatGPT Deep Research / Claude research modes are decorative padding that slightly dilutes density.

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

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

With no output schema, the description correctly supplies the response shape and the empty-result case. It stops short of stating result-count limits, ranking, or pagination behavior, which an agent issuing a broad query would benefit from knowing.

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 a single parameter, so the schema already documents query fully. The description restates essentially the same text as the parameter description (query kinds, return shape, 'not a web search') rather than adding syntax, format, or length constraints beyond it, making the 3 baseline correct.

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

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

States a specific verb (Searches) and specific resources (this account's brands and campaigns, plus Rebbel help/pricing/setup pages), and explicitly rules out a plausible misread with 'Not a web search.' It also distinguishes itself from the sibling fetch by explaining that fetch retrieves the full record for an id.

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

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

Explicitly routes the agent to the alternative (fetch) with the condition ('Pass a result's id to fetch for the full record') and gives an exclusion ('Not a web search'). It does not, however, contrast with the many list_* siblings (list_brands, list_campaigns) that an agent might otherwise pick for browsing the same data.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: typography is derived from the brand's own website rather than generated, and the write is a literal passthrough of the font names supplied. It does not mention auth/permission needs, but for an idempotent, non-destructive setter this is close to sufficient.

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

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

Two sentences, front-loaded with the core action and the critical constraint (write exact names, don't guess). The parenthetical is dense but informative; no sentence is filler.

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

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

There is no output schema, so nothing about return values needs explaining, and annotations carry the safety profile. The description covers the one thing that could go wrong with this tool — fabricating font names — and tells the agent how to source real ones, which is everything needed to invoke it correctly.

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

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

Schema description coverage is 100% and each parameter is already documented (including 'from list_brands' and 'not a guess'), so the baseline is 3. The description's emphasis on exact, non-invented font names largely restates what the schema already says for headingFont and bodyFont, adding little new per-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 (sets a brand guide's heading and body font) and explicitly frames it as a direct write rather than a generation step, which cleanly separates it from regenerate_brand_guide_section and generate_brand_guide. The 'same way the dashboard's manual Typography fields do' anchor makes the operation unambiguous.

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

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

Gives an explicit precondition — have the correct font name in hand first — and names concrete routes to obtain it (ask the owner, or read a fresh get_brand_guide result after retry_brand_ingest). It also states a clear prohibition: never invent a font name. That is when-to-use guidance that routes the agent across sibling tools.

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

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

Annotations already declare the safety profile (not read-only, idempotent, non-destructive, not open-world). The description adds genuine behavioral context beyond that: the logo surfaces in the dashboard brand list and on future posts' images, and the call succeeds even when no brand guide exists. It doesn't state replacement/overwrite semantics for an existing logo, but the added effect disclosure is substantive.

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 input constraint, with no redundant or filler text. Every sentence contributes a distinct fact (source, prerequisite, downstream visibility, edge-case allowance).

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 full schema coverage and annotations carrying the safety profile, the description covers prerequisite, effect, and a notable edge case (no brand guide). No output schema exists, but the description conveys the observable outcome; only explicit overwrite behavior is left unstated.

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

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

Schema description coverage is 100%, so both brandId and mediaLibraryAssetId are already documented with their sources (list_brands, upload_brand_image). The description reinforces the assetId provenance but adds no format, constraint, or edge-case detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Sets a brand's logo'), names the source constraint (an existing image library asset), and distinguishes itself from the sibling upload_brand_image by clarifying the ordering relationship. An agent can tell exactly what this does versus the upload tool.

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

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

Explicitly tells the agent to call upload_brand_image first and pass its assetId here, which is the key usage sequence. It also notes the operation works without an existing brand guide, removing a potential blocking assumption. It doesn't discuss alternatives for other logo-related workflows, but the routing guidance 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 declare it is non-readonly and non-destructive but say nothing about transactionality or side effects; the description supplies all-or-nothing semantics, exact-match refusal that changes nothing, dry-run-by-default, version-conflict refusal, approval state preservation, and that consistency checking consumes generation budget. This is rich context well beyond the annotation set.

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 its scope, then layers workflow, safety and exclusions, with every sentence carrying distinct information. It is long and dense, but the length is justified given the tool's complexity; only minor tightening is possible.

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

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

For a multi-operation mutation tool with no output schema, it covers dry-run behavior, version guarding, all-or-nothing failure, approval implications, budget cost, and alternative tools. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds operational meaning: how 'match' behaves (must match exactly one line or nothing changes and nearest lines are returned), the apply/expectedVersion sequencing rationale, and the checkConsistency cost. It largely mirrors the schema's own rich field docs, keeping it below a 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 precise verb and resource ('edits specific lines of a brand guide') and enumerates the exact editable sections, operations and fields. It also names the siblings it is not (set_brand_guide_typography, set_brand_logo, regenerate_brand_guide_section), so an agent can route without opening any schema.

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

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

Gives an explicit workflow ('call it once without apply, show the owner the changes, then again with apply true'), the prerequisites (expectedVersion from get_brand_guide), and clear exclusions mapped to alternative tools. When-to-use and when-not-to-use are both spelled out.

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.