The Profound Agency

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely useful behavior beyond that: answers are 'quoted or read from live data, never generated' and 'answer is null when the site does not cover it', disclosing provenance and the failure mode.

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 opening clause, and the longer topic enumeration earns its space by delimiting scope. It is a single dense sentence with minor list padding but no wasted framing.

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 return-value semantics and does so: it explains sources (source URLs), answer provenance (quoted/live, not generated), and the null case. Only the decision boundary against sibling tools is missing.

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

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

Schema description coverage is 100% and there is a single parameter with an example in the schema, so the baseline is 3. The description reinforces the expected input format ('a question in plain words') but adds no meaning beyond the schema example.

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 concrete verb (answer a question) and resource (theprofound.agency content) and enumerates the topic areas it covers, giving a clear sense of scope. However, it never distinguishes itself from overlapping siblings such as can_i_advertise (explicitly listed as covered) or list_capabilities, so an agent cannot tell which entry point to pick.

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

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

The topic list implicitly signals when the tool is applicable, and the null-answer clause signals its limits, but there is no explicit when-to-use/when-not guidance and no routing to alternatives despite heavy sibling overlap with can_i_advertise and the listing tools.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: that the answer is guidance only because policies change without notice and should be confirmed with the team.

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 core purpose and follows with parameter guidance and the guidance caveat. The long category enumeration is illustrative but slightly bloats an otherwise tight description.

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, the description covers purpose, parameter behavior, and the authoritative-vs-guidance caveat. It stops short of describing the shape of the returned limits, but that 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 coverage is 100%, so the baseline is 3, but the description adds semantics the schema lacks: the behavior of omitting 'channel' (checks every channel) and the state-level scope of 'state', plus concrete category examples. It adds value beyond the structured fields.

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 decision it answers (whether a restricted category can run on a channel) plus the constraints it returns (age gates, targeting, pre-approval). The enumerated categories make the scope unambiguous and distinguish it from generic sibling tools like list_categories or review_content.

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 how to drive it: pass a channel slug from list_channels to check one, omit it to see every channel, and add a two-letter state for state-level rules. It also names list_channels as the source of slugs, though it doesn't state when not to use this tool.

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

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

