The Profound Agency

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

Annotations already establish read-only, non-destructive, closed-world behavior. The description adds meaningful provenance guarantees ('quoted or read from live data, never generated'), source URLs, and a null-answer signal when the site does not cover a topic. No auth or rate-limit details are provided, but that is beyond what the annotations require.

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

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

Two sentences, front-loaded with the core definition and then a scope enumeration. The second sentence is long but every listed topic earns its place by clarifying coverage boundaries; 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 single-parameter, read-only QA tool, the description covers scope, provenance, source URLs, and the null-result behavior. With annotations conveying safety and no output schema needed, this is largely complete, though routing against siblings remains unaddressed.

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

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

Schema description coverage is 100%: the single 'question' parameter is fully documented in the schema, including an example and length constraints. The description only adds 'plain words,' which is a marginal nuance over the schema baseline.

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

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

The description names a specific verb ('answered'), the resource ('question... from theprofound.agency'), and enumerates covered topics like prices, fees, refund terms, and definitions. It stops short of distinguishing this tool from siblings such as can_i_advertise, which appears to cover one of the listed topics (whether a category can advertise on a channel).

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 or when-not-to-use guidance, and no alternatives are named. The topic list provides clear implied context for what questions it answers, but an agent must infer that specialized siblings may take precedence for their niches.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, destructiveHint=false, so safety is covered. The description adds genuinely useful context beyond them: what limits get returned (age gates, restricted targeting, pre-approval) and the caveat that policy changes without notice, making the answer guidance rather than authoritative.

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

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

Three sentences, front-loaded with purpose, then parameter usage, then the reliability caveat. The long category list is the only bulk and it earns its place by enumerating the covered scope.

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 lookup with no output schema and fully covered parameters, the description supplies scope, scoping behavior, and a reliability caveat. It does not describe the shape of the returned limits, but with annotations covering safety and no output schema, that gap is minor.

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 parameters are documented, but the description still adds value: it specifies the omit-channel behavior (returns all channels) and that the channel slug comes from list_channels, which the schema does not state. The state and category semantics largely duplicate 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?

The description states a specific outcome: determining whether a restricted category (alcohol, cannabis/CBD, firearms, etc.) can run on a channel and under what limits. The scope is concrete and an agent can distinguish it from siblings like list_channels or list_categories 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 clearly explains how to scope a check: pass a channel slug to check one, omit it to see every channel, add a state for state-level rules. It stops short of naming when-not-to-use or pointing at a specific alternative tool beyond referencing list_channels as the slug source.

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

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

