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

Annotations only declare readOnlyHint/destructiveHint/openWorldHint; the description adds the critical non-obvious trait that this nominally read-only tool consumes prepaid balance, that billing is per successful step at per-surface rates in USD, that the charge appears in the result field cite42Billing, and that prices come from cite42_pricing. The cost-confirmation threshold is exactly the kind of behavioral context annotations cannot convey.

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 workflow purpose in the first sentence, then layers billing and cost-confirmation rules. Every sentence earns its place, though the billing mechanics are dense and could be tightened without losing meaning.

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 6 parameters at full schema coverage and no output schema, the description covers purpose, cost model, where to get exact prices, and the confirmation threshold, plus the cite42Billing result field. It is nearly complete; minor gaps include expected runtime or scope of the aggregated response for what is clearly a heavy multi-surface job.

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 every parameter including models defaults, fullSweep interaction, and country default. The description adds only indirect hints (per-surface billing, call-count threshold) and no new syntax or format detail beyond the schema, so baseline 3 is appropriate.

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

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

States a specific verb+resource ('Run the competitor-content workflow') and enumerates the five constituent analyses (AI rankings, head-to-head comparison, citations, keyword demand, topic coverage) aggregated in one response. This clearly distinguishes it from single-surface siblings like cite42_rankings, cite42_compare, and cite42_citations by signaling it is a composite workflow.

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 actionable usage context: exact prices come from cite42_pricing (free), and for plans over 20 calls or $5 the agent should estimate cost and confirm with the user first. It does not explicitly contrast when to use this composite workflow versus the individual sibling tools, so it falls short of full alternative routing.

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

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

Annotations cover only the safety profile (readOnly, openWorld, non-destructive), so the description carries the rest — and does it well: billing is per succeeded step at per-surface rates, in USD against a prepaid balance, with the billing figure exposed in the cite42Billing result field and a spend-confirmation threshold. This is exactly the behavior (partial billing, prepaid drawdown) an agent must know before invoking.

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, followed by billing mechanics and the cost-confirmation rule; three sentences, each carrying weight. Slightly dense billing prose in the middle sentence, but nothing 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?

For a five-parameter composite with no output schema, the description covers cost, billing field, and confirmation thresholds, and names cite42_pricing as the price source. What the aggregated response actually contains is left implicit, which is a minor gap given there is no output schema to fall back on.

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 per-surface billing notes, defaults, the fullSweep-vs-models precedence, and character limits, so the schema does the heavy lifting. The description adds no parameter-level meaning beyond that, making the baseline 3 correct.

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

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

Names a specific workflow verb ("Run the topic-demand workflow") and enumerates the four surfaces it aggregates — SEO keywords, Trends, AI answers, audience conversations — which distinguishes it from the single-surface siblings (cite42_keywords, cite42_trends, cite42_search, cite42_reddit_trends). "Aggregated in one response" makes the composite nature explicit.

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 cost-scoped guidance ("plans over 20 calls or $5, estimate the cost and confirm with the user first") and routes to cite42_pricing for exact prices, which is useful operational guidance. However, it never states when to pick this aggregate over calling the individual sibling tools, which is the most likely selection dilemma for an 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 declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds two pieces of context not in the structured data: the balance is denominated in USD and the call is free. It does not describe pagination or return shape, but for a trivial read that gap is minor.

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

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

Two short sentences with zero waste. The resource and scope are front-loaded, and the cost note is appended last where it belongs.

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

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

For a zero-parameter read tool whose annotations fully cover the safety profile, the description supplies what is needed: what is returned, in what currency, and that it is free. It lacks any signal distinguishing it from the credits/usage/pricing siblings, which is the only real completeness gap.

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

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

The tool takes zero parameters, so the schema cannot be deficient and there is nothing for the description to compensate for. Baseline 4 applies; the 'for the connected account' phrase usefully clarifies which account's balance is returned.

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 (Check) plus resource (remaining Cite42 balance), currency (USD), and scope (connected account). However, it does nothing to distinguish itself from siblings like cite42_credits, cite42_usage, or cite42_pricing, which an agent could easily confuse with a balance check.

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 guidance and no mention of alternatives among the closely related sibling tools (cite42_credits, cite42_usage, cite42_pricing). The only implicit signal is the word 'Free', which hints at cost but not at selection logic.

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

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

Annotations only cover the safety profile (readOnly, openWorld, non-destructive), and the description layers on genuinely non-obvious behavior: priced per AI surface queried, billed against a prepaid balance, reported in a cite42Billing result field, and a cost-confirmation threshold for larger plans. That is real operational context an agent cannot infer from the schema or annotations.

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

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

Front-loaded with the core purpose, then layered pricing, sibling routing, and cost guardrails. It is a dense paragraph but nearly every sentence carries distinct operational value; a small amount of compression is possible 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?

