Revup

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=true and openWorldHint=true, covering the safety profile. The description adds useful failure semantics ("Missing types fail without creating anything") and idempotency guidance ("Reuse the same idempotency key for retries"), plus survey default behavior, but does not disclose permission requirements or creation side effects beyond what annotations imply.

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 run-on block of loosely related sentences, several of which are cryptic ("Uses normal dashboard availability and optional structured edits", "No AI generation"). Key routing/failure info is buried mid-paragraph rather than front-loaded, wasting the reader's attention.

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 tool (6 params, nested 50-op batch, no output schema), the description covers failure and type-discovery edge cases but omits what a successful creation returns and how the operations batch interacts with creation. The rich schema and response_mode parameter carry much of the load, so the description is adequate but not complete.

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

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

Schema description coverage is 67%, so much is already documented in the schema. The description adds only marginal meaning: the values.type fallback for cached clients and idempotency-key reuse. It gives no guidance on the operations structure or schedule 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?

States a specific verb and resource ("Create an ... available promotion type") and gives type-specific behavior for surveys. It is distinguishable from duplicate/update/validate siblings, but the purpose is slightly muddled by discursive asides like "Uses normal dashboard availability and optional structured edits."

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 conditional context: purchase integration and instant-win allocation require dashboard setup, and if cached discovery lacks a type, use the first content/set operation with values.type. However, it never explicitly contrasts with sibling tools (duplicate_promotion, validate_promotion) or states when-not to use this tool.

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

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

With annotations already declaring destructiveHint=true and idempotentHint=true, the description adds real behavioral value: exactly which artifacts are excluded (participants, results, integrations, language variants, sends), fail-safe handling of unsupported fields and unavailable images, and the invalidation rule when the source changes. It omits permission/auth requirements and what 'queue' returns, keeping it short of a 5.

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

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

Three dense sentences with zero filler: the operation, the exclusion list, and the failure/invalidation behavior, each front-loaded and independently useful. Nothing repeats the schema or annotations.

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

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

For a mutation tool covered by annotations and with no output schema, the description addresses copy scope, failure modes and source invalidation well. Gaps remain around the mutating inputs (expected_revision, the source promotion_id) and whether the queued operation returns a handle for get_operation_status.

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 only 20%, so the description must carry the load and largely does not. 'New dates' gestures at schedule, but promotion_id (the source), expected_revision (optimistic concurrency token), name, and idempotency_key receive no explanation, leaving an agent to guess at revision and idempotency semantics that the description implies but never states.

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

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

States a specific verb and resource: 'Queue a bounded configuration copy with new dates.' The word 'bounded' plus the enumeration of what is not copied cleanly separates this from create_promotion and update_promotion, 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?

The copy scope implies the intended use case (spinning up a similar promotion on a new schedule), but the description never says when to prefer this over create_promotion or update_promotion, nor what prerequisites exist. 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds the useful scope note that the read returns permissions and supported operations, but says nothing about freshness, caching, or whether results vary by credential — modest added value on top of 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?

A single sentence with no filler, leading with the operation and listing the three things read. Every word earns its place.

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

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

With no input parameters and no output schema, the description's job is to say what the call surfaces, and it names the account, allowed permissions, and supported operations. That is adequate for a zero-arg read, though it stops short of describing the shape or granularity of those capabilities.

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

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

The tool takes zero parameters, which is the baseline-4 case. The description's enumeration of account/permissions/operations is return-value information rather than parameter semantics, so there is nothing further for it to clarify.

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 pairs a specific verb ('Read') with a concrete resource ('the connected account, allowed permissions and supported operations'), so an agent immediately knows this is an account-introspection read. It does not explicitly contrast itself with any sibling, but the domain (account capabilities vs. the promotion/asset tools) is self-evidently distinct.

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 statement of when to call this tool, what precondition it satisfies, or which sibling to use instead. An agent must infer that it is a discovery/preflight call. No exclusions or alternative routing are provided.

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

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

Annotations already establish readOnly, idempotent, non-destructive, closed-world semantics, so the bar is low. The description adds genuinely useful context beyond them: the precondition that only complete R2 images are attachable, and the disclosure that temporary source URLs and provider errors are never surfaced in the response.

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

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

