Cleotic

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

Annotations already declare it is a non-read-only, non-destructive, non-idempotent, open-world write. The description adds genuinely new context: the state transition to 'watching', the fact that outreach is never actually sent, and a per-action resource cost model (plan capacity, Content Studio allowance, model budget). It does not cover auth requirements, but the consumption and side-effect disclosures go well 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?

Front-loaded with purpose and the routing rule, then action definitions, then costs. The dense colon-delimited enumeration is compact and every sentence carries distinct information; nothing is restated from the schema.

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

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

For a 5-parameter mutating tool with an output schema, the description supplies what the structured fields cannot: action semantics, side effects, the alternative tool, and the cost of each path. Return-value behavior is correctly left to the output 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 80%, so the baseline is 3, but the description meaningfully exceeds it by documenting every enum value of 'action' (which the schema leaves as a bare enum) and clarifying that suggestion_ids drives track_prompts. brand, opportunity_id and idempotency_key semantics remain schema-only, which is acceptable given their rich schema descriptions.

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

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

The description gives a specific verb and resource ('Record or start an opportunity's play'), states the resulting state change ('moves it to watching'), and explicitly separates itself from the sibling update_opportunities. An agent can distinguish this from every other opportunity-related tool 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 names the alternative ('Use it rather than update_opportunities') and the exact condition that selects it ('whenever the play was done'). Each enum action is further glossed with the real-world event it represents (fix shipped, outreach sent, page improved), so the agent knows which action to pick, not just when to call the tool.

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

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

Goes beyond the annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false, idempotentHint=false) by disclosing real cost/resource implications: plan capacity consumption (a brand, a segment, kept prompts) plus model budget for first answers and the first readiness scan. It also clarifies the keep/drop semantics of the accepted lists, which is behavioral context the annotations do not 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?

Front-loaded with the core action, then proposal semantics, then market guidance, then cost. Every sentence carries information, though the final cost sentence is dense and the overall text is long for a five-parameter tool.

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 the description covers creation semantics, required pre-confirmation, and cost. It stops short of stating preconditions explicitly (that the setup must be in a ready state) and of naming the initiating sibling start_brand_setup.

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 meaning beyond the schema: it explains that an empty accepted list keeps none of that kind, that the primary brand is always kept, and that market must be user-confirmed before being passed. Those are semantic constraints not fully spelled out in the field descriptions.

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 the brand from a ready setup's proposals.' An agent can distinguish this from get_brand_setup (retrieve), start_brand_setup (initiate), and save_competitor/save_prompt (manual writes) 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 clear workflow context: it names get_brand_setup as the source of segment.market/market_label and instructs confirming the market with the user first. It implies the post-setup stage but does not explicitly name start_brand_setup as the prerequisite or state exclusions, so it falls short of a full when/when-not routing rule.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=false and idempotentHint=false, so the safety profile is covered. The only behavioral content the description adds is 'as you' (identity attribution); it says nothing about visibility of the comment, permissions required, or how the non-idempotent write behaves, and notably the idempotentHint=false annotation sits oddly beside a required idempotency_key whose replay semantics are only explained 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?

A single front-loaded sentence with no filler; 'as you' is the one piece of information beyond the title. It is efficient, though arguably too terse for a mutation tool rather than genuinely well-proportioned.

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 the schema plus annotations carry the safety and parameter load. What is missing is any statement of when to comment versus other communication siblings and whether the comment is visible to others, which leaves the definition merely adequate for a write tool.

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

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

Schema description coverage is 100%, including detailed semantics for idempotency_key (reuse on retry, replayed flag) and sourcing of brand/opportunity_id from list_brands/list_opportunities. The description adds no parameter meaning beyond that, so the baseline 3 for a fully-documented schema is appropriate.

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

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

States a specific verb and resource ('Add a comment to an opportunity') and adds the attribution detail 'as you', so the agent knows the comment is posted under the caller's identity. It is clear, but it does not distinguish this from other write-style siblings (e.g. message_page, act_on_opportunity) or explain the opportunity-centric framing.

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 when-to-use or when-not-to-use guidance, no prerequisites, and no mention of alternatives such as message_page or act_on_opportunity for communicating on a record. The agent must infer usage entirely from the name.

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 (which only flag non-read-only, non-idempotent, open-world): it discloses the asynchronous contract ("Returns pending while it works"), the agent's internal sequence of goal/reader/angle then outline, and an explicit cost model — one plan Content Studio page counted on first write plus model budget. That is exactly the operational context an agent needs before spending quota.

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 action, then the input variants, then the async/return contract and cost in two dense sentences. Nearly every clause earns its place, though the four-source enumeration slightly restates what the schema already says.

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 still supplies the missing pieces an agent cannot infer: async pending status, the question/answer loop via get_page and message_page, and the billing unit. Nothing material is left out for a 7-parameter write tool.

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

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

Schema description coverage is 100%, so each parameter is already documented, including the brand ID-vs-name rule and the idempotency replay semantics. The description's list of the four sources mirrors the schema's own "Or ..." phrasing without adding new syntax or constraints, 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 Content Studio page") plus the four accepted input sources (opportunity, question/idea, Markdown draft, URL), which cleanly separates it from edit_page, revise_page, and mark_page_published among the siblings.

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

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