Annotations already cover readOnlyHint and openWorldHint, so the bar is lower, and the description still adds real value: it explains the email as an authorization gate ('stops anyone reading anyone else's order'), states the awaiting-payment return shape, and discloses an edge case (swept unpaid orders report as not found). It stops short of noting rate limits or pagination, so a 4 rather than 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 sentences, each doing distinct work: purpose, authorization requirement, and return behavior. Purpose is front-loaded and there is no filler or restatement of the name.

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

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

There is no output schema, so the description must carry return-value context; it does so partially by describing the unpaid state and the not-found edge case. Coverage is good for a two-parameter read tool, though it does not describe the general paid/successful response shape.

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 goes further by explaining why email is required (security match against the billing email) rather than merely repeating that it is the billing email, adding meaning beyond the schema's own description text.

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

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

The description names a specific resource and the exact data it returns: 'Payment and fulfilment state for an order you created.' That is concrete and actionable. It does not, however, explicitly differentiate itself from the sibling get_client_order, leaving the agent to infer the distinction.

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

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

The phrase 'for an order you created' and the required billing email imply the usage context (post-create lookup by the placing party). There is no explicit when-to-use or when-not-to-use guidance and no named alternative such as get_client_order, so the agent must infer the 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 and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that: it enumerates what is compared and computed, and explicitly frames output as figures only with no judgment, which shapes how the agent should present and act on results.

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 tight sentences, front-loaded with the comparison scope and dimensions, then the id source and the interpretation caveat. No filler; every clause carries information an agent needs.

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

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

With no output schema, the description compensates well by listing the compared fields and derived metrics. It is nearly complete for a read-only comparison tool; only edge behavior (e.g., invalid or duplicate ids) is 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% and the single ids param already documents both its source and cardinality (minItems 2, maxItems 4). The description restates root-of-ids from search_placements but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

Names a specific verb (compare) and resource (placements/publications) and enumerates the exact dimensions compared — price, DA, rating, turnaround, region, disclosure, indexing, categories — plus derived winners (cheapest, fastest, highest authority). This clearly differentiates it from search_placements and get_placement.

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 ids from search_placements" gives an explicit prerequisite and the source of input, and "two to four publications" constrains the use case. It stops short of naming an alternative or a when-not condition, but the workflow context is unambiguous.

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

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

Annotations only declare readOnlyHint=false and openWorldHint=false; the description adds the crucial behavior that no meeting exists until the human confirms, that the link must be presented rather than embedded, and that name/email must not be put into the URL. That is real behavioral disclosure beyond 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?

Two tight sentences: the first states what is produced, the second states the required handling. Every clause earns its place, and the prohibitions are front-loaded where they matter.

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 compensates by specifying the return shape (URL plus name and email as separate fields). Combined with the confirmation workflow, an agent has everything needed to call and use this tool correctly.

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

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

Schema description coverage is 100% and both parameters are documented there, so the baseline is 3. The description adds only that name and email come back as separate fields and are shown alongside the link, which is return-value context rather than new parameter meaning.

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

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

The description names a specific resource (the agency's booking URL) and its scope (30-minute meeting), plus what comes back alongside it. It is clear on its own, but it never distinguishes itself from the sibling create_text_link, which an agent must disambiguate without help.

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 unusually explicit: hand the URL to the human, have them enter name and email on the page, and do not treat the meeting as booked. It stops short of naming an alternative tool or stating when a different link type would be preferred over this one.

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 the mutation and open-world profile, and the description goes well beyond them: no payment occurs, the order remains unpaid until human checkout, no account/API key is needed, and unpaid orders are auto-deleted after 72 hours. These are exactly the non-obvious operational facts an agent needs.

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 crucial caveat ('this does not pay for anything') before detail, which is the right ordering for a high-risk misconception. It is slightly long and repeats the 'you are not the payer' idea twice, but each remaining sentence carries distinct operational content.

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

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

For a non-idempotent mutation with nested objects and no output schema, the description covers the human-in-the-loop requirement, the deletion window, and the payUrl return, and names the follow-up status tool. The gap is parameter-level completeness for placedBy/clientReference, which neither schema nor prose fully closes.

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 only 60%, and the description adds essentially no field-level meaning — it never explains items, quantity defaults, placedBy, clientReference, or notes. Its only parameter-adjacent statement implies the contact email matters, which the schema already says far more precisely.

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 a second concrete effect ('return a payment link'). The 'IMPORTANT: this does not pay for anything' clause sharply distinguishes it from anything resembling a payment or fulfillment tool among the 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?

Gives real pre-call guidance ('Confirm the placements and the total with a human before calling this') and post-call routing (send the link, and consult check_order_status before declaring anything bought), naming a sibling explicitly. It stops short of saying when NOT to use it (e.g. to reorder or to check status), but the workflow framing is unusually 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 (readOnlyHint=true, openWorldHint=false) already signal no side effects, and the description adds genuine behavioral context beyond them: nothing is sent until the human taps send, the agent must show the message first, and it must never send on the human's behalf without go-ahead. That human-in-the-loop contract is not derivable 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?

Three sentences, each earning its place: the what/return, the safety contract, and the routing rule. The resource and destination are front-loaded before the constraints.

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

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

No output schema exists, yet the description still explains the return value (message plus sms: link), covers the two required params implicitly through the message content, and specifies agent behavior. Nothing an agent needs to call and use this tool 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% for all three parameters (name, company, message), so the schema already documents each field including the maxLength on message. The description adds no parameter-level syntax or format detail beyond what the schema provides, making 3 the appropriate baseline.

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

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

States a specific action (prepare a text message to the agency), names the target number, and explains the return (the message plus an sms: link prefilled in the messaging app). It explicitly distinguishes itself from the sibling create_booking_link, so an agent can route correctly 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?

Names the alternative (create_booking_link) and the condition that selects it (scheduled call), then states the positive case for this tool (a quick question or asking for a call back). Both when-to-use and when-to-use-something-else are 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 declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds valuable behavioral context: the returned slot structure (start, end, readable label), the 30-minute weekday timezone constraint, and the critical caveat that a slot is not a booking and requires confirmation via create_booking_link.

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 tightly packed sentences: first states scope and return shape, second states the crucial non-booking caveat, third hands off to the sibling. Zero waste, front-loaded.

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?

Complete for a read-only availability checker with annotations covering safety and a description covering return shape, constraints, and the booking handoff. No output schema, but the description summarizes what's returned. Slight gap: pagination/empty-result behavior is not addressed, but not critical here.

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

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

Schema coverage is 100% with clear descriptions for daysAhead (default 7, max 30) and durationMinutes (default 30, range 15-120). The description mentions the 30-minute default but doesn't add syntax beyond what the schema provides, so baseline 3 is appropriate.

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

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

States a specific verb (returns slots) and resource (agency's appointment calendar open slots), with scope constraints (30-minute meetings, weekdays, agency timezone). Clearly distinct from create_booking_link, which is named as the next step.

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 what this tool is for (real open slots) and what it is not (a booking), and names the alternative/successor tool (create_booking_link) with the condition for using it. No ambiguity about when to invoke.

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 openWorldHint=false, so the safety profile is covered. The description adds that results are ordered 'newest first' and that changes are weekly, which is useful context. It doesn't detail pagination, result volume, or what a sync record contains beyond the named 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-loads what the tool returns before listing filters, which aids scanning. Two sentences, no redundancy, though the filter list is somewhat dense and could risk being read as exhaustively complex.

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 change-feed tool with 7 optional filters and no output schema, the description covers purpose, ordering, and the filter set. It stops short of describing the shape of a change record or pagination, but with annotations covering safety and schema covering params, this 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 coverage is 100% with each parameter fully described in the schema. The description names the filter dimensions (date, max price, categories, min DA, additions only, price drops only) but adds no syntax or format detail beyond what the schema provides. Baseline 3 applies.

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

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

States a specific verb+resource (get catalogue changes from weekly syncs) and scopes it to publications added/removed and price changes, newest first. Distinguishable from siblings like search_placements or get_placement which deal with current state rather than change history.

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 clause gives a clear use case: 'watch for new outlets or cheaper placements without re-reading the whole catalogue.' It implies when to use (change monitoring vs full catalogue reads) but doesn't explicitly name which sibling to use for a full read or current placement lookup.

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

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

With readOnlyHint=true and openWorldHint=false already declared in annotations, the description adds meaningful behavioral context: it explicitly states 'Priced per campaign, so no price is returned' and routes the agent to submit_campaign_brief for quotes. It also enumerates the returned content categories. It could go further by noting any authentication or rate-limit concerns, but for a read-only detail tool this is strong supplementary disclosure.

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 three sentences, front-loads the core purpose, and every sentence earns its place by either listing return contents or clarifying pricing behavior. The first sentence is dense but not wasteful. It could be slightly tighter, but the structure is effective.

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 single-resource tool with no output schema, the description fully explains what the returned detail includes (product identity, ad placements, creative formats, targeting options, caveats, capabilities) and explicitly covers the pricing caveat. Combined with annotations covering safety, an agent has everything needed to call and interpret this tool correctly.

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

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

Schema description coverage is 100%, and the single slug parameter is fully documented in the schema ('Channel slug from list_channels, e.g. "geo-targeted-mobile"'). The description itself adds no additional parameter semantics beyond referencing the product concept. This is the expected baseline 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 the specific resource ('one paid media product') and enumerates exactly what the full detail contains: what it is, where ads run, creative formats, targeting, caveats, and capabilities. It also distinguishes the tool from submit_campaign_brief by clarifying that pricing is not returned here. An agent can immediately tell this is a read-only detail fetch for a single 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?

The description gives clear context ('the limits and prerequisites a buyer should know before submitting a brief') and names the alternative for pricing ('submit_campaign_brief gets a quote'). It also points to list_channels as the source of the slug via the schema. However, it does not explicitly state when not to use this tool or any other exclusions, so it falls short of the top score.

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 description adds genuinely non-obvious behaviour beyond the readOnlyHint/openWorldHint annotations: the credential is a private token held only by the client, and an invalid or revoked link surfaces as a missing order rather than an auth error. That failure-mode disclosure is the kind of thing an agent cannot get 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?

Two sentences, no filler, and the return contents are front-loaded before the access caveat. The first sentence is a long comma-list, but every item earns its place by telling the agent what it will receive.

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

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

With no output schema, the description carries the burden of describing return content and does so item by item, plus the auth precondition and error semantics. The one gap is that it never differentiates this from the sibling status-check 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 the baseline is 3, but the description contributes extra meaning about the single parameter: it is client-held, not discoverable by the agent, and its failure mode is ambiguous. That is real semantic value layered on top of the schema's format documentation.

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

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

States a concrete verb and resource and enumerates exactly what the caller gets back (stage, next-step needs, client-submitted content, latest draft, publication). That is far more specific than the name/title. It does not, however, distinguish itself from the very similar sibling check_order_status, which the agent must infer.

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?

"For a paid order" and "Needs the client's private order link, which only they have" imply the caller persona and precondition, so usage is implied. It never names an alternative or says when NOT to use it, and the overlap with check_order_status is left unaddressed.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description still adds substantive behavioral context: the 3.5% checkout processing fee baked into the returned price, the link type semantics ("dofollow" vs "unspecified"), and how dofollowVariantId points to a separate package. It omits error/not-found behavior for an invalid id.

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

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

One front-loaded sentence with no filler, but the long parenthetical listing linkAttributes and dofollowVariantId makes it dense to parse. Every clause earns its place, though it could be split for readability.

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

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

With no output schema, the description carries the full burden of describing returns, and it enumerates the returned fields (price, fee-inclusive price, authority scores, turnaround, disclosure policy, link type, availability, logo, example article). For a single-parameter read tool, nothing an agent needs is missing.

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

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

Schema coverage is 100% and the schema already gives the format example ("hood-critic"), so baseline is 3. The description adds real meaning by identifying the id as the slug returned by search_placements, clarifying provenance beyond the schema's bare type/description.

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 by its id") and immediately anchors the id to its source ("the slug from search_placements"), which separates it from search_placements and compare_placements. An agent knows exactly what it gets back 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 tells the agent where the required id comes from (search_placements), which establishes the natural call sequence. It does not state when to prefer this over siblings like compare_placements, get_availability, or quote_placements, nor any exclusions.

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false). With no output schema, the description usefully characterizes the return shape: plain-language outcome names paired with the products that deliver them. It does not cover ordering, volume of results, or whether the catalog is static, but adds real context beyond the annotations.

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

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

Two sentences, front-loaded with what is returned and closed with the use case. The example list earns its place by concretizing an otherwise abstract catalog, 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 no-input, read-only lookup with no output schema, the description supplies exactly the missing pieces: what the entries contain and when to reach for it. Nothing an agent needs to invoke it correctly is 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?

The tool takes zero parameters, so the baseline of 4 applies. There is nothing for the description to disambiguate and it introduces no misleading parameter-like language.

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

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

The description names the resource precisely — outcome-to-product mappings rendered 'in plain language with the products that provide it' — and gives concrete examples (geo-fencing, retargeting, identity resolution). The verb is only implicit (it never says 'list' or 'return'), and it does not explicitly distinguish itself from sibling list_* tools like list_categories or list_channels, but an agent can still tell what it yields.

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, actionable usage context: a discovery/translation step before asking for specific products. No alternative tool is named and no exclusion is stated, so the routing guidance is good but not exhaustive.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety profile is covered. The description adds that counts are included, which is useful, but doesn't cover pagination, return shape, or rate limits. Acceptable but minimal beyond 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?

Two short sentences, front-loaded with what it returns and then the use case. No waste.

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 list tool with annotations covering safety, the description supplies purpose and a concrete use case. It could mention output shape or pagination, but the tool is simple enough that this is nearly complete.

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

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

Zero parameters, so baseline is 4. Description appropriately focuses on output rather than parameters.

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

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

Specific verb+resource: 'Every category in the network with how many publications carry it.' Clearly describes what is returned, distinguishing it from sibling list tools like list_channels and list_capabilities.

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 use it to pick valid values for search_placements, which is a concrete usage context. Does not state when not to use it or name alternative lookup paths, but the guidance is actionable.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely new context beyond that: it discloses the shape of the return value (each product with a one-or-two-sentence description) and the slug semantics that link this output to submit_campaign_brief. It says nothing about ordering or caching, but for a small fixed catalog that is minor.

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

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

Two sentences, front-loaded with what the tool returns and followed by the two highest-value facts: where the slugs are consumed and which sibling to prefer for detail. The channel enumeration is slightly long but earns its place by signaling coverage breadth; 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?

With no output schema, no parameters, and annotations covering safety, the description is close to sufficient: it describes the entries returned, the slug field's meaning, and routes detail lookups to get_channel. Only minor gaps remain (exact output structure beyond slug/description, ordering), which are low-stakes for a fixed catalog.

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 per the baseline this is a 4. The description correctly spends no words on parameters and instead uses the space to explain the output fields (slug + description), which is the more useful information for a no-arg list 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?

The description conveys a specific resource — the catalog of paid media channels, enumerated (Meta, CTV, mobile, search, audio, OOH) — and makes clear each entry carries a short description and a slug. The listing action is implied by the name rather than stated as a verb, but an agent can immediately tell what comes back and how it differs from get_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?

'The slugs are what submit_campaign_brief takes as channels' states the downstream use case explicitly, and 'Use get_channel for the full detail of one' names the alternative with the condition that selects it. Both when-to-use and when-to-use-something-else are covered.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description still adds real value beyond that: the 3.5% processing fee is baked into the budget, the shareUrl opens the store with placements pre-loaded in the cart, and 'the plan recommends, it reserves nothing' pre-empts the wrong assumption that this creates an order.

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

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

Three sentences, front-loaded with what the tool produces before the usage condition and the output/behavior caveat. No filler, no repetition of the tool name.

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

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

There is no output schema, but the description names the key return artifact (shareUrl → cart) and clarifies that nothing is reserved, which is what an agent needs to avoid mis-sequencing a follow-up create_order call. Complete for a read-only planning 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%, so all five parameters (including count default 5, minDomainAuthority, and budget exclusiveMinimum) are already documented in the schema. The description only restates the goal/audience/budget triad and the fee-inclusive budget meaning, which the schema itself already states.

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

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

States a specific verb and resource ('Recommend a set of publications') plus the exact inputs that drive the recommendation (goal, audience, budget). The added scope note that results are already quoted and fee-inclusive distinguishes it from a raw listing or quote tool.

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

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

'Use this when a buyer says what they want to achieve and what they can spend, rather than naming publications' gives a clear when-to-use condition and an implicit when-not (the named-publication path). The sibling that handles the named-publication case (quote_placements) is not named explicitly, so the agent must infer it.

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

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

Adds real context beyond annotations: it is free, stores nothing, returns no score, and reads only public pages. Annotations only cover readOnly/openWorld. It stops short of describing latency, rate limits, or output format, but for a lightweight instant check the disclosure is substantive.

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-packed sentences: what it checks front-loaded, then cost/storage constraints and the routing to request_audit. Every clause earns its place 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 1-param read-only tool with no output schema, the description covers scope, the five checks, privacy behavior, and the sibling alternative. Lacking only a hint of what the response looks like, which is minor given the schema's simplicity.

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?

One parameter at 100% schema coverage (baseline 3). The description adds that the check is performed 'from its public pages', clarifying the scope of the single 'website' input beyond the schema's domain-format note.

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 precise verb+resource ('check whether AI systems can read a website') and enumerates the five concrete checks performed. Names the sibling request_audit and distinguishes its scope (full audit, scored, human-reviewed).

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 to the alternative: use request_audit for the scored, human-reviewed full audit. The contrast between 'free, no score, nothing stored' and the paid full audit makes the selection condition unambiguous.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, yet the description still adds real behavioral context: the 3.5% processing fee is baked into the number, nothing is reserved, and unavailable placements are refused rather than silently adjusted. These are behavior facts an agent cannot get from the 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?

Four short, front-loaded sentences with no filler: pricing behavior first, then when to use it, then the non-reservation caveat and the failure mode. Nothing is padded, though the sentences are terse fragments rather than maximally economical.

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, single-parameter quoting tool with no output schema, the description covers purpose, cost semantics, side-effect absence, and error behavior. It could still say what the response contains (a total, per-placement breakdown, currency), which is the only meaningful 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 there is a single nested 'items' parameter whose id/quantity semantics are fully documented in the schema. The description adds no parameter-level detail (e.g., that quantity accepts multiples or how negative quantities behave), so it sits at the baseline.

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

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

States a specific verb and resource ('Price a set of placements') and adds the scope detail that checkout fees are included. It implicitly distinguishes itself from create_order by saying it is used to quote 'before creating an order', though it never names an actual sibling tool.

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

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

Gives clear usage context ('give a client a total before creating an order') and an important exclusion ('Quoting does not reserve anything'). It does not address when to prefer compare_placements, plan_placements, or get_availability instead, so the alternative-routing is incomplete.

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 only flag non-read-only, non-idempotent, open-world, non-destructive; the description adds the consequential detail annotations cannot convey — that approving the draft is irreversible ('cannot be undone'), the downstream routing to editors, and the two-changes-per-piece cap. That is exactly the extra context a mutation tool needs.

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 action, then the irreversible consequence, then the safety prerequisite and the retry cap. No filler; every clause routes the agent's behavior.

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

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

For a 4-parameter mutation tool with no output schema, the description covers preconditions, irreversible effects, downstream routing, and a call-count limit. An agent has all the information needed to decide whether and how to invoke it.

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

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

Schema coverage is 50%: feedback and orderLink are documented in-schema, and the enums for piece and action are self-describing. The description adds business meaning (what 'approve' vs 'changes' trigger at each piece stage) but does not explain the action enum or the orderLink format beyond the schema. With coverage at the midpoint, this is a solid 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 precise verb and resource: recording the client's decision (approve/changes) on an outline or draft produced by get_client_order. The two effects — approving an outline starts the draft, approving the draft sends it to editors — make it impossible to confuse with sibling submit_* or get_client_order tools.

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

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

Gives explicit preconditions ('Show the client the full text and get their explicit go-ahead first') and a hard limit ('Changes can be asked for twice per piece; after that our team works with the client directly'), which tells the agent both when to call and when to stop calling. It also points at the upstream tool (get_client_order) that produces the artifact under review.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real behavioral detail beyond that: results are paged ('returns a page of matches'), default ordering is highest Domain Authority first, and the result shape mirrors get_placement. It omits whether results are cached/rate-limited, which is minor for a read-only search.

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 filters then return behavior; no filler. It could have been tighter by folding the filter list, but each sentence carries distinct information.

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

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

For a 15-parameter, zero-required, read-only search tool with no output schema, the description adequately covers what can be searched, how results are ordered and paged, and what a result looks like. It stops short of naming the sort enum values or paging limits, but those are fully documented in the schema.

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

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

Schema description coverage is 93%, so the schema already documents nearly every parameter, including the dofollow caveat and the paging fields. The description's filter enumeration ('price, Domain Authority, Domain Rating, category, region, turnaround... link type and availability') largely restates what the schema already conveys, adding little beyond the default-sort behavior that the schema omits. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Search the publisher network for editorial placements') and immediately enumerates the filterable dimensions, which distinguishes it from the single-record sibling get_placement and from comparison tools like compare_placements and quote_placements.

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 mention that 'each result carries the same fields as get_placement' implies this is the bulk-discovery counterpart to the single-placement lookup, but the description never states when to search versus when to call get_placement, get_availability, or compare_placements directly. Usage is implied rather than prescribed, and no exclusions or prerequisites are given.

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 mark this as a non-read-only, non-idempotent, open-world write; the description adds substantial context beyond that: the paid-order requirement, the ownership-proof pairing, that a human reviews/approves before publication, and the explicit caution never to tell the client it is published or scheduled. That is meaningful behavioral guidance the agent cannot get from the annotations.

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

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

Front-loads the core action and then layers prerequisites and cautions in short sentences. Mostly earns its length, though "an unpaid order has bought nothing yet" restates the paid requirement already stated in the prior clause.

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 submission tool with no output schema, the description covers the essential behavior: prerequisites, ownership proof, and the human-review/approval pipeline. It does not describe what the call returns (e.g., confirmation or draft status), which would fully close the loop.

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 a cross-parameter rule the schema does not state: orderId and email must actually correspond, since a mismatched pair is indistinguishable from a missing order. This genuinely extends parameter meaning, though per-parameter formats 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?

Uses a specific verb and resource: "File the client's article draft against a paid order." The scope (a submitted article draft tied to an order, routed to editorial) is concrete and distinct from a generic content submission. It does not name a sibling such as submit_content to sharpen the contrast, so it falls short of 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?

Gives clear preconditions for use: the order must be paid and the order id + billing email must be a valid pairing, with a note on how a wrong pairing looks ("reads exactly like a missing order"). It also instructs to confirm the draft with a human before filing. No sibling alternatives are named, so it is clear context without explicit when-not alternatives.

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

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

Annotations 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?

Annotations declare readOnlyHint=false and idempotentHint=false; the description aligns with these by stating that sending again replaces the earlier version and by disclosing the downstream step (an outline is written for client approval). It never contradicts the hints, but it does not address what happens to a prior submission if the order has moved past the waiting state.

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, each carrying new information (source, minimum content, timing, resend behavior, confirmation rule), with the payload description front-loaded. Slightly telegraphic phrasing ('What the article should be built from') costs a little clarity but nothing is wasted.

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

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

For a 9-parameter mutation tool with no output schema, the description covers intake requirements, timing constraints, resend behavior, and the resulting review step. It is complete enough to invoke safely, with only the post-waiting-state behavior left 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%, so the baseline is 3. The description adds real meaning beyond the schema: it explains the minimum viable submission ('needs at least who they are and what the article should say, or a draft of their own'), which clarifies the otherwise loose required-parameter set of one.

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 ('submit_content' described as sending the client's article content) and immediately bounds the scope: it is what the article is built from, 'the same as the form on the client's order page.' An agent can distinguish this from submit_article_draft and review_content from the description alone.

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

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

Gives an explicit precondition ('Only while the order is waiting for content') and a workflow rule ('Confirm the content with the client before sending'), plus resend semantics. It does not name the closest sibling (submit_article_draft) as an alternative, so it stops short of full routing guidance.

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