Three short sentences, front-loaded with the core action. The two trailing sentences are relevant behavioral context rather than filler, though they could be tightened.

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

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

With no output schema, the description should describe what a status response contains (e.g., import progress or completion states). It tells the agent what is never returned but not what the status actually reports, leaving a real gap for a status-polling 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?

The single parameter asset_id has 0% schema description coverage (type integer, minimum 1 only). The description says the asset is "owned" but never explains what an asset ID is, where it comes from (e.g., returned by import_image), or what form it takes, so it does not compensate for the schema gap.

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

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

The description states a clear verb and resource ("Read the owned asset status"), and the title narrows it to image import checking. It does not, however, differentiate itself from sibling get_operation_status, which an agent could plausibly reach for instead.

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

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

"Only complete R2 images may be attached" is a downstream constraint, not guidance on when to call this tool versus list_assets, get_operation_status, or import_image. There is no when-to-use, no polling advice, and no mention of alternatives.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds one genuinely useful behavioral fact - that failure responses carry recovery guidance - but says nothing about job lifecycle, completion states, or latency/polling behavior.

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

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

Two short sentences with the core purpose front-loaded and no padding. The second sentence is terse to the point of ambiguity, but the overall size is appropriate for a simple polling tool.

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

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

With no output schema, the description carries the burden of describing the return shape, and it does so only obliquely ('duplication progress', 'failure details'). It is adequate for a one-parameter read tool but omits the linkage to duplicate_promotion and any notion of completion state.

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

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

Schema description coverage is 0% and the single parameter job_id is documented only as an integer with minimum 1. The description never explains what job_id identifies or where the caller obtains it, so it fails to compensate for the coverage gap.

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

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

The description states a specific verb and resource ('Read ... duplication progress') plus a scope qualifier ('account-scoped'), so an agent knows it is a status/read tool rather than a mutation. It does not, however, name or contrast itself with the sibling that actually starts the work (duplicate_promotion), so sibling differentiation is left to inference.

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

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

There is no when-to-use guidance: nothing says the job_id originates from duplicate_promotion, whether this should be polled repeatedly, or when to stop polling. The agent is given no condition that selects this tool over get_asset_status or get_promotion.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds the useful scoping constraint that participants are not exposed and nothing is published, but it says nothing about pagination behavior despite limit/cursor parameters, nor about the cost of fetching a full promotion.

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 the read operation front-loaded and no filler. It is appropriately tight, though given the undocumented parameters it is arguably too terse rather than too long.

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

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

A four-parameter tool with zero schema coverage and no output schema, yet the description explains neither the section selector, the limit/cursor paging, nor what the returned promotion data looks like. The negative boundaries are helpful but insufficient to call this correctly with confidence.

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

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

Schema description coverage is 0% across all four parameters, so the description carries the full explanatory burden — and it names none of them. The section enum (content, rules, security, design, prizes, quiz, etc.) and the limit/cursor pagination contract are entirely undocumented, leaving an agent to guess that sections are selectively fetchable.

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?

"Read the saved promotion details" gives a specific verb (read) and resource (saved promotion), and the word "saved" implicitly contrasts with preview/render siblings that operate on unsaved drafts. It stops short of naming which sibling to use when, but an agent can identify the tool's core operation.

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

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

The description implies usage (fetch a promotion by its id) and adds two negative boundaries — it does not expose participants and does not publish. However it never states when to pick this over list_promotions, get_promotion_report, or preview_promotion, and gives no prerequisites. Adequate but leaves the alternative-selection decision to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false, destructiveHint=false, so the safety profile is fully covered structurally. The description adds some constraint context (no identities, no raw URL paths, no causal inference) but is disorganized and provides no clarity on freshness limits, rate limits, or what the return actually looks like beyond a fragmentary list.

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 fragmented, comma-spliced utterances with no clear subject or verb. The information is front-loaded but poorly organized and difficult to parse as a coherent instruction.

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

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

For a 4-parameter tool with nested objects, no output schema, and no annotation guidance, the description is markedly incomplete. It gestures at output shape and privacy constraints but does not provide the parameter or usage information an agent needs to invoke it correctly.

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

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