With no output schema, the description partially compensates by naming a return field (cite42Billing) and a reusable requestId, plus the billing/permission implications of calling it. It does not describe the shape of the citation results themselves, which leaves a modest gap for a tool whose whole value is its returned corpus 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 models, fullSweep, url, and query semantics are already fully documented (including per-surface character limits and the fullSweep/models interaction). The description adds only the cost consequence of querying multiple surfaces, which is already implied by the models schema text. Baseline 3 is correct when the schema carries the parameter load.

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 and resource: "Find which sources a model's web search surfaces for a query," and immediately scopes it to aggregating cited URLs across models with per-model counts. It also draws an explicit boundary against a plausible misreading ("not the citation links a consumer chat UI renders for a logged-in user"), letting an agent separate it from cite42_find_ai_citation_gaps or cite42_search 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 concrete usage context: pass the requestId to cite42_recommendations when the user wants improvement advice, and pause for confirmation on plans over 20 calls or $5 with exact prices from cite42_pricing. It stops short of explicitly stating when to prefer this over the nearest sibling (cite42_find_ai_citation_gaps / cite42_rankings), so the alternative-selection guidance is implied rather than spelled out.

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

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

Goes well beyond the readOnly/openWorld annotations by disclosing billing mechanics (per AI surface queried, billed in USD to a prepaid Cite42 balance via the cite42Billing result field), the additional cost of fullSweep, and a mandatory user-confirmation threshold. It also reveals the chaining contract (requestId feeds cite42_recommendations), which an agent could not infer from schema or annotations.

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

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

Front-loads the core purpose and outputs, then layers chaining and pricing. Efficient overall, though three consecutive sentences on pricing/billing add density that could be trimmed without losing the critical cost-confirmation rule.

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

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

There is no output schema, and the description does name the two return components (per-brand rankings and co-mention graph) plus the billing result field, and it covers cost behavior for a 5-parameter tool. It stops short of explaining the shape of the co-mention graph or ranking payload, which is the main remaining gap.

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

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

Schema description coverage is 100%, so parameter meaning is already fully documented in the schema (including model defaults, fullSweep precedence, and char limits). The description adds no additional syntax or constraint detail about the parameters themselves, so the baseline 3 is appropriate.

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

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

States a specific verb and resource — comparing one primary brand head-to-head against a competitor set in AI answers — and enumerates the two outputs (per-brand rankings plus a co-mention graph). This clearly differentiates it from neighbors like cite42_rankings or cite42_analyze_competitor_content, which do not imply a head-to-head comparison with co-mention output.

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 routing guidance — pass the requestId to cite42_recommendations when improvement advice is requested — and an explicit cost/confirmation workflow (estimate and confirm with the user for plans over 20 calls or $5, prices from cite42_pricing). It does not, however, state when to prefer this over the closest siblings (cite42_rankings, cite42_analyze_competitor_content), so selection between similar comparison tools is left to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds one genuine trait not in the structured data — 'Free', i.e. no credit cost — which is useful for a cost-aware agent, but there is no pagination, auth, or return-format context.

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

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

Two short sentences, front-loaded with the tool's identity and relationship to its canonical sibling, with no filler. Every clause carries information the agent can act on.

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

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

For a zero-parameter, annotation-backed legacy alias with no output schema, the description covers identity, delegation to cite42_balance, and cost. Return-value shape is not described, but it is implied to match the sibling, so the gap is minor.

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

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

The tool takes zero parameters, so there is nothing for the description to clarify and the baseline of 4 applies. The alias reference correctly signals that the same (empty) input contract as cite42_balance is expected.

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

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

The description names the resource (credits/balance) via an explicit alias relationship to cite42_balance for older integrations, which lets an agent identify it without opening the schema. It does not restate the verb 'check balance' directly but the alias reference makes the purpose 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?

'For older integrations' gives the intended audience but never explicitly instructs the agent to prefer cite42_balance for new work. The when/when-not distinction is implied by the alias framing rather than stated.

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

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

With no annotations provided, the description carries the full burden and does substantial work: partial billing only for successful steps, per-surface rates, USD denomination, charge against a prepaid balance, the result field cite42Billing, and a cost-confirmation threshold. It does not state the operation's safety profile (read vs mutation) or any rate/concurrency limits.

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

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

Front-loaded purpose first, then billing model, then the confirmation gate without filler. The billing sentence is dense with parenthetical detail but every clause is 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?

Covers purpose and cost behavior well, and no output schema exists to relieve the description of return-value explanation. However, it never says what the returned gap data looks like, whether execution is synchronous or long-running, or expected latency for a five-surface sweep.

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 high (~80%): query, brand, url, models, and fullSweep all carry schema descriptions. The description adds the brand/domain/URL relationship but nothing new about model selection semantics or the cost of subsets, so 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 and resource ('Run the AI-citation-gaps workflow') and defines the output concept precisely as 'queries where AI answers cite others but not your brand, domain, or URL'. An agent can distinguish this from generic search tools, though no sibling (e.g. cite42_search, cite42_compare) is named to sharpen the boundary.

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

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

