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

Beyond the annotations, the description explains meaningful behavioral details: newly added keywords are tracked from now on, previously paused matching keywords are resumed, each keyword consumes a Daily Tracked Keywords slot, and the operation is reversible via `pause_rank_radar_search_terms`. It even addresses why no confirmation is needed, which is valuable context for agent decision-making.

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?

Every sentence earns its place: purpose, behavioral effects, quota constraint, reversibility, and return values are all covered without filler. The most important scoping decision (existing radar vs new radar) is front-loaded.

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

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

For a state-changing tool with no output schema, the description is unusually complete. It explains failure conditions, quota implications, reversibility, and what the return fields mean, including how the returned ids connect to sibling pause/resume tools.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds behavioral semantics not present in the schema: each submitted keyword occupies a quota slot, matching paused keywords get resumed, and the returned ids feed pause/resume tools. This enriches the agent's understanding of what the parameters actually cause.

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 and resource: 'start tracking extra keywords on an existing Rank Radar.' It explicitly distinguishes itself from `create_rank_radar`, so an agent can immediately tell this is for extending an existing radar rather than creating 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?

It states precisely when to use this tool ('on an existing Rank Radar, instead of creating a new one') and names the relevant alternatives (`create_rank_radar`, `pause_rank_radar_search_terms`). It also gives an actionable precondition: check `get_quota` first because the call fails when quota is exhausted.

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, and the description substantially enriches this: token spend that scales with numberOfCompetitors, 'cannot be undone,' non-idempotency ('each call spends tokens again and starts a separate dive'), and the async contract (immediate diveId + estimatedCompletionDate, poll until success carries nicheId). These behavioral details go far beyond what annotations alone convey and are exactly what an agent needs before invoking a paid, irreversible operation.

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?

Roughly 130 words for a tool that is destructive, paid, non-idempotent, and asynchronous — every sentence has a distinct job, and the purpose is front-loaded. It is efficient but slightly dense; the retry sentence bundles token cost, idempotency, and error-recovery alternatives into one long clause. Cleaner separation of the warnings would earn a 5.

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

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

With no output schema, the description carries the full burden of explaining the return contract, and it does: immediate diveId + estimatedCompletionDate, polling via get_dive_status, and the nicheId delivered on success for use with list_niches, get_niche_keywords, etc. Combined with cost, confirmation, and retry warnings, nothing an agent needs to call this tool safely 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 genuine cross-parameter semantics on top: numberOfCompetitors drives cost, and confirm must be true only after the user approves that cost. It also reinforces the required trio (marketplace, asin, numberOfCompetitors). It wisely does not duplicate the marketplace enum gotchas, which the schema already documents thoroughly.

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: 'start new niche research from a seed ASIN.' The 'new' qualifier implicitly separates it from the re-dive sibling (redive_niche), and the polling workflow content distinguishes it from the read-only status tools. An agent can tell exactly what this tool creates and from what input.

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 ('start new niche research') and names concrete alternatives with conditions: 'if a call errors or times out, poll get_dive_status (or check list_niches) instead of re-calling.' It also specifies the confirmation prerequisite — set confirm: true only after user cost approval. This is precisely the guidance needed to prevent the tool's dominant failure mode (duplicate paid dives).

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

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

Annotations only flag destructiveHint=true; the description adds substantial context the annotations cannot: tokens are spent per ASIN, the action is irreversible, it is NOT safe to retry (each call starts a separate dive and spends again), and the correct recovery is polling `get_dive_status`/`list_niches`. It further enumerates the no-cost failure modes (over plan limit, account niche limit, insufficient Amazon data) and the async return contract.

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 usage condition and the sibling contrast, then warnings. Every sentence carries unique operational information (cost, irreversibility, retry hazard, failure modes, async polling), though the description is dense enough that it approaches the upper end of what an agent needs.

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

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

For a destructive, token-spending, asynchronous tool with no output schema, the description covers the full lifecycle: cost warning, retry prohibition, recovery path, failure cases, and the returned `diveId`/`estimatedCompletionDate` plus polling loop to `success`/`nicheId`. Nothing an agent needs to invoke it safely is missing.

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

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

Schema description coverage is 100% and all three parameters already carry inline descriptions covering the 2-200 ASIN bound, the `confirm` cost-approval semantics, and the marketplace enum domain. The description largely restates these bounds rather than adding new parameter meaning, so the baseline of 3 applies.

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

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

The description gives a precise verb+resource ('builds the niche from the given ASINs only') and explicitly distinguishes itself from the sibling `create_niche_dive`, which 'discovers competitors around one seed ASIN'. An agent can route between the two without opening either schema.

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

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

States the exact triggering condition ('when the user already knows which products belong in the niche — e.g. they list competitor ASINs, or picked them from search results') and names the alternative for the other case. It also states the confirmation prerequisite, so the when-to-use decision is fully specified.

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 well beyond the annotations. It discloses that the operation spends Search Term tokens, that cost scales with numberOfKeywords, that it cannot be undone, that it is not safe to retry, that the first call is a preview that may return warnings, that warnings must be shown verbatim, and that a warning never blocks creation. The annotations already declare destructiveHint=true, but the description adds critical context about token cost, retry safety, and the warning-handling protocol. 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 well-organized: it front-loads the purpose, then the critical warning, then the retry guidance, then the warning-handling protocol, then the return value and prerequisites. Every sentence earns its place, though the length is substantial. It could be slightly tightened, but the density is justified given the high-stakes nature of the operation.

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 mutation tool with destructiveHint=true, no output schema, and 4 parameters, the description is remarkably complete. It covers prerequisites (nicheId from list_niches), cost behavior, retry safety, warning handling, return value (rankRadarId), and follow-up tool (get_rank_radar_data). An agent has everything needed to invoke this correctly and safely.

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

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