With 0% schema description coverage and 4 parameters (including nested period/comparison objects and an enum breakdown), the description is the only source, yet it mentions only periods, timezone, and filters vaguely. It never explains promotion_id, the breakdown enum values, or the comparison object semantics.

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

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

The description describes what the report contains (aggregate metrics, denominators, dates, timezone) but never states a clear verb+resource like 'read promotion performance metrics.' It reads more like a list of output characteristics than a purpose statement, leaving the agent to infer the tool fetches a report from the name alone.

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

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

No guidance is given about when to use this tool versus siblings. It never references get_promotion, preview_promotion, get_promotion_schema, or any other tool, so the agent has no routing signal.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so "No mutations" restates what is already structured. The description adds that the result covers settings and catalogs (the payload shape), which is useful, but it omits anything about permissions or response structure.

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

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

Two short sentences with the action and the workflow context front-loaded. The second sentence, "No mutations," is redundant with the annotations and does not earn its place, but the brevity overall is a strength.

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

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

There is no output schema, so the description carries the burden of describing what comes back. "Allowed settings and catalogs" is suggestive but vague for a 16-section discovery tool — an agent cannot tell whether it gets allowed enum values, field lists, or full configs.

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

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

There is one parameter (section) with 0% schema description coverage, so the description bears the burden — yet it only says "a section" without clarifying what a section selects or why settings differ per value. The 16-value enum is self-explanatory enough to keep this from falling lower, but the description adds little.

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

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

States a concrete verb and resource: reading allowed settings and catalogs for a section. It is distinguishable from data-fetching siblings like get_promotion because it frames itself as a discovery step tied to editing, though it never names those siblings 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?

Gives a clear usage trigger — call this before editing a section — which tells the agent where it fits in the workflow. It stops short of naming alternatives (e.g., get_promotion) or stating when this call is unnecessary.

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

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

Adds real operational constraints beyond the annotations: a 5 MiB download cap, validated PNG/JPEG/WebP/GIF bytes, and a 40-million-pixel ceiling, plus the required post-import polling step and retry semantics. It does not explain what the destructiveHint=true annotation implies about the account library, which is the one behavioral gap left.

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

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

Five short sentences, each carrying distinct information (purpose, input form, scope caveat, limits, follow-up, retry). The purpose is front-loaded and nothing is redundant with the schema or annotations.

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

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

For a two-parameter import with nested file object and no output schema, it covers input form, validation limits, the follow-up polling call, and retry behavior. It stops short of saying what the call returns immediately (e.g., an operation/asset handle), which would fully close the loop for an agent.

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

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

With only 50% schema coverage, the description compensates by clarifying that `file` is an actual file descriptor rather than a sandbox path, and by tying mime_type/size constraints to the accepted formats and limits. The idempotency_key semantics are already spelled out in the schema, so no credit is lost there.

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

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

States a specific verb and resource ('Import a user-uploaded or client-generated image into the connected account library') and explicitly disambiguates the scope by noting 'Revup does not generate content', separating it from render/preview siblings. An agent can identify this as the ingestion entry point 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 concrete operating instructions: 'Supply the actual file descriptor, never a sandbox path', 'Poll get_asset_status before attaching', and 'Reuse the identical payload and idempotency key for retries'. It names a sibling for the follow-up step, though it never states when NOT to use this tool or what alternative exists for non-image assets.

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

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

Annotations already declare the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=false), so the description's job is lighter. It usefully adds that only 'ready' assets are returned and that IDs are stable references. It says nothing about pagination behavior despite exposing limit/cursor, so it adds some but not rich context.

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

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

A single front-loaded sentence with zero filler; the resource and its purpose come first. It is efficiently worded, though its brevity borders on under-specification rather than tightness.

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?

This is a cursor-paginated list tool with no output schema, so the description should explain the return shape and how to page. It instead stops at 'stable IDs', leaving the agent without enough to call or iterate the tool confidently.

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

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

Schema description coverage is 0% and both parameters (limit, cursor) are bare integers/strings in the schema. The description never mentions pagination, page size, or how the cursor is obtained and reused, so it fails to compensate for the documentation gap.

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

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

