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

With no annotations, the description carries the full burden. It usefully discloses the return value ('Returns the chirp id'), which matters because there is no output schema, but it says nothing about whether authentication is required, what happens on an empty chirp (0 required params), or how chirps are moderated/flagged as mature.

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 action front-loaded and the return value appended. The parenthetical and example are brief enough to earn their place as disambiguation, though the billboard example is slightly decorative.

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 6-parameter creation tool with no annotations and no output schema, the description is thin: it omits the media-upload prerequisite, the optionality of every parameter, content constraints, and the comment-threading behavior implied by parentPostId. Only the return value is covered.

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

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

Schema description coverage is only 50%: text, isActive, and isMature have no schema descriptions, and the tool description adds nothing about them. The description does not compensate for the gap, leaving half the parameters with no semantic guidance anywhere.

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 (post a chirp) and disambiguates the domain jargon ('social post' on BillboardBug) with a concrete example. It is clearly distinct from the deal-oriented siblings, though it does not explicitly contrast with update_chirp or get_chirp beyond the verb.

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 no when-to-use guidance, no prerequisites (e.g. that imageId/videoId must come from upload_media first), and no statement of when not to use it. The 'e.g. announcing a new billboard' hint is illustrative, not a usage rule.

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 no annotations, the description carries the full burden and does reasonably well: it discloses that the deal goes live immediately, that media is mandatory, what identifiers come back, and a non-obvious negative behavior ('Never sets featured (paid) placement'). Missing auth requirements, whether creation is idempotent, and any rate limits keeps it short of a 5.

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

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

Three short sentences, zero filler, and the most decision-relevant facts (live, media required, non-featured) are front-loaded. Every sentence earns its place and nothing is repeated.

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 12-parameter, 7-required mutation tool with no output schema, the description covers the media prerequisite and even names the two return identifiers, which compensates for the absent output schema. Given the high schema coverage, remaining gaps (auth, mutation side effects) are minor rather than blocking.

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 83%, above the baseline threshold, so the schema already documents most parameters including the imageId/videoId relationship and default categoryId. The description adds only the media-or-video requirement, which duplicates the imageId schema text, and adds nothing to undocumented fields like isEnabled or altitudeMeters.

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 a live billboard deal at a real location') and distinguishes itself from update_deal/create_chirp siblings in the same toolset. The scope qualifier ('live', 'at a real location') is precise enough that an agent can pick this over list_my_deals or upload_media without opening a schema.

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

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

The precondition ('Requires an uploaded image or video') is a clear, actionable when-to-use gate that tells the agent it must call upload_media first. However, there is no explicit when-not-to-use or mention of update_deal as the alternative for editing an existing deal.

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 no annotations, the description carries the full behavioral burden. It usefully discloses the return format (base64 data URIs) and the downstream handoff to upload_media, but it omits auth requirements, rate limits, generation cost/performance, provider behavior, and failure modes.

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

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

Two tightly written sentences with no wasted words. The core action and output are front-loaded, followed by the downstream workflow and prompt preference.

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 tool with no annotations, no output schema, and only 25% schema description coverage, the description covers the return format and upload_media workflow. However, it omits the aiProvider parameter entirely and does not describe generation constraints or side effects, so it is adequate but incomplete.

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 low at 25%, so the description must compensate. It adds practical meaning for prompt and image dimensions via 'from a prompt (recommended 640x373)' and prompt style guidance ('Prefer realistic photos'), but it never names width, height, or aiProvider, leaving gaps in parameter semantics.

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

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

The description states a specific verb and resource: 'Generate billboard artwork from a prompt.' It distinguishes itself from media-storage siblings by naming upload_media as the downstream tool, so an agent can identify its role 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?

It gives clear usage context: use a prompt, recommended dimensions of 640x373, prefer realistic photos, and pass the returned base64 data URIs to upload_media. It does not state when not to use this tool or compare it to an alternative image-generation tool, but the workflow 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?

The readOnlyHint annotation already establishes that this is a safe read operation. The description adds the verification purpose, which is useful context, but it does not disclose return contents, missing-id behavior, or any auth/rate-limit considerations.

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 efficient sentence front-loads the verb and resource, then gives the purpose. Every phrase earns its place, and there is 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 simple one-parameter read tool with a readOnly annotation, the description is enough for selection and invocation, but it omits what the read returns and how missing or invalid ids are handled. With no output schema, those gaps remain.

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 must carry parameter meaning. "By id" only restates the schema property name and requiredness without explaining format, source, or lookup semantics beyond the schema's UUID format.

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 (read) and resource (chirp) scoped by id, and the read-back framing distinguishes it from write siblings like create_chirp and update_chirp. It does not explicitly name alternatives or exclusions, 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?