Beyond the readOnly/non-destructive annotations, it discloses the email-based access gate ('what stops anyone reading anyone else's order'), the awaiting-payment return shape (paid: false plus payment link), and the not-found outcome for swept unpaid orders. This is exactly the behavioral context annotations cannot carry.

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

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

Three compact sentences, front-loaded with what the tool returns, then the requirement, then an edge case. Dense and nearly waste-free, though the security rationale sentence could be trimmed slightly.

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

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

With no output schema, the description compensates by describing the return states (paid: false with payment link, and not-found for swept unpaid orders). Combined with the parameter requirements, an agent has everything needed to call and interpret this tool.

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

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

Schema coverage is 100%, so both parameters are already documented, and the baseline would be 3. The description adds meaning beyond the schema by explaining why email is required (as an access control gate on the caller's own order), which clarifies intent rather than just restating 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?

States a specific verb+resource ('payment and fulfilment state for an order') and scopes it to 'an order you created', which reads differently from sibling tools like get_client_order. An agent can identify the operation without opening the schema.

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

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

The description implies the usage context (checking an order you created, requiring the original billing email) but never explicitly contrasts with the closest sibling, get_client_order, or states when not to use this tool. Usage is inferable rather than spelled out.

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

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

Annotations already cover the read-only, non-destructive safety profile, and the description adds context beyond them: it discloses the comparison dimensions returned and the important caveat that results are 'figures only — which is better depends on what the client wants.' It doesn't mention rate limits, ordering, or failure behavior on bad ids, but the interpretive caveat is real added value.

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

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

Front-loaded with the core action and constraint in the first clause, with the caveat closing the description. The long enumeration of compared attributes is dense but each item is substantive rather than filler.

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

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

No output schema exists, so the description must carry the return-value burden, and it does: it lists the compared fields plus the derived 'cheapest/fastest/highest authority/most visited' answers. Only minor gaps remain around error handling for invalid or duplicate ids.

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

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

Schema description coverage is 100% and the single `ids` param is documented in-schema as coming from search_placements; the description only repeats that origin. The 2-4 cardinality bound is also already in the schema's minItems/maxItems, so no new parameter meaning is added.

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 (compare) plus resource (placements) and enumerates exactly what is compared — price, DA, rating, traffic, link type, turnaround, region, and derived winner picks. An agent can distinguish this from get_placement or quote_placements without opening any schema.

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

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

Explicitly says to source ids from search_placements and constrains to two-to-four publications, giving clear operating context. It does not name when to prefer this over quote_placements or plan_placements, so the alternative-routing is left implied.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, and the description goes well beyond them by disclosing the key behavioral truth: the meeting does not exist until the human confirms on the page, and the name/email must not be URL-encoded by the caller. This is exactly the kind of side-effect/authority disclosure an agent needs for a booking 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?

Front-loaded with the tool's output, then usage instructions, then safety constraints. Every sentence carries distinct weight; nothing is padding, and the length is justified by the high-consequence confirmation semantics.

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

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

With no output schema, the description fully describes the return value (URL plus separate name/email fields) and the confirmation workflow. An agent has everything needed to call it and to avoid misrepresenting the result.

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

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

Schema description coverage is 100% and both parameters are documented directly in the schema with the same 'show them alongside the booking link' intent. The description adds no format, constraint, or edge-case detail beyond what the schema already provides, so the baseline 3 applies.

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

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

The description states a specific resource and scope: 'the agency's booking URL for a 30-minute meeting,' and clarifies precisely what is returned (the URL plus the human's name and email as separate fields). An agent can distinguish this from other create/submit siblings 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 explicit operational guidance — hand the URL to the human and have them enter name/email on the booking page — plus a hard negative constraint ('never present a meeting as booked on the strength of this link alone'). It stops short of naming an alternative sibling, so it is a clear context rather than a routing decision, but the when/when-not framing is strong.

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 cover the safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=false). The description goes far beyond: the order stays pending until a human pays externally, no account/API key is needed, and unpaid orders are auto-deleted after 72 hours. These are non-obvious lifecycle and side-effect facts an agent cannot derive from structured fields.

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

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

Front-loaded with purpose and the critical 'does not pay for anything' warning in caps before any secondary detail. It is longer than most definitions but nearly every sentence carries an actionable constraint; only the API-key remark is somewhat tangential.

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 return-value burden and does so by naming the returned payUrl and the mechanism by which payment completes. Combined with the lifecycle and human-in-the-loop constraints, an agent has everything needed to call and follow up 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 60% with nested item objects, and the schema itself documents id/niche/quantity/contact.email. The description adds only indirect mapping ('give the link to the client' → contact.email, 'confirm the placements and total' → items). It does not explain quantity, niche pricing behavior, or placedBy semantics beyond what the schema already states, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource ('Open a pending order for a client') plus the key side effect ('return a payment link'). It is instantly distinguishable from check_order_status, which it names, and from quote_placements/plan_placements by its ordering intent.

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

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