States a specific verb and resource ('List ready account library images') with a clear qualifier ('ready') and a downstream purpose ('for promotion editing'). It does not, however, differentiate itself from siblings such as get_asset_status or import_image, which an agent must sort out on its own.

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 explicit when-to-use guidance, no when-not guidance, and no named alternative. The phrase 'for promotion editing' hints at context but never says why an agent would pick this over get_asset_status or list_promotions.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds two facts the annotations do not carry: results are paginated, and output is filtered by consented promotion restrictions. It stops short of explaining page size behavior or what happens when consent restricts everything.

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, front-loaded with the action and scope, with no filler. The second sentence is slightly vague in its phrasing ('consented promotion restrictions') but is not padded.

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

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

For a search tool with three undocumented optional parameters, no output schema, and no description of the query field or pagination mechanics, the description leaves real gaps. An agent knows what the tool returns at a high level but not how to drive its filtering or paging 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 0% for three parameters (limit, query, cursor), so the description must carry the burden and does not. The word 'paginated' weakly hints at cursor usage, but nothing explains what 'query' matches against (name, ID, status?) or that 'limit' caps at 50.

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 ('Find') and resource ('promotions') plus scope ('in the connected account'), which cleanly separates it from the singular get_promotion sibling. It does not, however, explicitly distinguish itself from list-like siblings such as list_assets or the write-side promotion tools.

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

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

There is no guidance on when to use this versus get_promotion, get_promotion_report, or preview_promotion, and no stated prerequisites or exclusions. The only context given is that results are paginated and filtered by consent restrictions, which describes output shape rather than tool selection.

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

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

Annotations already establish readOnly, idempotent and non-destructive behavior, and the description adds real context beyond them: the preview reflects the latest saved state, submissions are marked as tests, and no revision-bound browser URL is produced. That last point is valuable scoping behavior the annotations cannot convey.

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

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

Three short sentences, front-loaded with what is returned, then the two behavioral constraints. No filler, though the 'No revision-bound browser URL' clause is terse enough to be slightly cryptic without elaboration.

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

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

With no output schema, the description does well to name the returned artifacts (standard preview, public and share links), and annotations cover the safety profile. It falls short on the two undocumented input parameters, especially expected_revision, leaving a gap an agent would hit when calling the tool.

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

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

Schema description coverage is 0% and the description never explains promotion_id or the sha256-pattern expected_revision, even though the latter is a non-obvious optimistic-concurrency token. The phrase 'No revision-bound browser URL' gestures at revision semantics but does not tell the agent what expected_revision does or when to supply 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 description states a specific verb (Return) and resource (the standard preview, public and share links) for a saved promotion, so an agent can tell this is a read/preview operation. However, it never differentiates itself from the sibling render_preview, which is the most likely confusion point.

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: 'Preview always shows the latest saved promotion' and 'No revision-bound browser URL' hint that this is the non-revision-pinned preview path, but no alternative tool is named and no explicit when-to-use condition is given. An agent must infer the choice against render_preview.

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, open-world. The description adds genuinely new behavioral context: that CAPTCHA is not solved (a hard limitation), that the image is tied to the revision actually served, and that no entries/messages/payments occur. That is real value beyond the annotations.

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

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

Four short sentences, front-loaded with the core action and constraint, with no filler. Slightly choppy but each sentence 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?

For a read-only, two-parameter tool with full annotation coverage and no output schema, the description covers the essential caveats: side-effect profile, CAPTCHA limitation, and revision semantics. It could say more about the returned image format, but nothing critical 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 0%, so the description carries the load. It does explain the viewport enum values ('desktop or mobile') and implies the screenshot is of the promotion identified by promotion_id, but it adds no format, sizing, or identity details beyond that.

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: 'Return a desktop or mobile screenshot of the standard test preview.' The viewport options and 'tied to the revision actually served' scope it further. It does not, however, distinguish itself from the sibling preview_promotion, which an agent must choose between.

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?

'Compare the image against the requested design' implies the review use case, and 'standard test preview' hints at scope. But there is no explicit when-to-use or when-not, and no routing versus preview_promotion or validate_promotion.

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

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

