Nephia

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

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds valuable behavioral context beyond that by stating the operation is free and does not consume credits, which is critical for an agent deciding whether to call it. It could further mention output format or authentication, but with annotations covering the read-only safety profile, this is sufficient.

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 sentences with no filler. The primary purpose is front-loaded in the first sentence, and the second sentence packs cost information and usage triggers efficiently. Every word earns its place.

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

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

For a zero-parameter, no-output-schema utility, the description covers all necessary aspects: what the tool returns, that it is free, and when to invoke it. There is no missing operational detail an agent would need to use 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?

The tool accepts zero parameters, so the input schema fully documents the absence of arguments. Per the rubric, 0 params yields a baseline of 4. The description adds nothing about parameters because none exist, which is appropriate.

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

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

The description states a specific verb and resource: 'Get the remaining credit balance for the Nephia account.' It clearly differentiates from siblings by addressing account-level balance rather than operation estimates or data queries, and the 'Free — does not charge credits' note further distinguishes it from charged tools.

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

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

The description explicitly states when to use the tool: 'Use this before a charged call, or after an insufficient-credits error.' This provides clear context and a decision rule, and since no sibling provides the same balance-checking function, there are no alternatives to exclude.

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

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

The description adds useful behavior beyond the readOnlyHint annotation by stating that the call costs 0 credits and that the returned estimate is computed by the same functions that actually charge analyses_run. This reassures the agent that the estimate is accurate and side-effect-free. No annotation contradiction exists.

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

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

Two sentences, no filler. The most important trait (costs 0 credits) is front-loaded, followed immediately by what the tool returns and how the estimate is computed. Every sentence earns its place.

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

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

For a tool with one simple parameter, no output schema, and read-only/open-world annotations, the description covers what the agent needs: cost, return value, relationship to analyses_run, and accuracy guarantee. No critical information is missing.

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

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

Schema coverage is 100%: itemCount is documented as 'How many items you would send' with min and max values. The description's phrase 'that many items' reinforces the parameter's meaning but does not add substantial new semantics beyond the schema, so the baseline of 3 is appropriate.

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

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

The description states a precise verb (returns) and resource (how many credits analyses_run would charge), and clarifies scope ('for that many items, per kind'). It clearly differentiates this from analyses_run by framing it as a zero-credit estimation tool, leaving no doubt about what the tool does.

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

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

The description implicitly tells the agent when to use this tool: instead of running analyses_run, call this to learn the credit cost in advance. It names analyses_run as the relevant alternative. It does not explicitly mention excluding query_estimate or explore_estimate, but the reference to analyses_run is sufficient for the primary use case.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=false), the description discloses billing behavior: credits per item counts, actual charge reflected in meta.credits_used, and that unanswered batches are not billed. This is valuable operational context the annotations do not cover. No contradiction with annotations.

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

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

Four sentences with no filler. The main purpose is front-loaded, cost and alternative are woven in, and the text is compact. It could be slightly tighter but is well-structured for quick consumption.

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 9 parameters and nested objects, the description covers cost, estimation, and the billing outcome. It mentions the response's meta.credits_used, giving a hint of the return shape, but does not fully describe the output structure. Since no output schema exists, a bit more detail on the response format would improve completeness, but it is sufficient for correct invocation.

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

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

Schema description coverage is 89%, so the schema already documents most parameters. The description adds cost semantics per 'kind' (1 credit per 50 vs 25), which enriches that parameter's meaning. It does not add detail to items, limit, since, or schema parameters, but the schema covers them adequately. The added cost context justifies a slight upgrade from the baseline 3.

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

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

The description opens with a clear verb and resource: 'Read a set of items with one AI pass.' It names the four kinds (group, classify, agent, summarise) and their distinct behaviors, making the tool's purpose unambiguous. It also references the estimation sibling, which helps differentiate when to use this versus analyses_estimate.

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 says to use analyses_estimate first if cost matters, providing a clear alternative. It explains the credit costs per kind, which informs when this tool is appropriate. However, it does not explicitly state when not to use this tool versus other exploration tools like explore, so it stops short of full exclusion 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 only say readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false; the description goes far beyond that by disclosing exact credit costs per source, that failed searches are not charged, that runs are refused if the balance cannot cover them, and how to interpret 'fetched without rows' versus 'failed search.' This is precisely the behavioral context an agent needs beyond the annotation booleans.

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 long but every sentence contributes operational knowledge: pricing, failure modes, estimate flow, and rerun guidance. It is front-loaded with purpose, then moves through usage and cost. While it could be formatted as bullets, the density is appropriate for the tool's complexity.

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 three nested parameters and no output schema, the description covers prerequisites, cost contingencies, failure semantics, and re-use via list_mentions. It explains what outcomes mean and when to use the estimate companion tool. No critical operational gap remains for an agent to call it correctly.

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

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