Explicit prerequisites ('Confirm the placements and the total with a human before calling this'), explicit non-capability ('you cannot complete payment yourself'), an explicit prohibition tied to a sibling ('must not tell the client the placement is bought until check_order_status reports paid: true'), and a timing rule (send the link within 72 hours). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, and the description is consistent with them. It adds genuinely useful behavior the annotations don't convey: the exact return payload (message + sms: link that opens the messaging app) and that nothing is transmitted until the human taps send. It stops short of describing failure modes or length limits, keeping it at a strong 4.

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

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

A single front-loaded paragraph: purpose and return value first, then the safety constraint, then sibling routing. Every sentence carries distinct information with no 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?

There is no output schema, and the description covers return values, the human-confirmation workflow, and the alternative tool. Nothing needed to invoke this correctly is missing.

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

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

Schema description coverage is 100%, so name, company, and message are already documented in the schema with clear semantics (including the 400-character message limit). The description adds no parameter-level detail, so the baseline 3 applies.

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

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

States a specific verb and resource: it prepares a text message to the agency and returns the message plus an sms: link. It also names the sibling it is not (create_booking_link), so an agent can route without opening any schema.

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

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

Explicit when-to-use and when-not-to-use: 'For a scheduled call, create_booking_link is better; use this for a quick question or to ask for a call back.' It also states the human-in-the-loop requirement (show the message first, never send without go-ahead).

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 this a non-destructive, non-open-world read. The description adds genuinely new behavioral context on top: slots are booked in the agency's timezone, meetings are 30 minutes on weekdays, and—most importantly—a returned slot does not reserve anything until a booking link is confirmed.

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: resource first, return payload second, safety caveat last. Nothing is padding and the most important constraint (a slot is not a booking) lands where it will be read.

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 steps in and names the return fields (start, end, readable label), and it covers timezone and meeting-length semantics. It omits edge cases such as an empty result set or how many slots come back, which is the only visible gap for a two-parameter read 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 100% and both parameters (daysAhead, durationMinutes) are fully documented there, so the baseline is 3. The description's mention of 30-minute weekday meetings loosely reinforces durationMinutes but adds no syntax, units, or defaults beyond the schema.

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

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

States a specific verb and resource—real open slots from the agency's appointment calendar—and pins down the shape of those slots (30-minute, weekday, agency timezone). It also explicitly separates itself from create_booking_link, so an agent can tell the two apart without opening either schema.

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

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

The closing sentence routes the agent to the correct alternative and states the condition that selects it: a slot is not a booking, so hand the human a create_booking_link. It stops short of saying when the tool should not be called at all, but the practical next-step guidance is 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered; the description adds genuinely new behavior — the result is a weekly diff ordered newest-first, and it is a cheaper alternative to re-reading the catalogue. It does not disclose result-size limits or pagination, which keeps it from a 5.

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

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

One front-loaded sentence states the return content first, then the filters and their purpose. The em-dash filter list is dense but every clause earns its place; no filler or redundancy.

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

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

With 7 optional parameters and no output schema, the description carries the burden of describing the return shape, and it does so ('publications added and removed, and price changes, newest first'). It omits any mention of result volume, limits, or default window when no filters are supplied, which is the main remaining gap.

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

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

Schema description coverage is 100% and every one of the 7 filters is already documented in the schema, so the baseline is 3. The description restates the same filters (date, max price, categories, min DA, additions-only, price-drops-only) and adds intent rather than new parameter syntax, so it does not meaningfully exceed 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?

The description states a specific verb and resource: it returns the delta of each weekly catalogue sync — publications added/removed plus price changes — and gives the ordering ('newest first'). This is clearly distinguishable from siblings like search_placements or compare_placements, which operate on the current catalogue rather than its changes.

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

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

It gives a clear context of use ('watch for new outlets or cheaper placements without re-reading the whole catalogue') and enumerates the filter modes that map to that intent. It stops short of naming an explicit alternative tool or stating when not to use it, so it is clear but not fully routing.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the useful negative disclosure that no price is returned and that quotes come from submit_campaign_brief, but gives no return-format or pagination detail.

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

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

