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

Goes well beyond the annotations: it discloses the state gate (offer in review), that Vereel downloads https URLs versus uploading a file from the server's machine, the 5 MB and 6-photo caps, that the first photo becomes the cover, and the auth requirement. These are exactly the operational facts an agent needs before calling a non-idempotent, open-world write.

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

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

Three tight sentences, front-loaded with the action and its precondition, followed by the input choice and then the limits. No filler or restatement of the title.

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

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

Covers preconditions, input modes, format/size/count limits, cover ordering, and auth. The only gap is the return value and what happens when the offer isn't in review; with no output schema, a brief note on the response would have made it 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 already 100%, so the baseline is 3, but the description adds real value by framing imageUrl and filePath as mutually exclusive alternatives and clarifying where filePath resolves (the server's machine, not the caller's). It doesn't state behavior if both are supplied, but the added semantics exceed 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?

States a specific verb and resource ("Add one photo to an offer") plus a scoping condition ("still in review"), which cleanly separates it from siblings like vereel_create_offer and vereel_update_offer. An agent knows exactly what this does without opening the schema.

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

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

Gives clear preconditions (offer must be in review, read-and-write brand token required) and the either/or choice between imageUrl and filePath. It does not explicitly name sibling alternatives or say what to do if the offer is no longer in review, but the context for use is unambiguous.

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

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

Annotations only say it is a non-idempotent, non-destructive write; the description adds the material behavior: the offer is NOT public on creation, Vereel reviews and publishes it, the call notifies reviewers, and it requires a read-and-write brand token. That is real operational context (approval gate, external side effect, auth requirement) 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?

Five sentences, front-loaded with what the tool does, then the approval state, then the photo/category prerequisites, then the user-confirmation requirement, then auth. Every sentence carries a distinct constraint; nothing is repeated from 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?

For a 33-parameter nested creation tool with no output schema, the description covers the workflow, gating conditions, and auth, which is the hard part. The one gap is the return value: with no output schema, the agent is not told whether an offer id or pending status comes back, which matters for follow-up calls like vereel_add_offer_image.

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 91%, so the schema already carries parameter meanings and the baseline is 3. The description adds value on top by stating that at least one image is required before approval and that imageUrls can be deferred via vereel_add_offer_image, neither of which is in the schema. It says nothing about the conditional/EVENT-only fields, but those are well documented in the schema itself.

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

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

Uses a specific verb and resource ('Add an offer … to Vereel') and immediately defines what an offer is ('an influencer-marketing campaign') plus the scope ('for the brand that owns the token'). It also names the sibling tools that supply related pieces (vereel_add_offer_image, vereel_list_categories), so an agent can distinguish it from create/update paths 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?

States the preconditions for calling (needs a read-and-write brand token, category ids from vereel_list_categories, at least one photo) and the human-in-the-loop step ('Show the user the campaign details and get their go-ahead before calling'). It also gives the alternative path for images (add afterwards with vereel_add_offer_image), which is exactly the when-vs-which guidance an agent needs.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, and the description goes beyond them by spelling out the auth requirement and exactly which non-obvious data comes back (pre-approval gaps, rejection reviewer note). It does not cover not-found or not-owned error behavior, which is a mutation-free read so the omission is modest.

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

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

Two sentences, both front-loaded: the return payload first, the credential requirement second. The field enumeration is long but each item (status, photos, missing items, reviewer note) carries information an agent cannot get from a schema, so nothing is gratuitous.

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 appropriately takes on the job of describing return content, and with one fully documented parameter the input side needs no more. The only gap is the absence of failure behavior (invalid or foreign offerId), which would round out a single-record fetch.

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 offerId parameter is documented in the schema itself, including where to obtain it (vereel_create_offer / vereel_list_my_offers). The description adds no format, length, or validation 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?

Specific verb (get) plus resource scoped to the brand's own offer, and it enumerates the payload (fields, status, photos, missing requirements, reviewer note). Ownership wording ('the brand created through the API') implicitly separates it from vereel_list_my_offers and the public vereel_get_offer, but it never names those siblings 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?

Usage is implied by the 'my offer' ownership framing and by the sibling naming pattern, and the required credential type (brand token, read or read-and-write) is stated. There is no explicit when-to-use-this-instead-of-X guidance, e.g. no pointer telling the agent to use vereel_list_my_offers to discover an offerId or vereel_get_offer for another brand's offer.

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 and openWorldHint, but the description adds real context beyond them: no authentication token is needed and no payment amounts are exposed. That auth and content-boundary disclosure is exactly the kind of value annotations can't carry.

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

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

Three short, front-loaded sentences with no filler; the returned-field list does the heavy lifting and the two constraints come last. Every sentence earns its place.

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

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

No output schema exists, yet the description enumerates the returned fields (creator activity, deliverables, platforms, audience, follower minimum, deadline, link), so the agent knows what to expect on return. For a single-param read tool this is 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% and the single offerId parameter is already documented in the schema as 'The offer's id or numeric id'. The description adds no format, sourcing, or id-derivation guidance, so baseline 3 applies.

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

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

States a specific verb (get) and resource (one public Vereel offer) and enumerates the fields returned, so the agent knows exactly what comes back. It never names vereel_get_my_offer or vereel_search_offers; the 'public' qualifier implies a private counterpart but leaves the agent to infer the distinction.

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

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

