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?

Goes well beyond the annotations: states the operation cannot be undone, costs Search Term tokens scaling with numberOfKeywords, requires confirm:true after user approval, and creates a separate Rank Radar on each call. This materially changes how an agent should invoke and handle failures.

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 adds necessary operational guidance for a destructive, cost-incurring action. The purpose is front-loaded, followed by the key warning, retry guidance, output info, and prerequisites. No filler.

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

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

For a 4-parameter destructive tool with no output schema, the description covers invocation, required inputs, cost behavior, user confirmation, failure recovery, output identifier, and follow-up reading. Nothing critical is missing for correct selection and 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?

Although the schema already documents all parameters well, the description adds crucial behavioral semantics: cost scaling with numberOfKeywords, the confirmation requirement for confirm, and that nicheId comes from list_niches. It also notes the return value and how to read the data later.

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, actionable purpose: start tracking organic and sponsored keyword rankings for an ASIN within a niche. This clearly differentiates it from siblings like list_rank_radars, get_rank_radar_data, and create_niche_dive.

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

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

Explicitly tells the agent when to use the tool, warns that it spends tokens and is destructive, and instructs that on error/timeout it should check list_rank_radars rather than retry. Also notes the prerequisite of obtaining nicheId from list_niches.

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?

The description goes far beyond the `readOnlyHint` annotation by specifying the exact behavioral contract: three possible `status` shapes, their associated fields (`estimatedCompletionDate`, `nicheId`, `tokensUsed`/`tokensLeft`, `error`), and the follow-up behavior on success. It also discloses that dives can take minutes, guiding the agent on expected latency and retry semantics.

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 and front-loaded: first the primary purpose, then the return shapes, then the follow-up workflow, then polling guidance. Every sentence adds operational value, and the length is justified given there is no output schema to describe the response variants.

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 documenting all possible response shapes and fields. It also connects the tool to sibling tools for next steps (`list_niches`, `get_niche_keywords`, `get_niche_competitors`) and gives practical polling guidance. Nothing essential for correct invocation or interpretation 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 describes `diveId` as the identifier returned by `create_niche_dive` or `redive_niche`. The description reinforces this relationship and adds the nuance that a re-dive returns the same niche with refreshed data, but it does not add new parameter-level details beyond the schema. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'poll a niche dive... until it finishes.' It clearly identifies the tool as a status-polling endpoint tied to `create_niche_dive` or `redive_niche`, which distinguishes it from sibling tools that create, list, or mutate niches. The return-shape overview further removes any ambiguity about what the tool accomplishes.

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 it: after starting a dive with `create_niche_dive` or `redive_niche`, poll until it finishes. It also advises on re-polling with `estimatedCompletionDate` as a timing hint. It does not explicitly name alternative tools or provide when-not-to-use guidance, but the usage context is clear and sufficient.

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?

Beyond the readOnlyHint annotation, the description discloses the return format ('Returns an array of tracked keywords; each has id, keyword, searchVolume, ranks (per-day { date, organicRank, impressionRank }), and any highlight annotations') and date format requirements. This adds meaningful context about what the operation does and what the user should expect, without exceeding annotation coverage.

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 and concise. Each sentence earns its place: purpose, parameter requirements, operational behavior, return structure, and usage sequencing. There is no redundancy or fluff, making it easy for an agent to parse.

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

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

The description is complete given the tool's complexity. It covers what the tool does, the required parameters and their format, the return structure, and how to obtain the necessary ID. With readOnlyHint annotation and no output schema, this description provides enough context for an agent to invoke the tool correctly without ambiguity.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters thoroughly. The description adds marginal value by restating the date format and the need to obtain rankRadarId from list_rank_radars, but this information is already present in the schema. Therefore, 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: 'Retrieves historical keyword ranking data for the specified Rank Radar within the date range.' The verb 'retrieves' is specific, and the resource ('keyword ranking data' for a Rank Radar) is well-defined. It also distinguishes from siblings like list_rank_radars and create_rank_radar by focusing on data retrieval rather than management.

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 clear usage context by stating 'Use after list_rank_radars to discover a rankRadarId,' which establishes a prerequisite and workflow. However, it does not explicitly mention when not to use this tool or alternative approaches, so it falls short of a 5.

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

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

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 already declare readOnlyHint=true, and the description adds substantial behavioral context beyond that: the API does not apply paging, every page repeats the same rows, accounts with many niches return large responses, and there is no server-side search or sorting. This is exactly the kind of behavioral disclosure an agent needs.

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?

Although long, every sentence earns its place: purpose, return shape, and a critical limitation with concrete handling instructions. The TEMPORARY LIMITATION section is clearly signaled and front-loaded with actionable guidance.

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

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

With no output schema, the description still enumerates all returned fields and pagination metadata, defines what a Niche is, and covers the API's non-paging behavior, response size, and absence of search/sorting. An agent has everything needed to invoke the tool correctly and interpret the response.

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 describes both parameters completely, so the baseline is 3. The description raises this by adding the crucial caveat that pageSize and currentPage are effectively ignored because the API returns every niche in a single call—information that is not inferable from the schema alone.

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 action ('Use this first when the user asks about their niches') and explicitly states it 'Retrieves the Niches of the account.' It also names the key output fields, clearly distinguishing this as the account-level niche enumeration tool from the get_niche_* siblings.

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

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

It states exactly when to use the tool ('when the user asks about their niches, or to find a nicheId') and names the downstream tools that require the ID. It also provides explicit negative guidance: do not walk currentPage while hasNext is true because paging is not applied.

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.