Front-loads the purpose ('full detail for one paid media product') and then lists the returned facets in a single efficient sentence, closing with the pricing caveat. No wasted sentences.

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

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

No output schema exists, so the description carries the burden of describing returns, and it does so by enumerating the detail categories and capabilities. For a single-parameter read-only tool, the coverage is nearly complete; only return format specifics are absent.

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

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

Only one parameter with 100% schema description coverage; the schema already defines slug and points to list_channels. The description adds no syntax, format, or validation meaning beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('full detail for one paid media product') and enumerates the content returned (what it is, placements, formats, targeting, caveats, capabilities). It contrasts implicitly with the plural list_channels via 'one product', but does not name a sibling 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?

Implies usage by noting caveats a buyer should know 'before submitting a brief' and explicitly routes pricing to submit_campaign_brief ('gets a quote'). However it never states when to call get_channel versus list_channels or get_placement, so routing guidance is partial.

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

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

Annotations already declare readOnly and non-destructive, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the link is private to the client, and a wrong or revoked link surfaces as a missing order, telling the agent how to interpret failures. It also notes each publication is processed independently.

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

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

Front-loaded with 'For a paid order:' and every sentence carries information, but the long comma-chained enumeration of returned artifacts is denser and less scannable than it could be. No wasted filler, though.

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

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

With no output schema, the description correctly takes on the job of describing what comes back, and it covers the auth prerequisite and failure mode. It is nearly complete; a note on how it differs from check_order_status is the main missing piece.

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 one parameter and 100% schema coverage, the schema already documents the orderLink format in detail. The description only reinforces that the link is private and error-prone when wrong, adding little semantic detail about the parameter itself, so the baseline of 3 is appropriate.

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

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

The description makes clear this returns the full working state of a paid order — each publication, its stage, next steps, submitted content, and latest draft — which is a specific resource with a specific scope. It never states a retrieval verb explicitly since it is framed as an inventory of return contents, and it does not distinguish itself from the overlapping sibling check_order_status.

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

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

Usage is only implied: the tool is for a paid order and requires the client's private order link. There is no explicit when-to-use, when-not-to-use, or routing to alternatives such as check_order_status, which likely covers a lighter-weight status query.

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

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

Annotations already declare readOnly/openWorld=false/destructive=false, so safety is covered. The description adds real behavioral semantics beyond them: a missing field means the catalog has no value (unknown, not "no"), dofollowVariantId points to a separate package, and nichePricing signals price-varying niches. It stops short of covering auth/rate-limit or error 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?

Purpose is front-loaded and the (long) field enumeration is delivered in one dense sentence with no filler. It is heavier than ideal, but with no output schema every clause is documenting otherwise-unavailable return data, so the length is largely earned.

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 full burden of describing returns and does so comprehensively (price, fee-inclusive price, authority, traffic, turnaround, disclosure, link attributes, genres, niches, labels, availability, logo, example article). The absence convention is also stated, leaving nothing important 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 coverage is 100% and there is a single id param, so the baseline would be 3. The description adds genuine meaning the schema lacks: the id is the slug produced by search_placements, which tells the agent where to obtain a valid value rather than just its 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?

States a specific verb and resource: full detail for one publication, identified by the id/slug returned from search_placements. The reference to search_placements makes the read path for the required id explicit, so an agent can distinguish this from the search and compare siblings.

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

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

It implies when to use it by noting the id comes from search_placements, which is useful workflow context. However, it gives no explicit when-not guidance and never mentions the obvious alternatives (compare_placements for side-by-side, get_availability for availability-only queries), so routing still requires inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds useful context that results pair plain-language outcomes with the products providing them, but it says nothing about ordering, scale, or exact response shape, which matters more given there is no output schema.

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

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

