Rawa

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

Beyond the annotations it discloses the credit economics per mode (1 design / 50 credits vs. 240 for animate), the expectedCredits price-lock refusal, the 2-minute requestId retry window with no re-charge, the 1-5 minute latency, and exactly what the call returns (jobId, creditsCharged, creditsRemaining). The destructiveHint is given concrete substance, since 'replace' deletes the original's current file and that restriction (not for resize/animate) is stated.

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: the purpose and mode enumeration come first, then pricing, then the call protocol, so an agent can stop reading early for a quick call. It is dense and long, with several run-on clauses (cost, retry, permission, polling) stacked in single sentences, which costs a point on readability rather than on wasted content.

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

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

Though it has an output schema, the description still covers what matters operationally: what comes back, how long it takes, that a job panel means do not poll, and the exact follow-up call in each branch. For an 11-parameter, credit-charging, asynchronous, potentially destructive tool, 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 coverage is already 100%, so the bar for extra value is high, and the description clears it for the workflow parameters: it explains that dryRun is a quote-only call to run first, that expectedCredits must match the quoted amount or the call is refused, and that requestId must be new per request but repeated verbatim on a retry. Other parameters (aspectRatio must differ from the design's own; entityId for subject) are covered adequately by the schema itself.

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

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

A specific verb-plus-resource statement ('Redo a finished Rawa design … keeping its editable layers') that immediately enumerates the five modes (copy, graphics, subject, resize, animate), so an agent knows exactly what capability this is. It loses the top mark because it never names the closely-related siblings (resize_creative, edit_creative) that an agent must choose between for the resize and copy cases.

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 preconditions ('Works on any finished design of the brand, from list_creatives or the gallery'), the mandatory dryRun-first protocol, and the follow-up branch: use show_creatives if a job panel appears, otherwise wait_for_jobs with jobIds until allFinal. It also names the permission gate and points to get_workspace to check it, so the agent knows the fallback when generation is not allowed.

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

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

Beyond annotations, the description discloses the full cost model (50 credits per add, then 50 credits/day, search free), dryRun quote behavior including refusal cases, expectedCredits mismatch refusal, requestId retry semantics, and admin permission requirements. This is exactly the kind of behavioral context the annotations do not carry.

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

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

The description is dense and front-loaded with the main action before costs, dryRun, retries, and permissions. It is longer than typical but every sentence contributes necessary operational context for a complex mutation tool, though the single-paragraph structure could be easier to scan.

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

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

Given the tool's complexity, eight parameters, existing output schema, and mutation annotations, the description covers the critical gaps an agent needs: cost, dryRun workflow, expectedCredits guard, retry behavior, ambiguity handling, and permissions. Nothing essential for correct invocation appears 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 meaningful workflow semantics: query vs advertiserId/name candidate flow, keeping the same channel when adding a candidate, and how expectedCredits must match the dryRun quote. It does not add syntax-level details beyond the schema, but it clarifies parameter relationships well.

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: 'Start tracking a competitor's ads' on a named ad channel, and connects the result to list_competitor_ads and get_competitor_analyses. An agent can distinguish this from list_competitors or get_competitor_analyses without opening the schema.

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

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

The description gives clear operational context: use query to search by company name, handle multiple candidates by passing advertiserId and name, and use dryRun before agreeing to costs. It does not explicitly state when not to use this tool or name remove_competitor as the alternative for stopping tracking, so it stops short of the full when/when-not/alternatives bar.

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

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

Annotations already flag destructive and idempotent, but the description adds real substance beyond them: the schedule removal is permanent, the creative itself is left intact, and in-flight/published posts are out of scope. It also discloses an authorization prerequisite (admin must enable publishing over MCP) that no annotation conveys.

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

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

Front-loaded with purpose, then irreversibility, scope limit, and prerequisite in short clauses with no filler. The trailing permission sentence is terse to the point of being a fragment, which slightly hurts readability.

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

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

An output schema exists so return values need no explanation. Given a two-parameter mutation tool, the description covers permanence, side-effect scope, excluded states, and the authorization gate — everything an agent needs to invoke it safely.

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 publicationId and brandId are already documented, including the single-brand omission rule. The description adds no parameter-level detail beyond that, so the baseline 3 applies.

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

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

States a specific verb (call off/cancel) applied to a specific resource (a scheduled post) plus a scope condition (still scheduled, not yet publishing). This clearly separates it from submit_publication and list_publications 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 exclusion (already publishing or published cannot be cancelled here) and a prerequisite path via get_workspace for the admin publishing-over-MCP setting. It does not name the alternative tool to use for the published-post case, so it falls just short of full routing guidance.

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

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

Goes well beyond the annotations: it discloses cost ("Free") and, critically, the duplicate-call semantics — the same call within 2 minutes returns the existing event with deduplicated: true instead of creating a second one. That time-boxed behavior cannot be expressed by idempotentHint: false, so the description is adding genuine value rather than restating the annotation, and it does not contradict it (outside the 2-minute window duplicates are still possible).

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

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

Three short sentences, front-loaded with purpose before the scoping caveat and the dedup behavior. The one-word sentence "Free." is terse but does carry real information; slightly tighter phrasing could fold it into the prior sentence.

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?

An output schema exists and all parameters are documented, so the description only had to cover cost and duplicate-call behavior, which it does. What remains unsaid is what the returned object contains beyond deduplicated: true and whether repeated calls outside the window are safe — minor given the 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 83% and every parameter including brandId, markets and description already carries its own description, so the baseline is 3. The prose adds only a weak hint that the event "belongs to the brand," implying brandId scoping, but no format, default, or constraint detail beyond the schema.

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

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

States a specific verb and resource ("Add an event to the brand's marketing calendar") and scopes it with concrete examples (launch, promotion, campaign moment). It also delimits the resource against adjacent content ("separate from the holidays and cultural moments Rawa curates") and, by virtue of "Add", is distinguishable from list_calendar_events, update_calendar_event and delete_calendar_event.

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

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

Usage is implied by the examples of what counts as a calendar entry and by the note that it is "Free," so an agent can infer this is the cheap way to record a brand-owned moment. However, no sibling is named and there is no explicit when-not guidance (e.g., use update_calendar_event rather than re-creating, or that this does not cover holidays).

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered structurally. The description adds real value beyond that: irreversibility, the protection of curated events, and that the call is free.

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

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

Four short sentences, with the scope, the irreversibility warning, the exclusion, and the cost each stated once. Zero redundancy and no burying of the critical warning.

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

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

An output schema exists so return values need not be explained, and the annotations plus description cover the destructive profile and validity constraints. What is missing is minor: failure behavior for a nonexistent or already-deleted eventId, and no pointer to the edit alternative.

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

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

Schema coverage is 100% and both parameters carry their own descriptions, so the baseline is 3. The description only reinforces that the targeted event must be brand-owned and non-curated, without adding syntax or format detail beyond the schema.

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

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

States a specific verb and resource ('Delete ... calendar events') and narrows scope to 'the brand's own' events, explicitly excluding Rawa-curated ones. An agent can distinguish this from update_calendar_event or cancel_publication without opening the schema.

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

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

Gives a clear exclusion ('Rawa-curated events cannot be deleted') and a consequence warning ('This cannot be undone'), which is genuine when/when-not guidance. It stops short of naming alternatives such as update_calendar_event for modifying rather than removing an event.

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

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

Goes well beyond the annotations: states the 30-credit cost, mandates a dryRun-first confirmation flow, explains the expectedCredits guard, the requestId retry/dedup window (2 minutes, not re-charged), the MCP generation permission gate with wouldRefuse on dry run, the 1–5 minute latency, and the no-polling rule. These are operational facts an agent cannot infer from readOnlyHint/openWorldHint/idempotentHint.

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 before routing and cost mechanics, and nearly every sentence carries actionable information. It is long (roughly 280 words), but the length is driven by a genuinely multi-path workflow rather than padding; a tighter split of job-tracking guidance would still help.

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

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

For a costly, asynchronous, multi-source generation tool it covers sourcing, permissions, cost/confirmation, retry semantics, latency, and post-call tracking. Return fields are described even though an output schema exists, and 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 schema already documents each field and the baseline would be 3. The description adds real meaning on top: the creativeId-vs-imageUrl source choice, the sourceCreativeId/alreadyInLibrary return semantics, and the instruction to reuse sourceCreativeId rather than re-passing imageUrl.

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

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

States a specific verb and resource ('Edit a finished image from written instructions') and immediately bounds scope ('change or remove something in it, or add something to it'). It then explicitly separates itself from generate_design and adapt_design, so an agent can pick the right tool 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 alternatives keyed to conditions: text/layout on a photo → generate_design with photoCreativeId; a Rawa design → adapt_design; a pasted/attached image → request_image_upload; a local file → upload_image_file. Follow-up routing is also specified (show_creatives vs wait_for_jobs).

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 charging behavior (every design charged, cost = concepts × designsPerConcept, priced by format), dry-run quoting, expectedCredits refusal, retry deduplication within two minutes, permission requirements, and output timing. These are exactly the behavioral traits an agent needs for a costly, non-idempotent mutation with asynchronous completion.

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

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

The description is long but every sentence carries a distinct operational rule for a complex, high-cost, asynchronous tool. Purpose, photo handling, cost, retry, permissions, outputs, and polling are front-loaded in a sensible sequence 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?

Given the tool's complexity, 14 parameters, output schema, and asynchronous job model, the description covers the essential context: cost flow, dry-run requirement, retry behavior, permission checks, return shape at a high level, timing, and job-tracking alternatives. The output schema's existence means return values need not be fully restated, but the description still orients the agent adequately.

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

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

Schema coverage is 100% and the input schema already documents every parameter in detail. The description still adds cross-parameter meaning beyond the schema, especially the cost formula involving concepts and designsPerConcept, the expectedCredits refusal condition, requestId retry semantics, and photoCreativeId's exact preservation behavior.

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

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

The description opens with a precise verb and resource: generating finished, on-brand designs from a brief, one or more per concept. It implicitly distinguishes itself from generate_image by emphasizing full designs made by Rawa, and it explicitly distinguishes the photoCreativeId path where the user's photo is kept intact rather than generated.

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 operating instructions: call with dryRun first, tell the user the cost, then pass expectedCredits after agreement; use a new requestId per request and repeat only on retry. It also routes the agent correctly for job tracking: if a job panel shows, do not poll and use show_creatives later; otherwise call wait_for_jobs until allFinal is true.

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-destructive, non-idempotent write. The description adds the facts an agent actually needs: per-image pricing (30 standard / 20 fast), a 2-minute free retry window keyed on requestId, the expectedCredits mismatch refusal, and the MCP-generation permission prerequisite surfaced through wouldRefuse on a dry run.

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

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

Front-loaded with purpose and the alternative, and every sentence carries a distinct operational fact. It is dense and slightly sprawling across cost, retry and job-polling topics, but not padded; the return-value sentence overlaps somewhat with the output schema.

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

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

Covers cost quoting, the confirm-then-call sequence, idempotency/retry handling, permission failure mode, expected latency (1-5 minutes) and the two follow-up paths (job panel vs wait_for_jobs). Nothing an agent needs to invoke and follow through correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds real meaning by explaining the images array cardinality rule (one entry per distinct image, all in a single call) and how referenceCreativeIds differs from prompting from scratch, though it does not extend semantics for aspectRatio, quality or brandId beyond the schema.

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

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

States a specific verb and resource ("Generate on-brand images ... from prompts") and immediately names the excluded sibling ("Not a design: no headline, logo or layout - use generate_design for those"). An agent can distinguish this from generate_design without opening either schema.

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

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

Explicit routing rules: use generate_design for layouts, use referenceCreativeIds when the user points at existing images, one call for all requested images rather than one call per image. It also prescribes the dryRun-then-expectedCredits workflow and what to do instead of polling when a job panel appears.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is fully covered. The description contributes only a field inventory, which is largely redundant with the existing output schema; it says nothing about shape, failure modes, or whether missing sections are omitted or null.

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

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

A single tight fragment with zero filler and the content list front-loaded. It would be stronger as a complete sentence with a verb, but nothing in it is wasted.

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

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

For a simple read-only lookup with one optional, well-documented parameter and an existing output schema plus full annotations, the coverage of what data comes back is sufficient. Only the absence of sibling differentiation keeps it from a 5.

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

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

Schema description coverage is 100% and the schema already explains that brandId accepts an id from get_workspace/list_brands or a brand name and may be omitted for single-brand organizations. The description adds nothing beyond that, so the baseline 3 applies.

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

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

The fragment enumerates exactly what a caller receives (about, markets, voice, photography guidelines, colour palette, fonts, categories, logo URLs), which makes the resource unmistakable. It lacks an explicit verb such as 'returns' and never distinguishes itself from the similarly named sibling get_brand_analysis, so it falls short of a 5.

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

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

There is no when-to-use or when-not-to-use guidance at all — no mention of how this differs from get_brand_analysis, get_workspace, or list_brands. The only usage-adjacent info (omit brandId for single-brand orgs) lives in the schema, not the description.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real behavioral context beyond that: results are the *latest* analysis and come back 'one per connected account... never combined', which tells the agent to expect a fan-out rather than a merged document. It doesn't mention what a missing analysis yields or how fresh the analysis is.

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

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

A single sentence, front-loaded with the usage cue and followed by the resource description and the per-account scoping note. No filler or redundant phrasing.

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

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

An output schema exists, so return-value shape needn't be explained, and the multi-account fan-out plus optional account filter is covered. The remaining gap is edge-case behavior — what is returned when no analysis has been produced yet, or whether results are ordered/paginated.

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

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

Schema coverage is 100% and the nested account object already documents platform/accountId and the omit-for-all behavior, so the schema does the heavy lifting. The description restates the single-account case ('pass account for one') and says nothing about brandId, adding little meaning beyond structured fields. Baseline 3 applies.

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

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

The description names a specific resource — 'the latest written analysis Rawa made of the brand's marketing performance' — and frames it as 'the story rather than the numbers', which implicitly separates it from a metrics tool like get_performance_overview. It is clear what is returned, though it never names a sibling tool outright.

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

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

'Use this when the user wants the story rather than the numbers' gives an explicit selection condition tied to narrative-vs-metric intent, which is genuinely actionable. It stops short of a full when-not statement (e.g., when to prefer the numeric overview, or what to do when no analysis exists).

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

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

Annotations already declare readOnly, idempotent, and closed-world, so the safety profile is covered. The description adds some value by implying aggregation semantics: 'latest' per competitor and a 'merged' cross-signal view. It does not mention result size, freshness, or cost, but the output schema carries return-shape detail.

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

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

A single dense sentence with no filler, and the core content (latest report plus merged offer/event view) is front-loaded. It reads as a fragment rather than a complete statement, which slightly weakens its clarity.

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

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

The tool has full schema coverage and an output schema, so much of the burden is carried elsewhere. What is missing is positioning among the many competitor-related siblings; without it, an agent may pick the audience or creative-mix tool instead.

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 well documented in the schema, including defaults and cross-references to list_brands and list_competitors. The description adds nothing about how brandId, channel, or competitorId scope the report, so baseline 3 is appropriate.

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

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

The description specifies the resource precisely: the latest written report per competitor plus a merged view of offers, events, launches, and objectives. However, it is a noun phrase with no verb and does not distinguish this tool from close siblings like get_competitor_audience or get_competitor_creative_mix.

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

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

There is no guidance on when to use this tool instead of get_competitor_audience, get_competitor_creative_mix, or list_competitors. The agent must infer selection from the name 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?

With readOnlyHint, idempotentHint and destructiveHint already declared, the description still adds genuinely new context: the data is "what the ad libraries disclose, mostly for ads shown in the EU," which warns the agent about partial geographic coverage and upstream data limitations. It also discloses the aggregation default (sums all ads unless narrowed). No return shape or latency detail, but the safety profile is already covered.

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

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

The lead clause is front-loaded and states the payoff first. The middle sentence is a dense but informative metric enumeration, and the closing EU-caveat sentence earns its place by flagging a real data limitation. Slightly list-heavy, 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?

An output schema exists, so return values need no explanation, and all five optional parameters are fully documented in the schema. What remains for the description — aggregation defaults and the EU-centric source caveat — is present, so an agent has everything needed to call this correctly and interpret the result.

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

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

Schema coverage is 100% and every parameter carries a clarifying description, so the schema does the heavy lifting. The description only reinforces the default behavior for startedWithinDays and activeOnly ("unless ... narrows it"), adding marginal meaning rather than new syntax or format guidance. 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 clear subject and verb phrase ("Who the brand's competitors aim their ads at and who the ads reached") and then enumerates the exact breakdowns returned: reach and impressions per country, age/gender, Google surface, and targeting attributes. That enumeration differentiates it well from get_competitor_analyses and get_competitor_creative_mix, though no sibling is named 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?

"Sums every ad on record unless startedWithinDays or activeOnly narrows it" establishes the default aggregation behavior, which is a usage-relevant constraint. But it never says when to reach for this tool over list_competitor_ads or get_competitor_analyses, and lists no prerequisites or exclusions. Usage is inferable rather than stated.

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

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

Annotations already establish that this is a read-only, idempotent, non-destructive, closed-world operation. The description adds useful behavioral context: it aggregates across every channel the brand watches and counts every ad on record unless startedWithinDays or activeOnly narrows the scope.

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

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

The description is two tight sentences with no wasted language. It front-loads the aggregate purpose and then immediately states the default scoping behavior of the filters.

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 an output schema present, the description need not explain return values, and the annotations already carry safety and idempotency semantics. The description supplies the essential conceptual model — aggregate competitor creative mix across channels, with optional filters narrowing the ad set — which is sufficient to invoke 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 coverage is high at 80%, so most parameter meaning is already documented in the schema. The description reinforces the default counting behavior and names startedWithinDays and activeOnly as narrowing filters, but it does not add meaning for brandId, channel, or competitorId beyond what the schema provides.

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

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

The description states a specific retrieval and aggregation operation: the creative mix of a brand's competitors across watched ad channels, broken down by formats, media types, platforms, CTAs, and creative features. It is clearly distinct from list-oriented siblings like list_competitor_ads and from the individual-analysis-oriented get_competitor_analyses.

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

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

The phrase 'in aggregate' implies this is for aggregate competitor creative reporting rather than a list of individual ads, which gives some usage context. However, the description never explicitly names alternatives or states when to choose this tool versus list_competitor_ads, get_competitor_analyses, or get_competitor_audience, leaving selection to inference.

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

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

Annotations already cover read-only, idempotent, non-destructive, closed-world behavior, so the bar is lower; the description still adds real value by defining the result shape and the 'not_checked' sentinel for never-reviewed creatives. It does not say what happens if compliance is unavailable for the workspace or whether failed checks are paginated/truncated.

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

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

Two sentences, no filler, and the core identification ('compliance review of one creative') is front-loaded before the return-shape detail and the not_checked caveat.

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

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

For a two-param read with full schema coverage and an output schema, this is nearly complete; the return-value summary is arguably redundant with the output schema but aids tool selection. The only real gap is no mention of the error/unavailable case when a workspace does not run compliance reviews.

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 (fallback to brand name, omit for single-brand orgs) and creativeId (source tools) are fully documented in the schema. The description adds only the notion of 'one creative', 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 ('The compliance review of one creative') and enumerates what the response contains (score out of 100, risk level, failed checks with fixes). That is far more precise than a sibling like get_creative_insights, though it never names a sibling to contrast with.

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

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

Usage is implied rather than stated: 'where the workspace runs them' hints compliance only exists in some workspaces, and the 'not_checked' note tells the agent what a null result means. There is no explicit when-to-use/when-not guidance or pointer to an alternative (e.g., get_creative or get_creative_insights).

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 profile is covered. The description adds a useful hint about what comes back (versions plus the rendered image), but says nothing about cost, size, or failure behavior for a missing/inaccessible id.

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

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

A single front-loaded fragment with no waste; the key noun and scope come first. It is terse to the point of being slightly informal ('the picture itself'), but nothing is redundant.

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

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

With annotations covering safety, a fully documented two-parameter schema, and an output schema for return shape, the description needs only to state scope. It does that plus a brief payload hint, leaving only edge cases (unknown id, missing brand) unaddressed.

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

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

Schema coverage is 100% with both parameters documented, including the fallback behavior for brandId ('read from the id when omitted'). The description adds no parameter 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 resource (one creative by id) plus notable payload content (versions and the image itself), which distinguishes it from list_creatives and get_creative_insights. It never names a sibling explicitly, so differentiation is inferred from the 'one ... by id' scope rather than stated.

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

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

Usage is only implied: 'one creative by id' signals single-record retrieval versus the list/search siblings, but there is no explicit when-to-use or when-not-to-use guidance. The schema's creativeId note (ids come from list_creatives, search_library, get_job, get_upload) does the routing work rather than the description.

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 read-only, idempotent, closed-world safety profile, and the description earns its keep by disclosing a key aggregation behavior: results are per connected account, each on its own and never combined, with the account parameter selecting one. It also spells out the engagement-rate formula, which is behavioral context the annotations cannot carry.

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

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

The usage trigger is front-loaded and the second sentence groups the returned artifacts compactly. The prose is dense, with a long mid-sentence list and a parenthetical, but almost every clause carries information rather than filler.

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

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

An output schema exists, so return values need not be explained, and the description covers the trigger, per-account aggregation, the sibling boundary, and the engagement-rate definition. It leaves slight ambiguity about how windowDays interacts with the per-account breakdown, but overall it 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 the schema already documents platform, accountId, brandId and the windowDays default. The description reinforces the per-account scoping semantics of 'account' but adds little beyond what the nested schema description and brandId note already state. 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?

The description names a concrete payload: creative features that lift paid CTR and organic engagement, winning creatives, ad placements, and competitor/channel counts. It distinguishes itself from a named sibling by noting that get_competitor_creative_mix reads competitors' ads, so an agent can separate the two without opening either schema.

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

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

The opening clause gives an explicit trigger: 'Use this when the user asks what kind of creative works for the brand.' It also points to get_competitor_creative_mix for competitor ad content. It does not contrast with other analytics siblings like get_performance_overview or get_brand_analysis, so the routing guidance is clear but not exhaustive.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety bar is met structurally. The description adds genuine context beyond that: the brand budget is conditional ('when it has one') and the intended downstream behavior is to quote cost to the user. It stops short of noting any caching/freshness behavior, hence 4.

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

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

Two sentences: the first front-loads the return contents, the second is the actionable directive. No filler or restated title text.

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

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

An output schema exists so return shape needn't be explained, annotations cover the safety profile, and the parameter is fully documented in the schema. The description supplies the one thing structure can't: when to call and what to do with the numbers.

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 field already documents its source (get_workspace/list_brands) and the single-brand omission rule. The description adds nothing about the parameter, 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?

Enumerates exactly what the tool returns (remaining credits, plan, per-brand monthly budget and usage, per-tool credit prices) rather than restating the name. No sibling in the list touches billing, and the description makes that scope unmistakable.

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 directive: 'Call this before offering to generate anything, and quote the cost to the user.' That ties usage directly to the generation siblings (generate_design, generate_image, adapt_design) and tells the agent what to do with the result.

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

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

Annotations already declare readOnly/idempotent, so the description is free to add the traits that matter: final jobs are immutable (so re-reads are wasted calls) and finished images are returned inline as pictures the model can inspect. That is real behavioral context beyond the structured fields, not a restatement of them.

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 packed with useful detail, with no filler sentences. The long run-on enumeration of seven generator tools and the chained clauses make it slightly dense to parse, but 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?

An output schema exists, yet the description still tells the agent what the response contains (status, progress, error, media URLs, inline images) and what to do with it. Combined with the immutability rule and the sibling routing, an agent has everything needed to call this correctly on the first try.

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

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

Schema coverage is 100%, so both jobId and the optional brandId (including the 'read from the id when omitted' fallback) are already documented in the schema. The description only implicitly ties jobId to the generation tools and says nothing about brandId, 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 ("the state of a generation job") and enumerates the possible states and payload (progress counts, error, finished creatives with media URLs). It also names the exact upstream tools that produce a jobId, so the agent knows where the input comes from without opening the schema.

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

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

Explicit routing: use wait_for_jobs to block on completion, use show_creatives to display results instead of pasting URLs, and do not re-poll a final job. Each alternative is named with the condition that selects it, which is exactly the when/when-not guidance needed next to siblings wait_for_jobs, watch_jobs and show_creatives.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's remaining burden is domain behavior, which it meets: it discloses that numbers are the platform's own, that unreported rates are simply absent rather than zero, and gives the exact engagement-rate formulas for organic vs. paid. It does not discuss caching/freshness or data latency, which is the main residual gap for a metrics tool.

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

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

The trigger condition is front-loaded in the first clause, followed by the returned payload, the scoping rule, and then the metric definitions. It is dense but each sentence carries information an agent needs; the formulas are slightly heavy for a description but justify their space by preventing misreading of engagement rate.

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?

An output schema exists, so return shapes need not be explained, and the description fills the remaining gaps: what is measured, at what granularity, over what window, and how derived rates are computed or omitted. Combined with the fully described three-parameter schema, an agent can call this correctly without opening anything else.

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

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

Schema coverage is 100%, so the baseline is 3, and the description earns an increment by clarifying the aggregation semantics of 'account' — one account when passed, all accounts returned separately and never combined — which is the parameter's most consequential behavior. It adds nothing about windowDays beyond the schema's stated default of 90, and brandId resolution is already handled in the schema text.

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

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

The description states a specific verb and resource ('how the brand's marketing is doing in numbers') and enumerates the payload: KPIs with trend, reach, and top posts. It also pins the granularity ('per connected account, each on its own and never combined'), which separates it from aggregate siblings like get_brand_analysis. It never names those siblings explicitly, so the differentiation is inferential rather than stated.

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

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

The opening clause gives a clear triggering condition tied to a user intent, and 'pass account for one' vs. omitting it for every account gives concrete selection guidance. There is no explicit when-not or named alternative tool, so an agent facing an overlapping analysis request (e.g. get_creative_insights) must still reason about which to pick.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds the non-obvious context that this is bound to an in-progress panel session rather than a general resource, but says nothing about what the token represents or what the returned draft contains.

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

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

Very short and front-loaded, which is right for a tool agents should not call. But the sentence fragments awkwardly ('Internal to the Rawa TikTok panel: the post it is finishing'), spending words on identity rather than on what the tool returns.

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?

An output schema exists so return values need not be explained, but the core gap is the undocumented token and the ambiguous object being fetched. For a tool that agents are told to never call, the description still needs to be complete enough for a panel-integrated caller to know what token to pass.

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 required 'token' parameter has 0% schema description coverage, and the description never mentions it. An agent has no idea whether the token is a session id, an upload id, or a publication id.

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 phrase 'the post it is finishing' gestures at returning a TikTok draft but never states a verb or resource plainly. It does differentiate itself from siblings like prepare_tiktok_post by declaring itself panel-internal, but an agent cannot tell what it actually returns.

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?

'Never call this yourself' is an unambiguous exclusion that no sibling offers, which is exactly the routing signal an agent needs. It stops short of naming what to call instead (submit_tiktok_post or prepare_tiktok_post would be the natural alternatives), so it is not a 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds real behavioral context: the three possible link states, the processing-count semantics, and the alreadyInLibrary dedupe rule (an existing library image is reported as that creative, not a copy). No contradiction with annotations.

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

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

Three sentences, front-loaded with what the tool returns, then the dedupe quirk, then the downstream handoff. Dense but every sentence carries information; nothing is 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?

An output schema exists so return shape needs no prose, yet the description usefully flags the non-obvious alreadyInLibrary case and the link-state enum values an agent must branch on. Combined with read-only annotations and fully documented params, it is functionally complete.

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

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

Schema coverage is 100%, so both params (brandId, uploadId) are already documented, and the description largely restates uploadId's origin. The creativeId mentioned is not a parameter of this tool, so it adds no per-parameter meaning here – 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 – retrieving the upload behind a request_image_upload link – and enumerates exactly what comes back (link state, processing count, finished creatives with ids). It is clearly distinguishable from get_creative/list_creatives because it describes upload-session state rather than the creative library itself.

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?

Implies the use case (after request_image_upload, to check open/full/expired state and processing progress) and gives explicit downstream routing: take a creative id into resize_creative, edit_creative, remove_background. It lacks an explicit 'do not use X instead' exclusion against get_creative or list_creatives.

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 readOnly, idempotent, and non-destructive annotations, the description discloses the returned workspace data, permission checks for generation and publishing, remaining credits, and the single-brand behavior that affects all tools. This adds substantial behavioral context needed to interpret the connection's capabilities.

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 "Start here" and has no wasted sentences. The second sentence is dense and contains nested parentheticals, which slightly reduces readability, but every clause carries useful information.

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

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

Given that an output schema exists, the description does not need to explain return values, yet it still summarizes the key data and permission context. Annotations cover the safety profile, and the description completes the picture with workspace setup and single-brand behavior.

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

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

The tool takes zero parameters, so the baseline is 4. The description adds useful cross-tool context about brandId omission for single-brand organizations, though that note applies to sibling tools rather than this tool's own parameters.

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

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

The description states a specific bootstrap purpose and enumerates exactly what the tool returns: user identity, organization, brands with ids, credits, generation permission, and publish permission. It clearly distinguishes itself from sibling tools by positioning itself as the starting point for workspace context.

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

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

The phrase "Start here" gives explicit usage guidance for an initial call, and the note about single-brand organizations tells the agent when brandId can be omitted elsewhere. However, it does not explicitly name alternatives or when-not to use this tool versus siblings like get_brand or list_brands.

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 read-only/idempotent annotations, the description discloses meaningful data semantics: empty markets, brandVoice, or photographyGuidelines inherit the brand's values, empty ageRange/gender/language means any, and results truncate beyond limit. This adds real interpretive context for the returned audiences.

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

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

The description is compact and front-loads the domain concept of audiences. It is dense but every clause carries inheritance or truncation 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?

An output schema exists, so return structure need not be explained. However, for a listing tool the description lacks explicit operation framing and when-to-use context, leaving some ambiguity despite strong domain semantics.

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

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

Schema description coverage is 100%, so both parameters are already documented. The description adds a bit of meaning by explaining truncation relative to limit, but gives no further guidance on brandId semantics 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?

The description names the resource ("The brand's audiences") and implies retrieval through "Returns truncated", but never states the verb or operation explicitly. An agent can infer listing, yet it is not as clear as siblings like list_brands that encode the action in the name.

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

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

There is no guidance on when to use this tool versus alternatives such as get_competitor_audience or list_brands. It also does not mention prerequisites, such as when brandId can be omitted, despite that being documented only in the schema.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds real context beyond that: results are scoped to the connection's organization and filtered to brands the user can actually open, plus the one-brand omission rule. Return contents are left to the output schema, which is fine.

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, no filler: the scoping and id payload come first, then the downstream usage note. 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 parameters and an output schema handling the return shape, the description only needed to convey scope, permission filtering, and how the ids are consumed. It does all three, plus the single-brand edge case.

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

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

Zero parameters, so there is nothing to document in the schema; baseline is 4. Usefully, the description still explains how the ids it returns feed the brandId parameter on sibling tools and when that parameter may be omitted.

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

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

The description names a specific resource (the brands of the organization this connection is for, that the user can open) and states the payload (their ids). It signals a discovery/list role clearly, though it never explicitly contrasts with get_brand or list_entities, so an agent has to infer that differentiation from the names alone.

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

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

"Tools take a brandId from here; it can be left out when there is only one brand" is genuinely actionable guidance about downstream use and about the degenerate single-brand case. It stops short of stating when not to call it or naming get_brand as the alternative for full brand detail.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavior: results are sorted oldest first, the implicit default window is today through 30 days out, and over-window results are truncated rather than paged — the last point is the kind of silent failure mode an agent needs warned about.

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

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

Three sentences, no filler, and the identity of the resource is front-loaded before the defaulting and truncation rules. Every clause carries information the agent cannot get from structured fields.

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

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

With an output schema, rich annotations and full parameter coverage, the description fills the remaining gaps: ordering, default window, and truncation behavior. The one unresolved ambiguity is whether scheduled publications appear here or only in list_publications, which an agent deciding between the two would still have to guess.

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

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

Schema coverage is 100%, so all four parameters including the fromDate/toDate defaults are already documented. The description restates the default window and gestures at date narrowing but adds no format, boundary or interaction detail beyond the schema; baseline 3 applies.

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

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

States a specific verb and resource and enumerates exactly what the resource contains: the brand team's own events plus Rawa-curated holidays, seasons and cultural moments for its markets and industries. That content scope distinguishes it from the create/update/delete calendar siblings and from list_publications, which an agent could otherwise confuse it with.

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

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

Usage is only implied: the description says what happens when no dates are given and tells the agent to 'narrow the dates' when results are truncated, which is a useful remediation. But it never says when to choose this over list_publications or list_signals, nor any prerequisite for brandId beyond what the schema already states.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), so the description earns credit for the extra traits it does disclose: results are ordered newest first, page size defaults to 30 unless given, and the next page comes from nextCursor. It adds real behavioral context beyond the annotation block, though it says nothing about empty results or what happens when the brand has no watched competitors.

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 front-loaded sentence but very densely packed, spending most of its length enumerating returned fields that the output schema already declares. The pagination and ordering facts are valuable; the field list is largely redundant and pushes the sentence toward bloat.

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 an output schema present, the field enumeration is not needed, and the description leaves out the relational context most relevant to a 9-parameter tool with many competitor siblings: when to reach for this versus get_competitor_audience or get_competitor_analyses. It is adequate to call the tool correctly but not complete for selection.

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 89%, so the schema already explains each parameter thoroughly, including the brandId/competitorId omission rules and the Meta-only platform constraint. The description restates the limit default and cursor continuation without adding syntax or semantics the schema lacks, 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 ('Ads the brand's competitors are running') plus the channel scope and ordering, so the agent knows exactly what it retrieves. It never distinguishes itself from near-siblings like get_competitor_analyses, get_competitor_audience, or list_competitors, which is the one gap keeping this at 4.

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

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

Usage is only implied by the scope language ('every ad channel the brand watches them on', 'Omit for every competitor the brand watches'). There is no explicit 'use this when…' or 'use get_competitor_audience instead for…' guidance, which matters given several competitor-related siblings.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real context beyond that: the one-row-per-channel duplication rule and the fact that results are truncated past limit — both non-obvious behaviors an agent would otherwise misread.

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

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

Front-loaded with the resource, then the enumeration and the dedup caveat, ending with truncation. Slightly run-on and the fragment 'Returns truncated when there are more than limit' is awkward, but every clause carries information.

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

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

An output schema exists, so return values need no explanation, and the description covers the two things that would trip an agent: per-channel duplication and truncation at limit. Minor gap: it does not say how to retrieve the remainder once truncated (there is no offset parameter).

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

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

Schema coverage is 100%, so baseline is 3. The description earns above baseline by explaining why a company can appear multiple times (once per channel), which gives the channel filter and the row semantics meaning the schema text alone does not convey.

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 ('the competitors the brand tracks') plus the shape of each row (channel-tagged). It is distinguishable from list_competitor_ads and get_competitor_analyses by being the roster itself, though it never names a sibling to contrast with.

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

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

Usage is implied by the resource description rather than stated: an agent can infer this is the entry point for the tracked-competitor roster before drilling into ads or analyses. There is no explicit when-to-use/when-not or pointer to alternatives like list_competitor_ads.

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), and the description adds what they cannot: result ordering (newest first), the shape of each item (name plus media URL), cursor-based paging, and the pre-upload visibility caveat. Minor gap: it never says the listing is brand-scoped/requires a brand context beyond the brandId param.

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 what the tool returns and followed by the one behavioral caveat an agent would otherwise get wrong. No restatement of the title and no filler.

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

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

With six optional parameters, an output schema, and rich annotations, the description covers the essentials: scope, ordering, paging, and the notable exclusion. The remaining shortfall is guidance on the two filter parameters (assetTypes, favoritesOnly) that an agent would need to use the tool fully.

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

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

Schema coverage is 67%, above the point where the schema alone suffices but below full coverage. The description's mention of images/videos/SVGs loosely maps to assetTypes, but favoritesOnly and assetTypes have no description in the schema and get no explanation here, so the description doesn't compensate for the documented gaps.

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 verb ('list') and resource ('the brand's generated and uploaded images, videos and SVGs') are stated concretely, along with ordering ('newest first') and the fields returned ('names and media URLs'). What's missing is differentiation from near-siblings in the toolset such as search_library, show_creatives and get_creative, so an agent still has to guess which listing tool to pick.

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 second sentence gives an explicit exclusion plus an alternative path: a pasted or attached image won't appear here until it goes through request_image_upload. That is real when-not guidance routing to a named sibling, but it only covers that one edge case; there is no guidance on when to prefer this over search_library or get_creative.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety needs no restatement. The description adds genuine context beyond them: the default-fallback behavior and the empty-result case when a brand has no design systems.

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

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

Three sentences, each earning its place: definition, forward usage with default, and empty case. The forward usage — the most decision-relevant fact — is placed early.

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?

An output schema exists so return values need no explanation, leaving the description responsible only for definition, downstream usage and the empty edge case — all present. Nothing an agent needs in order to call this correctly is missing.

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

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

Schema coverage is 100% and the brandId description already explains sourcing it from get_workspace or list_brands and omitting it for single-brand orgs. The tool description says nothing about brandId and only implies the id's downstream use, so the schema carries the load — baseline 3.

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

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

States a specific resource (the brand's design systems) and defines what one is ('a full look — logos, colours, fonts, design rules'), which no sibling tool does. The agent can distinguish it from list_brands, get_brand and list_entities immediately.

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

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

Explicitly routes the result forward: pass an id as designSystemId to generate_design, generate_image or adapt_design, and states that omitting one yields the brand default. It stops just short of saying when not to call it (e.g. that it's unnecessary for a single-brand workflow already covered by get_brand).

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description still adds real context beyond them: results are paginated via nextCursor and each entity includes an image URL. It stops short of describing ordering or what missing entities mean.

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 with no filler, and the resource enumeration leads. The first sentence is a fragment, which slightly weakens the front-loading of what the tool actually 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?

With an output schema, rich annotations and full schema coverage, the description only needs to frame scope and pagination, which it does. The remaining gap is disambiguation from sibling list/search tools in a crowded namespace.

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 parameter documentation is already handled (including the ambassador/character clarification). The description's only parameter remark, 'Pass query to find them by name', echoes the schema's own query description without adding syntax or matching behavior.

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

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

Names the resource set precisely (products, places, characters/mascots, design elements) and states each item carries an image URL. However it is a noun-phrase fragment with no verb, and it does not differentiate itself from close siblings such as search_library, list_creatives or list_design_systems.

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

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

'Pass query to find them by name' gives one usage hint, but there is no guidance on when to prefer this over search_library or list_design_systems, and no when-not conditions. Usage is implied rather than stated.

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

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

Annotations already establish readOnly, idempotent, closed-world behaviour, so the lower bar applies. The description adds genuinely useful context beyond that: connection status ('active or needs reconnecting'), last-sync timing, and the important downstream effect that canPublish/publishWith determines whether and how posting can happen. It could have stated explicitly that it returns at most `limit` accounts in a single call, which is why it isn't 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 whole definition is one long sentence with layered colons and parentheticals, making it hard to scan. The most actionable instruction, checking this when data is empty, is buried at the end instead of being front-loaded. It is dense rather than bloated, but the structure needs work.

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 an output schema available, the description does not need to explain return shapes, and it still helpfully explains the non-obvious canPublish and publishWith fields. The diagnostic use case is covered. Minor remaining gap: it does not state pagination or single-page behaviour, though the limit parameter implies it.

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

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

Schema coverage is 100%, so both `limit` and `brandId` are already fully documented in the schema, including defaults and the single-brand omission rule. The description mentions the brand implicitly but adds no syntax or format detail beyond the schema. Baseline 3 is appropriate.

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

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

The definition gives a specific verb and resource ('marketing accounts connected to the brand') and enumerates the channels and returned fields, so an agent knows exactly what it gets back. It does not explicitly contrast itself with nearby list tools such as list_brands or get_brand, so it falls short of the 5 bar.

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 a concrete triggering condition: 'Check this when performance data or published posts come back empty.' That is real when-to-use guidance, especially useful for diagnosing broken connections. It omits when-not-to-use or a direct pointer to an alternative list tool, so a 4 rather than a 5.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds non-obvious behavior: results are ordered by creation time newest-first, timestamps are ISO, and status=scheduled ignores the lookback window entirely. That last point is a genuinely surprising query behavior an agent could not 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-loaded with identity and scope, then return fields, then ordering/pagination, then the alternative — every clause earns its place and nothing is repeated. The single dense paragraph reads cleanly despite carrying a lot of 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 an output schema present, the description needn't document return values, yet it still summarizes what each entry carries (channel, account, caption, format, timing, live link, failure reason). Combined with ordering, pagination, and the alternative route, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema, including the limit default, the cursor contract, and the lookbackDays/status interaction. The description restates pagination and the queue caveat rather than adding 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?

Names a specific resource (Rawa's publishing queue) with precise scope: posts scheduled or sent, by the user or via submit_publication, and enumerates the lifecycle states. It also names the sibling tool it is not (list_recent_posts), letting an agent distinguish the two without opening either schema.

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

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

Explicitly routes the agent: use this for the Rawa publishing queue, use list_recent_posts for everything on the channels with metrics. It also gives the operational rule for pagination ('follow nextCursor with the same filters') and the status=scheduled whole-queue caveat, so nothing about when/how to call it is left implicit.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds real behavioral detail beyond them: newest-first ordering, that an unreported metric is simply omitted, and that sentiment/themes only appear where Rawa has analysed comments. These conditional-presence rules are the kind of context an agent cannot get from the annotations.

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

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

Purpose and the sibling alternative bracket the description well, and it is front-loaded. However, the long enumeration of return metrics (reach, views, likes, comments, shares, saves, follows, engagement rate) largely duplicates what the existing output schema already declares, weakening the 'every sentence earns its place' test.

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 a rich output schema, full annotation coverage and 100% schema description coverage, the description only needs scope, ordering and sibling routing — all of which it supplies. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100% and every parameter (limit, brandId, platform, lookbackDays) is documented in the schema with defaults and enum values. The description adds only indirect hints — 'whoever published them' signals there is no author filter, and 'newest first' signals ordering is not parameterized — so the schema does the heavy lifting and 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 (posts synced from the brand's connected channels) with an explicit scope qualifier ('whoever published them') and ordering ('newest first'). It also names the sibling it is not (list_publications), so an agent can distinguish the two without opening either schema.

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

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

Gives an explicit routing rule: for content Rawa itself scheduled or sent, use list_publications instead. That resolves the main ambiguity with the closest sibling. It stops short of covering when-not to use it against the many other list_* tools, so it is clear context rather than full when/when-not guidance.

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

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

Annotations only say it is a non-idempotent, open-world, non-destructive write; the description adds what actually happens: no publish occurs, a panel opens, the user submits, the app delivers to the creator's TikTok inbox with status awaiting_user_action, the prepared post expires after an hour, and the call is free but gated on an admin setting. It also warns against a specific failure mode ('must not ask the user for those settings in chat').

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 and nearly every clause carries load-bearing information — permissions, fallback path, expiry, caption limit. It is a dense single block of long compound sentences, so it reads as a wall of text, but there is little outright waste to cut.

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

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

For a five-parameter, non-idempotent, open-world write with a human-in-the-loop handoff, the description covers the full lifecycle: prerequisite permissions, what the agent must not do, what happens after submission, how to check status, and what to do when the panel never appears. An output schema exists, yet the description still names publicationId, which is a bonus rather than a 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 baseline is 3, but the description adds real semantics beyond the schema: creativeId must be a video and never an image, omitting connectionId is only valid for single-account brands, scheduledAt must carry an offset and be in the future, and omitting it means immediate posting on submit. Only brandId goes unmentioned, though the schema covers it.

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

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

The opening names a specific verb and resource ('Post one of the brand's finished videos to TikTok') and the body clarifies the real action: it opens Rawa's TikTok panel where the user submits. It differentiates from submit_publication explicitly. However, the claim 'there is no tool for it' sits awkwardly against the sibling submit_tiktok_post, which an agent will see in the tool list, creating a moment of doubt about which path publishes.

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 prerequisites (admin must allow publishing over MCP, see get_workspace), a pre-call ritual ('Confirm the video, caption and time with the user before calling'), sibling routing (list_integrations, write_caption, list_publications, get_workspace), and a when-this-fails branch pointing at openInRawaUrl. Nothing about selecting or invoking this tool is left to inference.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false, but the description adds substantial operational context: cost of 30 credits, dryRun quoting, expectedCredits refusal guard, requestId retry window, generation-allowed prerequisite, returned jobId/credits, 1–5 minute readiness, and job-panel versus wait_for_jobs behavior. It does not contradict the annotations.

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

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

The description is long but front-loaded and dense with operational rules rather than filler. Every major sentence carries a distinct instruction, though the volume is high for a single description and could be tightened slightly without losing meaning.

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

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

For a complex mutation with cost, credit guards, source-routing alternatives, and asynchronous job handling, the description is complete. Since an output schema exists, it appropriately does not spend space explaining every return field, but still mentions jobId, creditsCharged, creditsRemaining, and sourceCreativeId metadata needed to continue the workflow.

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 each parameter. The description still adds meaningful cross-parameter semantics beyond the schema: imageUrl must be a direct public JPEG/PNG/WebP URL, requestId must be new per generation and repeated only on retry, and expectedCredits must match the quoted dry-run amount to avoid refusal.

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: cut the background out of a finished image, leaving a transparent PNG. It explicitly distinguishes among source types (brand creative, public image URL, chat attachment, local filesystem) and names the sibling tools to use for each, so an agent can route correctly without opening another schema.

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

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

Provides explicit when-to-use guidance and alternatives: use request_image_upload for pasted/attached chat images, upload_image_file for local filesystem images, and reuse sourceCreativeId instead of imageUrl for already-linked images. It also prescribes the dry-run-then-confirm workflow and the retry/idempotency behavior, leaving little to inference.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is known. The description adds genuinely useful context beyond that: the concrete effect (ads leave the brand's competitor feed), the irreversibility of spend (credits not refunded), and that removal itself costs nothing.

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, then consequences, then cost. No filler and no repetition of schema or annotation content.

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

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

An output schema exists so return values need no explanation, and annotations cover destructiveness and idempotency. The description fills the remaining gap – what is actually lost by removing – though it doesn't say whether re-adding later re-incurs cost.

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

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

Schema description coverage is 100%, with both brandId and competitorId already documented including sourcing (get_workspace, list_brands, list_competitors) and the single-brand omission rule. The description adds nothing about parameters, 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 combination ('Stop tracking a competitor') that clearly separates it from its sibling add_competitor. It doesn't name the sibling, but the pairing is unambiguous in context.

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

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

Usage is implied by the semantics of 'stop tracking', and 'Free' hints there's no credit cost to removing, but the description never states when to prefer this over alternatives or what prerequisites exist (e.g., needing a competitorId from list_competitors).

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 non-destructive, idempotent, closed-world mutation, so the safety profile is covered. The description adds one genuinely new trait — 'Free', i.e. no credit cost — but says nothing about whether the original generated title is retained or whether renames propagate to existing publications.

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

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

Two sentences, front-loaded with the action and the rationale, with the cost note isolated as a one-word sentence. No filler or restatement of the schema.

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

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

An output schema exists and all parameters are documented, so return values and inputs need no prose. The only real gap is the missing routing versus edit_creative for a tool set with many overlapping creative-mutation siblings.

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

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

Schema description coverage is 100%, with each of the three parameters documented including sourcing hints ('from list_creatives, search_library, get_job or get_upload') and the single-brand omission rule for brandId. The description adds nothing beyond that, 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 ('Rename a creative in the Library') plus the outcome ('findable by name instead of by its generated title'), so the effect is unambiguous. It does not differentiate from the closest sibling, edit_creative, which an agent could reasonably confuse this with.

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

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

The stated motivation (findability by name vs. generated title) implies when to use it, but there is no explicit when-not or named alternative such as edit_creative or tag_creative. The agent must infer the boundary from sibling names 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?

Adds substantial behavioral context beyond the annotations: the upload is free, the link expires after an hour, the panel reports each creativeId as images land, and an already-owned image lands as an existing creative. It also explains what the agent should do when no panel appears. None of this contradicts the annotations.

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

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

The opening imperative is front-loaded and nearly every sentence carries operational value. The single dense paragraph is long, but the length is justified by the multi-step upload workflow and fallback behavior.

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

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

Given the complexity, annotations, and output schema, the description covers the important cases: attached-image detection, immediate invocation, brand choice, panel versus URL fallback, creativeId reporting, maxImages, expiry, and cost. No critical agent decision is left unaddressed.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds useful meaning for brandId by explaining how to infer the brand from the conversation or image and when asking is appropriate, and it reinforces maxImages via the link capacity and one-hour expiry.

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

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

States a specific action and resource: request image upload by opening a panel or sending an upload URL so an attached image reaches Rawa. It clearly distinguishes this from searching the brand library and from the agent trying to read the attachment itself.

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

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

Explicitly says to call immediately when the user has pasted/attached an image and wants Rawa to act on it, and says not to ask the user to re-attach or confirm. It also names the fallback path: send uploadUrl and call get_upload with the uploadId, plus clear brand-selection rules.

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, and the description adds substantial operational context: exact credit costs, dryRun quoting, expectedCredits refusal behavior, requestId retry semantics, jobId returns, 1–5 minute readiness, and generation-permission checks via get_workspace. There is no contradiction with readOnlyHint=false, openWorldHint=true, idempotentHint=false, or destructiveHint=false.

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

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

The purpose is front-loaded, and most sentences carry useful information, but the description is extremely long and dense as a single block. It would be easier to scan with clearer separation between purpose, source rules, cost, and job handling.

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

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

For a complex, multi-modal generation tool with cost and retry semantics, the description covers everything an agent needs to call it correctly, including source selection, sizing rules, dry-run pricing, expectedCredits, and post-call job handling. The presence of an output schema does not leave any material 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 already documents each parameter and its enum values. The description adds valuable cross-parameter semantics beyond the schema: platform alone vs. aspect-ratio plus placement, video restrictions on sizes/format, and sourceCreativeId reuse for linked images. Some of this duplicates the schema, preventing 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?

The description names a specific verb and resource (resize an image or video) and explicitly distinguishes Rawa's generative re-framing from cropping, stretching, or letterboxing. It also differentiates image, clip, and Motion ad behavior so an agent can tell this apart from siblings like edit_creative or generate_image.

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

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

It gives explicit when-to-use guidance ('Use this whenever the user wants an image or a video resized, adapted or fitted...') and a clear exclusion ('do not resize the pixels yourself'). It also routes edge cases to specific siblings: pasted images to request_image_upload, local files to upload_image_file, and videos only from the library via creativeId.

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), and the description adds real context: semantic search only exists in some workspaces, results mirror list_creatives' fields, and output is truncated when matches exceed limit. The one gap is that truncation is disclosed without saying how to retrieve the remainder beyond raising limit.

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

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

Three sentences, no filler: capability first, then the positive use case, then the exclusion and its alternative. Each sentence changes agent behavior, and the routing-critical constraint is stated plainly rather than buried.

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

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

With an output schema present, return values needn't be detailed, and annotations cover safety; the description fills the remaining needs (capability variance, truncation, sibling routing). Only the undescribed assetTypes filter leaves a small hole for a four-parameter tool.

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

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

Schema coverage is 75%, so the schema already documents limit, query, and brandId. The description still adds meaning the schema lacks: that query matches both name/title and visual content, the latter only where semantic search is enabled — a distinction that changes how an agent should phrase queries. assetTypes remains undescribed in both places.

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

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

States a specific verb and resource (find creatives in the brand's library) and names both search modes: filename/title matching and, conditionally, semantic visual matching. It also distinguishes itself from list_creatives (same return shape) and request_image_upload, so an agent can route correctly without opening a schema.

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

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

Gives an explicit when-to-use (locate an existing creative before generating a new one, when the user asks for something they already own) and an explicit when-not (an image pasted/attached in chat is not in the library — call request_image_upload instead). This is the strongest possible routing guidance.

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

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

Annotations already declare the write, idempotent, and non-destructive profile, so the bar is lower. The description adds genuine context beyond them: favorites are per-user scoped (not workspace-wide) and the operation consumes no credits, which affects whether an agent should worry about cost. What is missing is whether unfavoriting is reversible/persistent or any per-user auth implication.

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, then scope, then cost. Nothing is redundant and each sentence contributes distinct information.

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

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

With an output schema present, return values needn't be explained, and annotations plus 100% parameter coverage carry the rest. The only soft spot is the absence of guidance on the per-user/permission implications of favoriting on someone else's behalf, which is minor for a low-risk toggle.

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 creativeId, brandId, and favorite are already fully documented with sourcing hints. The description's 'or unmark it' reinforces the boolean semantics but adds no sourcing 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 and resource ('Mark a creative as one of the user's favorites, or unmark it') and clarifies the set/unset duality that the name alone doesn't convey. It implicitly separates itself from sibling mutators like tag_creative or rename_creative by naming the Favorites concept, though it never explicitly contrasts with those siblings.

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

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

'Favorites are per person and show in the Library's Favorites view' implies when to use it (curating a personal shortlist visible in that view) and 'Free' signals no credit cost. There are no explicit when-not conditions or named alternatives such as tag_creative for organizational categorization, so usage is inferred rather than directed.

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: 30-credit cost, the dry-run/quote/confirm protocol, refusal on credit mismatch, requestId retry semantics with a 2-minute no-charge window, the generation-allowed-over-MCP prerequisite with wouldRefuse behavior, and 1-5 minute readiness. Annotations only say it is a non-read-only, non-idempotent, non-destructive operation; the description supplies the operational and financial consequences.

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

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

Purpose is front-loaded and every sentence carries operative information, but the single dense paragraph bundles routing, cost, retry, gating and polling rules without line breaks, making it 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 paid, asynchronous, gated generation tool with an output schema, this covers everything an agent needs: input-source routing, cost confirmation, retry identity, refusal conditions and what to do while the job runs. The output schema already documents returns, and the description still names jobId, creditsCharged and creditsRemaining as a convenience.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics: expectedCredits must match the quoted amount or the call is refused, requestId must be new per request and repeated only on retry, and sourceCreativeId should be reused rather than re-passing imageUrl. That is meaningfully more than the field docs alone.

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 ('Improve a finished image's detail, sharpness and clarity') and immediately distinguishes the outcome ('The result is a new version of it'). It is clearly separable from siblings like remove_background, resize_creative and generate_image without opening a schema.

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

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

Explicitly routes between the three input paths: creativeId for library creatives, imageUrl for public web files, request_image_upload for chat attachments (with 'do not ask them to re-attach it'), and upload_image_file for local files. It also prescribes the dryRun-then-expectedCredits flow and the wait_for_jobs vs job-panel branch, leaving nothing to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely new behavioral context: the viewer is what the user actually sees, so the agent must follow up with one short line and must never paste URLs or markdown images. That post-invocation contract is not inferable from any structured field.

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 what the tool does, then when to call it, then the required post-call behavior. Every sentence carries a distinct, actionable instruction 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 one-parameter display tool with an output schema, an agent needs purpose, trigger, id source, and follow-up behavior — all four are present. Nothing material is left to inference.

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

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

Schema coverage is 100% and the single parameter already documents the 1-24 range, ordering, and valid id sources (list_creatives, search_library, get_job, get_upload). The description's mention of 'a finished job's results (its creative ids)' largely restates the schema, 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 and resource ('Show creatives to the user in the chat') and immediately clarifies the mechanism — Rawa's viewer renders each at its own shape with download, open and full-screen buttons. This clearly separates it from retrieval siblings like list_creatives, search_library and get_creative, which return data rather than display 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?

'Call this whenever the user wants to see creatives' gives an explicit trigger, and it enumerates the upstream sources whose output feeds it (finished job creative ids, list_creatives, search_library). It doesn't state a when-not or contrast case explicitly, but the trigger and source routing are strong enough that an agent can select it confidently.

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 this is a non-read-only, open-world, non-idempotent write; the description adds substantial context beyond that: no credit cost, an admin must enable MCP publishing, a 2-minute dedupe window keyed on requestId, refusal when a requestId is reused with different arguments, and a hard failure when the creative's aspect ratio does not fit the format with resize_creative as the remedy. These are exactly the operational traits an agent cannot get from the annotations.

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

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

The core action and the immediate-vs-scheduled rule are front-loaded, and essentially every sentence carries non-redundant information. It is dense, however, with several independent rules packed into long sentences, so an agent must parse carefully rather than skim a short list.

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

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

For an 8-parameter, open-world write with real side effects, the description covers preconditions (admin allowance), input sourcing, scheduling semantics, retry/idempotency behavior, format selection, caption rules and a concrete failure mode. An output schema exists, so the absence of return-value explanation is not a 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 baseline would be 3, but the description adds genuine meaning: scheduledAt must be a future ISO 8601 timestamp carrying its offset (with worked examples), format is normally inferred from channel + creative and should only be passed to override, and caption is mandatory for every format except a story. It does not restate requestId's schema text in more depth than the schema already does, which keeps 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 specific verb and resource ('Post one of the brand's creatives to a connected channel, publicly') and immediately separates immediate vs scheduled publishing. It explicitly carves out TikTok to prepare_tiktok_post, so an agent can distinguish it from submit_tiktok_post, cancel_publication and list_publications without opening a schema.

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

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

Gives explicit when-not guidance ('Not for TikTok... call prepare_tiktok_post'), a user-confirmation requirement before calling, and the decision rule between connectionId and platform. It also names the upstream tools that supply each argument (list_integrations, get_workspace, list_creatives), leaving little to inference.

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