Gives a concrete gating rule: 'For plans over 20 calls or $5, estimate the cost and confirm with the user first', and routes price discovery to cite42_pricing. It lacks an explicit when-not or a direct comparison against alternatives, so it stops short of a 5.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), and the description adds substantial non-obvious behavior on top: partial-failure billing ('billed for the steps that succeed, at per-surface rates'), the billing currency and channel ('USD... to the user's prepaid Cite42 balance'), where the cost lands in the response (cite42Billing), and where to get exact prices (cite42_pricing). That is exactly the kind of cost/consumption disclosure an agent needs before invoking a metered fan-out 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 sentences, purpose first, then cost mechanics, then the confirmation gate; the ordering is well front-loaded and nothing is padded with marketing language. The two consecutive billing sentences ('Billed for the steps that succeed' / 'Billed in USD...') overlap slightly and could be compressed into one.

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 8-parameter, multi-surface fan-out tool with no output schema, the description covers what an agent most needs before calling: scope, metered cost, partial-success billing, and a pointer to exact pricing. The main remaining gap is the shape of the aggregated response beyond the cite42Billing field (per-surface result structure, latency, whether surfaces can fail independently in the body), which matters given there is no 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 every parameter (models, fullSweep, channels, country, competitors, topic, brand, audience) is already documented in the schema, including the 700/2000-character query limits and the fullSweep-vs-models precedence. The description only reinforces that surfaces are billed separately and defaults exist, adding little syntax or semantics the schema does not already provide — the baseline 3 for high coverage.

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 ('Run the content-opportunities workflow') and enumerates exactly what it fans out over (AI search, SEO keywords, trends, Reddit, YouTube, citations), plus the key differentiator that results come back 'aggregated in one response' rather than per-surface. It never names the single-surface siblings (cite42_search, cite42_keywords, cite42_trends) that an agent should weigh it against, so sibling differentiation is implicit rather than stated.

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 real conditional guidance for cost: 'For plans over 20 calls or $5, estimate the cost and confirm with the user first,' and the schema carries per-parameter routing (subset models, fullSweep). However, the description never says when to choose this aggregate workflow over the individual sibling tools it bundles, which is the central selection decision for this tool; usage must be 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 only cover safety (readOnly, openWorld, non-destructive), but the description adds substantial hidden behavior: per-surface metered billing in USD against a prepaid balance, charging only for successful steps, a named result field (cite42Billing), and a pre-confirmation cost gate. That is exactly the kind of cost/auth context an agent needs before invoking a paid, open-world tool.

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

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

Front-loads the verb and scope in the first sentence, then layers cost/billing mechanics. Efficient overall, though the second billing sentence repeats the cost-gating point alongside the cite42_pricing pointer, which a stricter edit could merge.

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

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

With no output schema, the description correctly states what comes back (evidence and a suggested prompt, not a finished brief) and names the billing result field. It leaves the structure/volume of the evidence payload unspecified, but for a 7-param, single-required-param tool this is close to complete.

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

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

Schema description coverage is 100% and the schema itself already documents every parameter well (models billing/subset semantics, fullSweep ignoring models, per-surface character limits, defaults). The description adds no parameter-level guidance, so the baseline 3 applies — the schema, not the description, carries this dimension.

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 ('Run the content-brief workflow') and enumerates the exact surfaces it aggregates (AI answers, citations, SEO keyword demand, trends, Reddit, YouTube), which clearly distinguishes it from the single-surface siblings (cite42_search, cite42_trends, cite42_reddit_trends, cite42_citations). It also clarifies the deliverable boundary: it returns evidence plus a prompt, and the caller writes the brief.

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 operating context — when the user wants a cross-surface brief, and the cost-confirmation threshold for large runs (>20 calls or $5) — and routes to cite42_pricing for exact prices. It stops short of explicitly contrasting with the narrower siblings (e.g. 'use this instead of chaining cite42_keywords + cite42_trends'), so the alternative selection is implied rather than spelled out.

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

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

Annotations cover the read-only/open-world/no-destruction profile, and the description adds substantial non-obvious behavior: outcome-based billing tiers, that the reply echoes requestedKeyword, the possible status values ("exact" or "no_data"), and the trap of reading an alternative's metrics as the seed's. It does not state rate limits or auth requirements, but for a billed read tool this is well beyond the annotation baseline.

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 purpose, then usage, then behavioral/billing caveats in a logical order. Dense but a couple of the billing sentences could be tightened; nothing is repeated verbatim 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?

With no output schema, the description carries the return-value burden and does so: it explains the echoed keyword, the status field, and where related terms appear, plus the billing basis and field name. An agent has everything needed to call and interpret this correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds meaning beyond the schema by tying ideas:true to a specific user intent and to a higher billing tier. Country/language semantics are entirely left to the schema.

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

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

States a specific verb+resource ("Classic keyword data for a seed term") and explicitly distinguishes itself from the batch sibling and from AI-search tools ("Not a multi-model AI-search query"). An agent can route between cite42_keywords, cite42_keywords_batch, and cite42_search 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 an explicit condition for omitting vs. setting ideas:true ("Omit ideas when the user only needs that seed's monthly search volume... Set ideas:true only when the user asks for related, alternative, or long-tail suggestions"), plus a cost-confirmation rule for plans over 20 calls or $5.

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

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

Annotations already cover the safety profile (readOnly, openWorld, non-destructive), but the description adds substantive behavioral context beyond them: the call is metered ('Billed by outcome'), billed in USD against a prepaid balance, the cost appears in a named result field (cite42Billing), and large jobs require user confirmation. This is exactly the kind of cost/authorization disclosure annotations cannot 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?

Four tight sentences, front-loaded with the core purpose and scope, then the exclusion, then the billing and cost-confirmation rules. No sentence is redundant or restates the tool name.

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

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

With no output schema, the description still names the fields returned (volume, CPC, competition) and the billing result field, and it covers scope limits and cost handling. Nothing an agent needs to invoke this correctly and set user expectations 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 description coverage is 100%, so the schema already documents seeds, country, and language, including the 2-50 bound and defaults. The description restates the count constraint but adds no syntax or format 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?

States a specific verb ('Check') and resource ('search volume, CPC, and competition') with an explicit scope ('two to 50 distinct seed keywords in one request'). The clause 'No related ideas' differentiates it from the sibling cite42_keywords, so an agent can tell them apart 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 operational context: it points to cite42_pricing for exact prices and instructs the agent to estimate and confirm cost with the user when plans exceed 20 calls or $5. It does not, however, explicitly frame when to choose this over cite42_keywords other than the implicit 'no related ideas' distinction.

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, openWorld, non-destructive), but the description adds substantial behavior beyond them: billing occurs only for steps that succeed, charged at per-surface rates in USD into a prepaid balance, with results surfaced in the cite42Billing field. This is exactly the cost/permission context an agent needs before invoking a metered workflow.

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

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

