Cleotic

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

Annotations already declare the safety profile (readOnly=false, destructive=false), and the description goes well beyond them: it discloses the state transition to watching, the cost model (track_prompts consumes an active prompt of plan capacity per question plus model budget; draft_outreach consumes a Content Studio generation), and a key side-effect guarantee ('Cleotic never sends it'). This is exactly the behavioral context an agent needs before mutating.

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 the sibling contrast before enumerating actions, then closes with cost. Dense but nearly every clause earns its place; the action-by-action list is long but necessary given five undocumented enum values.

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?

An output schema exists, so return values need no explanation. Given a 5-param mutation tool with plan-capacity side effects, the description covers purpose, alternative routing, per-action meaning, cost, and a side-effect guarantee — 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?

Schema coverage is 80%, so brand, opportunity_id, suggestion_ids and idempotency_key are already documented. The description compensates for the one gap that matters: the action enum values carry no per-value schema description, and the description defines all five. That is meaningful added semantics above 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+resource ('Record or start an opportunity's play') and immediately gives the resulting state change ('moves it to watching'). It also names the sibling it replaces (update_opportunities), so an agent can distinguish it 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?

Explicitly says to use it rather than update_opportunities 'whenever the play was done', and then spells out the selection condition for each of the five actions (fix_shipped, pitched, optimised, track_prompts, draft_outreach). When-to-use and the alternative are both 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?

Adds behavior beyond the annotations: the lifecycle consequence of completing all questions (plan is built) and the pending-until-visible state transition, plus the model-budget cost. Annotations cover mutation/open-world profile, but the description usefully supplies the async state and cost context they don't.

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

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

Three tight sentences, front-loaded with the action and followed by the lifecycle consequence and cost. No filler, though the phrasing is slightly compressed in places.

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 an output schema present, return values need not be spelled out, yet the description still conveys the pending/visible lifecycle and the completion trigger. It is complete enough for an agent to call correctly, with only the lack of explicit alternatives as a minor 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%, so the schema already documents brand, answers, page_id, skip_remaining, and idempotency_key in detail. The description's 'facts only you know' adds tone but no parameter semantics 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?

States a specific verb+resource ('Answer or skip a page's interview questions') and clarifies the scope ('the facts only you know'), which separates it from read-side siblings like get_answer/list_answers. It does not explicitly name an alternative, so it falls just short of a 5.

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

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

Gives clear workflow context: once every question is answered or skipped the plan is built, and the tool returns pending until get_page shows it. This tells the agent where in the pipeline to call it, but it names no conditions for preferring it over siblings or when not to use 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?

Annotations already declare the write/non-destructive/open-world profile, and the description adds genuinely new context: the capacity cost (a brand, a segment, kept prompts from plan capacity) and model budget for first answers plus the site's readiness scan, and the invariant that the primary brand is always kept. This is meaningful behavioral disclosure beyond 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?

Three sentences, all front-loaded with the core create action first, then selection semantics, then prerequisite, then cost. Dense but each clause carries information. Slightly long compound sentences keep it from a 5.

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 an output schema covering return values and annotations covering the safety profile, the description supplies what remains needed: selection semantics, the user-confirmation prerequisite for market, and capacity/model-cost implications. Nothing an agent needs to invoke 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics: an empty list keeps none of that kind, the primary brand is always kept regardless, and market must be user-confirmed and sourced from get_brand_setup. These rules meaningfully augment the parameter docs.

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 combination ('Create the brand from a ready setup's proposals') and implicitly distinguishes itself from start_brand_setup (which creates the setup) and get_brand_setup (which reads proposals). An agent can tell it apart from the sibling save_* tools that persist individual proposals.

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 states the prerequisite to confirm the market with the user first and pass it as market, pointing to get_brand_setup's segment.market and market_label for the code and label. Also explains the keep/discard semantics of the lists. It does not, however, explicitly frame when to choose this over start_brand_setup, 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 declare readOnlyHint=false, destructiveHint=false and idempotentHint=false, so the safety profile is partly covered. However, the description adds nothing beyond the bare action: it doesn't say whether comments are visible to other users, whether they can be edited or deleted, or what happens on duplicate submissions beyond what the schema's idempotency_key text explains.

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 short sentence that is front-loaded with the action. It is efficient, though it is arguably terse to the point of under-specification rather than optimally informative.

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?

An output schema exists, so return values need not be described, and all four parameters are fully documented in the schema. What is missing is context for a mutation tool: visibility of the comment and any usage conditions, leaving the definition adequate but not complete.

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

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

Schema description coverage is 100% and every parameter (body, brand, opportunity_id, idempotency_key) is documented in the schema itself, so the baseline is 3. The description's only contribution, "as you", marginally clarifies attribution but adds no format or constraint detail 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?

The description gives a clear verb+resource pair ("Add a comment to an opportunity") that an agent can distinguish from siblings like get_opportunity or act_on_opportunity. It stops short of differentiating itself from other write tools or stating scope, but the core action is unambiguous.

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

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

There is no guidance on when to comment versus posting via another tool, no prerequisites (e.g. needing a valid opportunity_id from list_opportunities), and no exclusions. The only hint is "as you", which implies the comment is attributed to the calling user.

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 cover the safety profile, and the description adds value beyond them: the tool opens into an 'interview', returns a pending status while questions are written, and consumes model budget. That async/pending behavior and cost disclosure are 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 tight sentences, front-loaded with the action and its sources, then the lifecycle behavior, then the cost. No filler and every 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 create tool with an output schema, the description covers entry paths, the interview/pending lifecycle, and cost. Nothing critical is missing, though a note on the relationship to draft_page and on the eventual non-pending outcome would round it out.

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 a little by framing opportunity_id as the 'content gap opportunity (its draft_content play)' and the question as an alternative initiation path, clarifying how the two optional inputs relate rather than just naming them.

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

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

States a specific verb (Start) and resource (a Content Studio page), plus the two entry paths: a content gap opportunity's draft_content play or a question. It names the follow-up sibling get_page, though it does not contrast itself with the nearby draft_page/redraft_page_section 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?

Explains the two valid ways to initiate a page and directs the agent to get_page to retrieve the interview questions before the plan is built. It stops short of saying when to prefer this over draft_page for an existing page, so the routing guidance is clear 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 the write/open-world/idempotent-false profile, and the description adds genuinely non-structured behavior: the returned public link (an external exposure) and the consumption of plan report capacity plus model budget on narrative plans. It does not explain what happens to capacity on failure or retry, hence not a 5.

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

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

Three short sentences, front-loaded with the action, then the return, then the cost. No filler; each sentence adds a distinct fact.

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?

An output schema exists so return values need not be spelled out, and the schema covers most parameters; the description still conveys the shareable-link outcome and cost. A note on capacity exhaustion or duplicate-report behavior would fully close it out.

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 80%, so the schema already documents from/to defaults, brand resolution, and the idempotency_key replay contract. The description only echoes the date-range concept and adds no syntax or semantics beyond the schema – 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?

Specific verb+resource ('Save a shareable report of the brand's results for a date range') with a clear output ('Returns its public link'). It is distinguishable from siblings like list_reports and revoke_report, though it never names an alternative to sharpen 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?

Implies the usage context (producing a shareable snapshot over a date range) and gives plan-capacity cost guidance, but offers no explicit when-to-use/when-not or routing against list_reports or revoke_report.

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 destructiveHint=true and readOnlyHint=false, but the description adds context annotations cannot: irreversibility ('It cannot be restored'), cascade semantics (deleting a segment deletes its prompts and answers; deleting a prompt deletes its answers), and billing effect ('Free, and frees the plan capacity the item used'). This is unusually rich behavioral 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?

Front-loaded with the action and the one-ID rule, then cascade effects, then alternatives. Every sentence carries information, though the trailing 'Free, and frees the plan capacity the item used' is a slightly appended billing note rather than a core fact.

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 multi-target tool with an output schema already covering return values, the description supplies the missing pieces an agent needs: mutual exclusivity of the ID parameters, irreversibility, cascade blast radius, and escape hatches. Nothing material is 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 description coverage is 100%, so per-parameter meaning is already documented (baseline 3). The description adds a genuine cross-parameter constraint not expressible in the schema: exactly one ID must be supplied. It does not, however, elaborate on the brand/idempotency_key pairing beyond what the schema 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?

The description states a specific verb ('Delete') and enumerates exactly which resources are deletable (competitor, segment, prompt, page, report), plus the constraint 'pass exactly one of its IDs'. It is immediately distinguishable from save_competitor, save_segment, save_prompt and revoke_report, which it names.

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-not guidance and routes to alternatives: pause via save_competitor/save_segment/save_prompt to keep history, or revoke_report to kill only a report's link. The selection conditions are stated, not inferred.

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 meaningful behavior beyond annotations: the call is asynchronous and returns 'pending' with partial progress, and it consumes one Content Studio generation plus model budget, a real cost the annotations do not convey. Annotations already cover safety/mutability, so this disclosure of async semantics and budget cost is a genuine value-add.

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

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

Three short sentences, each earning its place: the action, the return/follow-up behavior, and the cost. The operation itself is front-loaded before the caveats.

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?

The description covers the action, the readiness prerequisite, the async pending pattern, the follow-up tools, and the cost. Since an output schema exists, return-value detail need not be repeated here, so 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 description coverage is 100%, and the schema itself explains brand resolution, page_id sourcing, and idempotency-key replay semantics in detail. The description adds no parameter-level information beyond what the schema already provides, so the baseline 3 is correct.

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 (write the draft) and resource (a page's ready plan, section by section), which clearly distinguishes this bulk page-drafting operation from the sibling redraft_page_section and from create_page. It does not explicitly name those alternatives, so it falls just short of a 5.

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

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

Gives a clear precondition (the page must have a *ready* plan) and directs the agent to the right follow-up tools, get_operation or get_page. There is no explicit when-not clause, but the readiness gate effectively defines the context for use.

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, idempotent, openWorld, non-destructive, so the safety profile is covered. The description adds genuinely new behavior: connected=false when tracking is not set up, and that only pages and evidence are paged while summary is not.

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 resource, then view semantics, then the paging caveat. The telegraphic style is dense but every clause carries information; nothing is redundant with the schema.

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

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

With a full schema and an output schema present, the description need not explain parameters or returns. It fills the remaining gaps — view semantics, tracking-not-set-up handling, and paging scope — leaving little an agent must infer.

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 beyond it by explaining what each view value actually yields and by clarifying the paging applicability per view, which the enum alone does not convey.

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 (AI crawler visits and AI referrals to the brand's site) and clarifies the data source (its tracking), plus the connected=false signal. No sibling tool covers AI traffic, so the agent can distinguish it immediately.

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 enumerates the three view modes and what each returns (summary totals, pages per-page, evidence individual visits), which effectively guides mode selection. It does not name explicit alternatives or when-not-to-use conditions, but no close sibling exists to route against.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint), so the bar is lower. The description adds what the response contains, but since an output schema exists that content is largely duplicated rather than additive. No auth, rate-limit, or error behavior is disclosed.

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 what is returned and followed by the routing rule. No filler and nothing that fails to earn 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 an output schema handling return-value structure and annotations handling the safety profile, the description needs only to state identity and routing, which it does completely. 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?

There is a single parameter with 100% schema description coverage, so the schema already documents answer_id fully. The description reinforces its provenance ('an answer_id from list_answers'), which adds a little origin context but no format or syntax detail 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 (get) and resource (one AI answer) and enumerates the payload contents (brands, recommendations, ranked list, outcome, citations). This clearly distinguishes it from the sibling list_answers, which is named explicitly.

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

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

Gives explicit routing: use this to read a single answer_id obtained from list_answers, and use list_answers instead to scan many answers. Both the when-to-use and the alternative are stated with no inference required.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds that this is a single aggregated call whose answer metrics can be narrowed by a segment, but discloses nothing further about cost, latency or ordering beyond what structured fields provide.

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 aggregation scope is front-loaded ahead of the alternative-routing sentence. The first sentence is long and comma-chained, but every listed metric carries information rather than 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?

With an output schema present, return values need not be described, and the annotations cover safety; the description supplies scope, sibling routing and the segment effect, which is enough for correct invocation. Minor gaps such as retention/plan-limit behavior are already handled inside the parameter schema, so nothing critical is missing.

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

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

Schema description coverage is 100%, so date, brand and segment semantics (defaults, 180-day window, ID-or-name resolution) are already fully documented in the schema; the baseline is 3. The only added meaning is 'A segment filters the answer metrics', a marginal clarification of the segment parameter's effect.

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 ('The brand's Overview in one call') and enumerates the returned dimensions: visibility, share of voice, recommendation, competitor standing, readiness, traffic, inbox and Content Studio status. It explicitly names the siblings it is not (get_perception, list_citations, get_ai_traffic, get_readiness), so an agent can distinguish aggregation from single-slice tools without opening a schema.

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

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

Gives explicit routing: 'For one slice in depth use get_perception, list_citations, get_ai_traffic or get_readiness' — the condition (single-slice depth vs. all-in-one) that selects the alternative is named. It does not state a when-not case or prerequisites, which keeps it short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by saying it exposes the current state before changes and listing the settings returned, though it does not cover auth or rate-limit details.

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 two tight sentences, front-loads what settings are returned, then gives usage and sibling routing. Every clause earns its place and nothing is redundant.

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 an output schema present, the description need not explain return structure. It provides enough purpose, usage, and sibling differentiation for a one-parameter read tool whose annotations already cover safety.

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 brand parameter is fully documented in the schema as an ID from list_brands or an exact/unique-prefix name. The description adds no additional parameter syntax or format detail beyond what the schema already provides, so the 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?

The description uses a specific verb (“Read”) and resource (“brand's settings”) and enumerates the exact contents: primary brand, competitors, segments, site tracking/CMS status, brand voice, and Content Studio skills. It explicitly distinguishes itself from get_brand_overview by saying metrics belong there, so an agent can select it correctly among 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 states concrete uses: finding competitor_id and segment values other tools take, and checking current state before changing a setting. It also names the alternative for metrics (“For metrics use get_brand_overview”), giving explicit routing 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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld). The description adds a genuine behavioral nuance beyond them: proposals are only present 'once it needs approval', so the payload is state-dependent. That is useful context an 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?

It is a single compact sentence, so nothing is wasted, but the nested 'progress and, once it needs approval, its proposals' clause plus the trailing relative clause makes it dense and slightly awkward to parse. Front-loading the resource is good; the structure could be cleaner.

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 a rich annotation set and an existing output schema, the description need not enumerate return fields, and it correctly focuses on the setup lifecycle and proposal availability. Only minor gaps remain, such as behavior when the setup is not yet at the approval stage or when setup_id is invalid.

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

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

There is a single parameter with 100% schema description coverage, and the schema already tells the agent the id comes from start_brand_setup. The description alludes to 'a brand setup's' but adds no syntax or constraint detail beyond the schema, so the baseline of 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 the specific resource (a brand setup) and what is retrieved (progress, and its proposals once approval is needed), which distinguishes it from get_brand_overview and get_brand_settings. It is a noun fragment rather than a verb+resource statement, but an agent can still tell what it does.

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

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

Usage is implied: call this to read a setup's progress, and once it reaches the approval stage to obtain proposal_ids. It names approve_brand_setup as the consumer of those ids, but gives no when-not guidance or explicit alternative for reading brand data.

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 as a read-only, idempotent, non-destructive, open-world lookup, so the safety profile is covered. The description adds useful behavioral context about what each mode yields (citations, models, brands named, snippets, trend), but says nothing about retention limits, rate limits, or permission requirements beyond that.

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, zero filler, with the dual-mode structure front-loaded in the first clause. The clipped noun-phrase opener ('One cited source') is slightly less readable than a full verb phrase but is efficient.

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 annotations covering the safety profile and an output schema covering return structure, the description's job is limited to distinguishing the two lookup modes, which it does. Date-window behavior and the required brand come from the schema, so nothing critical is missing.

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

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

Schema description coverage is 100%, so domain, source_id, brand, from, and to are all documented in the schema itself (including where domain and source_id come from: list_citations). The description's domain-vs-source_id contrast is largely a restatement of the schema's own hints, 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?

The description names a specific resource (a cited source) and clearly splits its behavior into two lookup modes — by domain and by source_id — with what each returns. It stops short of using an explicit verb like 'retrieve', but the resource and mode distinction make it differentiable from the sibling list_citations.

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 usage through the mode split (domain → domain-level rollup, source_id → single page detail), which tells the agent how to choose between the two parameter paths. However, it never states when to use this tool over list_citations, nor that brand is required, so the guidance is only 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 already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds only that the target is a 'public' page and that in-page links are valid slugs; it says nothing extra about failure modes or rate limits, and an output schema handles returns.

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

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

Three short sentences, front-loaded with purpose, then input provenance, then the alternative-tool rule. No filler, no repetition of the name or annotations.

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

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

For a single-parameter, read-only fetch with rich annotations and a declared output schema, the description covers purpose, slug provenance, and tool routing. Nothing needed to invoke 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?

Schema coverage is 100% with the slug documented as coming from search_docs, so the baseline is 3. The description goes further by explaining that links inside a page are themselves slugs this tool accepts, which adds a genuine discovery path beyond the schema text.

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

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

States a specific verb (fetch) and resource (one public Cleotic documentation page) and scopes it to a single slug, which cleanly distinguishes it from sibling list/search tools like search_docs and list_pages.

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 search_docs first when you have no slug,' naming the alternative and the condition that selects it. That is exactly the when-to-use guidance an agent needs to pick between the two.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is handled. The description adds a genuinely new behavioral constraint beyond structured data: 'Only the member and connection that made the write can read it,' which warns the agent about per-connection scoping and potential authorization failures. It stops short of describing failure behavior when the operation does not exist or is still pending.

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 front-loaded: the return payload is described first, then the access restriction. Every clause earns its place by telling the agent something actionable.

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?

An output schema exists, so return-value shape need not be explained, and annotations cover the safety profile; the description still usefully names the status vocabulary and the caller-scoping rule. Complete enough to call correctly, with only minor gaps around terminal-state and not-found 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?

With a single parameter at 100% schema description coverage, the schema already fully documents operation_id and its provenance. The description reinforces the polling purpose but adds no new format, syntax, or constraint detail for the parameter itself, 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 verb+resource ('Follow a write') and enumerates exactly what is returned: live status (pending/completed/failed), progress, and retry delay. No sibling tool in the list deals with async operation tracking, so the agent can immediately place it without opening a schema.

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

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

Usage is implied rather than stated: 'Follow a write' plus the schema note that operation_id comes from a write tool tells the agent this is the post-write polling endpoint, and 'how long to wait before checking again' hints at the polling loop. However, there is no explicit when-to-use framing, no statement of when to stop polling, and no named alternative.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds real behavioral value by framing this as a prerequisite read before mutating actions and by disclosing the shape of the returned evidence (who is winning, excerpts, sources, trend, timeline). It stops short of noting any access, latency, or size constraints, but with annotations carrying safety that gap 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 the resource and payload, then the routing guidance. The parenthetical list is dense but each item is a distinct piece of return content rather than filler; slight verbosity keeps it from a 5.

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?

An output schema exists, so return values need not be spelled out, yet the description still previews the payload for planning purposes. For a two-required-param read tool it covers purpose, routing, prerequisites, and content, leaving nothing an agent needs in order to call 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 description coverage is 100% and both parameters (brand, opportunity_id) are documented in the schema, including where to obtain each value. The description adds nothing about parameter format or interaction, 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 names a specific verb+resource ('One opportunity with its evidence') and enumerates the payload contents: evidence, play, tool call, before/after proof, timeline, comments. It also distinguishes itself from list_opportunities and from write siblings act_on_opportunity/create_page, so an agent can identify it without opening a schema.

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

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

It gives explicit sequencing ('Read it before act_on_opportunity or create_page') and an explicit alternative for the browse case ('to browse the inbox use list_opportunities'). Both when-to-use and when-not-to-use are covered, which is rare and directly 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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds useful context beyond that: the draft is returned as Markdown 'in parts when long' (explaining the cursor pattern) and include_preflight notes that checks 'fetch the live page', which is a meaningful side effect. It stops short of detailing rate limits or auth, hence not 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, front-loaded with the returned payload before the workflow routing. The field enumeration is dense but earns its place by telling the agent what to expect, though it borders on a run-on list.

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 tool with an output schema, the description correctly avoids re-explaining return values and instead covers when to call it and the pagination/branching behavior. Only minor gaps remain (e.g., no note on preflight cost or live-vs-draft behavior), but nothing critical is missing.

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

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

Schema description coverage is 100%, so the schema fully documents brand, page_id, cursor, and include_preflight. The description echoes the long-draft pagination idea ('in parts when long') but adds no syntax or format detail beyond the schema. Baseline 3 is correct.

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 ('One Content Studio page') and then enumerates the fields it returns (question, interview questions, plan/sections, checks, Markdown draft, results), so an agent knows exactly what it retrieves. It is clearly distinguishable from list_pages, which it names as the discovery 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?

Explicit workflow routing: 'Read it after create_page to see the interview and plan, and before draft_page; to find pages use list_pages.' This gives when-to-use and names the alternative for the find case, leaving little 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 cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so this is judged on added context. The description adds real behavioral detail: empty-period handling with has_data/latest_analysis_at, a cap on competitors ordered best-first, period-scoped analysis, and a plan-availability caveat — none of which the annotations express.

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

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

A single front-loaded paragraph that leads with what is returned, then layers in the empty-data contract and plan caveat. Dense but every sentence carries distinct information; no filler 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?

With an output schema present, the description need not explain return values, and it correctly focuses on gating (plan availability), empty-result behavior, and period scoping. An agent has almost everything needed; the only gap is explicit sibling routing.

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 period bounds, retention limits, brand resolution, and the max_competitors cap/ordering are already fully documented in the schema. The description restates competitor capping and period scoping without adding syntax 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+resource (perception of the brand and its competitors) and defines the return shape precisely: scores out of 10 per dimension, by model, with evidence quotes and trend. It does not, however, distinguish itself from nearby siblings such as get_brand_overview, so the agent must infer which tool to reach for.

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 useful operational context (analysis is scoped to the period, has_data is false when empty, latest_analysis_at points to a valid period) and warns it is not on every plan. But it never states when to choose this over alternatives like get_brand_overview — usage is implied rather than routed.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description goes beyond them by decoding a data semantic an agent cannot infer: 'null limit = unlimited'. It doesn't discuss freshness/caching of plan data, but the added interpretation earns a 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?

Two sentences, no filler; the content inventory comes first and the usage trigger second, so it is front-loaded correctly. The colon-separated inventory is slightly dense but every item listed is a distinct part of the response and 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 an output schema present, the description is not obliged to describe return values, and it correctly spends its words on what the plan object covers and when checking it matters. Nothing an agent needs in order to call this zero-argument read 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. No misleading parameter language is present.

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 (Read) and resource (the organisation's plan), then enumerates exactly what the payload contains: limits and their use, included features, generation allowance, model budget, and collected models. That enumeration cleanly separates it from neighbours like get_brand_settings and get_brand_overview without the agent 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 concrete trigger: 'Check it before a write that costs plan capacity, a generation, or model budget.' That is a real when-to-use condition rather than generic filler. It stops short of naming an alternative or an explicit when-not, so it lands just under 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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint, so safety and mutability are covered. The description adds that competitor scans are started in the app, not via MCP, which is useful behavioral context. Beyond that, it doesn't disclose pagination behavior or rate limits, though the schema covers pagination.

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 tool's purpose, followed by a compact enumeration of views. It is reasonably concise, though the view list is long and could be slightly more structured (e.g., bulleted). 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?

Given nine parameters (one required), full schema coverage, an output schema, and comprehensive annotations, the description covers each view's return content and notes the out-of-band competitor scan behavior. 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 all nine parameters are already documented in the schema with defaults and constraints. The description maps view values to returned content, which is useful, but adds no syntax or format details beyond the schema. 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?

The description clearly states the tool returns the brand site's AI readiness scan and enumerates the five views (summary, action_plan, pages, history, competitors) with what each returns. It is distinguishable from siblings like get_readiness_finding and run_readiness_scan, though it does not explicitly name 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?

The description gives clear context for each view and notes that competitor scans are started in the app, not through MCP (a useful exclusion). It does not explicitly state when to use get_readiness_finding or run_readiness_scan instead, but the view enumeration functions as usage 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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds the shape of the finding (rationale, fix, failure location), which is genuine context, but says nothing about permissions, scoping to run_id, or pagination behavior.

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

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

Two tight sentences with no waste; the identifying content of the finding is front-loaded and the workflow hint follows immediately.

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 an output schema present, return values need no explanation, and the description covers the tool's content and its link to verify_readiness_fix. It is nearly complete, though the relationship to get_readiness and run_id scoping could be clearer.

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 brand, check_id, run_id, limit and cursor are already documented in the schema. The description only touches check_request_id, and even that repeats the schema text, so it adds little beyond structured data — 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?

The description names a specific resource ('one readiness check') and enumerates its contents (why it matters, drafted fix, where it fails), which distinguishes it from get_readiness (a list) and verify_readiness_fix (a re-check). It does not explicitly contrast itself with those siblings, keeping it short of a 5.

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

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

It implies the follow-up workflow by stating 'Pass check_request_id to follow a verify_readiness_fix re-check', which is useful routing context. However, it never says when to call this versus get_readiness, nor any exclusion or prerequisite, so usage is only 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 already establish readOnly/idempotent/openWorld, so the bar is lower. The description still adds genuine behavior: newest-first ordering, cross-model coverage in prompt mode, mention-in-context in brand mode, and the empty-result case for an unmentioned brand versus prompt_id always returning rows.

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 resource and ordering, then the two modes in parallel. Dense but every clause carries meaning; the final 'while prompt_id shows a prompt's answers either way' clause is slightly tangled but resolves the empty-result ambiguity.

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 an output schema present, return values need not be explained. The description covers the mode switch, ordering, and the empty-result edge case — the pieces an agent needs to call it correctly and interpret results. Date-window and pagination constraints are left to 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 coverage is 100%, so baseline is 3. The description goes beyond the schema by explaining the interaction between brand and prompt_id — which parameter governs which result mode — rather than describing each field in isolation, which the schema already does.

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 the resource (AI answers) and the ordering (newest first), then precisely splits the tool into two modes keyed on prompt_id. This is specific and separable from siblings like get_answer (singular) and answer_page_questions, though the listing verb itself is only implied by the title.

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 core when-to-use decision is spelled out: pass prompt_id to get a prompt's answers across models, omit it to get answers mentioning the brand. No sibling tool is named as an alternative and no explicit exclusions are given, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds a genuinely useful non-schema behavioral trait: brands are returned in name order 'so paging stays steady as brands are added,' which informs pagination tuning. It omits auth, rate limits and response-size caveats like the schema's per-page row reduction.

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 core action and the entry-point guidance are front-loaded, which is good. However, the first sentence is a 40+ word run-on enumerating every returned metric and sub-field ('each with the answers and models behind it...'), which duplicates the existing output schema and adds length without adding selection value.

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?

An output schema exists, so return values need not be explained, and annotations cover the safety profile. Purpose, entry-point role, ordering behavior and the pagination-relevant ordering rationale are all present; only an explicit alternative/comparison with sibling listing 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 coverage is 100%, so all five parameters (from, to, kind, limit, cursor) are already fully documented in the schema. The description adds no syntax, format or default detail beyond what the schema provides, so the 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?

The description states a precise verb+resource ('List the brands and studies you can access') and explicitly frames its role as the entry point ('Start here to find a brand ID'), which distinguishes it from siblings like get_brand_overview that require an existing brand ID. An agent can tell what it returns and why it would call it first.

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?

'Start here to find a brand ID' gives explicit when-to-use guidance for the discovery phase. It implies others such as get_brand_overview/get_brand_settings follow, but never names a when-not condition or an alternative for this specific listing, so it stops short of 5.

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

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

Annotations already cover read-only/idempotent/non-destructive, so the bar is lower. The description adds a non-obvious behavioral fact: 'Only domains and pages are paged,' which tells the agent overview is not paginated. No auth/rate-limit context, but the paging asymmetry is meaningful 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?

Three tight clauses: what it is, then the three views, then the paging caveat. Front-loaded, zero filler, 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 an output schema present, return-format details are unnecessary, and all 10 params are described in the schema. The view semantics and paging note round out the main ambiguities. Minor gap: no guidance on how 'influence' or 'source gaps' are computed, but that is arguably output-schema territory.

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 baseline is 3. The description goes beyond the enum by describing what each view returns (totals by ownership/source type, cited domains with gaps, pages ranked by influence) and clarifies paging applicability, which the schema alone does not convey.

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 ('sources AI answers cite for this brand's prompts') and enumerates the three views it can return, making the scope concrete. It doesn't name a sibling tool to differentiate against, but the citation-specific scope is unambiguous against list_answers/list_prompts/list_pages.

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?

Explains what each view is for – overview for ownership/source-type totals by week, domains for competitor source gaps, pages for influence ranking. That is genuine selection guidance for the main decision (which view). No explicit when-not-to-use or alternative tools are named.

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

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

Annotations already cover read-only, idempotent, non-destructive behavior, so the bar is lower. The description adds context annotations cannot: the returned fields, stage vocabulary, and the semantics of counts.ready_to_win (watching items whose gap has closed). It omits anything about auth or rate limits, but adds real behavioral value over 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?

Two sentences, front-loaded with what the tool returns and then the routing advice. The first sentence is a dense run-on that packs fields, stages and counts together, but 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?

An output schema exists, so return shape need not be re-explained; the 8-parameter schema is fully described. Combined with the explicit follow-up workflow, an agent has enough to call this correctly, though nothing covers the active/view default interaction or pagination caveats.

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 all filtering params (kind, view, stage, segment, assignee, limit, cursor) are documented in the schema itself. The description restates the stage values but adds no syntax, defaults, or interactions 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 (list) and resource (the brand's opportunity inbox) and enumerates its contents: content, readiness, source, traffic and coverage gaps with score, demand, stage and assignee. It also names sibling tools (get_opportunity, act_on_opportunity, update_opportunities), so an agent can distinguish it 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?

Explicitly frames the tool as the entry point: 'Start here to find an opportunity_id, read it with get_opportunity, and change it with act_on_opportunity or update_opportunities.' That is a clear workflow with named alternatives. It stops short of stating when-not to use it (e.g., when the ID is already known).

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 this as a safe, idempotent, read-only listing, so the description's remaining job is to add context, which it does: it discloses what the rows contain (drafting progress, and for live pages AI crawler reads and brand-naming/citing answers) and that lane membership reflects page lifecycle stage. It stops short of describing ordering or how many rows to expect, but that is minor and partly covered by the 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?

A single dense sentence, front-loaded with the verb and resource, followed immediately by the follow-up action. No filler, no restatement of the title, and every clause carries information.

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

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

With an output schema present, the description need not explain the return shape, and it correctly focuses on purpose, lane semantics, and the get_page handoff. Pagination (limit/cursor/next_cursor) is left entirely to the schema, which is acceptable but leaves the listing-lifecycle behavior slightly unstated in prose.

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 earns above baseline by giving semantic meaning to the lane enum values: it explains that 'live' pages surface crawler reads and cited answers, and that needs_refresh signals staleness, which the raw enum strings do not convey.

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 and resource ('list the brand's Content Studio pages') and scopes it by lane. It is immediately distinguishable from get_page, create_page, and draft_page in the sibling list because it is the enumeration tool, and it explicitly frames itself as the entry point ('Start here to find a page_id for get_page').

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 usage context: use this first to obtain a page_id for get_page, and it enumerates the three lane values an agent can filter by. It does not state exclusions (e.g., when to prefer list_brands or search_docs instead), but the routing intent is explicit rather than 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 already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description goes further by disclosing the return shape and ordering (segment, status, labels, monthly AI searches, mention counts), which is 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, zero waste: the first front-loads what is returned and in what order, the second handles routing to siblings. Nothing is redundant or buried.

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?

Output schema exists, so return values need not be spelled out, yet the description summarizes them helpfully. With annotations covering safety and a fully documented schema, an agent has everything needed to call this 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%, so every parameter (to, from, brand, limit, cursor, status, segment) is already documented with defaults, formats, and pagination behavior. The description adds nothing about parameter usage; the fields it lists (segment, status, labels, searches) describe output rather than inputs, 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+resource (brand's tracked prompts) and immediately disambiguates with sort order (highest AI search demand first) and the fields returned. It is clearly distinguished from siblings suggest_prompts and save_prompt, which are named.

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 the tool is for finding a prompt_id for list_answers, and names suggest_prompts and save_prompt as the creation-path alternatives. That covers when to use it and which siblings do the adjacent jobs, though it doesn't state when-not to use it (e.g., versus list_answers' own filtering).

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered by structured data. The description adds return-content context (date ranges, share links) but says nothing about pagination, result volume, or rate limits, so it is only modestly additive.

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, zero filler, with the inventory of the resource front-loaded before the routing guidance for related tools.

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?

Output schema exists, so return values need no explanation, and annotations cover the safety profile. The description is essentially complete for a simple one-param list tool, with only pagination/result-size behavior 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?

One parameter with 100% schema description coverage; the schema already explains that brand accepts an ID from list_brands or an exact/unique-prefix name. The description adds no format or syntax detail beyond that, so the baseline 3 is warranted.

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 the specific resource ('the brand's saved reports') and its scope, plus what the listing carries (date ranges, public share links). It explicitly differentiates from both revoke_report and create_report, so an agent can place it among siblings without opening a schema.

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

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

Gives a concrete when-to-use condition ('find a report to revoke_report') and routes the create case to create_report. The alternative tools and the condition selecting each are named rather than 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 declare the write (readOnlyHint=false) and non-destructive (destructiveHint=false) profile, so the safety bar is lower. The description still adds genuine downstream context that annotations do not carry: the call triggers ongoing tracking of whether AI engines read, mention and cite the URL.

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 action and scope, with the second sentence covering consequence. No filler, no restatement of the title.

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

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

An output schema exists, so return values need no explanation, and the description covers purpose plus the downstream tracking effect. The main remaining gap is routing guidance against sibling tools, which is minor for a narrowly scoped write.

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 brand, page_id, url and the idempotency replay semantics all documented in the schema itself. The description adds no syntax, format, or constraint detail beyond that, 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: recording that a drafted page is live, with the key scope qualifier that it was published outside a connected CMS. An agent can distinguish this from draft_page/create_page, though no sibling is named explicitly.

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

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

Usage is implied by 'a drafted page is live' - you call it after drafting when the page goes live off-platform - but there is no explicit when-to-use, when-not-to-use, or named alternative (e.g. versus a CMS-connected publish path or create_page).

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 carry the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), and the description adds real value beyond them: the asynchronous nature ('Returns pending while it is rewritten') and the cost model ('model budget; no Content Studio generation'). It does not explain what happens to the prior section text or the interaction between the required idempotency key and the idempotentHint=false annotation.

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

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

Three short, front-loaded sentences with no wasted framing; the core action comes first. 'No Content Studio generation' is slightly jargon-dependent, but it still earns its place as a cost caveat.

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?

An output schema exists, so return values need not be explained, and the description still notes the pending status usefully. For a mutation tool with full schema coverage and annotations, the gaps (prerequisites, prior-text fate) are 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 description coverage is 100%, including a full explanation of idempotency_key replay semantics, so the schema does the heavy lifting and baseline 3 applies. The description only gestures at 'steer' generically and adds no syntax or format detail 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: 'Rewrite one section of a drafted page', with the optional steering input named. This distinguishes it from the whole-page sibling draft_page, but it never names that sibling explicitly, so an agent must infer the boundary 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?

Implies usage through 'one section of a drafted page' and 'optionally steered', so the context is inferable, but there is no explicit when-to-use-this-vs-draft_page guidance, no prerequisite (e.g. page must be drafted first), and no 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 declare destructiveHint=true, but the description adds meaningful detail beyond them: the link cannot be restored, the report persists with revoked: true rather than being deleted, and the call is free. It does not address the tension between idempotentHint=false and the idempotency_key parameter, which the schema handles instead.

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

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

Four short sentences, front-loaded with the action, then permanence, then the fallback path, then cost. Every sentence carries distinct information with 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?

An output schema exists, so return values need no explanation. The description covers what is destroyed, what survives, irreversibility and cost — everything an agent needs to invoke this mutation safely.

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 brand, report_id and idempotency_key are already fully documented in the schema. The description adds no parameter-level information. Baseline 3 is appropriate when the schema carries the full burden.

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 with precision: 'Kill a report's public link.' It also implicitly distinguishes itself from create_report, which it names as the alternative path. 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?

Gives clear context for choosing this tool — it destroys a public link irreversibly — and routes the agent to create_report when they actually want a working link. No explicit trigger conditions for when revocation is appropriate, but the alternative is named clearly.

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 (readOnly=false, destructive=false, openWorld=true), while the description adds substantial undisclosed behavior: permission requirements, the weekly scheduling constraint and its refusal payload, the cost model ('one full scan, counted for the month'), and the pending return state with follow-up tools.

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?

Highly front-loaded and every sentence carries information (permissions, eligibility, refusal payload, cost, follow-up). Slightly dense with parenthetical clauses, which costs a little readability, but 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 mutating, open-world tool with an output schema and full parameter coverage, the description supplies everything else an agent needs: authorization scope, the refused-call branch, quota accounting, and what to call next (get_operation or get_readiness).

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 both parameters are already fully documented in the schema, including the idempotency replay semantics. The description adds scheduling context around when a scan may be started but no additional parameter syntax or format, 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: 'Start a full site readiness scan of the brand's website.' It is clearly distinguishable from siblings like get_readiness (read state) and verify_readiness_fix (re-check one issue), both of which it names.

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 states who may call it (owners and admins only), when it can be called (first scan, or a retry while none has completed), and what happens otherwise (refused with scheduled_only and next_run_at). It also routes the agent to get_readiness for can_start_scan and names verify_readiness_fix as the alternative for issue-level re-checks.

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 destructiveHint=false; the description adds genuinely non-obvious behavior: renaming triggers an automatic re-read of existing answers, the operation reports 'pending' during that work, and adding a competitor consumes one tracked-brand slot of plan capacity. Permission requirements and the effect of pausing on retained data are still unstated.

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 dense sentences that front-load the primary create/edit/pause action before moving to side effects and cost. No filler, though the cost sentence is compressed enough that an agent must parse 'one tracked brand of plan capacity' carefully.

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?

An output schema exists, so return-shape details are unnecessary, and the description still adds the meaningful 'returns pending' interim state. Combined with annotations and idempotency semantics in the schema, an agent has enough to call this correctly; only the pause semantics and permission prerequisites 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?

Schema coverage is 57%, so the description must compensate for several undocumented parameters. It clarifies competitor_id's role (edit vs. add) and status behavior (pause/resume), and notes that a name change re-reads answers. The 'name' and 'domain' parameters remain unexplained in both places, keeping it below 5.

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

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

Names the resource (competitor) and enumerates the distinct operations it performs: create, edit via competitor_id, and pause/resume tracking. The tool is unambiguous against siblings such as save_prompt, save_segment, and update_brand, which operate on different resources.

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 states the condition that selects edit mode ('with competitor_id edit one') versus creation, and calls out pause/resume tracking. It also flags the plan-capacity cost of adding a competitor, which informs the decision. It stops short of naming alternative tools for related tasks, so it is not a full 5.

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 flags; the description goes well beyond them by disclosing the replacement semantics ('changing an existing prompt's text replaces it, keeping the old prompt's answers in its history') and the cost model (plan capacity, immediate answers from every model, model budget). These are exactly the side effects an agent needs before mutating state, and they reconcile with 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?

Three sentences, front-loaded with the create/edit distinction before the cost detail. The final cost sentence is a dense run-on packing in three separate behaviors ('new, replaced and resumed prompts get an answer from every model straight away, using model budget'), but nothing is redundant.

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 13-parameter mutation with an output schema already covering return values, the description handles behavior and cost well but is thin on the bulk of the optional metadata fields. An agent can safely decide whether to call it, but cannot reliably fill tags, persona, category, language, intent_type or funnel_stage from this definition.

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

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

Schema description coverage is only 38% (brand, market, segment, prompt_id, idempotency_key), so eight parameters — tags, text, status, persona, category, language, intent_type, funnel_stage — are undocumented in the schema. The description adds meaning only for text (replacement behavior), status (active/paused cost) and the segment target; the remaining five-plus metadata fields are left entirely unexplained, so it only partially compensates.

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 and clearly splits the two modes: 'Add a prompt to a segment, or with prompt_id edit one.' An agent can tell create from edit without opening the schema. It does not, however, name or distinguish itself from siblings such as suggest_prompts or list_prompts, which matters for an agent choosing between generating, listing and saving prompts.

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

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

It gives clear conditional guidance: omit prompt_id to add, supply it to edit, and it notes the cost consequence that selects one path over another ('an active prompt is plan capacity'). What is missing is any when-not guidance or explicit pointer to the alternative tools (suggest_prompts, list_prompts) for the same job.

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 goes beyond the annotations (readOnlyHint=false, idempotentHint=false) by disclosing operational cost semantics: active segments consume plan capacity, collect from all plan models on specific days, and use model budget. It also explains that resuming triggers immediate collection of missed prompts. This is valuable context not present in the schema or 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?

The description is concise, front-loading the primary action ('Add a segment') before detailing edit/pause/resume and cost implications. Every sentence adds value about behavior or cost. It could be slightly more structured with bullets, but it remains readable.

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

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

Given the tool's complexity (multi-mode operation, cost model, scheduling) and the presence of an output schema (which needn't be explained), the description covers key behavioral aspects: creation, editing, pausing/resuming, and cost/collection details. It omits explicit mention of required parameters `brand` and `idempotency_key`, but these are 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 63%, meaning some parameters (e.g., `name`, `prompt_limit`, `language`) lack descriptions. The tool description does not add semantic detail for these parameters. It does clarify the role of `segment` (edit vs. add) and `status` (pause/resume), but this is largely inferable from the schema. 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?

The description clearly states the tool's multi-modal purpose: add a segment by default, or edit/pause/resume an existing one when the `segment` parameter is supplied. It names the specific resource ('segment') and distinguishes the create and update modes. However, it doesn't differentiate from all siblings like save_competitor or save_prompt, though these are clearly different resources.

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 when to use create vs. edit/pause/resume based on whether the `segment` parameter is provided, but it doesn't explicitly state when to use this tool versus alternatives like update_brand or set_primary_brand. No explicit exclusions or prerequisites are given beyond the cost/routing note.

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, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds that the search targets public documentation and returns matching pages, but does not add rate limits, result behavior, or ranking details beyond what the annotations and output schema provide.

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 concise sentences with the main action and the usage decision front-loaded. No filler or repetition.

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

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

Given the rich annotations, full schema descriptions, and presence of an output schema, the description provides enough context to select and invoke the tool correctly without repeating structured data.

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 both parameters are already documented in the input schema. The description mentions keyword search but adds no syntax, matching rules, or limit behavior 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?

The description states a specific verb (Search) and resource (public Cleotic documentation), and distinguishes the tool from the sibling get_doc by contrasting keyword search with slug lookup.

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 search when you do not know which page you need, and use get_doc when you already have a slug. The alternative is named directly.

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 write/not-read-only, non-destructive, open-world, and non-idempotent. The description adds genuinely non-structured behavior: editing how answers name the brand triggers an automatic re-read of existing answers and the call returns 'pending' until it completes, plus that it is free. It does not restate annotation-covered facts.

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 tight sentences, front-loaded with the action and the partial-update rule, followed by sibling routing and the async/status caveat. 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?

Output schema exists so return values need no explanation, and the description covers the async 'pending' lifecycle and cost. For a mutation tool, the remaining gap is the unresolved overlap with update_brand on renaming, which an agent may need to disambiguate.

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 schema baseline is 3, but the description adds PATCH-style semantics not present in the schema: 'Pass at least one; what you leave out stays as it is.' That meaningfully changes how an agent constructs the args beyond the field-level docs.

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

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

States a specific verb and resource — create or edit the tracked brand — and enumerates the editable surface (name, domain, aliases). It explicitly distinguishes itself from save_competitor and update_brand by name, so an agent can separate it from siblings without opening schemas.

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

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

Names two alternatives with explicit routing conditions ('to add a competitor use save_competitor; to rename a brand or study, or pause it, use update_brand'). However, this leaves a real ambiguity: the description also says this tool edits the brand's name, while update_brand is said to rename a brand — the boundary between the two is not fully resolved.

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 openWorldHint=true but say nothing about lifecycle or cost. The description adds that it returns pending while reading (async behavior) and that it consumes model budget to read the site — valuable context an agent cannot get from the 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?

Front-loaded with purpose, then the async/poll/approve flow, then the cost caveat. Every sentence carries a distinct, actionable piece of information 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 an async, multi-step, open-world mutation with an output schema already present, the description supplies the missing pieces: async semantics, the polling target, the approval handoff, and cost. Nothing an agent needs to invoke or sequence 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?

Schema description coverage is 100%, so both url and idempotency_key are fully documented in the schema. The description adds no syntax or semantic detail beyond that, so the baseline 3 applies.

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

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

States a specific verb (start/"add a brand") and resource, then describes exactly what the tool does: reads the website and proposes brand, competitors, segment, and prompts. This clearly distinguishes it from siblings get_brand_setup and approve_brand_setup, which it names.

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?

Lays out the full workflow: call this, poll get_brand_setup until approval is needed, review with the user, then call approve_brand_setup. Both the timing and the alternatives are explicit, leaving nothing 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?

Goes well beyond the annotations: it discloses ranking behavior (ranked by AI search demand only when the provider has data), how to interpret null/0 values, that nothing is persisted and no IDs are returned, and the cost (one AI model call). That's rich context 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?

Three dense, front-loaded sentences with no filler; the persistence caveat and cost are packed efficiently. Slightly information-dense but 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 an output schema present, return values need not be spelled out, yet the description still clarifies the null/0 semantics of monthly_ai_searches and the cost/handoff behavior. Complete enough for correct invocation.

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

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

Schema description coverage is 100%, so brand/segment/topic/count are already documented in the schema. The description adds no parameter-level syntax or defaults beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Suggest prompts') plus scope ('for a segment about a topic'), which cleanly distinguishes it from list_prompts and save_prompt 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?

It routes the agent explicitly: 'Saves nothing and returns no IDs: add the ones you want with save_prompt.' This names the follow-up tool and its params. It doesn't contrast against list_prompts, so it stops short of a full when/when-not matrix, but the actionable handoff is clear.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true and destructiveHint=false, so the description is not required to re-establish the safety profile. It goes further by disclosing that resuming restarts collection on Mondays/Wednesdays/Fridays, fires missed prompts immediately, and consumes plan capacity and model budget — real operational consequences 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 the core capability before the cost caveat. The second sentence is dense but every clause (collection days, immediate prompt answering, capacity/budget consumption) carries distinct decision-relevant information. Minimal 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?

An output schema exists, so return values need not be explained. For a mutation tool, the description covers the operations and a notable side-effect of resuming. It stops short of permissions/authorization requirements and of clarifying behavior when name and status are provided together, but the essential calling information is present.

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%: 'brand' and 'idempotency_key' are documented in the schema, while 'name' and 'status' are not. The description loosely maps 'rename' to name and 'pause or resume' to status (active/paused), which adds a little semantic glue, but it never spells out the name/status-to-parameter mapping or interaction when both are supplied. This only partially compensates for the coverage gap.

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

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

The description opens with a specific set of verbs and the resource: rename a brand or study, or pause/resume it. An agent can immediately distinguish this from siblings like update_brand_voice, get_brand_settings, or approve_brand_setup. It also names both target objects (brand/study), matching the 'brand' parameter's dual nature.

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 what the operations are but gives no explicit when-to-use-vs-alternative guidance: nothing routes the agent away from update_brand_voice for voice changes or toward get_brand_settings to inspect state first. The cost note for resuming implies caution but does not frame it as a decision rule. Usage is only 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 already declare the safety profile (readOnlyHint=false, destructiveHint=false), so the bar is lower. The description adds genuinely useful behavior the annotations cannot convey: that setting 'none' clears the tone and that the change is forward-only, not retroactive. It does not mention the caller-supplied idempotency mechanism, but that is documented in the 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, no filler, with the primary action front-loaded and the non-retroactive caveat immediately after. Every clause carries information.

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

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

With annotations covering the safety profile and an output schema covering return values, the description need only cover scope and semantics, which it does. The one remaining gap is any explicit routing versus sibling tools.

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 67% and the schema already documents brand and idempotency_key, so the baseline is 3. The description goes beyond the schema on the tone parameter by explaining that the 'none' enum value means 'clear it' — an enum member the schema lists without explanation.

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 ('Set the default tone for the brand's Content Studio pages') and even covers the clearing case ('or none to clear it'). It is clear enough to distinguish from update_brand, though it never explicitly contrasts itself with any sibling.

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 a real scope rule — it affects the next draft of every page and does not rewrite existing drafts — which tells the agent the effect window. However, it offers no explicit when-to-use vs. alternatives guidance (e.g., relative to draft_page or redraft_page_section), leaving routing 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 cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the bar is lower. The description still adds genuine non-schema behavior: 'All listed opportunities change together or none do' discloses batch atomicity, and listing restore implies dismiss/snooze are reversible rather than destructive. It does not cover auth requirements or rate limits, so not 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, zero waste: core action first, the batch-atomicity constraint second, the sibling routing rule last. Every sentence carries load and the most important information is 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?

An output schema exists, so return values need not be explained, and the description covers the action set, atomicity, and alternative routing. The remaining gap is whether the action parameters combine (e.g., setting a stage while dismissing) or are mutually exclusive, which an agent must infer from 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 100%, so the baseline is 3. The description enumerates the action verbs that map onto the stage/assignee/snooze_until/dismiss/restore parameters, which reinforces intent, but it adds no format, default, or mutual-exclusivity detail beyond what the schema already states for each parameter.

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?

Opens with a specific verb+resource+scope: 'Triage inbox opportunities' followed by the exact action set (stage, assign, snooze, dismiss, restore). It names the sibling act_on_opportunity and the condition that separates them, so an agent can distinguish it 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 an explicit routing rule: 'To record a play that was done, such as a fix shipped or outreach sent, use act_on_opportunity instead.' It states the when-to-use for this tool (triage/state change) and the exclusion with the alternative named, leaving nothing 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?

Adds substantial context the annotations do not: the write side effect (the result updates the task), the returned pending state and its id, the follow-up call chain, and exact cost/rate limits (free once per 10 minutes by opportunity_id; one monthly re-check by check_id). This is exactly the disclosure burden for a non-readOnly, non-idempotent 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-loads the core action and scope, then branches into the two modes, then states cost last. Dense but every sentence carries distinct, needed 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?

With an output schema present the description need not explain return values, yet it still signals the pending status and the correct follow-up tools, and it covers cost and side effects. Nothing required to invoke 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?

Schema coverage is 100%, so the baseline is 3, but the description goes further by explaining the mutually-exclusive semantics of opportunity_id vs check_id and what each produces, which the schema alone does not convey.

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 (re-check) and resource (a fix), and immediately differentiates itself from the bulk sibling with 'without a full scan', which rules out run_readiness_scan. The two operating modes are named concretely.

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

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

Explicitly tells the agent which parameter selects which behavior (opportunity_id re-checks an inbox readiness task; check_id re-checks an open finding) and names the follow-up tools (get_operation, get_readiness_finding). It lacks an explicit 'do not use when...' clause, but the routing is clear.

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