"To verify it posted" gives a clear intended usage context: checking that a chirp was successfully created and can be retrieved. It does not state when not to use the tool or name alternative read tools, but no exclusions are needed for this simple case.

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, so the safety profile is covered. The description adds genuinely new behavioral context beyond the annotations: 'Works without an API key,' which tells the agent about authentication requirements for this call. It does not, however, describe what a non-live or missing deal returns.

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 resource, with no filler. 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?

For a two-parameter read-only lookup with no output schema, the description covers action, keys, purpose, and auth. It is nearly complete; only the failure/empty-result behavior and the meaning of the two IDs remain unstated.

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

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

Schema description coverage is 0%, so the schema only supplies types and uuid formats. The description references both parameters by name as the lookup keys, giving them role context, but does not explain what a storefront or billboard identifier refers to or where to obtain them.

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 gives a specific verb and resource ('Read a deal back') and names the two identifying keys used for the lookup. It is distinguishable from list_my_deals and search_deals by its by-ID read-back semantics, though it does not explicitly contrast itself with them.

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

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

'to verify it is live' supplies a concrete use case, which is more than nothing, but there is no explicit when-not guidance and no named alternative for retrieving deals by other means. Usage is implied rather than prescribed.

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, so safety is covered. The description adds real behavioral context beyond it: an API key is required, the dataset is large (~7,000 entries), and the default category used by create_deal is Miscellaneous. It stops short of describing pagination or ordering 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?

Three short, front-loaded sentences with no filler; the core action leads. It loses a point because the vague 'for categoryId (about 7,000)' phrasing spends its brevity on something an agent can't act on.

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 list tool with no output schema, the description covers auth requirements, scale, filtering, and a cross-reference to create_deal's default. The main omission is the 'max' parameter and result-set/pagination behavior, but overall it is adequate 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 coverage is 0%, so the description must compensate for both parameters. It partially does for nameContains ('Pass nameContains to filter') but gives no substring/case semantics, and it never explains the 'max' parameter or its 1-500 bound. Real value added, but incomplete against a 0% coverage 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 clear verb+resource: 'List storefront categories', which is distinct from siblings like get_deal/search_deals. However, 'for categoryId (about 7,000)' is confusing since no categoryId parameter exists, muddying what the tool actually returns. The core purpose is still recoverable.

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 implied usage ('Pass nameContains to filter') and useful cross-tool context ('Default used by create_deal is Miscellaneous'), which hints at when an agent would reach for it. But it names no alternative and gives no when-not guidance, so routing vs. siblings 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?

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description adds the meaningful scoping constraint that results are limited to the API key's own account rather than filterable by user, but it says nothing about pagination or result limits despite exposing limit/offset.

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 efficient sentence with the scoping detail front-loaded and no filler. It is arguably too terse, 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?

No output schema exists, but the description does not indicate the return shape, pagination behavior, or default limit, which matter for a list tool with limit/offset. It is adequate for identification but incomplete for correct invocation.

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

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

Schema description coverage is 0% and both parameters (limit with maximum 100, offset with minimum 0) are undocumented in the schema. The description mentions neither, so it fails to compensate for the coverage gap on a paginated listing 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 (List) and resource (deals) plus a clear scope: deals owned by the API key's account. It implicitly distinguishes itself from search_deals (query-based) and get_deal (single), but never names a sibling 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 description gives no when-to-use or when-not-to-use guidance and no mention of alternatives such as search_deals for filtered queries or get_deal for a single record. Usage must be inferred entirely from the name and the phrase 'owned by the API key's account'.

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?

readOnlyHint=true already tells the agent this is a safe read. The description adds the API-key requirement and the minimum query length, which is modest added value, but says nothing about result ordering, pagination behavior, or rate limits.

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 core action and no filler. It is efficient, though it spends words on a constraint the schema already enforces rather than on the undocumented parameters.

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 3-parameter tool with no output schema and no schema descriptions, the definition is thin: paging parameters and result shape/pagination semantics are left entirely unaddressed, so an agent cannot confidently bound or page a query.

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 must carry parameter meaning. It only restates the min-3-character rule already enforced by minLength on 'search' and never explains limit (max 100) or offset, leaving two of three parameters undocumented anywhere.

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 (search) and resource (deals) plus the scope of matching (by text, min 3 characters). It distinguishes itself reasonably from list_my_deals by being a text query, though it never names that sibling 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?