Gives concrete entry conditions for each of the four starting points and routes the agent to get_page to read questions and message_page to answer them, covering the full follow-up loop. It stops short of naming an explicit alternative for the case where a page already exists (e.g., edit_page/revise_page), so no true 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, openWorldHint=true, idempotentHint=false, and destructiveHint=false, but the description adds substantial traits beyond that: the call returns the public link immediately while figures build asynchronously (usually within a minute), and it consumes real resources (one report of plan capacity, plus model budget for narratives). These are exactly the operational facts an agent needs before calling.

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 filler, correctly front-loaded: purpose first, then return timing, then cost. Each sentence delivers a distinct decision-relevant fact and nothing is repeated from the schema 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?

An output schema exists, so the description is not obliged to document return values, yet it still clarifies the asynchronous link semantics. Combined with cost/quota disclosure and the schema's full parameter documentation, an agent has everything needed to invoke 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?

With 80% schema coverage the schema already documents to/from defaults, brand resolution, and idempotency_key retry behavior, so the baseline is 3. The description adds meaning the schema does not carry — that the date range is interpreted as a comparison against the prior equal-length period — which clarifies how to/from are actually used.

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

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

The description gives a specific verb (save/create) and resource (a shareable report of the brand's results), plus the distinctive scope that the range is compared against the immediately preceding equal-length period. That scope detail separates it from siblings like list_reports and revoke_report without needing to 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?

Usage is implied by the purpose: an agent can infer this is the tool for producing a shareable brand report. However there is no explicit when-to-use or when-not-to-use guidance, no mention of prerequisites (plan capacity, report narratives), and no routing between this and alternatives such as list_reports or get_brand_overview.

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 destructiveHint=true, so permanence is expected, but the description adds real value beyond that: it details cascading deletion (deleting a segment deletes its prompts and answers; deleting a prompt deletes its answers), confirms no restore path, and notes the side effect of freeing plan capacity. It doesn't cover auth/permission requirements, but the cascade and irreversibility disclosures are substantive.

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

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

Extremely dense and front-loaded: the action and its irreversibility lead, then cascade effects, then alternatives, then cost/capacity. Every clause earns its place with no filler.

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

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

For a destructive multi-resource deletion tool with an output schema, the description covers the safety-critical facts an agent needs: which IDs are valid, that exactly one is required, irreversibility, cascade scope, and the routing alternatives. Nothing material is missing.

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

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

Schema coverage is 100% and every parameter carries a description naming its source (list_brands, get_brand_settings, list_pages, etc.), so the schema does the heavy lifting. The description reinforces the 'exactly one ID' constraint, which the schema does not enforce structurally, adding modest value 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 (delete) and enumerates exactly the resource types covered (competitor, segment, prompt, page, report) with the 'pass exactly one of its IDs' rule. This distinguishes it clearly from revoke_report, which is named as the alternative for a narrower action.

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 this for permanent deletion, use save_competitor/save_segment/save_prompt to pause (preserve history), and use revoke_report to kill a report's link only. The when-to-use and when-not-to-use are both stated with named alternatives.

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

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

Adds behavior the annotations don't carry: optimistic concurrency (a stale base_version is refused), a locking constraint on live pages, and a cost signal ('Free'). The annotations only declare the safety profile (readOnly=false, destructive=false, idempotent=false), so this is genuine added value. It stops short of explaining what happens if a find string is ambiguous or whether multi-edit application is atomic, leaving a small gap.

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 modes, then preconditions, then the sibling routing. Every clause carries actionable information; 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 11-parameter mutation tool with an output schema and full annotation coverage, the description supplies what structured fields cannot: concurrency semantics, the live-page lock, and routing to revise_page. Return values are covered by the output schema, so nothing essential 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 64%, so the schema documents several parameters itself; the description reinforces which fields are editable (markdown, edits, title, goal, reader, angle) and repeats the base_version dependency. It adds the semantic framing of 'replace its Markdown' vs 'exact find-and-replace edits' as alternative modes, which helps mode selection, but does not document brand or idempotency_key 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?

Names a specific verb (change/edit) plus resource (page) and enumerates the concrete capabilities: replace Markdown, find-and-replace edits, and title/goal/reader/angle edits. It also distinguishes itself from the sibling revise_page by stating that live pages are locked. An agent can identify this tool without opening any schema.

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

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

Explicit preconditions ('Pass base_version from get_page') and an explicit exclusion with a named alternative ('A live page is locked: revise_page first'). The when-to-use versus revise_page routing is unambiguous, which is exactly the distinction siblings create.

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 genuinely useful behavior beyond that: the tracking-setup caveat (connected is false), the definitional rule that bots/crawlers/Cleotic's own fetches are never visits, and which views are paged. It stops short of disclosing rate limits or the interaction between view and traffic_view.

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

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

Purpose is front-loaded and every sentence carries content (definitions, view semantics, paging rules) with no filler. The style is a dense run of short declaratives rather than prose, which is efficient but slightly hard to parse on first read.

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

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

With 10 parameters, an output schema, and full annotation coverage, the description supplies the non-structural context an agent needs: metric definitions, view semantics, paging, and the tracking-not-connected edge case. The one gap is that it never clarifies whether traffic_view acts as a filter on top of view, or how the two interact.

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, but the description adds meaning the schema does not: what each view actually returns, that only pages and evidence are paged, and that provider names must match the summary's system names. This goes beyond the terse schema text for view and traffic_view.

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: AI crawler requests and AI-referred visits to the brand's site, with explicit definitions of visits vs crawler requests and of AI share. No sibling tool covers traffic analytics, so the boundary is unambiguous.

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

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

The view enumeration (summary = totals/providers/crawlers/referral sources/pages to improve/by week; pages = per-page; evidence = individual visits) implies which view to pick for which need. However there is no explicit when-to-use guidance, no routing to alternatives like get_brand_overview, and no statement of when this tool is the wrong choice.

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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower; the description still adds real behavioral context by disclosing that this is a multi-metric roll-up in one call and that a segment 'filters the answer metrics' rather than everything. It stops short of describing retention/latency behavior, but the schema already handles date-window and retention caveats.

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 call returns and followed by the routing rule and the segment caveat. The first sentence is a long enumeration but every item corresponds to actual returned content, so it earns its length; only minor tightening is possible.

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

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

For a read-only aggregate tool with a 100%-documented schema and an output schema covering return values, the description supplies everything an agent needs: content scope, alternative tools, and the segment filtering nuance. Nothing required for correct invocation appears to be 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; the description goes beyond the schema by clarifying the scope of the optional segment parameter ('filters the answer metrics'), which is a behavior the schema description does not state. The brand/date parameters add no extra meaning in the prose, but nothing is misleading.

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 resource (the brand Overviewe) and enumerates exactly what it returns: visibility, share of voice, recommendation with basis and change, competitor standing, and readiness/traffic/inbox/Content Studio status. It also names the sibling tools it is not, so an agent can separate the aggregate view from the single-slice tools without reading schemas.

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

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

Explicitly routes to alternatives: 'For one slice in depth use get_perception, list_citations, get_ai_traffic or get_readiness.' That is a clear when-not-this condition paired with the correct substitutes, leaving little to inference beyond the obvious 'use this for the overall picture'.

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 and the bar is lower. The description adds useful framing as a state-inspection read used to source IDs for other tools, but offers nothing on rate limits, auth scopes, or payload shape beyond the output schema.

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

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

Two tightly packed sentences with the scope front-loaded before the routing hint, and every clause (settings list, ID lookup, pre-change inspection, metrics alternative) 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?

With an output schema present, the description is not obligated to describe return values, and it covers purpose, usage trigger, sibling routing, and the pre-mutation inspection role completely. 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?

There is a single 'brand' parameter with 100% schema description coverage that already explains ID vs. exact/unique-prefix name resolution. The description adds no syntax or format detail beyond the schema, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource ('Read the brand's settings') and enumerates exactly which settings are returned (primary brand, competitors, segments, tracking/CMS status, brand voice, Content Studio skills). It also explicitly differentiates itself from the metrics sibling by naming get_brand_overview, so an agent can select 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?

Gives explicit positive triggers ('find the competitor_id and segment values other tools take') and a clear workflow role ('see the current state before changing a setting'), plus an explicit exclusion routing metrics queries to get_brand_overview. Nothing is left to inference.

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

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

Annotations already 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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds only the 'public' scope constraint, which is useful (private pages presumably fail) but there is no error behavior, rate limit, or failure-mode context 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?

Three short sentences, no filler, with the core action front-loaded and the routing hint last. 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 single-parameter, read-only lookup with an output schema and full annotation coverage, the description supplies everything needed: what is fetched, what the slug is, and how to obtain one. Return values are properly left to the output 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% and the slug parameter is already documented with an example, so the baseline would be 3. The description adds real value by explaining where slugs come from (in-page links, or search_docs output), which clarifies the value the agent should pass.

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 scope: fetch one public Cleotic documentation page by slug. The 'public' qualifier and 'by slug' key distinguish it cleanly from list_pages and search_docs without needing to open either schema.

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

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

Explicitly routes the agent: 'Use search_docs first when you have no slug' names the alternative sibling and the exact condition that selects it. It also clarifies that in-page links are already valid slugs, telling the agent when no lookup step is needed.

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, non-destructive and openWorld, so the safety profile is covered. The description adds genuinely useful context about the shape of the payload (evidence, play, the tool call that carries it out, proof, timeline, comments) rather than restating the annotations. It stops short of disclosing anything about auth, freshness, or rate limits, but the bar is lower here.

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

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

Front-loaded with the core purpose, and the routing guidance lands in the final sentence where it is easy to find. The long parenthetical content list is dense but each item is informative; only slight trimming would be possible.

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 orients the agent on payload richness. Combined with full parameter coverage and annotations covering safety, 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 both params are documented in-schema (brand resolvable from list_brands, opportunity_id from list_opportunities). The description adds no syntax or format meaning 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 and resource ('One opportunity') and then enumerates precisely what the payload contains — evidence, play, tool call, before/after proof, timeline, comments — so the agent knows exactly what it gets. It is clearly distinguished from list_opportunities (browsing) and act_on_opportunity/create_page (acting), which appear in sibling tool 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?

Gives an explicit sequencing rule ('Read it before act_on_opportunity or create_page') and names the alternative for the other mode ('to browse the inbox use list_opportunities'). Both when-to-use and when-to-use-something-else are stated, 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?

Annotations already declare readOnly, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds value beyond that by disclosing pagination of long Markdown via an internal cursor and by noting that the latest conversation may contain a question the page agent is waiting on, which is operationally useful behavioral context not present in 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 first sentence is a long enumeration of returned contents but is efficiently packed and front-loads the resource. The second sentence cleanly handles sequencing. It is a single dense sentence plus one routing sentence, which is reasonably sized for a rich read tool, though the first sentence borders on a laundry 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?

With an output schema present, the description is not required to explain return value shape. It still complements the schema by summarizing what is inside a page and by explaining the cursor-driven pagination flow (markdown_next_cursor from the previous call), which is exactly the contextual information an agent needs to invoke this correctly. Nothing critical appears 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 each parameter already has a thorough description in the schema (brand ID or name, cursor for next Markdown part, page_id origin). The description does not add per-parameter detail the schema lacks. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb (get/read) and resource (one Content Studio page), and enumerates the rich contents returned (brief, questions, outline, Markdown, conversation, suggestions, live results). It explicitly names siblings create_page, message_page and list_pages, so an agent can distinguish this retrieval tool from creation and listing tools.

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

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

Provides clear timing guidance: read it after create_page and message_page, and use list_pages to find pages. This signals when this tool is the right pick versus discovery via list_pages. It does not, however, contrast against the other page-reading siblings like get_doc or edit_page, but the population of sibling alternatives for a single-page fetch is limited.

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 readOnly, idempotent, non-destructive, open-world, so the safety profile is covered. The description adds real interpretive context beyond that, notably the 'null limit = unlimited' convention and the fact that it exposes per-segment model collection. Not a rich behavioral narrative, but a useful increment over 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 resource and the contents, then the when-to-use trigger. Dense but every clause carries information. The enumerated contents list is slightly long but each item is a distinct capability of the plan object.

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 already describing the return shape, the description need not restate fields, and it correctly focuses on purpose and timing. The read is fully specified for a no-parameter, annotated, schema-documented tool.

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

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

The tool takes zero parameters, so there is nothing for the schema or description to disambiguate. Baseline 4 applies; the description cannot add parameter meaning where none exists.

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) and then enumerates exactly what is returned: limits and their use, included features, Content Studio allowance, model budget, and per-segment AI models. No sibling tool reads plan data, so it 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?

Explicitly says when to call it: 'before a write that costs plan capacity, a generation, or model budget.' That is clear pre-flight guidance. It does not name an alternative tool, but no sibling overlaps this concern, so the omission is minor.

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 readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so safety behavior is covered. The description adds useful context about what each view returns and clarifies that competitor scans cannot be started here, but says nothing about authentication, rate limits, or how 'open findings' change between runs.

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 front-loaded and each view is covered in one compact clause with no filler. The semicolon-dense sentence is information-dense and the competitor caveat is slightly buried at the end, but the structure 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 an output schema present, the description only needs to orient the caller, and it does so by enumerating what each view yields and what the tool cannot do. An agent has enough to select a view and invoke 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 each of the 9 parameters is documented there, so the schema carries the load. The description reinforces the view semantics and the page_id case but adds no format or syntax detail beyond what's already in 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?

Starts with a precise noun phrase identifying the resource ('The brand site's AI readiness scan') and enumerates five distinct views, so an agent can tell exactly what each invocation returns and how it differs from siblings like get_plan or get_brand_overview.

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 maps every view to a use case ('view action_plan: open findings to fix', 'view pages: pages the scan read'), which effectively tells the agent when to pick each mode. It also explicitly excludes competitor scanning ('started in the app, not through MCP'), but gives no guidance on when to prefer summary over action_plan or how it relates to run_readiness_scan.

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 cover the safety profile (readOnly/idempotent/non-destructive/openWorld), so the bar is lower, and the description still adds real context: sort order, what each mode returns (brands mentioned/recommended vs mention in context), and the important edge-case semantics that one mode can be empty while the other still returns 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 core fact ('AI answers, newest first') before the two branches, and every clause carries information. The semicolon-joined final sentence is dense but not padded.

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 shapes needn't be explained, and the annotations plus rich schema cover safety and parameters. The description supplies the mode split, ordering, and empty-result behavior, leaving little an agent needs 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 already documents every parameter (dates, limit, model, cursor, segment, prompt_id). The description reinforces prompt_id's mode-switching role but adds no syntax or format detail 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 (list AI answers) with ordering ('newest first') and then splits the tool into two clearly-scoped modes keyed on prompt_id. This lets an agent understand behavior well, though it never explicitly names siblings like get_answer or list_citations 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?

Gives clear conditional guidance: with prompt_id you get a prompt's answers across models; without it you get answers mentioning the brand. The 'either way' clause on the empty case tells the agent when each mode still yields results, but no explicit alternatives or exclusions 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 the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower, yet the description still adds a genuine behavioral guarantee: brands are returned in name order "so paging stays steady as brands are added" — a stability property not derivable from annotations. It does not discuss auth scoping or rate limits, keeping it at 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?

Purpose and ordering guarantee are front-loaded, with the entry-point cue last. The middle clause is a long laundry list of returned metrics, but each item is scoped and no sentence is filler.

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

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

With annotations covering safety, a full output schema, and 100% parameter coverage, the description only needs purpose, ordering, and entry-point guidance — all present. Minor gap: no hint about how large the result set can be before paging, though the schema's cursor/limit notes mitigate this.

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 fully documents from/to/kind/limit/cursor, including defaults, window caps, and enum values. The description adds no parameter-level detail beyond the ordering note, 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?

Opens with a specific verb+resource ("List the brands and studies you can access") and explicitly frames itself as the entry point ("Start here to find a brand ID"), which separates it from detail-oriented siblings like get_brand_overview or get_brand_settings. An agent can route to 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?

"Start here to find a brand ID" gives clear, actionable context for when to reach for this tool, and the enumeration of returned data implies it's the discovery/index call. It stops short of naming when NOT to use it or pointing to a specific alternative for per-brand detail, so it falls just short of the top score.

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

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

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 declare the safety profile (readOnly, idempotent, non-destructive), so the description's contribution is the domain semantics: what 'drafting', 'sent', 'live' (locked, results tracked) and 'revising' actually mean, plus newest-first ordering. That is real context beyond the structured fields, though it says nothing about result size or truncation 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 sentences, front-loaded with the resource and ordering, then the status vocabulary, then the routing hint. No sentence is redundant and nothing is 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?

With an output schema present the return shape need not be described, and pagination is fully covered by the limit/cursor schema descriptions. Ordering, status semantics, and the next-step tool are all supplied, leaving no gap an agent needs filled before calling it.

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

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

Schema coverage is 100%, so the baseline is 3. The description earns the extra point by giving meaning to the status values the schema only labels as "Optional filter", clarifying the lifecycle states an agent will see in results and can filter on.

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 (the brand's Content Studio pages), the ordering (newest first), and the status vocabulary the list exposes. It also distinguishes itself from get_page by positioning itself as the entry point that yields a page_id, so an agent can tell it apart from get_page/create_page 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?

"Start here to find a page_id for get_page" gives explicit when-to-use guidance and names the follow-on sibling. It stops short of stating when NOT to use it (e.g. when you already hold a page_id) or naming list_brands/search alternatives, so it is clear context without 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 readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description adds non-obvious behavior the annotations don't: the demand-based sort order and the fact that mention counts are scoped to the requested period. It does not add auth or rate-limit context, but the annotation baseline lowers that burden.

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. The resource and ordering come first, the routing guidance second, and nothing is repeated from the schema 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?

With an output schema present and pagination fully described in-schema (limit/cursor/next_cursor), the description covers the remaining agent-relevant context: sort order, period scoping of the mention count, and downstream tool routing. The only mild redundancy is enumerating return fields that the output schema already defines.

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 seven parameters (to, from, brand, limit, cursor, status, segment) are each documented in-schema, so the schema carries the parameter burden. The description references the period and segment dimensions only indirectly and adds no syntax or format detail beyond the schema — the 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 (the brand's tracked prompts), states the ordering ('highest AI search demand first'), and enumerates the returned fields (segment, status, labels, monthly AI searches, brand mentions). An agent can distinguish this from list_answers, suggest_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 explicitly routes the agent: use this to obtain a prompt_id for list_answers, while suggest_prompts proposes and save_prompt persists. That covers the primary selection decision against the closest siblings, though it states no exclusion conditions or prerequisites (e.g., brand must already be set up).

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 cover the safety profile (not read-only, not destructive, open-world), and the description adds genuinely new behavior: the page becomes locked, Cleotic re-evaluates its target questions as of that day, and the call is free. It omits retry/idempotency semantics even though a required idempotency_key implies they matter.

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 with no filler; the scope constraint and the side effects are front-loaded before the pricing note.

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, an output schema, and annotations present, the description covers the essentials: what it records, the eligibility scope, and the locking/comparison side effects. The residual gap is that it never addresses the idempotency_key's retry contract, which is the one non-obvious field on a write tool.

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

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

Schema description coverage is 100%, so all four parameters, including the detailed idempotency_key semantics, are already documented in the schema. The description adds no parameter-level meaning beyond that, which is the baseline case.

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 ('Record that a page is live at a URL') and immediately scopes it to 'pages published outside a connected CMS', which cleanly separates it from the sibling send_page_to_cms.

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 qualifier 'for pages published outside a connected CMS' tells the agent the condition under which this tool applies rather than the CMS-sync alternative. It stops short of naming the alternative tool explicitly or stating exclusions for already-published pages.

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

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

Beyond the annotations (which only carry safety hints), the description discloses asynchronous behavior ('Returns pending while it works'), the required follow-up read via get_page, the side effects ('may edit the page or the brief'), and a cost model ('model budget; the first draft of a page uses one Content Studio page'). These are exactly the non-obvious traits an agent needs before invoking a write tool.

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

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

Three compact sentences, front-loaded with the purpose and then the async behavior and cost. Nothing is padded; the cost sentence is terse but does carry unique 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 four-parameter write tool with an output schema, the description covers purpose, side effects, async return handling, and cost. An agent can decide to call it, know that 'pending' is expected, and know how to retrieve the reply.

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 all four parameters, including the idempotency_key replay semantics. The description adds no parameter-level guidance beyond that, which is the expected baseline when the schema does the heavy lifting.

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

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

The description gives a specific verb and resource ('Talk to a page's agent as you') plus four concrete intents (answer its question, ask for a change, approve its outline, ask why), so the agent knows exactly what kinds of actions this covers. It stops short of naming siblings such as edit_page or revise_page, and the clause 'may edit the page or the brief' is the only hint at how this differs from a direct edit 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?

The enumerated intents function as clear use-cases and the follow-up path is stated ('read the reply with get_page'). There are no explicit exclusions, however — nothing says when to use edit_page or revise_page instead of routing through the page agent.

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=false, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds genuinely useful traits: results continue counting from the original go-live date and the operation is free. It does not mention the idempotency-key retry behavior or what happens if the page is not live.

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 core action followed by the workflow and cost note. The one-word 'Free.' is borderline but conveys a real decision-relevant 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 explained, and annotations carry the mutation safety profile. Still, for a write tool that takes over a live page, the description leaves open whether the page stays publicly live during revision and how it relates to the sibling edit_page.

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 all three parameters (brand, page_id, idempotency_key) fully documented in the schema, so baseline is 3. The description adds no parameter-level meaning beyond that.

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

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

States a specific verb and resource: it unlocks a live page for revision and names the follow-up actions (send or publish). This differentiates it from create_page and edit_page, which operate on non-live pages, though the exact state transition is described indirectly as 'unlock' rather than a concrete mutation.

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 second sentence implies a workflow (revise now, then send/publish when ready) and implicitly routes to send_page_to_cms or mark_page_published. However it never explicitly says when to choose this over edit_page, nor what preconditions apply (does the page have to be live already?).

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false, but the description adds non-obvious behavior beyond them: the revocation is permanent and irreversible, and the report remains listed with revoked: true. It also notes the operation is free. It does not mention required permissions or error behavior, keeping it at a strong 4.

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

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

Four short sentences, front-loaded with the action and its irreversible consequence; the one-word 'Free.' earns its place by conveying cost. No filler.

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

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

With an output schema present, return values need no explanation, and the description covers the destructive consequence and the post-state. It stops short of covering auth/permission requirements or failure modes for a destructive 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%, so the schema fully documents brand, report_id, and idempotency_key. The description adds no parameter-level detail, which is the expected baseline when the schema does the heavy lifting.

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

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

States a precise verb and resource: it kills a report's public link, and it explicitly distinguishes revocation (link dies, report survives) from deletion. Against siblings like delete_item and create_report, an agent can tell exactly which outcome this produces.

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 routing condition: because a revoked link cannot be restored, the alternative is create_report for a new link. It does not state explicit when-not-to-use cases (e.g., use delete_item to remove the report itself), so it falls short of full alternative coverage.

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: annotations only cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), while the description discloses the authorization requirement (owners/admin), the refusal mode with concrete error fields, the async pattern (returns pending, poll with get_operation/get_readiness), and the quota cost of one scan counted against the month with no monthly allowance.

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?

Dense and front-loaded: purpose first, then eligibility, then refusal/limits, then follow-up. Almost every clause carries information, though the mid-section compresses several distinct rules (scheduling cadence, refusal fields, sibling pointer) into a single run-on sentence that is slightly harder to parse than it needs to be.

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, quota-consuming, asynchronous tool, the description covers everything the agent needs before calling: who may call, when the call is refused, the async follow-up path, and the cost. Return-value details are rightly left to the existing output 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 both parameters (brand, idempotency_key) are already fully documented in the schema. The description adds only indirect context about retries that touches the idempotency key, but no new syntax or format detail; baseline 3 is correct when the schema does the heavy lifting.

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

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

States a specific verb+resource with scope: 'Start a full site readiness scan of the brand's website.' It also distinguishes itself from the two closest siblings by name — get_readiness (status) and verify_readiness_fix (re-checks one issue) — so an agent can route without opening any schema.

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

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

Explicit eligibility and preconditions: owners/admins only, and the call is permitted only for a first scan or a retry while none has completed; otherwise it is refused with scheduled_only and next_run_at. It also names the follow-up alternatives (get_operation, get_readiness) for the pending result.

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 safety (readOnlyHint=false, destructiveHint=false), and the description adds genuinely non-obvious behavior: a naming/alias change silently re-reads existing answers and the call returns pending until done, plus a capacity cost. That is real side-effect disclosure beyond structured fields, though permission requirements and what a paused competitor stops doing are not stated.

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 create/edit distinction before the async and cost caveats. Dense phrasing ('one tracked brand of plan capacity') is compact but 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 described, and the description still covers the create/edit branch, the async re-read state, and cost. Only the relationship to brand/study scoping and pause semantics remain thin for a 7-parameter mutation tool.

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

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

Schema coverage is 57%, so the schema documents part of the surface. The description adds meaning only for competitor_id (edit vs add); brand, name, domain, and status semantics are left entirely to the schema, and the alias-replacement behavior is described in the schema, not the description.

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

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

States a specific verb and resource and then splits the two modes precisely: add versus edit/pause/resume via competitor_id. An agent can distinguish it from siblings like save_fact, save_prompt, and update_brand without opening any schema.

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

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

Gives a clear condition for each branch (omit competitor_id to add, supply it to edit or pause/resume tracking). It does not name any alternative tool or exclusion (e.g. when to prefer update_brand_settings-style tools), so it stops short of full routing guidance.

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

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

Annotations cover the safety profile (readOnly=false, destructive=false, idempotent=false), and the description adds genuinely useful behavior beyond them: facts are deduplicated ('the same fact is stored once'), user-sourced facts skip the approval wait, and the call is 'Free'. It doesn't clarify permission requirements or what a rejection does to an existing confirmed fact.

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

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

Purpose and the add-vs-edit split are front-loaded, and every sentence carries information (dedup rule, source requirement, approval flow, cost). It is dense but not padded, though the middle sentences could be tightened.

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 11-parameter tool with two enums and an output schema present, the description covers the decision-relevant behaviors: mode selection, sourcing rules, confirmation workflow, and dedup. Return-value details are rightly omitted since an output schema exists.

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 cross-parameter meaning the schema documents only per-field: the from_user/source_url dependency, the fact_id triggering edit/confirm/reject mode, and the fact_id-absent behavior of clearing segment and stale_after. That is real added value 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+resource ('Add a fact to the brand's fact library') and distinguishes the two operating modes (add vs. edit/confirm/reject via fact_id). It does not name the read-side sibling search_facts, but the mode split is enough for an agent to place the tool.

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

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

Gives real conditional guidance: use from_user only for facts the user stated in-conversation (which are auto-confirmed), and propose self-found facts with source_url so they wait for user confirmation. It stops short of explicitly routing to alternatives like search_facts for reading or save_segment for segment-level facts.

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=false, destructiveHint=false), so the bar is lower. The description adds genuinely useful behavior beyond them: replacing text retains the old prompt's answers in history, and active prompts consume plan capacity while new/replaced prompts trigger a first answer from every model against model budget.

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 primary action and mode switch, then behavioral and cost consequences. Every sentence carries load; the cost sentence is dense but justified for a write operation with budget implications.

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 the key decision inputs: mode selection, history retention on replacement, and cost. Minor gaps remain around the active/paused enum effect and the many free-text metadata fields, but nothing critical for correct invocation is missing.

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

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

Schema description coverage is only 38% across 13 parameters. The description clarifies the most consequential semantic (prompt_id toggles edit vs. create) and echoes segment scoping, but the remaining fields (text, tags, status, persona, category, language, intent_type, funnel_stage) get no added meaning, so it 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?

States a specific verb and resource ('Add a prompt to a segment') and immediately distinguishes the two operating modes: create when prompt_id is omitted, edit when it is supplied. An agent can tell exactly what the call does and which mode it is entering 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 routing between add and edit ('with prompt_id edit one') and supplies cost context that informs whether to call it. It does not name sibling alternatives (e.g. suggest_prompts for generating prompts, list_prompts for retrieval), so it falls short of explicit 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 openWorldHint=true, destructiveHint=false, and idempotentHint=false, so the safety profile is covered. The description adds real context the annotations cannot: an active segment consumes plan capacity and collects daily from every plan model against model budget, copied prompts each consume one prompt of capacity, and Google AI Overviews/AI Mode are excluded from collection. That is genuinely useful cost and coverage disclosure.

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

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

The content is dense and earns its place, but it is delivered as one long, run-on paragraph with several stacked clauses per sentence, and the opening sentence is awkward to parse. Front-loading of the core action is decent, but readability suffers.

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, and annotations cover the mutation/safety profile. The description fills the remaining gaps — modes, audience semantics, comparison workflow, and cost — so an agent has enough to call it correctly, though geo/language/brand usage is left entirely 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 73%, so the schema carries most parameter detail; the description still adds meaning the schema does not, explaining that 'audience' is the buyer prompts are asked as, that 'age and gender alone rarely change answers', and that copy_prompts_from exists to enable segment comparison. Undescribed fields (brand, geo, language, prompt_limit) are adequately covered by inline schema descriptions.

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 (segment) and enumerates its modes: add, edit (via 'segment'), and pause/resume via status. It distinguishes itself from nearby write tools like save_prompt and save_competitor by describing what a segment actually contains (market + language). The first sentence is slightly garbled ('or with segment edit one or pause and resume it'), which keeps it from 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 gives conditional guidance: leave out 'segment' to add, pass it to edit, use status to pause/resume, and create a new segment with copy_prompts_from to compare audiences. That covers when-to-use for each mode, though it never names a sibling alternative or an explicit 'do not use this for X' case.

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

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

Annotations already declare readOnlyHint, 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 already declare readOnly/idempotent/openWorld, so the bar is lower, yet the description still adds value: hybrid word+meaning matching for query, proposed-first ordering without query, and guidance to quote only confirmed facts and verify stale ones. It does not discuss pagination behavior, though the schema's cursor/limit fields cover 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?

Four compact sentences front-load the tool's identity and matching behavior, then the downstream usage caution. Slightly dense but every sentence contributes; the stale-fact caution is the most tangential.

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

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

With an output schema present and full annotation coverage, the description needn't cover return values. It supplies purpose, match semantics, ordering, alternative-tool routing, and usage caution, leaving no major gap for a 6-param filtered search.

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 adds meaning beyond the schema by explaining that query does hybrid keyword+semantic matching and that omitting it returns everything with proposed facts first, giving the query parameter conceptual weight.

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

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

States a specific verb (search) and resource (the brand's fact library), then defines the two fact states (confirmed vs proposed) so the agent understands the domain. It explicitly routes write operations to the sibling save_fact, distinguishing itself from it.

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 behavior with vs without query ('best matches by words and meaning' vs 'every fact, proposed first') and names save_fact as the alternative for adding/confirming/rejecting. It lacks explicit steering against other search siblings like search_docs or search_site, but the write-vs-read context is clear.

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

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), so the description's added value is corpus and freshness semantics: it reads pages from the latest readiness scan, caps at 100, refreshes after each scan, and that 'index says when the site was last read'. Those are real behavioral facts an agent cannot derive from annotations.

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

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

Four compact sentences, front-loaded with what is returned before the usage advice and freshness note. Dense but no filler; the phrase 'Cleotic reads the pages its latest site readiness scan found' is slightly indirect but carries necessary 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, return values need not be spelled out, and the corpus scope, freshness signal and usage guidance are covered. Pagination behavior is left entirely to the schema's cursor/limit descriptions, which is acceptable though it means the description is silent on multi-page retrieval.

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, query, limit and cursor are already documented in the schema; baseline is 3. The description echoes the 100-row cap but adds no syntax, format or query-language detail beyond what the schema provides.

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

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

States a specific verb and resource: passages from 'the brand's own website' matching a query 'by words and meaning', with page provenance. The phrase 'the brand's own website' cleanly separates it from siblings search_docs and search_facts without opening their 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?

Gives explicit context: 'Use it to see what the site already says before asking the user, and quote it as the site's wording.' That is a clear trigger and even prescribes how to reuse the result. It stops short of naming when to prefer search_docs or list_pages instead.

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

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

Annotations mark it non-read-only, open-world, and non-destructive; the description goes further by disclosing the exact downstream behavior (creates a draft that is never published, the team publishes it, Cleotic later marks the page live) plus cost ('Free') and a user-confirmation requirement. It does not clarify retry/replay behavior, which is only covered in the idempotency_key schema.

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

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

Three tightly packed sentences with zero filler, leading with the action and state change before prerequisites and the confirmation requirement. 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, return values need not be described, and the description still covers the state transition, prerequisite, fallback, cost, and confirmation duty. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents all three parameters and the baseline is 3. The description adds real meaning for 'brand' by requiring that it resolve to exactly one ready CMS destination, a constraint the schema does not express.

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 (send) plus resource (page) plus destination (the brand's connected CMS) and the resulting state (new draft, never published). This clearly separates it from siblings like mark_page_published, create_page, and edit_page without opening any schema.

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

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

Gives a concrete prerequisite ('exactly one ready CMS destination'), a when-not ('otherwise send it from the app'), and a safety directive ('Confirm with the user first'). It does not explicitly name sibling tools as alternatives, which keeps it from a 5, but the routing guidance is clear and 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 declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, but the description adds non-obvious behavior the annotations cannot convey: changing how answers name the brand triggers an automatic re-read of existing answers and the call returns 'pending' until it completes, plus cost ('Free'). It doesn't cover auth/permission requirements or the replace-vs-merge nuance for aliases (left to the schema), so it is strong but not exhaustive.

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 purpose, then update contract, then sibling routing, then async side effect and cost. Every clause carries distinct 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?

An output schema exists, so return values need not be described, yet the description still flags the important 'pending' interim status after a name-affecting change. Combined with sibling routing and the partial-update contract, an agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: it identifies the editable fields as name/domain/aliases and clarifies the partial-update semantics ('what you leave out stays as it is'). It does not restate per-parameter formats, which the schema already handles.

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 ('Create or edit the brand being tracked') plus the fields involved (name, domain, aliases), and explicitly differentiates itself from two siblings (save_competitor, update_brand) by naming when each is used instead. An agent can pick this tool without opening any schema.

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

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

Gives explicit routing rules: use save_competitor to add a competitor, use update_brand for renaming a brand/study or pausing it. It also states the partial-update contract ('Pass at least one; what you leave out stays as it is'), which removes any ambiguity about when this is the right call.

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 it is a non-readonly, open-world write that is not destructive, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: it returns 'pending' while reading (async), and it consumes model budget to read the site. It does not cover failure modes, auth requirements, or rate limits, so a 4 rather than 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 tight sentences with zero filler, front-loaded with what the tool does before the polling workflow and the cost note. Every clause earns its place and none repeats the schema 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?

An output schema exists, so return-value detail is unnecessary, yet the description still supplies the one return fact that matters for orchestration ('returns pending'). For an async, multi-step workflow tool, an agent has everything needed to call it and route to the next step.

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 thorough idempotency_key explanation, so the schema carries parameter semantics entirely. The description adds nothing about url format or key reuse beyond what the schema already states, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('Add a brand') and immediately specifies the mechanism and scope: Cleotic reads the website and proposes the brand, competitors, a segment, and prompts. An agent can distinguish this entry-point tool from siblings like update_brand or save_competitor without opening any schema.

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

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

Explicitly names the follow-up workflow and the exact siblings to use: poll get_brand_setup until approval is needed, review proposals with the user, then call approve_brand_setup. The when-to-use path and the alternatives are both 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, open-world). The description adds genuinely new behavioral context beyond them: the one-model-call cost, the fact that ranking depends on the demand provider having data, and the null/0 sentinel meaning for monthly_ai_searches.

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 purpose and each carrying distinct information (ranking caveat, no-save behavior, cost). No filler or repeated schema content.

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

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

An output schema exists, so return structure needn't be repeated, and annotations carry the safety profile. The description fills the remaining gaps an agent needs: cost, the meaning of a null/0 demand figure, and the absence of persisted IDs.

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

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

Schema description coverage is 100%, so brand, segment, topic and count are already documented, establishing a baseline of 3. The description doesn't add syntax or format detail for any input parameter; its illustrative parameter list (text, tags, category, intent_type) actually belongs to the sibling save_prompt, not this tool.

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

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

States a specific verb and resource ('Suggest prompts for a segment about a topic') and immediately carves out scope by noting it 'saves nothing and returns no IDs,' which distinguishes it from save_prompt and list_prompts 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 clear workflow context: this is a suggestion-generation step whose output is consumed via save_prompt (text, tags, category, intent_type). It routes the agent forward, but never states when to prefer this over list_prompts or what conditions make it worth the model-call cost.

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