Front-loads purpose before any caveats, and every sentence carries information (output nature, downstream tool, billing, confirmation threshold). Slightly dense with billing mechanics, but nothing is redundant.

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

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

With no output schema, the description still characterizes the return ('evidence and a suggested prompt') and points to the cite42Billing result field, so an agent knows what comes back. Only minor gaps remain, such as what constitutes a billable '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%, so defaults, enums, and the fullSweep/models relationship are already documented in the schema. The description reinforces the per-surface billing implication of `models` but adds no syntax or format detail beyond what the schema provides; baseline 3 is appropriate.

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

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

States a specific verb and resource (run the AI-prompt-map workflow) and the exact output: a researched list of buyer prompts worth tracking. Names the data sources it merges (AI search, SEO demand, trends, citations, Reddit, YouTube), which distinguishes this composite workflow from single-source siblings like cite42_keywords or cite42_reddit_trends.

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

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

Gives clear context and downstream routing: the output is evidence plus a suggested prompt, not a finished list, and those prompts can be tracked via cite42_tracker_create. Adds an explicit cost-control rule ('over 20 calls or $5, estimate and confirm with the user first'). Missing only explicit when-not-to-use guidance against the single-surface research siblings.

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 indicate it is a safe, non-destructive read operation. The description adds that the tool is free and returns pricing data, and the name and annotations confirm it is a static lookup. This is sufficient for a zero-parameter, read-only informational 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?

The description is a single, well-structured sentence that front-loads the purpose and then adds usage context. Every part earns its place with no unnecessary detail.

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

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

Given the tool's simplicity (no parameters, no output schema) and the presence of annotations, the description provides all necessary information: what it returns, when to use it, and that it is free. No further detail is required.

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

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

The tool has zero parameters, so there are no parameter semantics to describe. A baseline of 4 is appropriate because the description does not need to explain parameters, and the schema, though empty, is accurate.

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

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

The description states a specific verb and resource ('Get the exact Cite42 price table in USD') and enumerates the contents (per-surface rates, flat-rate tools, workflow maximums, free tools). This clearly distinguishes it from sibling tools like cite42_balance or cite42_usage, which concern account state rather than pricing.

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 explicitly names when to use it: 'for cost questions and to estimate a plan before running it.' It provides a clear context and no ambiguity about when to invoke this tool versus alternatives.

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

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

Annotations only declare readOnly/openWorld/non-destructive; the description adds substantial behavioral context the annotations lack: per-surface pricing, USD billing against a prepaid balance, the cite42Billing result field, a free pricing lookup path, and a confirm-first rule for large plans. That is exactly the kind of cost/authorization disclosure an agent needs before calling a billable read.

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

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

Front-loads the core purpose and outputs before the billing and chaining notes. It is dense but each sentence carries a distinct fact (outputs, chaining, pricing, threshold). Slightly long, but nothing is truly wasted.

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

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

No output schema exists, yet the description names the returned metrics (mention rate, average position, per-model breakdown) and the billing result field, so an agent knows what to expect. Combined with cost and chaining guidance, it is nearly complete for a 4-param billable tool, with only minor gaps in return structure detail.

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

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

Schema coverage is 100%, so all four parameters are already well documented in the schema (models billing, fullSweep behavior, character limits). The description reinforces the per-surface pricing model but adds no parameter syntax or format detail beyond what the schema provides, 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?

States a specific verb (measure) and resource (brand/competitor rankings in AI answers), then enumerates the concrete outputs: mention rate, average position, per-model breakdown. The list of AI surfaces is named explicitly, so an agent understands exactly what this produces versus generic search/compare siblings.

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

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