Schema coverage is 100%, so the schema already documents all four parameters. The description adds meaningful context beyond the schema: it explains the cost implication of numberOfKeywords, the confirmation requirement for confirm, the source of nicheId (list_niches), and the minimum for numberOfKeywords. It doesn't add syntax details for asin, but the schema already covers that. This is a strong complement to the schema, though not a full 5 because the schema already does most of the work.

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 ('start tracking'), a specific resource ('organic and sponsored keyword rankings for an ASIN within a niche'), and clearly distinguishes this from sibling tools like list_rank_radars, get_rank_radar_data, and delete_rank_radar. The title and description align, and the scope is unambiguous.

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

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

The description explicitly says when to use this tool (to start tracking rankings), and provides clear exclusions: 'Not safe to retry: each call spends tokens again and creates a separate Rank Radar — if a call errors or times out, check list_rank_radars instead of re-calling.' It also names the prerequisite source for nicheId (list_niches) and the follow-up tool (get_rank_radar_data). This is explicit when/when-not guidance.

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

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

Going well beyond the destructiveHint annotation, the description discloses the full blast radius (keywords, competitors, all dives and diveboxes), irreversibility, that spent dive tokens are NOT refunded, the confirm gate, and the conflict failure mode. Every consequential behavior an agent must surface to a user is covered.

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: purpose, cascading consequences plus token policy, the confirm gate, and the conflict precondition with resolution. The warning is front-loaded and the structure leads from action to consequence to safeguard to edge case.

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 operation with no output schema, everything needed to call it safely is present: success effects, irreversibility, financial impact, the required confirmation flag, the failure mode, and the resolution path. There is no meaningful gap an agent would need to infer.

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

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

Schema description coverage is 100%: both nicheId and confirm already carry thorough schema descriptions, including 'Confirm with the user first.' The description's 'Set `confirm: true` only after the user approves' reiterates schema semantics rather than adding new parameter-level meaning, so the high-coverage baseline of 3 applies.

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

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

The description states a specific verb and resource ('permanently remove a niche'), making the operation unambiguous. It also inherently differentiates from siblings: it is the destructive counterpart to read-only tools like list_niches and get_niche_keywords, and targets a different resource than delete_rank_radar.

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 frames when to use it ('a niche the user no longer needs') and states a hard precondition: a niche used by any Rank Radar cannot be deleted. It also names the exact remedy and sibling tool to consult ('delete or archive those rank radars first (`list_rank_radars` with the `nicheId` filter shows them)').

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 mark destructiveHint, but the description adds valuable behavioral context: no restore endpoint, effect on Daily Tracked Keywords quota, and the relationship to list_rank_radars status: ARCHIVED. 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: action, irreversibility, approval condition, quota effect, status mapping, and alternative tool. Slightly longer than strictly necessary but front-loaded and well structured.

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 mutation with no output schema, the description covers prerequisites, irreversibility, side effects, alternative behavior, and response expectations are not needed. An agent has everything needed to select and correctly invoke this 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 explains confirm and rankRadarId. The description repeats the same semantics ('only after the user approves', 'from list_rank_radars') without adding new parameter-level detail, 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 and resource: 'permanently remove a Rank Radar and all of its keyword ranking history.' This clearly distinguishes from pausing/archiving by explicitly contrasting with pause_rank_radar and explaining the ARCHIVED status.

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

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

Explicit usage guidance: use when permanent deletion with history removal is intended, and explicitly names pause_rank_radar as the alternative when the user wants to stop tracking while keeping history or asks to 'archive'. Also gives the approval precondition: set confirm only after user approves.

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?

Discloses that each call consumes one AI Copywriter prompt irreversibly, is asynchronous, returns a generationId, and should not be retried on failure. This goes well beyond the destructiveHint=true annotation by specifying the actual side effect (quota consumption) and the safe recovery path.

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?

Every sentence carries a distinct operational fact: purpose, non-publishing, quota cost, no-retry rule, async return, and polling procedure. The warning is front-loaded and the retry/polling guidance is placed before the async note, making it easy to scan.

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 no output schema and a destructive quota side effect, the description covers the full lifecycle: confirm cost, pass required inputs, get generationId, poll status until complete, and avoid retries. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents nicheId source, strategy enum meanings, and currentListing structure. The description adds only an instruction to ask the user for strategy preference and reminds that the listing is drafts only, which is already implicit in the schema; no new syntactical parameter semantics.

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 specifies the verb ('draft'), the resource ('an optimised Amazon listing — title, bullets and description'), and the input ('from a niche's keyword research and the seller's current listing'). It also distinguishes itself from the status-polling sibling by explaining it returns a generationId and that get_listing_copy_generation_status should be used for monitoring.

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

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