Schema coverage is 100% and the schema already documents every parameter with descriptions. The description adds extra meaning around estimateToken (its 15-minute validity, that mismatched arguments are refused, and that it must come from explore_estimate after user approval) and clarifies that variable legs are billed on actual results, so quotes should be 'up to'. Because the schema carries the structural detail, the description's extra parameter context elevates it above baseline.

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

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

The description opens with 'Ask the Sources once, now, without creating a keyword, and read the mentions they return,' which states a specific verb, resource, and scope. It further differentiates from siblings by framing it as the way to test a discovery angle before creating a keyword, and by pointing to explore_estimate and list_mentions as counterparts. This leaves no ambiguity about what the tool does.

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

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

It explicitly names the precondition 'Call explore_estimate first, show the person the total, and send its estimateToken only after they agree,' and gives an alternative for re-reading a run ('read it again with list_mentions kind="runs" run=<run.id> rather than running it twice'). It also frames the use case as testing before creating a keyword, which is a clear when-to-use. This is exemplary usage guidance.

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

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

Beyond readOnlyHint and openWorldHint, the description discloses zero cost, no Source calls, the valid=false refusal payload (status, code, fix sentence), the valid=true payload (total, perLeg, balance), and the estimateToken required by explore. No behavioral surprises are left hidden.

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 purpose is front-loaded and the workflow is clear. However, the final sentence largely repeats return fields already listed in the valid=true sentence, and 'without calling any Source' appears twice. Still, relative to the schema complexity, it is reasonably tight.

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

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

With no output schema, the description carries the full burden of explaining return values and failure modes. It covers both valid branches, the zero-cost/no-Source behavior, and the next step of passing estimateToken to explore. Nothing essential is missing for an agent to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents the two parameters and all nested fields. The description adds the useful relationship 'arguments of explore, minus the token,' but no per-parameter semantics beyond the schema. Baseline 3 is appropriate.

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

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

The opening phrase 'Price an Explore run without calling any Source' names a specific verb, resource, and scope. It also distinguishes itself from the sibling explore tool by saying it takes 'the arguments of explore, minus the token' and later passes estimateToken to explore.

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 clearly frames when to use it: before running an explore, to show the person the cost, then pass estimateToken to explore. It also notes it costs 0 credits and calls no Source. It does not explicitly enumerate when not to use it or contrast with other estimate siblings like query_estimate, 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 declare readOnlyHint=true and openWorldHint=true, and the description adds valuable behavioral context beyond them: it states the operation is free ('does not charge credits'), that returned criteria are 'already merged', and that stale Sources should be reported before using their mentions. This is meaningful for correct agent behavior and does not contradict annotations.

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

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

The description is longer than minimal, but every sentence earns its place: the first sentence is a dense specification of the return payload, the next two give diagnostic use cases, and the last adds cost information. It is front-loaded with the core purpose and contains no filler.

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

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

For a simple read-only tool with one parameter, no output schema, and an explicit enumeration of returned fields, the description is complete. It explains what the tool returns, when to use it, and the cost behavior, so an agent can invoke it correctly without additional context.

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

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

Schema coverage is 100% and the single `id` parameter is fully documented in the schema, including the 404 vs 403 behavior. The description adds no parameter-level detail, so it earns the baseline for high schema 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 uses a specific verb ('Get') and resource ('keyword'), and enumerates the exact response contents, distinguishing it from siblings like get_keyword_results and get_keyword_events. It frames the tool as the diagnostic view for 'why did/didn't this get caught?', which clearly identifies its unique purpose.

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 tells the agent when to use the tool: to answer 'why did/didn't this get caught?' and to report a stale Source before answering from mentions. It does not explicitly name alternatives or state when-not-to-use, but the use cases are clear and actionable.

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

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

The readOnlyHint and openWorldHint already establish its non-mutating nature. The description adds useful behavioral context: events are replayed in webhook shape, activity logs checks and deliveries, runs includes no-op answer runs, and the operation is free and does not charge credits. There is no contradiction.

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 longer than minimal, but every sentence adds value: it covers the primary use case, distinguishes the sibling tool, explains three modes, and notes the credit behavior. It is structured around kind values and remains efficient despite the complexity.

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 must communicate return shapes, and it does: events lists the exact fields, activity lists the log entry fields, and runs are described as stored AI answer runs with citations and brand mentions. Ordering, mode behavior, and an alternative are also covered, making this complete for a six-parameter tool.

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

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