Gives clear usage context: the requestId chains into cite42_recommendations when the user wants improvement advice, and it sets an explicit cost-confirmation threshold (over 20 calls or $5). It does not explicitly name when to prefer this over cite42_compare or cite42_search, so it falls short of full alternative routing.

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

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

Annotations already establish read-only/non-destructive/open-world, but the description adds the operational profile that annotations cannot: which resources are fetched (page, robots.txt, up to two AI-cited pages), that HTML is returned without JavaScript, exactly when a charge applies (report includes page-comparison advice backed by quotes), currency and billing target (cite42Billing, prepaid balance), and a spend-confirmation threshold.

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

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

Front-loads the purpose and then walks modes in a logical url-with/url-without order, and most sentences carry unique operational detail. It is still a single dense paragraph with mild redundancy (cite42_pricing appears twice, billing restated), which costs it the top mark.

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

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

For a 7-parameter, nested-object tool with no output schema and no required parameters, the description covers trigger, mode branches, side effects, cost model, confirmation policy, and explicit exclusions. An agent has enough to decide whether, when, and how cautiously to call 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?

Adds real meaning over the schema: it explains how url and query interact across the with/without-saved-result modes, that requestId/trackerRunId/evidence are the three ways to supply 'a saved result', and that models only affects the no-saved-result citations check. However, since schema coverage is 71% and the schema already restates the url/query/models behavior, some of this is duplicative, and the context object (goal/brand/domain/audience) is never explained.

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 and scope: 'Page-level AI visibility recommendations,' and immediately anchors the trigger ('for when the user asks how to improve a page'). It also distinguishes itself from the nearest sibling by naming cite42_citations as the pricing analogue, so an agent can separate this from the plain citations tool without opening schemas.

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

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

Gives explicit mode selection: with a saved result (requestId/trackerRunId/evidence) it reports on one measured prompt; without one, 'url alone' runs a free technical check while 'url with query' runs a citations check first. It also names when-not (no site-wide crawl, keyword advice or tracker activation) and routes pricing questions to cite42_pricing, plus a confirmation rule above 20 calls or $5.

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

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

Annotations already establish read-only, open-world, and non-destructive behavior, but the description adds meaningful context: pages may be cached, extraction is not independently verified, exact dates/growth/quote insights are unavailable, output fields are listed, and billing behavior is explained. It also notes the deprecated risingThreads alias, which helps avoid misuse.

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

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

The description is front-loaded with purpose and return behavior, followed by warnings and billing details. It is somewhat dense and long, but most sentences carry relevant information for a complex paid, open-world tool; a bit of tightening could improve readability.

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

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

With no output schema, the description compensates by explaining what is returned: titles, authors, excerpts, relative ages, scores, comment counts, sampled comments, and summaries. It also discloses coverage limits, billing, and cost-confirmation thresholds, making it complete enough for correct invocation.

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

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

The input schema already documents all three parameters at 100% coverage, including topic, timeframe, and subreddits. The description does not add syntax, constraints, or examples beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The opening sentence states a specific verb and resource: 'Discover relevant Reddit discussions with Google Search and read up to three thread pages through Gemini URL context.' It clearly distinguishes this tool from siblings like cite42_search and cite42_youtube_trends by scoping it to Reddit discussions and Gemini-read threads.

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 operational constraints such as checking coverage warnings and confirming costs for large plans, but it does not explicitly say when to use this tool versus alternatives like cite42_search or cite42_trends. Usage is implied by the Reddit-discussion focus, not stated as an alternative-selection 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/openWorldHint/non-destructive, so safety is covered. The description adds genuinely useful non-schema behavior: per-surface pricing, USD billing against a prepaid balance, the cite42Billing result field, and a cost-confirmation threshold. It omits rate limits or auth requirements, keeping it just below top marks.

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

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

Three sentences, front-loaded with purpose then billing then cost-control guidance; every sentence earns its place. It is dense with parentheticals 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?

With no output schema, the description correctly summarizes return values (answers plus cited sources) and names a billing result field. It also covers the cost-confirmation workflow. Some operational details (rate limits, auth) are absent but not critical for calling 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 the schema already documents query, models, and fullSweep in detail (including enums, defaults, and character limits). The description's parameter-related content (subsets, defaults, fullSweep cost) largely restates schema information, 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 (run a query) and resource (AI models), names the five surfaces covered, and describes the return shape (each model's answer plus its cited sources). This clearly distinguishes it from siblings like cite42_compare, cite42_citations, or cite42_rankings.

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 when-to-use guidance: pass a subset of models when the user names surfaces or wants lower cost, omit for defaults, use fullSweep for all five, and confirm with the user for plans over 20 calls or $5. It does not explicitly route to alternative siblings (e.g., cite42_compare for cross-model comparison), so it stops 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?

Annotations cover the safety profile (readOnly, openWorld, non-destructive) and the description goes well beyond them: per-surface billing, USD charging to the prepaid Cite42 balance, the cite42Billing result field, a pointer to cite42_pricing for exact prices, and an explicit authorization threshold before large spend.

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 purpose and output shape, then the chaining value, then the cost rules. Information-dense with no filler, though the multi-clause billing sentence is heavy compared to the rest.

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

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