Two sentences, front-loaded with what the tool returns before the usage instruction. The 'and so on' filler and marketing-flavored 'outcomes we can deliver' slightly dilute an otherwise tight definition.

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-parameter read-only lookup with no output schema, the description conveys what the agent will get back and what to do with it, which is the essential information. It could be more complete by hinting at result size or whether the list is exhaustive, 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?

The tool takes no parameters, so per the rubric the baseline is 4; there is nothing for the description to disambiguate. No parameter documentation is needed or given.

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 the resource concretely ('the outcomes we can deliver') and enumerates representative contents (geo-fencing, website retargeting, visit tracking, identity resolution), making the outcome-oriented scope clear. It implicitly distinguishes itself from sibling list tools like list_categories and list_channels by framing items as client-facing outcomes mapped to products, though it never explicitly contrasts 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?

'Use this to translate what a client wants into what to ask for' gives a clear situational cue for when to reach for this tool over the many placement/order siblings. It does not name an alternative (e.g. ask) or state any exclusion, so it stops short of full when/when-not guidance.

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

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

Annotations already establish that this is a read-only, non-destructive, closed-world operation. The description adds useful behavioral context beyond that: it returns every category/genre/niche in the network with publication counts. It does not discuss pagination, auth, or rate limits, but the annotations cover the core safety profile.

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 compact sentences, with the resource scope front-loaded and the usage guidance immediately following. 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?

With no output schema, the description usefully explains what is returned: categories, genres, restricted niches, and publication counts. It is sufficient for a no-parameter lookup tool, though it could note ordering or pagination if relevant.

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 has zero parameters, and the schema description coverage is complete for an empty input schema. The description correctly adds no parameter discussion because there is nothing 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 identifies the exact resource set (categories, genres, restricted niches) and adds the returned count of publications per item, making the tool's purpose immediately clear. It also distinguishes this lookup from search_placements by framing it as the source of valid filter values.

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 says to use this to pick valid values for search_placements' categories, genres, and niche filters. That is clear when-to-use guidance, though it does not describe when not to use it or name any alternative lookup tool.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds return-shape behavior (each channel has a 1-2 sentence description) and the slug semantics, which is valuable since there is no output schema.

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

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

Three compact sentences, front-loaded with what a channel is, then the slug contract, then the alternative tool. No filler.

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

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

With no parameters and no output schema, the description carries the return-value burden and does so — enumerating content, describing entry shape, and explaining the slug's role. Nothing an agent needs to call it correctly is missing.

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

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

Zero parameters, so there is nothing to disambiguate and the baseline is 4. The description correctly implies the tool takes no filtering input and returns the full 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 and resource — enumerates the paid media products returned and clarifies each entry carries a short description plus a slug. It distinguishes itself from get_channel and from the catalog/list siblings by being the full channel roster.

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

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

Explicitly routes the agent: 'Use get_channel for the full detail of one,' and explains the downstream consumer ('The slugs are what submit_campaign_brief takes as channels'), making the when and when-not clear.

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

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

Annotations already cover the read-only, non-destructive, closed-world profile, and the description adds genuinely new behavior: the total includes a 3.5% processing fee, backlink/SEO goals exclude nofollow links, the shareUrl pre-loads the cart (empty when niche pricing applies), and nothing is reserved. That is substantive context an agent cannot infer from the annotation triple.

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

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

Front-loaded with the core recommendation purpose, and every clause carries information (fee, nofollow, shareUrl, non-reserving). It is dense with parentheticals and semicolons, which slightly taxes readability, but nothing is padding.

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

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

With no output schema and a read-only annotation profile, the description supplies what the agent needs: how budget is computed, what the plan excludes, what the returned shareUrl does, and that no inventory is reserved. All 7 parameters are documented at 100% coverage, leaving no obvious gap.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds semantic meaning beyond the schema: budget is inclusive of the processing fee, goal wording drives nofollow filtering, and the niche/price relationship explains the empty-cart case. It stops short of adding per-parameter syntax the schema lacks.

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 ('Recommend a set of publications') scoped to goal/audience/budget, and explains it is pre-quoted within budget. It also implicitly separates itself from the naming-based siblings via 'rather than naming publications', so an agent can route without opening any schema.

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

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