Usage is implied by the verb 'search' and the API-key prerequisite is noted, but there is no explicit when-to-use guidance, no mention of when to prefer list_my_deals or list_categories, and no pagination advice for a tool that exposes offset/limit.

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?

No annotations are provided, so the description carries the full behavioral burden and delivers almost nothing. It does not say whether this is a partial/merge update or a replacement, what happens to omitted fields (all but id are optional), whether the edit is reversible, or what authorization beyond ownership 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?

A single front-loaded sentence with no filler or redundancy. It is efficient, though the terseness is a coverage problem rather than a conciseness virtue.

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

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

For a 7-parameter mutation tool with no annotations, no output schema, and under-half schema description coverage, the description omits nearly everything an agent needs: partial-update semantics, field-level effects, and error behavior.

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

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

Schema description coverage is only 43% (text, id, isActive, isMature are undocumented), and the description adds no parameter meaning at all. With coverage below 50%, the description was expected to compensate for the undocumented fields and does not.

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

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

Names a specific verb and resource ('Edit an existing chirp') plus a scope constraint ('you own'), so it is clearly distinguishable from create_chirp and get_chirp. It stops short of explicitly contrasting itself with those siblings, but the core purpose is unambiguous.

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

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

The phrase 'you own' implies a precondition and thus implied usage (only edit your own chirps), but there is no statement of when to prefer this over create_chirp or update_deal, and no mention of failure modes when the chirp is not yours.

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 no annotations, the description carries the full behavioral burden and it does disclose the two most consequential traits: this is a full replace (not a patch) and isEnabled:false is the takedown switch. It omits what happens to fields left unspecified, permission/auth requirements, whether the prior deal is recoverable, and the response shape.

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, zero filler, with the replace semantics front-loaded and the takedown case second. Nothing is repeated from the title or schema.

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

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

This is a 14-parameter, 9-required mutation with no annotations and no output schema, so the description is the only place behavioral context can live. It is too thin for that: no identification of which arguments select the deal, no warning about the blast radius of a full replace, and no media-requirement guidance.

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 71%, so the schema already documents most parameters; baseline is 3. The description adds real meaning for isEnabled, which has no schema description at all, by defining it as a takedown flag. It adds nothing for the other 13 parameters, including the imageId/videoId requirement noted in 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 ('Replace an existing deal') and anchors it to a sibling ('same fields as create_deal'), so the agent can distinguish it from create_deal without opening either schema. It stops short of naming the identifying keys (storefrontId/billboardId) that a replace operation hinges on.

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 one concrete usage scenario ('use isEnabled:false to take a deal down when the promotion ends'), which is genuinely useful. But it never states when to choose update_deal over create_deal, get_deal, or list_my_deals, and gives no preconditions such as needing an existing deal id.

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

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

With no annotations, the description carries the full behavioral burden; it does disclose the return value ('Returns the blob id') and that base64 is accepted alongside file paths, which is useful. It omits permissions/auth requirements, size limits, and what happens on re-upload or failure — meaningful gaps for a mutation tool.

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

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

Three short sentences, each earning its place: action, category routing, and return value. Front-loaded with the verb and resource.

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

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

No output schema exists, and the description compensates by naming the return value (blob id). Parameter behavior is largely covered by the schema plus the category routing. Minor gap: no guidance on choosing filePath vs base64Data beyond '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 75%, so the schema documents most fields, but the description adds real meaning by mapping each enum value to its domain (billboard-* for deals, post-* for chirps) and by noting base64Data is an alternative to filePath. That goes beyond the raw enum list.

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 ('Upload a local image/video file ... to BillboardBug') with both input modes named. It also clarifies where each category lands (deals vs chirps), so an agent can place it relative to create_deal/create_chirp without opening other schemas.

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

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

Explicitly tells the agent which category to use for deals versus chirps, which is the primary selection decision for this tool. It stops short of saying when to call upload_media at all (e.g., before create_deal vs. using generate_image as an alternative), but the context is clear.

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