With no output schema, the description takes on the job of describing returns (per-model tone split, verbatim phrases, aggregate, cite42Billing field) and does so. Cost, chaining, and scope for a paid open-world tool are all covered.

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

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

Schema description coverage is 100%, so the schema already documents brand, query, models, and fullSweep in detail. The description reinforces that each surface is billed separately but adds no syntax or format detail beyond the schema, matching the baseline for a fully-documented 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?

Specific verb (score) plus resource (AI model answers about a brand for a query) plus the exact output shape (per-model positive/neutral/negative split with verbatim phrases, plus aggregate). This is clearly distinguishable from siblings like cite42_rankings or cite42_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?

Explicitly routes the agent: the returned requestId feeds cite42_recommendations when the user asks for improvement advice, and it prescribes cost confirmation for plans over 20 calls or $5. It never states when NOT to use this tool, but the forward-chaining and billing guardrails are concrete.

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?

Far exceeds the annotation hints (readOnly=false, idempotent=true, destructive=false): it discloses that activation authorizes ongoing billed calls until paused, that the balance guard can refuse the call, that tracker emails send a setup summary and results on every completed run even when nothing changed, and the full billing model. These are exactly the side effects and cost implications an agent needs before invoking a writer.

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

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

The core action and scope are front-loaded in the first sentence, followed by guard rails, response contents, and email/billing behavior in a logical order. It is dense but every sentence carries operative information; only minor tightening would help.

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

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

With no output schema, the description compensates by describing the response (balance, cost per run, runsDryAt) and covers billing, email side effects, and the refusal condition. Combined with the safety annotations, an agent has everything needed to call it correctly and anticipate outcomes.

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 schema, including that maxCostMicroPerRun is the exact estimatedCostMicroPerRun from the latest record. The description reinforces the equality constraint but adds no format, range, or derivation detail beyond what the schema and annotations provide, 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 (activate/resume) and a precise resource (recurring weekly or monthly tool calls/trackers), and its meaning is clearly separable from siblings like cite42_tracker_pause, cite42_tracker_run, and cite42_tracker_create. An agent can tell what this does without opening a schema.

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

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

It gives clear operating context for when activation applies (resuming recurring billed runs) and hard preconditions: maxCostMicroPerRun must match the latest estimate, and activation is refused when the balance can't cover the next run. It stops short of naming the sibling to use instead when you don't want recurring runs (pause) or want a one-off (run), so it is clear context without explicit 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 substantial context beyond annotations: the created object is a draft, no recurring calls begin at creation, management and reporting are free, and each run bills one call per prompt at per-surface rates. This cost and lifecycle detail is exactly what the annotations (readOnly=false, destructive=false) do not convey.

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

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

Front-loads the purpose in the first clause and keeps to three dense sentences. The trailing billing sentence is useful but the paragraph is packed; nothing is wasted, though it is heavier than strictly needed.

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

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

With no output schema and a nested cadence object, the description covers lifecycle (draft, no auto-runs), cost, and prompt sourcing well. It stops short of stating that activation is required to start runs, which is left implicit.

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 88%, so the schema already carries most parameter meaning (brand/competitors usage per primitive, cadence fields, model defaults). The description reinforces the 'one measurement' and 'set once for all prompts' model but adds no syntax or defaults 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 ('Create a draft weekly or monthly tracker') plus the exact scope of what a tracker is: one measurement applied to a list of prompts. It distinguishes itself from activation siblings by noting 'Creation does not start recurring calls,' so an agent can tell it apart from cite42_tracker_activate/run.

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

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

Gives clear context for when this applies and points to a source of input ('Prompt lists can come from cite42_map_ai_prompts research') plus the implied follow-up of activation. It lacks an explicit exclusions clause (e.g., when to use update vs. create), so it falls short of a 5.

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

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

Annotations already declare destructiveHint and idempotentHint, yet the description adds substantially: what is destroyed (configuration plus run history), what survives (financial usage and billing ledger records), the failure preconditions (queued/running runs), and the cost ('Free'). This is materially more than the annotations convey.

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, each carrying distinct information: effect, precondition, retention, cost. Front-loaded with the destructive action and 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 irreversible mutation with a single required parameter and no output schema, the description covers the full burden: preconditions, side effects, what is retained, and cost. Nothing an agent needs before invoking it 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?

Only one parameter (trackerId), and schema description coverage is 100% with a clear provenance note ('Cite42 tracker ID returned by a tracker management or report tool'). The description adds nothing about the parameter, so baseline 3 applies.

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

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

States a specific verb and resource ('Permanently delete a draft or paused tracker') and immediately scopes what else goes with it (saved configuration and run history). The distinction from sibling trackers tools like cite42_tracker_pause and cite42_trackers is clear from the 'draft or paused' constraint and the permanence 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?

Gives concrete when-not conditions: active trackers must be paused first, and deletion is rejected while a run is queued or running. This effectively routes the agent to cite42_tracker_pause, though it never names that sibling explicitly, so it stops just short of fully explicit alternative 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 idempotentHint=true, destructiveHint=false, and readOnlyHint=false. The description adds real value beyond them by stating that configuration and run history are preserved, and that the operation is free (no credit cost) — details an agent cannot get from the schema or hints.

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

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