Schema description coverage is 100%, so the schema already fully documents id, kind, limit, since, engine, and source. The description adds high-level meaning for the three kind values but does not meaningfully expand on parameter syntax or constraints 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?

The description clearly identifies a specific verb/resource pair: reading/replaying a keyword's events or activity. It explicitly distinguishes itself from get_keyword_results by explaining what an event includes beyond a mention amount, and the title reinforces the three kinds of data returned.

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

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

It states when to use this tool ('without a webhook receiver'), defines each kind's purpose, and explicitly points users to get_keyword_results when they want human-readable mentions. This is direct, actionable routing guidance.

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

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

Beyond the sparse annotations, the description discloses important behavioral traits: the default text mode is free, semantic mode charges 1 credit per question with a 10-minute free repeat, results are cursor-paged with nextCursor, and q= already handles keyword filtering in text mode. It does not mention auth or rate limits, but the pricing, paging, and misuse warning add considerable value beyond the annotations.

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

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

The description is five sentences, front-loading the core relationship to list_mentions and the purpose. Each sentence contributes distinct information: scope, use cases, cost model, a warning, and paging. It is slightly longer than minimal but every sentence earns its place; 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?

Given the 14-parameter schema with full coverage and no output schema, the description provides essential context: scope, cost, paging, and a key pitfall. It anchors to list_mentions to convey the response shape and mentions the bucket enrichment. It could explicitly describe the response structure, but the combination of schema coverage and the list_mentions reference makes it sufficiently 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?

With 100% schema description coverage, the baseline is 3, but the description adds semantic insight beyond the schema: it clarifies that bucket= is used for sorting categories (e.g., pricing complaints), that q= in text mode is the keyword filter (so bucket should not be used for that), and that cursor must be passed back unchanged. These clarifications help avoid common mistakes.

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 exactly what the tool does: returns the same mentions as list_mentions but scoped to one keyword, additionally carrying the bucket each mention was sorted into. It gives concrete use cases ("what has my <brand> monitor caught?", "show me the pricing complaints") and explicitly differentiates it from the sibling list_mentions, making 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?

The description provides explicit when-to-use guidance with concrete examples, and warns against a common misuse ("Do not set it to filter by keyword: that is what q= in text mode already does"). It also names the alternative list_mentions as the baseline and explains cost implications of mode selection, helping the agent choose the right tool and parameters.

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 idempotency and non-destructiveness, and the description adds meaningful behavioral context beyond them: it clarifies that the read mode writes nothing, that setting a brand only affects reply drafts, that nothing polled is changed, no search is started, and no credits are charged. No contradiction with annotations.

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

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

Three sentences, front-loaded with the core purpose and the condition for use, followed by a compact call sequence and side-effect notes. Every sentence earns its place; no filler or repetition.

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

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

For a two-parameter tool with rich schema descriptions and no output schema, the description covers the full operation modes, side effects, and prerequisite id source. An agent can correctly choose and invoke the tool without unresolved 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?

Schema description coverage is 100%, and the schema already explains the absent/id/null behaviors precisely. The description reinforces the same semantics in prose but does not add new parameter-level meaning 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?