Explicitly says when to use (drafting from a niche's keyword research and current listing), and when not to re-call on error/timeout, directing to poll get_listing_copy_generation_status. It also instructs to set confirm:true only after user approval, and to ask the user for strategy preference if unknown.

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 include readOnlyHint=true, and the description adds context about the return payload (totalSellableUnits, distribution array with fields) and the `lastUpdatedAt` null condition. This goes beyond the annotation by explaining output semantics and edge cases, though it doesn't discuss pagination or rate limits, which are not relevant for a small read operation.

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 paragraph of moderate length. It front-loads the when-to-use trigger, then states requirements and output. Every sentence earns its place, with no redundant or vague phrasing.

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 there is no output schema, the description explains the return structure (distribution array with fc, state, availableStock, availableStockPercentage) and the nullability of lastUpdatedAt. It also mentions prerequisites for sellerId, making the tool self-sufficient for a user to invoke correctly. This is complete for a simple read-only inventory distribution 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 fully documents all three required parameters (asin, sellerId, marketplace) including patterns and enums. The description repeats the parameter names but adds no new meaning beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool's function with specific verb+resource: 'get inventory distribution' per ASIN. It explicitly distinguishes from siblings by focusing on inventory levels and fulfillment center stock, which no sibling covers. The trigger phrases ('asks about inventory levels, stock by fulfillment center') make 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: 'Use this when the user asks about inventory levels...' It also lists required input sources (sellerId from list_seller_profiles or Connections page). However, it doesn't mention when not to use this tool or suggest alternatives, so it misses the 'when-not/alternatives' element for 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 establish readOnlyHint=true, so safety is covered. Beyond that, the description discloses the three return shapes keyed by status, the timing behavior (dives take minutes), the estimatedCompletionDate hint, and the re-dive semantics (same nicheId, refreshed data), which is valuable operational context for a polling tool. It stops short of mentioning any rate limits or quota behavior, so not a full 5.

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

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

The description is front-loaded with the core instruction and organized by return status, with every sentence carrying load (workflow, return shapes, follow-ups, cadence). It is somewhat dense but not padded.

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

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

With no output schema, the description correctly compensates by describing the three response shapes and how to use the nicheId downstream. Nothing an agent needs to poll and act on the result is missing.

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

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

Schema coverage is 100% and the single parameter (diveId) is fully described in the schema, including its source tools. The description adds no syntax or format detail beyond what the schema already provides, so the baseline 3 applies.

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

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

The description states a specific verb (poll), resource (a niche dive), and ties it to the exact producer tools (create_niche_dive, create_niche_dive_from_competitors_list, redive_niche), distinguishing it clearly from those siblings. An agent can immediately tell this is the status-check endpoint rather than a dive-creation 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?

It says explicitly when to use it ('poll ... until it finishes'), names the predecessor tools, gives re-polling cadence guidance ('dives can take minutes', use estimatedCompletionDate to know when to check), and routes to the correct follow-up tools on success. The full workflow context is provided.

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 readOnlyHint annotation, the description discloses that polling is free and does not consume another AI Copywriter prompt, which is critical behavioral context. It also explains the three distinct response shapes and their meanings, making the tool's runtime behavior transparent.

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

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

Three sentences, each earning its place: the purpose and polling loop, the response shapes, and the cost-saving guidance. The most important information is front-loaded, and there is no fluff.

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 fully compensates by detailing all three status shapes and the fields carried in the result. The required parameters are clearly tied to the generation workflow. Nothing needed to invoke or interpret this tool correctly is missing.

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

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

Schema description coverage is 100%, with both nicheId and generationId already explained in the schema. The description reinforces that generationId comes from generate_listing_copy but does not add substantial new parameter semantics beyond the schema.

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

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

The description uses a specific action ('poll') against a specific resource ('listing-copy draft') and clearly distinguishes it from generate_listing_copy. It also enumerates the possible statuses, leaving no ambiguity about what the tool returns.

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 ('to poll a listing-copy draft started with generate_listing_copy'), when to poll again ('generating' status), and when not to re-call the sibling ('always poll rather than re-calling generate_listing_copy'). This is model behavior for usage guidance.

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

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

Annotations declare readOnlyHint=true and the description reinforces this with the safe retrieval verb. It adds useful behavioral detail beyond annotations, such as BSR supporting ranking by sales position and the boundary with get_ranking_juice, though it does not mention pagination, limits, or data freshness.

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 a use statement and uses a compact field-list format for returned data. There is some redundancy between the opening use-case list and the later enumeration of outputs, but each sentence contributes useful information.

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

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

With no output schema, the description thoroughly enumerates both niche-level statistics and competitor-level fields, so an agent knows what to expect. The single required parameter and read-only annotation keep complexity low; minor omissions like pagination or response shape do not block correct invocation.

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

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

Schema description coverage is 100%, and the only parameter, nicheId, is already well documented in the schema including that it comes from list_niches. The description adds nothing new about the parameter, so the baseline 3 applies.

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

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

The description opens with explicit use cases (competitor ASINs, product titles, BSR, sales/revenue benchmarks, niche opportunity scoring) and names the exact resource: Competitors within a specified Niche. It also distinguishes itself from get_ranking_juice by redirecting users who need ranking juice breakdowns.

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

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

'Use this for...' gives clear invocation contexts, and the description explicitly routes ranking juice breakdowns to get_ranking_juice. However, it does not contrast with get_niche_keywords even though the output includes 'keyword statistics', so the sibling routing is not fully exhaustive.

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

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

Annotations declare readOnlyHint: true, and the description adds meaningful behavioral context by detailing the return payload: search volume, relevancy (numeric or 'Outlier'), asinRanks mapping, and latestResearchDate. This clarifies the data structure and expected content beyond the annotation.

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

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

The description is efficiently structured with a usage trigger, a clear outcome statement, and a compact list of return fields. Every sentence earns its place; no fluff 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?

With no output schema, the description compensates by describing the returned data fields and a sample structure for asinRanks. It covers the core invocation needs for a one-parameter tool, though it could elaborate on interpreting 'Outlier' or relevancy scores, which is a minor gap.

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

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

Schema coverage is 100% with a clear description for nicheId (from list_niches). The tool description references 'the specified Niche' but adds no new meaning beyond the schema, which already explains the parameter's origin and purpose. 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 opens with a specific usage trigger ('when the user asks about keywords, search terms, or search volume for a niche') and clearly states the tool retrieves the master keyword list. It distinguishes itself from siblings like get_niche_competitors or get_niche_roots by focusing on keywords and search volume.

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 when the user asks about keywords, search terms, or search volume for a niche'). It does not mention when not to use it or name alternative tools, but the direct trigger provides strong 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?

With readOnlyHint=true annotation already covering the safety profile, the description adds valuable behavioral context by detailing the output structure ('roots' and 'normalizedRoots' tables) and the meaning of each field (frequency, broadSearchVolume, broadSearchVolumeRatio). It also explains the extraction logic via an example, going beyond what annotations provide. 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 well-structured: first the usage triggers, then the operation, then the detailed output fields. The example is illustrative and every sentence provides necessary information without redundancy. It is appropriately sized 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?

Since there is no output schema, the description takes responsibility for explaining return values. It thoroughly describes the tables (roots, normalizedRoots), each field (root, frequency, broadSearchVolume, broadSearchVolumeRatio), and additional metadata (per-keyword breakdowns, latestResearchDate). It also covers usage context, making it self-sufficient for an agent to select and invoke the tool correctly.

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

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

The schema already fully documents the only parameter nicheId (including the note 'from list_niches'), giving 100% schema coverage. The tool description does not add further semantic detail about the parameter itself, so the baseline score of 3 applies despite the description's broader context.

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 'Retrieves the keyword lexical roots for the Niche' and provides a specific example ('bluetooth headphones' yields 'bluetooth', 'headphones', 'bluetooth headphones'). It distinguishes itself from sibling tools like get_niche_keywords by focusing on derived roots rather than raw keywords, and ties to user intent ('highest-impact words', 'prioritize terms').

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 opens with explicit 'Use this when...' and lists three concrete triggers: 'find the highest-impact words across a niche's keywords', 'asks about keyword roots', and 'wants to prioritize terms for a listing'. However, it does not specify when not to use the tool or mention alternative tools (e.g., get_niche_keywords), so it lacks the 'when-not' or alternatives detail needed for 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 mark the tool as readOnlyHint=true, and the description adds meaningful context beyond that: it details the return structure (used/capacity per feature, null for unlimited, nextRefreshDate) and confirms the tool returns data without side effects. This is useful behavioral disclosure for an agent.

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. It front-loads the usage trigger before explaining the response format. Every clause adds value—feature names, null semantics, and the ISO timestamp—without redundancy. No filler or unnecessary 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 simple read-only tool with no parameters and no output schema, the description is complete: it explains exactly what the tool returns, including the specific fields and their possible null values. It gives the agent everything needed to invoke and interpret the result.

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

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

There are zero parameters and the schema is empty. The description explicitly states 'Takes no arguments,' which confirms the parameterless nature and matches the schema exactly. For a no-parameter tool, the baseline is 4, and the description fulfills this.

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 the specific verb 'get' with resource 'quota usage and capacity' and enumerates the exact billable features (DIVED_ASINS, RANK_RADAR_KEYWORDS, etc.). This clearly distinguishes it from all sibling tools, none of which mention quota.

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 provides explicit usage triggers: 'when the user asks how much quota or how many tokens they have left' and 'before creating a Niche Dive or Rank Radar to check remaining headroom.' This is clear context for when to use, though it does not mention alternatives or exclusions.

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

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

The readOnlyHint annotation already establishes safety, and the description adds substantial context by detailing the return structure: currentListing/optimizedListing breakdowns, per-property contributions, per-competitor scores, and latestResearchDate. It explains the proprietary 'Ranking Juice' concept, which is valuable beyond the annotation.

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

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

The description is composed of two efficiently structured sentences, with the usage guidance front-loaded. Every sentence contributes unique information—trigger conditions, resource, return details, and metric definition—without redundancy or fluff.

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?

Despite having no output schema, the description fully explains what the tool returns, including the nested breakdowns and research date. It also provides sufficient context for an agent to understand when to invoke it, making the description complete for a single-parameter read-only tool.

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

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

Schema coverage is 100% for the single parameter nicheId, and the schema already describes it as a unique identifier from list_niches. The description adds no further parameter-specific meaning, so the baseline 3 applies.

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

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

The description clearly states a specific verb ('Retrieves') plus resource ('Ranking Juices for each Competitor within the specified Niche') and defines the proprietary metric. It also provides user-intent triggers ('how do I rank higher', 'what's my ranking juice') that distinguish this from sibling tools like get_niche_keywords or get_niche_competitors.

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 first sentence explicitly directs when to use the tool: 'Use this when the user asks... or wants listing-optimization guidance.' This gives clear context for selection without ambiguity, even though it doesn't name alternative tools directly.

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

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

Annotations only declare readOnlyHint, but the description goes well beyond that: the 90-day date-range cap, that paused keywords are excluded, that rank 101 means outside the top 100, the pagination termination rule (hasNext), and the full response field list. This is rich behavioral context that annotations do not 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?

Front-loaded with purpose and constraints, and nearly every sentence carries useful information. It is somewhat dense and long, but the content is largely non-redundant rather than padding.

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

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

With no output schema, the description compensates by enumerating response fields (currentPage, pageSize, total, lastPage, hasNext, hasPrev) and the per-keyword shape (ranks, searchVolume, relevancy, highlights), so an agent knows exactly what it gets back.

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 already 100%, yet the description adds real meaning about how currentPage/pageSize interact and the max of 100. However, it claims omitting both returns 'every active keyword in one result,' which sits awkwardly against the schema's stated pageSize default of 20 — a minor inconsistency that costs it a point.

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 ('Retrieves historical keyword ranking data for the specified Rank Radar') and explicitly names the sibling tools for adjacent data (get_rank_radar_ppc_data, get_rank_radar_sqp_data), so an agent can disambiguate 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 when-to-use context, the prerequisite workflow ('Use after list_rank_radars to discover a rankRadarId'), the alternative tools for PPC and SQP metrics, and the condition that selects paginated vs unpaginated reads.

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=true, and the description goes well beyond that: it discloses the 90-day range cap and that <=30 days stays fast, null/0 semantics when a seller runs no ads, paused keywords being excluded, rate limiting (~60 req/min), that each call counts toward API usage, and full pagination mechanics. This is rich behavioral context layered on top of the safety annotation.

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

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

The passage is long but front-loaded with the trigger and densely informative, with each sentence carrying constraint, semantics, or pagination detail. Slightly heavy for a single block, but nearly every sentence earns its place with no filler.

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

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

Given no output schema, the description compensates by enumerating the returned metrics, explaining null/0 cases, and detailing pagination fields (currentPage, pageSize, total, hasNext, hasPrev). Combined with rate-limit and alternative-tool guidance, an agent has everything needed 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%, so a baseline of 3 applies, but the description adds genuine meaning: it frames startDate/endDate with the 90-day/30-day constraint, explains includeCampaigns' purpose and when to enable it, and recommends pageSize 100 plus currentPage+1 paging for large Radars. It goes beyond restating schema text.

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

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

States a specific verb+resource ('advertising (Sponsored Products) performance for the keywords of a Rank Radar') and scopes it to the keywords of a specific Rank Radar, which distinguishes it from the sibling list_ppc_campaigns. An agent can tell exactly what it returns without opening the schema.

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

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

Opens with explicit trigger ('Use this when the user asks about advertising performance for the keywords of a Rank Radar'), names the contrasting alternative ('For the seller's campaigns as a whole, use list_ppc_campaigns'), and gives the prerequisite ('Use after list_rank_radars to discover a rankRadarId'). When-to-use, when-not, and ordering are all covered.

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

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

Annotations only provide readOnlyHint=true, but the description adds substantial behavioral context: rate limiting (~60 requests/minute), API usage cost, pagination mechanics, null handling for low-volume keywords, SQP publication delay, and the fact that paused keywords are excluded. This goes well beyond 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 long but well-organized and front-loaded with the primary use case. Each sentence carries information, though some details (e.g., metric field breakdown) could be considered dense. It remains efficient for the complexity of the tool.

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

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

There is no output schema, so the description must explain return values, which it does thoroughly: metric naming conventions (*TotalCount, *AsinCount, *AsinShare), rate fields, null conditions, and pagination response fields. Combined with the parameter and behavioral coverage, the description is complete for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds useful performance guidance ('30 days or less keeps it fast') and pagination usage advice ('pageSize 100 for large Rank Radars', 'call again with currentPage + 1 while hasNext is true'), which enriches parameter understanding beyond the schema.

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

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

The description states a specific verb (get) and resource (Search Query Performance data for a Rank Radar), and explicitly identifies the data source (Amazon Brand Analytics). It distinguishes from siblings like get_rank_radar_data and get_rank_radar_ppc_data by focusing on shopper search/click/cart/purchase metrics for keywords.

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

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

It gives a clear use case ('when the user asks how shoppers search, click, add to cart and buy for the keywords of a Rank Radar') and a prerequisite ('Use after list_rank_radars'). It does not explicitly name alternative tools or state when not to use this one, but the context is strong enough to route the agent correctly.

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 annotation already indicates a safe read operation. The description adds valuable context: it describes the return fields (asin, title, parentAsin, brand, status, imageUrl, hasVariations), pagination metadata, and default behaviors for status, pageSize, and currentPage. This goes beyond the annotation and helps set expectations.

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

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

The description is concise yet information-dense. It front-loads the primary use case, then lists required and optional parameters in a structured way, and ends with the return format. Every sentence adds value without redundancy.

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

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

Despite having no output schema, the description compensates by listing the exact fields returned and pagination metadata. It covers prerequisites, filters, defaults, and return structure. For a read-only list tool with 7 parameters, this is 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?

All 7 parameters have schema descriptions (100% coverage), so baseline is 3. The description adds extra semantic value by clarifying defaults (status defaults to Active, pageSize defaults to 20, currentPage defaults to 1), which are not fully captured by the schema. It also reiterates the case-insensitive behavior, but that is already in the schema.

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

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

The description clearly states the tool's purpose: to browse or search a seller's own Amazon catalog on a given marketplace. It uses specific verbs ('browse', 'search'), names the resource ('seller's own Amazon catalog'), and lists key filters, distinguishing it from related tools like get_seller_listing_changes.

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 when to use this tool ('when the user wants to browse or search a seller's own Amazon catalog') and provides prerequisites (sellerId + marketplace, discovered via list_seller_profiles). It does not explicitly state when not to use alternatives, but the context is clear enough for a 4.

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 the description does not contradict this. It adds useful behavioral context beyond the annotation by explaining the paginated response shape, the per-item fields, and how includeCorrelations: true attaches ranking/conversion impact.

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 dense paragraph that front-loads the use case, then systematically covers prerequisites, filtering/sorting options, the optional correlation flag, and the exact return fields. Every sentence adds operational value without restating the schema 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 13 parameters, no output schema, and only a readOnlyHint annotation, this description carries the full burden of explaining invocation. It covers required args, filter/sort semantics, output fields, pagination metadata, and the conditional correlation object, making it sufficiently complete for an agent to select and call the tool correctly.

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

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

Schema coverage is 100% with descriptions on every parameter, so the baseline is 3. The description adds value by grouping parameters into filters, sorting, and correlation, and by linking sellerId to the discovery tool list_seller_profiles. It also explains the output structure, which helps when selecting includeCorrelations.

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 'Use this when the user asks what changed on their Amazon listings — price, content, or image edits', which clearly identifies the action (list changes) and the resource (seller listing changes). It also distinguishes the tool from sibling tools like get_seller_catalog and list_seller_profiles by focusing on changes over time.

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 states when to use the tool ('when the user asks what changed on their Amazon listings') and gives concrete prerequisites: requires sellerId + marketplace and points to list_seller_profiles for discovery. It does not explicitly mention when not to use it or name alternative tools, 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?

The readOnlyHint annotation already indicates safety. The description adds substantial behavioral detail: pagination, default filters, list of returned fields including nested searchTerms, and the fact that dismissed alerts are excluded. 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 a single, information-dense paragraph that front-loads the main purpose and then systematically covers output fields and pagination. No redundant sentences.

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

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

Given the tool's complexity (six optional filters, pagination, deeply nested item structure) and the absence of an output schema, the description provides a complete inventory of the response shape and behavior. Everything an agent needs to know is included.

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 descriptions cover all six parameters, and the description merely restates filter names and updatedSince's purpose already in the schema. It adds marginal context beyond the schema, so a 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 opens with a direct use case ('find wasted PPC ad spend') and clearly identifies the resource (blind-spend alerts) and scope (across connected Amazon seller accounts). It distinguishes itself from sibling tools like list_rank_radars or get_niche_* by focusing on wasted-spend alerts.

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?

States when to use ('find wasted PPC ad spend'), explains default behavior (active alerts, last 30 days), and specifically calls out updatedSince for incremental polling. It doesn't explicitly compare to alternative tools, but the use case is clear enough.

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 readOnlyHint: true, and the description adds meaningful behavioral context: default active status, 30-day window, filter semantics (e.g., updatedSince for incremental polling), and the fact that dismissed alerts are excluded. It doesn't cover rate limits or auth, but the read-only safety is already disclosed by annotations and the description reinforces safe usage.

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

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

The description is front-loaded with the primary use case and efficiently packs in scope, defaults, filters, return fields, and pagination metadata without fluff. Each sentence serves a purpose and adds concrete detail, making it well-structured for an agent.

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 has no output schema, the description compensates by explicitly listing the fields in each response and pagination metadata. It fully covers purpose, behavior, filter options, and result structure, making it self-sufficient for an agent to select and invoke correctly.

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

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

Schema description coverage is 100%, with detailed descriptions for every parameter. The description adds value by explaining defaults (active, 30 days) and the incremental polling use case for updatedSince, but the schema already carries most parameter meaning. This matches the baseline for full 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 clearly identifies the resource ('indexing-issue alerts') and the action ('Retrieves a paginated list'), and explains what an alert represents (ASIN no longer indexed for tracked keywords). It distinguishes this tool from siblings like list_blind_spend_alerts by specifying the issue type.

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 opening 'Use this to find products that may have lost search visibility' gives clear when-to-use guidance. It also explains default behavior (active alerts, last 30 days) and how to filter or paginate, but does not explicitly state when not to use it or name alternative tools for other alert types.

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, which the description aligns with by describing a retrieval operation. It adds useful behavioral context: pagination metadata (currentPage, pageSize, hasNext), sort order by newest first, and the 50-item page limit, which are not in 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 a single paragraph but logically organized: use case first, then return values, then optimization tips. Every sentence adds information, but it is slightly dense; a bulleted structure could improve skimmability without adding length.

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 listing tool with a rich schema and no output schema, the description covers when to use it, what it returns, how to paginate, and how to narrow results. It lacks explicit mention of default values for pageSize/orderBy, but these are fully documented in the schema, so the description is 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?

The input schema already has 100% parameter description coverage, including defaults and examples. The description only reiterates the page size limit and search use cases without adding new meaning, so it meets the baseline but does not elevate 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 uses specific verbs ('list', 'retrieves') with a clear resource ('Niches') and immediately states its primary use case: finding a nicheId for other tools like get_niche_keywords. It also defines what a Niche is, distinguishing this listing tool from sibling tools that operate on a specific niche.

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 first when the user asks about their niches') and gives concrete guidance on narrowing results via searchText or searchAsin instead of paging. It does not explicitly state when not to use it or name alternative tools for other scenarios, but the 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 only declare readOnlyHint. The description adds the operational context that matters: ~60 requests/minute rate limit, each call counting toward API usage, a 30-day default window capped at 90 days, pagination semantics, and the includePlacements toggle affecting both response size and which sort fields are accepted.

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 use case before requirements and output details, and almost every sentence carries non-redundant information. It is a dense single block, though, and the long enumeration of returned metrics could be trimmed since much of it is inferable.

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, so the description compensates by enumerating the returned campaign fields and pagination metadata. Together with prerequisites, window limits, rate limits, and filter exclusivity, an agent has everything needed 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%, so the schema already documents all 13 parameters; the baseline would be 3. The description still adds value by stating the asin/parentAsin mutual exclusion, the default reporting window, and a concrete sort recipe (sortBy: "spend", sortOrder: "DESC") that the schema alone does not suggest.

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 (list Sponsored Products PPC campaigns for a seller) plus the concrete questions it answers (top spenders, high ACOS, placements, campaigns advertising a product). It also distinguishes itself from the closest sibling by naming get_rank_radar_ppc_data as the per-keyword 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?

Explicit about when to use it (user questions about Sponsored Products campaigns), prerequisites (sellerId + marketplace from list_seller_profiles), and where it stops (per-keyword ad data belongs to get_rank_radar_ppc_data). It also gives a routing heuristic for the common 'biggest spenders' question instead of paging everything.

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 mark this as readOnlyHint=true, and the description adds useful behavioral detail beyond that: pagination metadata, a hard cap of 50 items per page, the need for multiple calls on large accounts, and the fact that archived Rank Radars are only returned when explicitly requested. These disclosures help the agent set expectations without contradicting the annotation.

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

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

The description is front-loaded with the most important use case, then explains the resource, returned fields, and pagination behavior without fluff. Every sentence earns its place, and no information is duplicated 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?

There is no output schema, so the description correctly compensates by enumerating the returned item fields and pagination metadata. It gives the agent enough detail to know what results to expect and how to page through a large account, making the tool safe to select and call.

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 five parameters with full coverage, so the description does not need to repeat parameter meanings. It does add usage-oriented hints like filtering by nicheId and the 50-item page cap, but these map onto existing schema fields rather than introducing new parameter semantics.

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: it 'Retrieves a paginated list of Rank Radars' and is explicitly positioned as the way to 'find a rankRadarId before calling get_rank_radar_data'. It also enumerates the returned fields, which distinguishes it from sibling tools like create_rank_radar or pause_rank_radar.

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 usage context: call this before get_rank_radar_data, and filter by nicheId when the user has already identified a niche. It does not explicitly discuss when not to use it or compare it against alternatives like create/pause/delete, so it falls just short of fully explicit when/when-not guidance.

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

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

The readOnlyHint annotation already indicates a safe read operation. The description adds valuable behavioral context by detailing the response structure: each profile's fields (sellerId, sellerName, marketplace, hasAdApi, createdAt) and pagination metadata (currentPage, pageSize, total, lastPage, hasNext, hasPrev). No contradictions 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, front-loaded with usage guidance, and the second sentence enumerates the response structure without excessive detail. Every sentence earns its place, and the formatting makes it easy to scan.

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?

Despite having no output schema, the description fully explains both the list contents and pagination metadata. It also covers the tool's purpose, usage timing, and relationship to sibling tools, making it self-sufficient for an agent to select and invoke correctly.

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

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

Input schema covers 100% of parameters with clear descriptions, so the baseline is 3. The description mentions pagination metadata but does not add new meaning to the parameters themselves. It reinforces that pageSize and currentPage control paging, which the schema already explains.

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?

Description uses a specific verb ('list') and explicitly identifies the resource ('connected seller profiles') with scope ('the organization's'). It also distinguishes itself from sibling tools by positioning it as the discovery step for sellerId/marketplace needed by other tools, making its unique purpose clear.

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?

Description states exactly when to use it: when the user asks which Amazon seller accounts are connected, or as a discovery step. It also names specific dependent tools that require its output, giving strong contextual guidance on when this tool is the right choice.

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

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

With readOnlyHint=true already set, the description still adds substantial behavioral context: pagination behavior, the nature of each entry (token-consumption event), and the exact fields included. It goes beyond annotations by describing response structure and metadata, giving agents full transparency on what to expect.

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 dense paragraph but every sentence contributes value: usage triggers, what is returned, filtering options, and response fields. It is longer than minimal but appropriately so for a complex list tool; 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?

With no output schema, the description fully explains what the caller will receive, including pagination metadata and per-item fields. It also clarifies that it's organization-wide, filters by type/search/date, and returns token-consumption events—complete coverage for a 6-parameter read-only list tool.

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

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

Schema coverage is 100% with detailed per-parameter descriptions. The tool description reinforces how filters map to user needs (e.g., filtering by type, search, and date range) and adds meaningful context about pagination defaults and page size caps, complementing rather than repeating the schema.

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

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

The description opens with explicit user intents ('who consumed tokens, how their quota was spent, or wants an audit') and names the exact resource ('billable feature usage logs'). It clearly distinguishes from sibling tools like list_niches or get_quota by focusing on token-consumption events.

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 strong when-to-use guidance ('Use this when...') and lists supported filters. It does not explicitly mention when not to use it or name alternatives, but the context makes it clear this is for audit/quota questions, distinguishing it from read-only tools like get_quota.

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

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

Goes well beyond the annotations: discloses that tracking stops for all keywords, the Daily Tracked Keywords quota is freed, data and history are retained, the operation is idempotent, and the resulting status is PAUSED not ARCHIVED. The description's 'without losing anything / fully reversible' claim clarifies rather than contradicts the conservative destructiveHint:true — the hint signals mutation, the description explains why no data is destroyed.

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: terminology mapping, behavioral effects, reversibility, sibling routing, status semantics, and idempotency. Dense but logically ordered with the core purpose front-loaded in the first sentence.

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

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

Complete for a single-parameter tool with full schema coverage: an agent knows what it does, when to pick it, what changes, what doesn't, how to reverse it, and how to verify the result via list_rank_radars. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100% and the schema already documents rankRadarId as the Rank Radar UUID from list_rank_radars, so the baseline of 3 applies. The description adds surrounding context (quota, status, reversal) but no parameter-specific semantics 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 + resource ('pause tracking on a Rank Radar') and immediately resolves the API terminology trap: 'the action the DataDive API calls archiving'. It explicitly differentiates from sibling tools delete_rank_radar, resume_rank_radar, and implicitly from pause_rank_radar_search_terms by scoping to the whole Rank Radar.

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

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

Gives explicit when-to-use ('when a user asks to archive a Rank Radar'), names the reversal alternative (resume_rank_radar), and routes around delete_rank_radar ('prefer it... whenever the user may want the data back'). Also clarifies the status semantics in list_rank_radars so an agent knows how to verify the outcome.

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 is rich in behavioral detail: it says the operation is reversible, keeps history, frees slots, requires no confirmation, and is safe to repeat. However, the annotations declare destructiveHint: true, while the description insists 'nothing is lost' and 'Reversible ... needs no confirm'. This directly contradicts the annotation, so per the rubric behavioral transparency must be scored 1.

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

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

The description is front-loaded with the core purpose and includes several useful operational details. It is slightly wordy in places—'archiving' plus 'history kept' plus 'nothing is lost' partially overlap—but every sentence contributes actionable guidance, so it remains effective and compact enough.

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 no output schema and no nested objects, the description is complete: it covers when to use it, what effect it has, how to get inputs, reversibility, idempotency, and why confirmation can be skipped. The only serious issue is the contradiction with the destructive annotation, which is already penalized under behavioral transparency.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaningful semantics beyond the schema: it clarifies that keyword ids must not be the keyword text, and it names the exact sources of valid ids from get_rank_radar_data and add_rank_radar_search_terms. This materially improves the agent's ability to construct a correct call.

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 ('stop tracking individual keywords') and a precise resource ('on a Rank Radar while keeping the Rank Radar itself active'), which clearly distinguishes this tool from siblings like pause_rank_radar and resume_rank_radar_search_terms. It also explains the practical use case of trimming an overly broad keyword set, leaving 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?

The description explicitly states when to use it ('the way to trim a keyword set the user finds too broad') and contrasts it with pausing the entire Rank Radar by emphasizing the radar stays active. It also points to the reverse operation and tells the agent where to get keyword ids, so the agent knows exactly how to proceed.

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 destructiveHint=true and readOnlyHint=false. The description adds substantial behavioral context: token spend per ASIN batch, irreversibility, non-idempotency (each call spends tokens and starts a separate re-dive), asynchronous execution returning `diveId` and `estimatedCompletionDate`, the expected polling flow, and that the `nicheId` persists so rank radars/reports follow refreshed data. This far exceeds the annotation baseline and contradicts nothing.

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: purpose and sibling distinction first, then critical cost/destructive warnings, then modes, then async behavior and persistence. Every sentence earns its place. It loses a point only for being a single wall of text with many embedded qualifiers — minor segmentation would aid scanning — but it is far from bloated.

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 complex tool with 7 parameters, destructive side effects, two modes, mode-dependent parameters, and no output schema, the description is remarkably complete. It explains return values (`diveId`, `estimatedCompletionDate`), the full async lifecycle (poll `get_dive_status` until `success`), cost behavior, and the persistence guarantee, while correctly referencing sibling tools (`get_dive_status`, `create_niche_dive`). Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, and the schema already documents each parameter well. The description adds value beyond the schema by connecting parameters to modes (`same_competitors` needs no other argument; `discover` is sized by `numberOfCompetitors` and steerable by `heroAsin`/`lockedAsins`/`excludedAsins`) and by adding the user-approval requirement for `confirm`, which the schema does not convey.

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

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

The description states a specific verb ('refresh'/'re-dive'), a specific resource ('an existing niche'), and immediately distinguishes itself from the sibling `create_niche_dive`. An agent can tell exactly what this tool does and how it differs from the nearest alternative without opening the schema.

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

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

Explicitly names `create_niche_dive` as the alternative and tells the agent to use this tool instead of creating a new niche. It also gives mode-selection guidance (`same_competitors` for refreshing stale data, `discover` when the niche has changed) and retry guidance (poll `get_dive_status` on error/timeout rather than re-calling). Nothing is left to inference.

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

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

Beyond the destructiveHint annotation, it candidly describes quota-dependent partial resumption, the bad-request failure mode when no quota remains, reversibility via pause_rank_radar, and idempotency on already-active radars. These are meaningful behavioral facts not captured in the schema or annotations.

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

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

The description is front-loaded with the core action and each subsequent sentence contributes a distinct fact: state precondition, quota behavior, reversibility, failure mode, and repeatability. No filler or redundant restatement of the title.

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

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

For a single-parameter mutation with no output schema, it covers preconditions, quota handling, failure behavior, reversibility, and idempotency, and references the relevant sibling tools (list_rank_radars, get_quota, pause_rank_radar). Nothing necessary for correct invocation is missing.

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

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

The schema already documents rankRadarId with 100% coverage. The description adds useful meaning by constraining it to PAUSED radars, excluding ARCHIVED ones, and explaining that quota limits may cause only part of the keyword set to resume.

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 action ('restart tracking on a Rank Radar') and defines the exact object state it applies to (PAUSED via pause_rank_radar, not ARCHIVED). This makes it easy to distinguish from siblings like resume_rank_radar_search_terms and pause_rank_radar.

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 says when the tool applies (a Rank Radar paused with pause_rank_radar), when it cannot apply (ARCHIVED), and points to get_quota as a prerequisite check when quota matters. It also states that repeating the call is safe, so there is no ambiguity about invocation conditions.

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 quota consumption and failure behavior, reversibility via pause_rank_radar_search_terms, idempotence for already-active terms, and the requirement to pass ids rather than text. These are material behavioral details not available 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?

Four dense, purposeful sentences. The purpose is front-loaded, with quota implications, reversibility, id sourcing, and idempotence each earning their place. There is 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 no output schema, the description covers when to use it, prerequisites, failure conditions, reversibility, repeat-safety, and parameter sourcing. Nothing essential is missing for an agent 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 description coverage is 100% and both parameters are clearly documented. The description reinforces the 'not keyword text' rule and the source of ids, 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 specific verb and resource: resume tracking of paused Rank Radar search terms. It clearly differentiates from the sibling pause_rank_radar_search_terms and explains the quota implication, leaving 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 says when to use the tool, instructs the agent to check get_quota first, clarifies that the operation is reversible, and points to get_rank_radar_data as the source of keyword ids. This gives concrete routing and prerequisite guidance beyond simple tool selection.

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