Gives a clear trigger condition: use it when a buyer states an outcome and a spend limit instead of naming publications. It does not explicitly name the alternative tools (quote_placements, search_placements, compare_placements) that handle the naming case, so the routing is implied rather than spelled out.

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

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

Annotations already establish readOnly/openWorld/non-destructive, and the description adds genuinely useful non-annotation context: instant execution, free of charge, no scoring, nothing stored, and that it works only from public pages. It stops short of describing failure modes or rate limits, so not quite a 5.

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

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

Two sentences, zero filler, and the highest-value information (what is checked, plus the free/instant constraints) is front-loaded before the sibling routing pointer.

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

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

With no output schema, the description correctly pre-empts the return value by listing the five checks, and it covers cost and storage semantics. It could say more about how results are presented, but for a one-param read-only probe it is close to 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 100% and the single 'website' parameter is documented there with a format example ('example.com'), so the schema does the heavy lifting. The description adds no syntax or format detail beyond the schema – baseline 3.

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

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

States a specific verb and resource ('whether AI systems can read a website') and enumerates the exact five checks performed (robots.txt crawler access, llms.txt, Organization/FAQ structured data, title/description). It explicitly distinguishes itself from the sibling request_audit, so an agent can route without opening either schema.

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

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

Gives explicit when-to-use ('checked instantly from its public pages', 'free, no score') and names the alternative with its selecting condition ('For the full audit — scored out of 100 and reviewed by a person — use request_audit'). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds genuinely new behavioral facts beyond that: quoting does not reserve anything, unavailable placements are refused rather than partially quoted, and niche items are priced at the outlet's niche price with no shareUrl returned when it diverges from standard pricing. These are non-obvious consequences an agent could not infer from the annotations.

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

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

Four sentences, front-loaded with the core purpose and fee, followed by usage then edge-case behavior. Every sentence is load-bearing, though the final niche/shareUrl sentence is dense and could be tightened slightly.

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

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

With no output schema, the description carries the return-value burden and does mention shareUrl implicitly, but it does not describe the overall shape of the priced response (totals, per-item breakdown, fee line). Given the tool's simplicity and full schema coverage, this is nearly complete but leaves a small gap around what the quote returns.

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

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

Schema description coverage is 100% with a single nested 'items' parameter, so the baseline would be 3. The description goes beyond the schema by explaining the pricing consequence of the niche field (outlet niche price, refusal where unsupported, absence of shareUrl), which adds real semantic meaning to how 'niche' affects the 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?