Two short sentences, zero waste, with the core action front-loaded and the preservation guarantee immediately after. The trailing 'Free' is terse but carries genuine cost 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 mutation with rich annotations and no output schema, the description covers what changes (recurring calls stop), what survives (configuration and history), and cost. Only the reversal path (use tracker_activate to resume) is left implicit.

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

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

Only one parameter with 100% schema description coverage, which already explains that trackerId is the Cite42 tracker ID from a management or report tool. The description adds no syntax or sourcing detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource: pausing future recurring calls for a tracker. The clause 'while preserving its configuration and stored run history' implicitly differentiates it from cite42_tracker_delete, though no sibling is named explicitly.

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

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

Usage is implied (stop recurring runs without losing setup), but there is no explicit when-to-use, when-not-to-use, or named alternative such as cite42_tracker_delete or cite42_tracker_activate. An agent must infer the routing decision.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description still adds real behavioral context beyond them: results are 'bounded', they are 'stored' (no new run is triggered), and the operation is 'Free', which is useful cost information. It stops short of stating pagination or result-envelope 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?

A single front-loaded sentence that opens with the verb and resource, then compresses the return contents into a tight clause list, closing with the cost note. No filler sentences and nothing repeated from structured fields verbatim.

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

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

With no output schema, the description carries the burden of describing returns, and it does so by naming the payload categories (per-tool results, changes vs. prior observation, statuses, sampled times, costs). Combined with annotations that settle safety and scope, and a fully documented two-parameter schema, an agent has enough to call it correctly; only pagination/ordering details are absent.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema, including the limit cap for LLM context and the trackerId provenance. The description's 'bounded' hints at limit and 'one tracker' at trackerId but adds no new semantics, 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?

Specific verb 'Read' plus a precise resource, 'bounded stored run history for one tracker', and it enumerates what that history contains (per-tool results, deltas from the prior observation, statuses, sampled times, costs). It does not explicitly name a differentiating sibling such as cite42_tracker_run, though 'stored' implicitly signals it returns past runs rather than triggering a new one.

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 word 'stored' and the 'Free' note imply this is the zero-cost way to inspect prior runs rather than launch one, which is a usable contextual cue. However, there is no explicit when-to-use, when-not-to-use, or named alternative (e.g. cite42_trackers for listing, cite42_tracker_run for executing), so the agent must infer the routing.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false. The description adds genuinely non-structured context: the run is queued (async) rather than synchronous, retries with the same token collapse to one logical run, and runs are billed while tracker management/reporting is free. It stops short of saying where results land or how long a run takes.

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

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

Three short sentences, front-loaded with the action and followed by idempotency and billing. Every sentence carries information, though the pricing clause is dense and slightly tangential to invocation mechanics.

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 only two required params, no output schema, and rich annotations, the description covers action, idempotency, and cost. The one notable gap is not routing the agent to cite42_tracker_report for retrieving results after the queued run completes, though the free-report remark hints at 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, but the description adds the behavioral consequence of requestToken ('a repeated requestToken returns the same logical run') that the schema only gestures at with 'deduplicate a retried manual run'. trackerId is left entirely to the schema, which is acceptable given its full 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 ('Queue one manual run') scoped to a tracker's saved tool inputs. The word 'manual' implicitly distinguishes it from scheduled lifecycle siblings like cite42_tracker_activate/pause, so an agent can separate it without opening schemas.

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

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

The description gives clear context for invoking it (trigger an immediate run from saved inputs) and adds cost framing ('each run bills one call per prompt') that helps the agent decide whether to spend budget. It does not explicitly name an alternative or a when-not-to-use condition (e.g., scheduled runs vs. activate), so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, covering the safety profile. The description adds useful behavioral context beyond that: the tool is free and returns a concrete set of fields (status, cadence, tool configuration, cost estimate, accepted per-run maximum, next/last run times). It does not cover pagination or output format, but with no output schema the field list is valuable.

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

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

The description is two short fragments, front-loaded with the verb and resource, and contains no filler. The single-word cost note "Free." earns its place by conveying a meaningful constraint.

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

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

For a zero-parameter, read-only list tool with no output schema, the description supplies the key returned fields and cost status. It omits pagination or ordering details, but annotations carry the safety profile and the listed fields are enough to call and interpret the 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 the baseline is 4. There are no parameters for the description to clarify, and the schema is fully descriptive for its empty shape.

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 verb "List" and resource "trackers" with account scope, and enumerates the returned fields. It does not explicitly name or differentiate itself from nearby siblings such as cite42_tracker_report or cite42_tracker_run, so it falls short of a 5.

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

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

Provides no guidance on when to use this tool versus alternatives like cite42_tracker_report or cite42_tracker_run, and no when-not conditions. "Free" is cost information, not usage direction, so the description gives the agent little routing help.

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 the description adds real substance on top: the whole definition is replaced (clobbering risk), the edit returns the tracker to draft so new recurring cost can be confirmed, and runs bill one call per prompt at per-surface rates while management and report reads are free. These are side effects and cost traits an agent cannot derive from the annotations or schema.

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

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