The description implies the right context (fetching a single public offer by id, no token required), but gives no explicit when-to-use versus search_offers or get_my_offer, and no exclusions. With seven siblings, routing guidance is thin.

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 and openWorldHint=true, so the safety profile is covered. The description adds the non-obvious auth detail "No token needed" and enumerates example category values, both of which are new information an agent would otherwise have to discover by failing a call.

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

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

Three short sentences, each carrying a distinct payload: what it lists, what the output is good for, and the auth constraint. Front-loaded with the purpose, zero filler or restatement of the title.

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

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

With no output schema, the description must convey the return shape; it conveys that the response is categories with ids and human-readable names via examples. It could be slightly firmer about the exact fields returned, but for a trivial zero-param lookup this is nearly 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?

The tool takes zero parameters, so the baseline of 4 applies. The description correctly sticks to explaining the output (category ids) rather than inventing input semantics, which is the right allocation for a parameterless tool.

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

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

States a specific verb and resource ("List the categories Vereel files offers under") and immediately grounds it with concrete examples (beauty, fashion, travel). It also names the two sibling tools that consume the result, so an agent can distinguish it from vereel_search_offers and vereel_create_offer 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?

"Their ids are what vereel_create_offer takes as categoryIds and vereel_search_offers takes as category" explicitly tells the agent the downstream use case and the prerequisites for those tools. It stops short of an imperative like "call this first to discover valid category ids" or naming when not to use it, but the routing context is clear.

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

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

Annotations only declare readOnlyHint and openWorldHint; the description adds real substance beyond that: newest-first ordering, the four possible status values with their meanings (including that rejected carries Vereel's note), and the auth requirement (brand token, read or read-and-write). This is exactly the context annotations cannot convey.

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

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

Two sentences, front-loaded with scope and ordering, then status semantics, then use cases and auth. No filler; each clause (ordering, statuses, token type) carries information an agent would otherwise lack.

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

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

For a zero-required-param read tool with no output schema, the description covers ordering, status interpretation, use-case intent, and the auth prerequisite. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so limit (1–50, default 20) and cursor are already fully documented in the schema. The description adds no pagination or ordering semantics beyond what the schema states, so the baseline 3 applies.

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

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

States a specific verb+resource with explicit scope: offers created by the brand that owns the token, newest first. This cleanly separates it from vereel_search_offers (broad search) and vereel_get_my_offer (single item) without the agent needing to open 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?

Names concrete use cases ('check progress', 'find an offer's id'), which is genuinely actionable. It stops short of stating exclusions or pointing to alternatives like vereel_search_offers or vereel_get_offer, so routing is inferred rather than explicit.

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 readOnlyHint/openWorldHint annotations, it discloses ordering (newest first), a data-visibility constraint (no payment amounts shown to anonymous visitors), pagination behavior, and that no token is needed. That last point is a genuinely useful auth clarification, though it omits any rate-limit or result-size 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?

Four short sentences, front-loaded with purpose, then filters, then the visibility caveat, then pagination/auth. Every sentence carries distinct information with no repetition of name or title.

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

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

For a 7-param read-only search with no output schema, the description covers purpose, filtering, paging, auth, and data visibility. It doesn't sketch what an offer record contains beyond ordering, but nothing essential to correct invocation is missing.

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

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

The description enumerates the filter dimensions (words, category, type, platform, language), which helps map intent to parameters. But with 57% schema coverage it leaves gaps (e.g., the `limit` param is undocumented here) and the mismatch between its 'nextCursor' wording and the actual `cursor` parameter name adds minor friction.

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 ('Search the influencer-marketing offers') plus scope ('published on Vereel', 'creators can apply to', 'newest first'). This clearly separates it from sibling tools like vereel_list_my_offers and vereel_get_offer.

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 'public offers, what an anonymous visitor sees' framing implicitly tells the agent to use this instead of the my-offers siblings, and 'Use nextCursor to get the next page' gives concrete usage. However, it never explicitly names an alternative or a when-not condition.

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 mutation, destructive, idempotent, and open-world behavior. The description adds important operational context: partial updates only change supplied fields, photo omission removes photos, public/rejected offers are immutable via API, and a read-and-write brand token is required.

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

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

The description is front-loaded with purpose and constraints, then covers photo handling and auth. Every sentence contributes actionable information without repetition.

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

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

Given 34 parameters but 91% schema description coverage, annotations covering safety traits, and no output schema, the description provides the missing operational essentials: state eligibility, partial-update behavior, photo handling, alternative tool routing, and auth requirements.

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 high at 91%, so the schema carries most parameter detail. The description still adds meaningful semantics beyond the schema, especially that omitted fields are unchanged and how the photos array should be passed for reorder/removal versus addition.

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 (change an offer), scopes it to offers the brand created through the API while in review, and distinguishes it from sibling actions like vereel_create_offer and vereel_add_offer_image. An agent can identify what this tool does without reading the schema.

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

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

It explicitly covers when the tool can be used (offer still in review) and when it cannot (already public or rejected). It also names the correct alternative for adding photos, vereel_add_offer_image, making the routing decision clear.

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