Goes well beyond the annotations by disclosing side effects the hints cannot convey: the report is stored in Revup, a Slack notification goes to the Revup team outside the connected account, the response includes a feedback_id, and promotions are not modified. It also states the secret-handling policy (no passwords, tokens, or personal data), which is exactly the kind of guardrail that prevents harmful invocations.

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

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

The purpose is front-loaded in the first clause, then triggers, then required payload, then privacy warning, then side effects. Six sentences, all carrying distinct information, with no restatement of the title or name.

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

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

For a write tool with no output schema, the description supplies the missing pieces: what gets persisted, the external notification, the returned feedback_id, and the non-mutating scope. The only omission is promotion_id, which is a minor parameter-level gap rather than a barrier to correct invocation.

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

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

With only 40% schema description coverage, the description usefully compensates for three of the five parameters: it defines what a good 'note' contains, tells the agent where to source 'request_id' (from the error response), and says to include 'tool_name' when available. 'promotion_id' is never mentioned in either place, leaving a genuine gap, so it falls short of 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 ('Report a Revup bug, confusing behavior, or a missing capability to the Revup team') and enumerates what counts as reportable. This is unmistakably distinct from the promotion CRUD/read siblings, so an agent can select it 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 trigger conditions ('when a tool errors unexpectedly, returns something that looks wrong, or cannot do what the user asked') plus an explicit gate ('call it only when the user wants to report it'), which correctly prevents the agent from filing unsolicited reports. No sibling alternative is named, but none is applicable since nothing else in the toolset reports feedback.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, but the description adds material context beyond them: omitted values survive (merge, not replace), a theme replaces all colors (a specific destructive side effect), changes hit the public promotion immediately, and retry keys must be reused verbatim. It also mandates user confirmation for high-stakes term changes, which annotations cannot express.

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

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

Dense but front-loaded: the core action comes first, then merge semantics, then the confirmation obligation, then retry rules. Every clause carries operational information; nothing is filler.

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

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

For a destructive mutation with no output schema, it covers the essentials agents need: schema pre-read, merge behavior, immediate public effect, confirmation requirement, and idempotency/retry rules. The remaining gap is expected_revision handling, which is left to the bare schema pattern.

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

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

With 60% schema description coverage, the description adds real meaning: merge semantics for omitted values, the theme-replaces-colors rule, and that operations are ordered/narrow. It does not, however, explain expected_revision's optimistic-concurrency role (schema gives only a pattern), which is the parameter most likely to cause a failed call.

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

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

Specific verb+resource: 'Apply narrow ordered changes to a promotion, including public promotions.' It distinguishes this tool from create_promotion/duplicate_promotion by emphasizing narrow ordered edits rather than creation or copying, and it clarifies that live public promotions are in scope.

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 directive to 'Read its schema first' (i.e., get_promotion_schema) and spells out a when-to-act condition: show the user the exact change and get explicit confirmation before altering prize, Official Rules, or start/end dates on a promotion accepting entries. It stops short of naming sibling tools explicitly or excluding cases (e.g., when to prefer validate_promotion or preview_promotion).

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds real value by clarifying that the output is advisory (warnings) and that nothing is repaired, but says nothing about how the issues are produced or returned.

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

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

A single front-loaded sentence with no filler. It is efficient, though the terseness comes partly at the cost of missing scope detail.

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

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

With no output schema, the description usefully signals that the return is a set of advisory issues and warnings. However, for a tool keyed on a promotion_id it never explains that identifier, and no output shape or severity semantics are given.

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

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

Schema description coverage is 0% for the single required parameter promotion_id, and the description never mentions it or its meaning. The description therefore does nothing to compensate for the undocumented parameter, unlike the baseline-3 case where the schema already carries the semantics.

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

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

The description states a verb ("Read") and a resource ("saved advisory readiness issues and warnings"), but never mentions promotions, so the tie to the tool name validate_promotion is left implicit. It also doesn't distinguish itself from near-neighbours like get_promotion_report or preview_promotion, which an agent could easily confuse with 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?

There is no statement of when to call this versus the sibling tools that also surface promotion state (get_promotion_report, preview_promotion, get_promotion). The agent must infer the selection criteria entirely from the tool name.

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