The description names a specific operation pair ('Read or choose') and a specific resource ('the brand a keyword's reply drafts speak for'), with a clear condition ('when the account has several'). This distinguishes it from broader keyword-update or management siblings without needing to open the schema.

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

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

The description gives explicit calling guidance: call without brandProfileId to inspect brands and the current choice, then call with a brand id or null. It also states the appropriate context ('when the account has several'). It does not explicitly name sibling alternatives or exclusions, so it stops short of a full when-not map.

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

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

The annotations only say destructiveHint=true, but the description goes further by explaining that deleting a bucket does not delete mentions, mentions become uncategorised, and the count appears as unclassified. It also discloses the free nature and the separation of sorting charges, adding meaningful behavioral context beyond the structured annotations.

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

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

The description is compact and front-loaded with the primary purpose. Each sentence adds useful information: the operation, the deletion side effects, the ask-before-deleting policy, and the cost behavior. There is no redundant or filler content.

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

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

For a dual-action tool with no output schema, the description covers the important behavioral and cost context well. It still relies on the schema for parameter specifics like bucketId, and does not describe the response shape, but the combination of schema and description is sufficient for correct invocation.

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

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

Schema coverage is 67%, and the description does not significantly add parameter meaning beyond what the schema already provides. The parenthetical about a name and one sentence maps to label and rule, but those are already described in the schema. The color, action, id, and bucketId parameters still rely on the schema or enum values.

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

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

The description clearly states the specific operation: create or delete a bucket on a listening keyword, and defines what a bucket is. This distinguishes it from sibling tools like keyword_create or keyword_manage, which operate on keywords rather than buckets.

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 context for when to use the tool: create or delete a bucket on a listening keyword. It also provides explicit guidance to ask before deleting and clarifies that sorting is charged separately, which helps choose this tool over paid alternatives, though it does not name specific sibling tools.

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

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

Even though annotations already mark this as a write operation, the description reveals substantial behavior beyond them: charging ('polling that is charged per check at each Source's credit rate'), the estimateToken's 15-minute validity and argument-binding constraint ('A token for other arguments is refused'), the backfill side effects and its nephia:spend permission requirement, and the webhook rule ('Never invent this URL, ask the person for it'). No contradiction with the annotations; openWorldHint=true is consistent with the many additionalProperties objects in the schema.

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

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

The description is long but front-loaded — definition first, then the minimal shape, then the estimate workflow — and every sentence carries information an agent needs rather than repeating schema text. For a 23-parameter tool with 14 source types and billing semantics, the length is proportionate; a small amount of material (topic-keyword handling) also appears in the schema's subjectRole description, so it is slightly redundant but not wasteful.

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

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

Given the tool's complexity — 23 parameters, nested source overrides, per-source interval floors, billing, and a required estimate artifact — the description covers everything an agent needs to call it correctly: prerequisites, approval workflow, special cases, permissions, and cost disclosure. No output schema exists, so return-value documentation is not required, and the success path is adequately hinted by the pointer to read results via list_mentions, get_keyword_results, or get_keyword_events.

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 87%, so the baseline is 3, and the description wisely avoids restating the schema's per-source override details. Instead it adds cross-parameter meaning the schema cannot: the minimal viable keyword ('one Source, one interval and an optional webhook'), the estimateToken-to-arguments binding, the topic-keyword default ('created with match word'), and the inheritance model where an absent searches array inherits globalCriteria. This is meaningful added semantics above the high-coverage baseline.

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

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

The opening sentence states a specific verb and resource — 'Create a keyword, the one object you monitor with' — and then defines the object's anatomy (terms, Sources, settings). It names the confusable sibling keyword_estimate and clarifies the relationship ('it runs the same validation, writes nothing, and returns the price and the estimateToken this tool requires'), so an agent can distinguish create from estimate and update 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 an explicit, two-part workflow: 'Call keyword_estimate with the same arguments first' and 'send its estimateToken only after they agree,' which is strong when-to-use guidance with a named alternative. It also routes the agent to get_keyword for the shape of rules and channels. However, it never states when NOT to use this tool — e.g., that modifying an existing keyword belongs to keyword_update — so the exclusion half of the guidance is 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 include readOnlyHint=true and openWorldHint=true, and the description reinforces this by stating 'Costs 0 credits and writes nothing.' It goes beyond the annotations by detailing the output structure: valid=true carries monthlyCredits, per-Source and per-search breakdowns, firstScanCredits, plan allowance, credits left, and for changes monthly difference and resetSearches. It also explains valid=false carries the refusal details. No contradictions.

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 dense but well-organized, front-loading the core purpose and then layering specifics. Every sentence adds information—costs, output fields, free sources, topic handling, and the token requirement. Despite its length, it is efficient and well-structured for the complexity involved.

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 23 parameters, nested objects, and no output schema, the description provides comprehensive context: it details the output fields, the conditions for free sources, the meaning of valid flags, and the backfill cost ceiling. It also references searches[].overrides for source-specific requirements, which is necessary for correct invocation. No critical information appears missing.

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

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

Schema description coverage is 87%, so the schema already documents most parameters. The description adds meaningful context: the id parameter's absence/presence determines new vs change, the topic keyword behavior (match, sentimentEnabled, aiStep with problem_fit), and the backfill cost implications. This adds value beyond the schema without redundantly repeating it.

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

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

The description clearly states the tool's purpose: to price a new keyword (using keyword_create arguments) or a change (using keyword_update arguments) without writing. It distinguishes the two modes via the presence of an id and explicitly mentions that it writes nothing, which differentiates it from the write tools.

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

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

The description provides a clear workflow: show the person monthlyCredits before any write, then pass estimateToken to that write with the same arguments. It also notes that valid=false carries the refusal the write would give, so the tool can be used to check validity without committing. It does not explicitly name alternative tools, but the usage context is unambiguous.

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

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

Annotations already signal destructive/non-read-only behavior, and the description adds substantial context: the operation is free, paused sources stopped by an operator remain stopped on resume and surface in blockedSources, purge is irreversible, and customer consent is required. No contradiction with annotations.

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

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

The description is dense and mostly front-loaded, with the scope and actions in the first sentence. A few clauses are slightly awkward, but every sentence contributes operational value.

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

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

For a 3-parameter mutation with no output schema, this is thorough: it covers credit effects, return behavior via blockedSources, retention vs purge, irreversibility, and consultation requirements. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% and both action and purge are already well documented. The description adds extra meaning by explaining the blockedSources return field and reinforcing the irreversible data-loss implications of purge=true, which goes beyond the schema.

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

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

States a specific verb ('manage'), a resource ('keyword'), and the scope ('across every Source at once'), then enumerates the three distinct lifecycle actions: pause, resume, delete. This differentiates it clearly from per-source tools like keyword_source_manage.

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?

Defines when each action applies and gives explicit operational guidance: pause stops polling/spending, resume restarts, delete retires and frees a slot. It also instructs the agent to ask before pausing, deleting, or purging. It does not explicitly name sibling alternatives, but the 'across every Source at once' framing makes the intended scope clear.

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

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

Beyond the annotations, the description discloses concrete side effects: other Sources and searches are untouched, certain inputs are refused, manually stopped Sources return in blockedSources on resume, and the operation does not consume credits. These are meaningful behavioral details not inferable from annotations alone.

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

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

The description is dense and front-loaded, with no filler. The only slight weakness is the final sentence, 'Pausing is also how you stop the polling that does,' which is grammatically awkward and less clear than 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?

For a 3-parameter mutating tool with no output schema, this description provides inputs, restrictions, side effects, fallback behavior, and cost impact. An agent has enough context to decide when to call it and what to expect, including the blockedSources nuance on resume.

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 schema already documents id and action and enumerates source values; the description adds value by tying action to real-world state changes and by surfacing validation rules about un-polled Sources and the last polling Source. It does not describe each enum value, but those names are self-explanatory and the schema covers the rest.

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 pair ('pause/resume') and an exact resource ('one Source of a keyword'), then immediately clarifies scope: 'without touching its searches or the other Sources.' This clearly distinguishes it from related tools like keyword_manage and keyword_source_set.

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 an explicit when-not case: refusal on the last still-polling Source, and directs the agent to use keyword_manage instead. It also adds cost guidance ('Free — does not charge credits') and frames pausing as the way to stop polling, helping the agent choose the right operation.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description goes well beyond them: it explains the two-phase commit (estimate writes nothing, write fails 'if the save started over a search the estimate did not announce'), cost implications ('charged per check at each Source's credit rate'), and the destructive semantics of enabled=false ('removes its checks; its searches stay stored'). No contradiction with annotations.

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

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

The description is very long, but it is front-loaded with the core purpose and the critical estimate/write workflow before the per-source detail block. Each sentence carries real information for a complex tool; the density is justified, though the wall-of-text per-source section could be better broken up. Minor structural critique only.

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 explains return semantics explicitly: 'monthlyCredits before and after, and resetSearches' and 'applied says which of the two happened: only applied=true is a save.' It also covers the failure condition, cost, and per-source behavior. For a 7-parameter two-phase mutation tool, nothing an agent needs is missing.

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

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

Despite 86% schema coverage, the description adds substantial value: it clarifies the mode enum semantics (estimate takes no token, write requires it), explains the searches replacement behavior ('Keep the id of each search you keep'), documents refreshIntervalSeconds bands, and provides an exhaustive per-source guide to overrides with a concrete ai_answers example. This far exceeds the baseline for high-coverage schemas.

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

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

States a precise verb pair (add/replace) with a specific resource (one of a keyword's sources) and an explicit scope constraint: 'leaving every other Source untouched.' The title and first sentence align, and the description clearly differentiates from siblings like keyword_source_manage and keyword_estimate by naming them and their distinct roles.

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 an explicit when-to-use protocol: 'Call keyword_estimate first, show the person the monthlyCredits it returns, and send its estimateToken only after they agree.' It also names exclusions and alternatives: 'To stop it for a while, use keyword_source_manage instead' and 'switch coBrandsEnabled with keyword_update.' The estimate-then-write sequence is unambiguous.

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

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

Annotations declare destructiveHint=true, readOnlyHint=false, idempotentHint=true, and openWorldHint=true. The description adds substantial context beyond these: it reveals that the tool starts or changes polling with per-check credit charges, that estimateToken must exactly match the arguments and expires in 15 minutes, and that null clears fields while omitted keys are untouched. It also confirms it never starts a search. These details align with the annotations and significantly enhance the agent's understanding of side effects and constraints.

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 long but every sentence carries weight. It is structured logically: purpose, exclusions, workflow, charging model, and a final reminder. It front-loads the primary action and then builds context. No redundant or filler sentences; the density is justified by the tool's complexity.

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 20 parameters and no output schema, the description covers the critical operational aspects: the mandatory estimateToken prerequisite, the distinction between omit and null, the charging model, and the scope limitation. It does not explicitly describe the return value, but for an update tool this is often a confirmation; the absence is acceptable given the rich workflow guidance. Overall, an agent has enough to invoke it correctly.

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

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

Schema coverage is 85%, so most parameters already have descriptive entries. The description adds cross-cutting semantics that apply to all optional fields: 'A key you leave out is left alone; null clears it.' It also clarifies the estimateToken requirement — that it must be for exactly these arguments and is valid 15 minutes. This goes beyond the schema's per-field descriptions and aids correct usage.

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

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

The description opens with a clear verb-resource pair — 'Change a keyword's settings' — and enumerates the exact fields (name, interval, sorting, etc.). It explicitly differentiates from keyword_source_set by stating 'Never its Sources or searches: that is keyword_source_set', and distinguishes keyword_estimate as a validation-only call. The purpose is unambiguous and distinct from all sibling tools.

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

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

The description gives explicit when-to-use guidance: it instructs to call keyword_estimate first with the same arguments, show the monthlyCredits to the user, and only then send the estimateToken after agreement. It also clearly states what this tool does NOT do (sources/searches belong to keyword_source_set) and explains the omit-vs-null semantics. This leaves no ambiguity about the correct workflow or 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?

The description goes beyond the annotations (readOnlyHint and openWorldHint) by stating it is free and does not charge credits, and that listing never triggers a sorting pass so it cannot bill. It also adds that another account's id returns a 404, not 403 (though this is in the schema, the description reinforces the behavioral expectations). No contradiction with annotations.

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

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

The description is two sentences, tightly packed with essential information: what is returned, how it relates to another tool, and the cost/side-effect behavior. No fluff, front-loads the core purpose, and every clause adds value.

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

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

Given the single parameter and no output schema, the description adequately outlines the return content (buckets with id, label, rule, count; plus unsorted and pending counts). It also explains the linkage to get_keyword_results. It could specify the exact return structure (array vs object) but that is not essential for an agent to call it correctly.

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

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

The single parameter 'id' is fully described in the schema: 'Keyword id, from list_keywords. Another account's id is a 404, never a 403.' The main description does not add additional parameter semantics, so it relies on the schema, which is complete (100% coverage). Baseline of 3 is appropriate.

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

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

The description clearly states the tool lists the buckets a keyword sorts its mentions into, enumerating the fields (id, label, plain-language rule, count) and adding unsorted/pending counts. It also differentiates its purpose from get_keyword_results by explaining the relationship of the ids and labels, which helps an agent understand what this tool is for.

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

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

The description explains how the output is used: the ids are passed as bucket= to get_keyword_results, and the labels explain the meaning of ids in that output. It also notes that the tool is free and never triggers a sorting pass, so it can be called without cost concerns. It doesn't explicitly contrast with sibling tools like keyword_bucket_manage, but the read-only listing intent is clear.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the bar for added behavioral disclosure is lower. The description adds real value: it explains the data semantics around stale sources, clarifies what does and does not count as signal, and notes that the tool is free and does not charge credits. No contradiction with annotations.

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

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

The description is dense but every sentence earns its place: core listing behavior, returned fields, the critical stale-source caveat, sibling routing, and cost behavior. It is front-loaded with the main action and keeps the most important caveat early.

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

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

With no output schema, the description carries the burden of explaining return values, and it does: eventCount, unclassifiedCount, staleSources, and Source health fields. It also explains the account scope and how the returned keyword IDs feed other tools, making the tool fully callable and interpretable.

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

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

The tool has zero parameters and the schema is empty, so the baseline is 4. The description correctly focuses on the resource shape instead, defining the returned metrics and the nested Source health fields, which is more useful than parameter documentation would be here.

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

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

The description names a specific verb and resource ('List every keyword on the account') and immediately distinguishes itself from get_keyword, which provides full configuration. The scope is unambiguous and clearly differentiated from siblings.

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

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

It explicitly positions itself as the starting point: 'Start here: a keyword id is what get_keyword_results, get_keyword_events, list_keyword_buckets and keyword_manage take.' It also routes to get_keyword for full configuration and warns to report stale sources before drawing conclusions from mentions. It does not exhaustively contrast with all listing siblings, but the key routing is present.

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 are minimal (readOnlyHint false, openWorldHint true, idempotentHint false, destructiveHint false), so the description carries the full burden of behavioral disclosure. It goes beyond annotations by explaining the cost model (free text mode, 1 credit per semantic question with a 10-minute free window), the paging behavior (hundred rows at a time, cursor-based), the inclusion of matchedTerms and relevance explanations, and the exact-match semantics of author filtering. It also discloses that semantic mode charges and that paging is not the right way to count. This is comprehensive and consistent with annotations.

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

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

The description is long but every sentence serves a purpose. It is front-loaded with the core purpose and key differentiators, then logically proceeds to usage examples, cost, paging, and specific parameter guidance. Given the tool has 18 parameters and complex semantics, the length is appropriate. There is no redundancy or fluff; each clause adds information an agent needs to call the tool correctly.

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 18 parameters, no output schema, and minimal annotations, the description must fully equip an agent to invoke the tool correctly. It explains what the response contains (sentiment, intent, relevance, bucket, agent readings, matchedTerms), how paging works, the cost model, and when to use alternatives. It also covers edge cases like 'unread' values, the meaning of absent filters, and the behavior of engagement thresholds for sources that lack counters. Nothing an agent needs to know 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?

Even though the schema covers 100% of parameters with descriptions, the tool description adds significant contextual meaning beyond the schema. It explains the interplay between parameters (e.g., 'Do not set it to filter by keyword: that is what q= in text mode already does'), warns against using both engagement and engagement_min ('Send this or engagement_min, never both'), and clarifies nuanced behaviors like the author filter being exact match and the engagement rules being per-Source. It also clarifies that 'source' is preferred over 'type' for narrowing. This adds real value beyond the schema's field-level descriptions.

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

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

The description opens with a specific verb-resource-scope statement: 'Read everything your keywords caught, newest first, across every Source and every keyword on the account...' It names the exact resource (mentions), the scope (all keywords and sources), and the ordering. It also distinguishes itself from siblings by naming mentions_stats and get_keyword_results as alternatives for different jobs. An agent can immediately tell what this tool does and how it differs from the others.

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 is explicit about when to use this tool versus alternatives: it gives example queries, says to use mentions_stats for counting, get_keyword_results for a single keyword, and warns against using mode=semantic for keyword filtering. It also explains when to use run and kind, and that cursor paging works by passing nextCursor unchanged. No ambiguity remains about when to select this tool.

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

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

Given the annotations (readOnlyHint=false, openWorldHint=true), the description adds significant behavioral context: it explains the credit charging logic (1 credit per asked mention, free for 10 minutes, different mention charges again), the deduplication of copies, the exclusion of the input mention from results, and that meta.credits_used indicates cache usage. This is rich and non-obvious behavior that the annotations don't cover.

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 long, but every sentence provides essential behavioral or use-case detail, and the most important purpose is front-loaded. The credit logic and cache behavior are crucial for correct usage and are clearly organized. No wasted words.

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 tool with no output schema, the description covers everything an agent needs: what the input should be, what happens to the output (similar mentions, sorted by similarity), edge cases (collapsing copies, excluding input), and billing/caching semantics. The use of meta.credits_used is also explained.

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 schema already covers the id parameter perfectly (100% coverage with format and source description). The tool description doesn't repeat parameter details but adds a critical constraint (collected in the last 30 days) that is already in the schema, so it adds minimal extra value. Baseline 3 is appropriate.

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

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

The description clearly states that this tool finds mentions similar to a given one, listing the exact use case (showing a complaint is not a one-off) and scope (across all keywords and Explore runs). It distinguishes it from list_mentions and get_keyword_results by defining the similarity behavior, though it doesn't explicitly name a sibling alternative.

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 explains when to use it (to find similar mentions, gather more quotes) and mentions the 30-day input freshness constraint, which implies the input must come from recent results. It doesn't explicitly say when not to use it or compare to siblings, but the use case is fairly clear.

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

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

Annotations only declare readOnlyHint and openWorldHint, but the description adds substantial behavior: rows omit zero-count combinations, total/truncated/unread fields have distinct meanings, terms double-count mentions, and counts include muted/hidden mentions that list_mentions excludes. No contradiction with the annotations.

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

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

The description is long but front-loaded and dense: purpose and usage examples come first, followed by output behavior and caveats. A few phrases, like 'how many, when, where, by whom and on which terms,' are somewhat redundant with the examples, but every sentence contributes meaningful selection or invocation guidance.

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 covers the key response fields (rows, total, truncated, unread), the 90-day window limit, counting quirks like double-counted terms, and the relationship to list_mentions. An agent has enough context to select, invoke, and interpret results correctly.

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

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

Schema description coverage is 100%, so the baseline is 3; the description adds use-case-driven guidance for group_by ('day' for week comparisons, ['source','sentiment'] for source complaints, 'term' for top terms) and explains open-axis truncation and 'unread' semantics. It does not re-document every parameter, but the schema already handles that.

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

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

Opens with 'Count mentions instead of reading them,' which is a specific verb, resource, and direct contrast to the sibling list_mentions. The 'how many' framing and the question examples make it unmistakably a counting tool, not a retrieval tool.

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

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

Explicitly directs agents to call it before list_mentions for any question that starts with 'how many,' and gives concrete question-to-group_by mappings. It also closes with 'Page list_mentions afterwards only to quote,' providing a clear when-not and alternative.

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

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

Even with readOnlyHint and openWorldHint annotations, the description goes well beyond them by disclosing credit cost, soldRate being always null due to missing sold detection, coverage being tied to observed searches, and explicitly stating this is not a complete index. This is high-value behavioral transparency that materially prevents misinterpretation.

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

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

Four sentences, each earning its place: output summary, cost, date constraints, soldRate caveat, and coverage caveat. The core result type is front-loaded, and there is no filler or repetition of schema details.

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 stats tool with no output schema, the description covers the essential invocation semantics: optional filters, defaults, range limits, cost, ordering, and a critical null field caveat. It is slightly incomplete only in that it doesn't describe the full response shape beyond the listed aggregates, but nothing needed to decide whether to call 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?

Schema coverage is 100%, so the baseline is 3. The description adds meaningful constraints not present in the schema: the default 30-day range, the 365-day maximum range, and 'newest first' ordering. It also names the filterable dimensions in plain language, reinforcing the schema without fully duplicating it.

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

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

The description clearly states a specific resource (Vinted market), specific outputs (p25/median/p75 and per-day listing count), and a precise verb ('Get'). It also conveys scope and filtering. However, it does not explicitly differentiate this tool from related siblings like vinted_price_history, so it stops short of full sibling differentiation.

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 provides strong usage constraints: 5 credits per request, default 30-day window, 365-day maximum, soldRate always null, and coverage limitations. It does not explicitly say when to choose this tool over alternatives, nor does it name sibling tools, so the usage context is implied rather than directly guided.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, and the description is consistent with both. It adds valuable behavioral context beyond the annotations: the 3-credit cost per request, the sampling semantics ('Points are movements, not poll ticks... recorded when the price or status changed, or once every 24 hours'), and the coverage model. No contradiction with 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?

Five sentences, each earning its place: core purpose and ordering, cost, sampling semantics, coverage limitation, and the explicit scope caveat. The most important info is front-loaded in the first sentence, and no sentence is redundant with the schema or annotations.

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

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

Comprehensive for a read-only lookup tool with 100% schema coverage. It explains the return concept (points), cost, coverage limitations, and ordering. The only minor gap is that with no output schema, it does not detail the exact response shape, but the 'points' explanation substantially compensates for that.

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

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

Schema coverage is 100%, so baseline is 3. The description adds real meaning by defining what a 'point' is (a movement or a 24-hour tick), which enriches understanding of the limit, from, and to parameters — clarifying that limit counts movements and that from/to bound observedAt events. This goes beyond the schema's bare parameter definitions.

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: 'Get every price and status Nephia observed for one Vinted listing.' It clearly scopes to a single listing and is readily distinguishable from sibling vinted_market_stats (market-level data) and the query/analysis tools. The 'oldest first' ordering and per-listing scope leave no ambiguity about what this tool does.

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

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

Provides clear context: it is a per-listing history tool with explicit limitations ('Coverage grows with usage... only for items that appeared in a search Nephia observed' and 'This is not a complete index of Vinted'). This implies when it is appropriate, though it stops short of naming specific alternative tools or explicit when-not-to-use exclusions.

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