The description states a specific verb and resource ('Price a set of placements exactly as the store's checkout would, including the 3.5% processing fee') and clearly differentiates itself from the order-creating siblings by framing itself as the pre-order pricing step. An agent can tell this apart from create_order, plan_placements, and compare_placements 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?

'Use this to give a client a total before creating an order' gives clear situational context and implicitly routes to create_order as the follow-up. It lacks an explicit negative case or named alternative for when NOT to quote (e.g., when availability is unknown), so it falls just short of the top band.

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

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

Beyond the annotations, the description discloses that the audit uses public data only, requires no logins or analytics access, installs nothing, is reviewed by a person, and does not return a score. These are important behavioral traits that the annotations do not cover, and there is no contradiction with readOnlyHint=false, openWorldHint=true, idempotentHint=false, or destructiveHint=false.

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

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

The description is front-loaded with the core purpose and scope, then layers in constraints, alternative routing, and return behavior. Every sentence adds useful information, and there is no wasted 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 six-parameter tool with a nested contact object, an enum track, and no output schema, the description covers what is necessary: what is audited, what data is used, how the result is delivered, and that no score is returned. It is complete enough for an agent to call 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 high at 83%, so the schema already documents most parameters including nested contact fields and the track enum. The description does not add parameter-level meaning beyond what the schema provides, which matches the baseline of 3 when the schema does the heavy lifting.

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

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

The description states a specific verb and resource: 'Request a free audit' of AI visibility. It also distinguishes the request from submit_campaign_brief and implies a human-reviewed process rather than an instant score, so an agent can tell it apart from related siblings.

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

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

It gives explicit when-to-use guidance: 'Use this when a client wants to know why assistants do not mention them,' and names an alternative: 'use submit_campaign_brief when they already want to buy media.' It also clarifies that the audit is free and non-committal, which prevents misuse.

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 non-idempotent, but the description adds real substance: approving the draft sends it to editors and cannot be undone, approving the outline starts the draft, and there is a hard limit of two change requests per piece. These are behavioral constraints an agent cannot infer from the annotations alone.

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

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

Three sentences, no filler, and the object of the operation is front-loaded. The opening clause ('The client's decision on one publication's latest outline or draft from get_client_order') is slightly dense but earns its place by anchoring the tool to its data source.

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

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

For a five-parameter mutation tool with no output schema and only 60% schema description coverage, the description supplies the prerequisites (explicit client consent), irreversibility, and rate limit. It omits any mention of what the call returns or error behavior, but otherwise an agent has enough to invoke it correctly.

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

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

Schema coverage is 60%, so the schema documents orderLink, feedback and publication. The description compensates by explaining what the action enum actually triggers depending on piece (approve outline -> draft starts; approve draft -> editors; changes -> limited to two). It adds little about orderLink/feedback formats, but the enum semantics are meaningfully clarified.

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 operation: recording the client's approval or change request on one publication's outline or draft, and ties it back to the get_client_order resource. It is clearly distinguishable from content-creation siblings like submit_content or submit_article_draft, 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?

Strong procedural guidance: show the client the full text and get explicit go-ahead first, and changes can only be requested twice per piece before the team takes over. It routes the agent to get_client_order as the source of the content, but does not contrast itself against the other submit_* siblings that might look similar.

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 read-only, non-destructive, and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: results are paged, defaulted to highest Domain Authority first, mirror get_placement's field set, and gain nichePrice when a niche filter is applied. It does not mention rate limits or what the response looks like when zero filters are supplied.

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

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

Purpose is front-loaded in the first clause, the filter surface follows, and return behavior closes the description. Two dense sentences with essentially no filler, and the long filter list is earned by 18 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?

With no output schema, the description carries the burden of explaining returns and does so: paging, default ordering, per-result fields, and the nichePrice addition. For a broad search tool this is close to complete, though it omits behavior with no filters applied and any result-count or rate considerations.

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

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

Schema coverage is 100% and every parameter already carries a description, so the baseline is 3. The description's filter enumeration largely restates the schema, including the niche/nichePrice and price-sort interaction that is already documented on the niche parameter, adding little beyond what structured data provides.

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

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

States a specific verb and resource ('Search the publisher network for editorial placements') and enumerates the filterable dimensions, so an agent knows exactly what the tool does. It implicitly contrasts with get_placement via 'each result carries the same fields as get_placement', but never names the closer siblings (compare_placements, plan_placements, quote_placements) to differentiate itself.

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

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

Usage is only implied: the description is a catalog search, so an agent can infer it is for discovery, and the niche/price interaction hints at a planning workflow. However, there is no explicit when-to-use, no when-not-to-use, and no routing to alternatives such as compare_placements or quote_placements for follow-up steps.

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 write, destructive, non-idempotent. The description adds the ownership-proof mechanism (orderId plus the order's billing email), the paid-order requirement, and the downstream workflow — a human editor reviews before publishing. It also flags an operational trap ('a wrong pairing reads exactly like a missing order'), which is behavior an agent could not deduce from annotations or schema.

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

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

Five dense sentences, front-loaded with purpose and the ownership rule before the editorial and communication constraints. Every sentence carries a distinct instruction (proof of ownership, payment precondition, human review, client-facing wording, confirm-before-filing) with no filler.

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

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

For a destructive, non-idempotent mutation with six parameters and no output schema, the description covers preconditions, the identity check, downstream handling and the messaging constraint. Output shape is not needed since the concerning behaviors are all inbound, and 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 the baseline is 3, but the description adds genuine meaning for the orderId/email pair by framing them as a joint ownership proof rather than two independent lookups. It explains the failure mode of a mismatched pair, which the schema does not. The draft, title, authorName and referredBy fields are left to 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: filing a client's article draft against a paid order, which is more precise than the name alone. It implicitly separates this from generic siblings like submit_content and submit_campaign_brief by specifying an already-paid order, but it never names an adjacent alternative, so an agent must infer the boundary.

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 real preconditions: the order must be paid, and the draft text must be confirmed with a human before filing. It also states what not to do (don't claim the piece is published or scheduled). It stops short of naming an alternative tool or the case where a sibling like submit_content should be used instead.

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 say readOnlyHint=false, openWorldHint=true, non-idempotent, non-destructive. The description adds crucial context beyond that: nothing is purchased or committed, it opens a conversation, a human prices it and replies, and confirmation with a human is required before sending. It also explains the completeness score and the missing-details list. Slightly short of 5 because it doesn't state what happens on a duplicate submission or the non-idempotent consequence.

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

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

Front-loads purpose and sibling differentiation, then behavior, then selection guidance. Dense but each sentence earns its place. Slightly overlong with multiple clauses in the final sentence, but no padding.

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

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

Covers purpose, routing, non-commitment behavior, response contents, and human-confirmation requirement for a 9-parameter nested-object tool with no output schema. Complete enough to invoke correctly, though it doesn't describe error or validation behavior on the nested contact object.

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

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

Schema coverage is 89%, so the schema documents most parameters. The description adds meaning the schema does not: that capabilities are for known outcomes and channels are for known channels, and the routing to list_capabilities and search_placements/list_channels. This is useful disambiguation rather than restatement.

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 ('Submit a paid media brief'), and explicitly distinguishes itself from the sibling create_order by naming it and the condition that selects it (press placement, fixed price). An agent can route between the two without opening either schema.

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

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

Gives explicit when-to-use (advertising campaigns across display/video/CTV/social/search/audio/OOH, priced per campaign) and when-not-to-use, naming create_order and the alternative condition. Adds selection guidance between capabilities vs products vs both.

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 annotations already declare destructiveHint=true and idempotentHint=false. The description adds useful behavioral context beyond that: re-sending replaces the earlier version, the team writes an outline afterward for approval, and the client should confirm the content first. It does not describe failure modes or permissions, but the replacement and workflow details are valuable.

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 six sentences and front-loads the core definition before moving to requirements, timing, and workflow. It is not bloated, though it could be slightly tighter by consolidating the content requirements into fewer clauses.

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 10-parameter mutation tool with no output schema, the description covers the key context: content inputs, publication scope, submission timing, replacement behavior, and downstream outline approval. It is complete enough to call correctly, though it does not cover errors or return 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 coverage is 100%, so the baseline is 3. The description adds meaning by stating that at least identity and article substance, or a client draft, are needed, and by clarifying that the publication parameter is required when an order has multiple publications.

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 and title together indicate submitting the content a publication's article will be built from, and it clarifies that each publication on an order needs its own content. It does not explicitly distinguish this tool from the sibling submit_article_draft, but the core purpose is clear.

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

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

It states a clear condition: only while the publication is waiting for content, and sending again replaces the earlier version. It also advises confirming with the client before sending. It stops short of naming alternatives such as submit_article_draft, so the agent gets context but not sibling routing.

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