Three sentences, front-loaded with the replace semantics and the read-modify-write instruction before the state-change and billing notes. Every sentence carries weight, though the closing billing sentence is the least essential to correct invocation and could be trimmed.

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, no-output-schema mutation tool this covers the essentials: replacement semantics, required full payload, resulting draft state, and cost model. It stops short of stating whether prior run history or reports survive the edit and whether the tracker must be paused first, which would have made it fully self-contained.

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

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

Schema description coverage is high (89%), so the baseline is 3, but the description adds meaning beyond the schema: it explains that a tracker read returns 'this exact shape', which justifies why five fields are required and why a full payload must be sent. The field list (name, cadence, measurement, prompts, configuration) also orients the agent to the parameter set without repeating per-field syntax.

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

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

States a specific verb and resource ('Replace a tracker definition') and immediately enumerates the replaced fields (name, cadence, measurement, prompts, configuration). The contrast with 'not a partial patch' cleanly separates it from an edit/patch style tool and from siblings like tracker_create, tracker_pause, or tracker_delete.

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 read-modify-write workflow: read the tracker, change what you need, send it back, and warns that a partial payload is wrong. It does not explicitly compare against tracker_create or tracker_activate, so the agent must infer when replacement is preferable to those alternatives, but the operational context is strong.

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

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

Annotations already cover the safety profile (readOnly, openWorld, non-destructive), and the description goes beyond them by disclosing the billing model, the cite42Billing result field, prepaid-balance charging, and a 20-call/$5 confirmation threshold. That is concrete behavioral context 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?

Front-loads the purpose in the first clause, then layers billing and the cost-confirmation rule. Every sentence carries information, though the billing/cost material occupies half the description.

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

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

For a read-only, no-output-schema tool this covers the essentials: what is returned, the billing field, and a spend guardrail. It is only slightly short on explicit sibling routing for the other trend tools.

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

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

Schema description coverage is 100%, so geo, term, and timeframe are already fully documented with examples and defaults. The description adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

Names a specific data source and the exact returns: Google Trends interest-over-time, related/rising queries, and a rising/falling/stable label. The 'Google Trends' qualifier distinguishes it from the cite42_reddit_trends and cite42_youtube_trends siblings, though it doesn't name those alternatives.

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?

Adds a useful distinction ('flat-priced data tool, not an AI-model query') and a cost-confirmation rule, which is real usage context. However, it never states when to pick this over the reddit/youtube trend siblings, leaving the main routing decision implicit.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the return contents and the 'Free' cost trait, but says nothing about how many calls 'last calls' covers, pagination, or freshness, which limits its 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?

A single front-loaded sentence that states the resource, the returned fields, and the cost trait, with zero filler. The clipped 'Free.' fragment is deliberate and earns its place by answering the cost question up front.

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

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

With no output schema and no parameters, the description must carry the return-value burden, and it does list costs, statuses and remaining USD balance. It stops short of specifying the window size ('last calls') or noting the overlap with cite42_balance, which are the only real gaps.

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 no parameter semantics to explain and the baseline is 4. The description correctly implies a no-argument call scoped to 'the connected account'.

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+resource ('Get recent Cite42 usage for the connected account') and enumerates the payload: last calls with cost and status plus remaining balance in USD. It does not, however, distinguish itself from siblings cite42_balance and cite42_credits, whose domains it partially overlaps by reporting balance.

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 guidance and no alternatives are named, despite three closely related billing/quota siblings (cite42_balance, cite42_credits, cite42_pricing). The trailing 'Free' hints that cost is not a concern when calling it, but that is inference, not instruction.

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

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

Annotations cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), and the description adds genuinely new behavioral context outside them: the call is billed in USD against a prepaid balance, the charge appears in the cite42Billing result field, and there is an approval threshold at 20 calls/$5. Return-format and latency details are absent, but the billing disclosure is substantive.

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

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

Three sentences, all earning their place: the first defines the data, the rest cover billing and the confirmation threshold. Front-loaded with the capability before the cost caveat. Slightly dense with the parenthetical field reference, but no filler.

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

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

With no output schema, the description does the work of enumerating the returned data categories, and it covers the billing side effect, which is the main risk of invoking it. The one gap is the absence of routing guidance versus the other trend/content-opportunity siblings.

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 topic, region, and timeframe are already documented with lengths and defaults in the schema. The description adds no additional semantics about parameter behavior, so the baseline of 3 for schema-driven parameters applies.

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

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

Names a specific verb+resource ('YouTube trend data') and enumerates the concrete outputs (rising videos, creator angles, title patterns, channel examples, video-market opportunities), which tells an agent exactly what it gets back. It implicitly separates itself from cite42_reddit_trends and cite42_trends via the 'YouTube' scope, but never names those siblings, so the differentiation is left to inference.

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

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

The description gives a concrete usage rule for cost control: check cite42_pricing for exact prices and estimate/confirm with the user for plans over 20 calls or $5. However, it offers no guidance on when to choose this over cite42_trends, cite42_reddit_trends, or cite42_find_content_opportunities, so the tool-selection 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.