AMZ Vault

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

Annotations only provide readOnlyHint=false and destructiveHint=false; the description adds meaningful behavioral context: submit opens a thread, list shows threads with team replies, reply continues a thread, and replies surface both in list results and on the web at /feedback. It also clarifies that this is not an Amazon write. It stops short of describing auth expectations or failure/error behavior, but the core side effects are 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?

The description is dense but every sentence earns its place: purpose and action modes first, when-to-use second, follow-up visibility third, support access fourth, and email alternative last. It is well-structured and front-loaded, avoiding fluff while covering all necessary 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?

For a multi-action communication tool with no output schema and limited annotations, the description covers action semantics, per-action parameters, result visibility, alternatives, and escalation paths. An agent has enough context to select the right mode, supply the correct fields, and know where replies will appear. Nothing critical for correct invocation is missing.

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

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

Schema coverage is 67%, and the description adds valuable action-parameter grouping: submit maps to subject, body, and category; reply maps to thread_id and body; list shows account threads with team replies. This goes beyond the schema's individual field descriptions by explaining how parameters are used per action. Status filtering is left to the schema, but the description still carries meaningful semantic weight.

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

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

The description names a specific channel ('Feedback & support channel to the AMZ Vault team') and immediately clarifies it is NOT an Amazon write. It enumerates the three actions (submit, list, reply) with their exact effects, making the tool's purpose unambiguous and distinguishable from sibling tools like account_support_access.

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 conditions: use it when the user reports a problem with AMZ Vault itself, when data is missing, or when sending the team an idea. It also names an alternative tool (account_support_access) and an email fallback, so an agent knows exactly when this tool is appropriate and when to route elsewhere.

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 destructiveHint=false, and the description complements this by clarifying the access restriction, cross-tenant scope, and the exact set of returned insights: per-dataset sync time/status/error, staleness, connection verdicts, auto-sync state, and AI client connection history. 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 front-loaded with the core purpose and scope. Every clause contributes meaningful information, including usage constraints and parameter guidance. It is somewhat long, but the density justifies the 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?

Given there is no output schema, the description does a good job enumerating what the tool returns and what it excludes. It covers access level, scope, operational nature, and parameter intent. Minor omissions like pagination or empty-result behavior are not critical for selecting and calling 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 documents all three parameters. The description adds a useful example for new_within_days and lists the parameter names, but it does not substantially deepen the meaning of user_id or seller_connection_id 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 clearly identifies the tool's function: a per-connection health check for onboarding and sync status across all tenants. It states the specific question it answers, the datasets involved, and the output verdicts. It also distinguishes itself from financial/reporting siblings by explicitly saying it carries no revenue, units, margins, ASINs, or emails.

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 strong context: it is super-admin only, operational only, and suitable for triaging recent sign-ups via new_within_days with an example. It implies when not to use it by excluding non-operational data, though it does not name specific alternative sibling tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: the tool returns a framework guide, always includes a toc, and supports section-specific reads. This helps the agent know what kind of response to expect even without an output schema.

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

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

The description is compact and front-loaded: content list first, then the critical call-to-action, then the parameter usage hint. Every sentence earns its place with no vague filler or repetition of schema details. It is dense but immediately scannable.

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 one-parameter, read-only reference guide with no output schema, the description is complete: it states what the guide covers, when to use it, that a toc is always included, and how to request a single section. An agent has enough context to select the tool and invoke it correctly without further investigation.

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 the single optional section parameter fully described via enum and description, so the baseline is 3. The description adds value by explaining the intended usage of the parameter: 'pass section= (see toc) for a focused read.' This tells the agent why and when to use the parameter, not just what it is.

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 tool as the operator's brand & PPC decision framework and enumerates its specific contents: margin spine, product postures, campaign structure/bidding, harvesting/negation logic, guardrails, and decision triggers. This distinguishes it from the many data-query and staging tools among its siblings. The imperative 'CALL THIS' makes its role as a decision guide unmistakable.

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, highly actionable usage guidance: call this before analyzing an account or proposing ANY optimization, covering bids, budgets, negatives, harvest, campaigns, and pricing. It also frames the tool as the 'default operating model,' making the priority clear. The section= hint adds a focused-use path rather than requiring a full read every time.

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 discloses critical behavior beyond annotations: only the draft is queued, the actual email requires an admin action on the Send Notice screen, the greeting is auto-added, and bell=true triggers an in-app notification. It also flags admin-only usage. No contradiction with the annotations exists, and the disclosure materially changes how an agent should invoke and verify the 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?

Three sentences carry all essential information with no redundancy. The most important constraint (queue-only, admin-only) is front-loaded, followed by usage context and parameter guidance. Every sentence earns its place, making the description dense yet easy 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?

For a simple 4-parameter action with no output schema, the description covers purpose, when to use it, admin restrictions, the asynchronous send behavior, body format rules, and the optional bell flag. Nothing an agent needs to invoke it correctly is missing, and the absence of an output schema is acceptable because the operation is a fire-and-forget queue request.

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

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

With 75% schema description coverage, the schema already documents user_id, body, and bell. The description adds value by clarifying body formatting ('blank line = new paragraph'), explaining the auto-added greeting, and explicitly defining bell's effect ('raises an in-app notification when sent'). It also names the undocumented subject parameter in context, partially compensating for that gap.

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

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

The description opens with a specific verb and resource: 'Queue a one-off notice email to a user for admin review (ADMIN-ONLY).' This clearly distinguishes it from read-only account tools like account_report or account_profiles and from other stage_* staging tools, while the parenthetical 'admin-only' further narrows its audience and scope.

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 states a clear trigger: 'Use after an ops-review finding that warrants proactive user outreach.' It also sets an explicit boundary by emphasizing this action only queues a draft and does not send, preventing misuse. It does not name alternative tools, but the provided context is sufficient to guide selection among many account and staging siblings.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: the ADMIN-ONLY access restriction, deduplication behavior, occurrence counts, and the explicit inclusion of failed SP-API sync runs and scheduled tasks. It does not detail non-admin failure behavior or result limits, but the added context is genuinely useful.

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 efficient: one sentence defines the content, one gives the use case, and one compresses all parameters into a single clause. Information is front-loaded (what it is, admin-only restriction before params). Slightly run-on, but every sentence earns its place.

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

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

With no output schema, the description gives a reasonable hint at return shape via 'occurrence counts'. It covers filters, default lookback window, and source services. Gaps are minor: user_id is not mentioned in the prose summary, and there is no pagination or limit information. For a read-only feed tool with 5 optional params, this is nearly complete.

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

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

Schema coverage is 60%, leaving level, service, and q without full semantic coverage. The description compensates by encoding the enum values ('level (error|warning|throttle), service (web|worker)') and clarifying q as 'search source/message'. It slightly duplicates the schema's hours default and omits user_id, but it adds meaning where ambiguity is highest.

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 resource and scope: an 'Operational health feed (ADMIN-ONLY)' that returns 'deduped errors / warnings / API-throttle events' with occurrence counts plus failed SP-API syncs and scheduled tasks. The specificity of content enumerated distinguishes it clearly from sibling tools like account_health_check and account_feedback.

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 guidance: 'Use for "review the ops log" / troubleshooting sweeps', which tells an agent the exact user intent that should route to this tool. It does not name alternatives or state when-not-to-use-this, but the usage context is unambiguous enough to select correctly among siblings.

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

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

Annotations already mark it as readOnly and not destructive, so the safety profile is covered. The description adds the useful context that this is a listing operation over bridged connections, but it does not disclose what the returned data looks like or whether an empty result is possible.

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

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

A single, front-loaded sentence that states the action and scope with no filler. Every word earns its place.

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

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

Given the tool's simplicity (no params, no output schema, simple list operation), the description is largely complete. It explains what is listed and the relationship to seller connections, though it stops short of describing the fields or shape of each profile returned.

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

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

The tool has zero parameters and 100% schema description coverage, so there are no parameters to explain. Per the baseline for param-less tools, the description is sufficient and does not need to compensate for any undocumented inputs.

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 ('List') and names a precise resource: advertising profiles/PPC accounts that are bridged to seller connections. This clearly distinguishes it from siblings like account_sellers (which would list seller connections) and ppc_account_summary (which would summarize account performance).

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 makes the intended use clear: call this to see PPC accounts linked to the token's seller connections. However, it does not explicitly state when not to use it or name alternatives, so the agent must infer the boundary from sibling names.

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

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

Annotations already cover read-only and non-destructive behavior. The description adds useful context beyond that: the report bundles period cards, settlement waterfall, freshness caveats, and quote_rules, and signals that it is a single consolidated call. This gives the agent a meaningful picture of 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 compact and information-dense. It front-loads the canonical purpose, lists the key report contents, and closes with an explicit usage preference. Every clause earns its place without 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?

For a read-only report tool with no output schema, the description gives enough high-level content and usage context to guide invocation. It could be more complete by explaining quote_rules or the meaning of 'freshness caveats,' but overall the agent can infer the tool's role and scope.

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 description provides no parameter-level guidance. Schema coverage is 75%, but the 'currency' parameter is undocumented and the description does not clarify it or add meaning to any parameter. The tool relies entirely on the input schema, which has a notable gap.

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

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

The description clearly identifies the tool as the canonical account overview, listing its main components (period cards, settlement waterfall, freshness caveats, quote_rules). It is distinct from the many specialized pnl_* siblings by emphasizing 'ONE call' and the canonical status, though it does not explicitly name an alternative 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 gives explicit guidance to prefer this tool for 'how is the account doing' questions, which is a clear usage signal. However, it does not state when not to use it or explicitly compare against alternatives like pnl_breakdown or pnl_summary, so some inference remains.

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 destructiveHint=false. The description adds meaningful context beyond those annotations by specifying that results are scoped to what 'this token can access' and by previewing the return payload (marketplaces and currencies), which is especially useful given there is no output schema.

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

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

A single, front-loaded sentence with no filler. The verb and core constraint appear immediately, and every remaining phrase ('Amazon seller connections', 'this token can access', 'marketplaces and currencies') contributes essential information.

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

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

For a zero-parameter read-only listing tool, the description covers the essential behavior, access scoping, and the main output fields. It could be slightly more explicit about the exact return structure or pagination, but given the tool's simplicity and the readOnly/destructive annotations, it is largely 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 tool has zero parameters, so no parameter explanations are required; the baseline for 0-parameter tools is 4. The description's mention of marketplaces and currencies refers to the output, not parameters, and therefore does not need to compensate for any schema gaps.

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 ('List'), a precise resource ('Amazon seller connections'), and the access scope ('this token can access'), plus the returned attributes (marketplaces and currencies). This clearly differentiates it from sibling account_* tools like account_profiles or account_report, which target different account data.

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 no guidance on when to use account_sellers versus alternatives such as account_profiles or account_feedback. There are no exclusions, preconditions, or scenario-based routing hints, leaving the agent to infer usage solely from the tool name and title.

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 only minimal annotations (readOnlyHint=false, openWorldHint=false), the description carries the full safety disclosure: support can see what the user sees but 'can change nothing,' access auto-expires after 7 days, every view notifies the user, and revoke takes effect immediately. It openly labels the operation as changing account access.

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

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

Two sentences, front-loaded with the core action, with each clause adding a distinct fact: scope, auto-expiry, read-only, notifications, immediate revoke, user permission, and when to offer it. There is no filler.

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

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

For a one-parameter command tool with no output schema, the description is complete: it explains what the tool does, when to use it, the exact effect of each action, and the safety prerequisite. Nothing essential 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 has one parameter with 0% description coverage, so the description is the only source of parameter semantics. It explains both enum values in detail: action=grant enables 7-day expiring read-only access; action=revoke disables it immediately.

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 precise action and resource: 'Grant or revoke the AMZ Vault support team's READ-ONLY view of this account.' This clearly identifies the tool's function and distinguishes it from the many diagnostic and reporting siblings, while the mention of account_feedback reinforces that it is a separate access-control operation.

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

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

The description gives explicit when-to-use guidance: 'offer it only when support needs to see a problem first-hand' and notes it is 'usually alongside an account_feedback thread.' It also states a mandatory prerequisite: this 'ALWAYS needs the user's explicit go-ahead.'

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 destructiveHint=false, covering the safety profile. The description adds that the request is LIVE (not cached) and that the response includes the full contentModuleList, which is useful behavioral context beyond the annotations.

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

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

Two dense sentences with zero filler. The core action is front-loaded, and the dash clearly separates the main purpose from the dataset distinction and key-listing tip.

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 must carry the return-value explanation. It does so by promising 'full contentModuleList' and linking it to editing. It does not detail optional-parameter effects or error/pagination behavior, but for a single-document live read the description is nearly sufficient.

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

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

Schema description coverage is only 33% (only seller_connection_id has a schema description). The description partially compensates by explaining that content_reference_key values can be listed via data_query 'aplus_content', but it does not clarify marketplace_id or the key's exact format. Useful hint, but not complete param guidance.

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 ('Fetch'), a precise resource ('ONE A+ content document LIVE'), and deliberately contrasts it with the aplus_content dataset ('holds metadata only'). Also names a sibling tool (data_query) for listing keys, so an agent can tell them apart.

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 to list keys via data_query 'aplus_content' and explains that the dataset contains metadata only — effectively saying 'use this tool when you need the full live document, use data_query only for keys/metadata.' This is clear when-to-use and when-not-to-use 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 description adds substantial behavioral context beyond the readOnlyHint annotation: it defines what 'pending' means, breaks down the pending sub-statuses, clarifies that shadow mode means AI applied nothing, and discloses pagination fields and the mine/all_users ownership boundary. It also reinforces READ-ONLY semantics and clearly routes mutations to a sibling tool, with no contradiction against 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: the core purpose is front-loaded, status semantics are compactly enumerated, scope behavior is stated, and the read-only boundary and mutation alternative are explicit. The length is justified by the tool's complexity and the lack of an output schema.

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

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

For a complex 10-parameter tool with no output schema, the description covers purpose, statuses, scope, pagination, read-only behavior, and the mutation alternative. It is not fully complete because it omits details on mode filtering, rule_id, include_full_reasoning, and the params object, but an agent can correctly invoke the default list behavior and navigate the main decision points.

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 description adds meaningful semantics for the most important parameters: action=list, status values with their behavioral implications, scope ownership behavior, and pagination concepts. Given only 40% schema coverage, this helps substantially. However, it does not clarify mode, rule_id, include_full_reasoning, or the params object, so some parameter gaps remain.

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 tool as the approval inbox for V2 rule automation, the only surface for pending automation approvals, and explicitly limits it to read-only listing via action=list. It also distinguishes this tool from MinMax/AOE/scheduled-task systems and from stage_automation_review, making its 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?

It explicitly states when to use the tool (list pending automation approvals, with status and scope semantics) and when not to use it: approving, rejecting, or undoing items belongs in stage_automation_review. It also calls out that MinMax/AOE/scheduled-task tools are separate systems, preventing cross-tool confusion.

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 provide readOnlyHint=true, openWorldHint=false, and destructiveHint=false, covering the safety profile. The description adds some context about what data is included (configs, modes, guardrails, cycles) but does not disclose behavioral traits like return format, pagination, or freshness. With annotations covering the main behavioral concerns, a neutral 3 is appropriate.

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

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

The description is compact, with the core resource and contents front-loaded in the first sentence, followed by a terse disambiguation sentence. Every word contributes to orientation or disambiguation, and there is no redundancy or 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?

For a simple read-only status tool with one optional parameter and no output schema, the description covers the essential scope and adds a critical disambiguation. It does not describe the response shape, but the listed contents (configs, modes, guardrails, cycles) give a reasonable expectation of what will be returned. Overall, it is complete enough for correct invocation.

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

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

Schema description coverage is 100% for the single optional profile_id parameter, which already explains its meaning and optionality. The tool description adds no additional parameter semantics beyond what the schema provides, so the baseline score 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 clearly identifies the resource as the Adaptive Optimization Engine and lists its contents: per-campaign configs, modes, guardrails, and recent optimization cycles. It explicitly distinguishes itself from automation_activity, so an agent can tell them apart. However, it lacks a specific action verb like 'retrieve' or 'list', relying on the tool name 'status' to convey the operation.

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

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

The description gives a clear when-not signal by stating 'NOT the automation approval inbox (automation_activity)', which prevents confusion with a key sibling. It does not explicitly state when to use this tool versus other automation siblings like automation_rules or automation_recent_tasks, but the phrase 'Adaptive Optimization Engine' implies the intended use case.

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

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

Annotations already provide readOnlyHint=true and destructiveHint=false. The description adds that the list returns schedules and assignments and that mutations are handled elsewhere. This is sufficient for a simple read-only operation, though it does not go deep into output behavior or auth requirements.

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

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

A single front-loaded sentence contains the tool's purpose, read-only nature, required action, and the sibling for mutations. Every word earns its place.

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

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

For a single-action read-only tool with readOnlyHint=true, this is nearly complete. The only gap is that action-specific params are referenced in the schema but never concretely specified in the description, though the 'list' action appears self-sufficient.

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

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

Schema coverage is high and action/profile_id are already described in the schema. However, the params object says 'see description' while the tool description never enumerates action-specific fields. The description adds no real parameter-level meaning beyond what the schema already provides.

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

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

The description states a specific verb ('shows'), a specific resource ('schedules + assignments'), and explicitly contrasts itself with the mutation sibling stage_dayparting_schedule. It is immediately clear what this tool does and what it does not do.

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 READ-ONLY, specifies action=list for reads, and directs mutations to stage_dayparting_schedule. This gives the agent clear when-to-use and when-not-to-use guidance.

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

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

Annotations already establish readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the temporal scope ('Recent') and the general result contents, but does not disclose details like ordering, default limits, or whether results are cached or live. It is adequate but not rich.

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

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

Two short sentences, front-loaded with the core subject and contents, followed by a necessary exclusion. Every word earns its place with no wasted 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 read-only list tool with optional parameters, the description gives a good sense of what is returned, but the undocumented 'limit' parameter and absence of an output schema leave a meaningful gap. An agent knows the general purpose but not how to constrain or paginate results.

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 only 50% because the 'limit' parameter has no description, and the tool description does not clarify it. 'profile_id' is documented in the schema, but the description adds no parameter-level meaning. The agent is left to infer what 'limit' controls.

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 as 'Recent MinMax budget-analysis runs' and enumerates the type of data returned: scope, top performers, and campaigns running hot. The explicit 'NOT the automation approval inbox (that is automation_activity)' distinguishes it from the most likely sibling confusion.

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 tells the agent when this tool is appropriate — when recent MinMax budget-analysis results are needed — and directly warns against using it for the automation approval inbox, naming automation_activity as the correct alternative. This is clear routing guidance.

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

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

Annotations already establish readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that it returns status, cadence, and last execution results, but it does not clarify whether results are per scheduled task or per run, nor any recency window or ordering. This is adequate but not rich.

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 efficient sentence with no filler. The verb and key result fields are front-loaded, making it easy to scan and act on.

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

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

For a read-only list call with two optional parameters, the description is mostly usable, but there is no output schema and the description does not specify the timeframe implied by 'recent' or whether each returned item represents a scheduled task or an individual run. This ambiguity weakens completeness for an agent choosing among similar automation tools.

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

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

Schema description coverage is 100%, so both limit and profile_id are already documented in the schema. The description adds no additional parameter-level meaning, which is acceptable given the high schema coverage.

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

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

The description uses a clear verb and resource: 'Get the list of scheduled automation tasks' with specific fields (status, cadence, last execution results). It is mostly distinguishable from siblings like automation_scheduled_tasks, though it does not explicitly clarify that this is about recent runs versus the task definitions themselves.

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?

No guidance is provided on when to use this tool versus automation_scheduled_tasks, automation_activity, or other automation-related siblings. The only contextual hint is an optional profile_id referencing account_profiles, but there is no explicit when-to-use or when-not-to-use guidance.

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

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

Annotations already mark the tool as read-only and non-destructive, and the description reinforces this with explicit behavioral details: all actions are read-only, dry_run 'applies NOTHING', and auto mode 'can only be set in the app, never from here.' It also discloses approval_mode semantics and ownership visibility for list results, adding value beyond the annotations.

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

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

The description is dense but front-loaded with the most important fact (READ-ONLY) and every clause carries operational significance. It is longer than typical descriptions, but the approval_mode breakdown and scope/behavior explanations are necessary for correct invocation and not wasted words.

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

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

For a multi-action, nested-parameter tool with no output schema, the description covers the critical invocation concerns: action selection, scope semantics, rule_id usage, mutation boundary, and the mandatory describe step. It does not detail the exact output shape of get/dry_run, but that is not required to 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 80%, and the description adds meaningful semantics on top: it explains how scope filters results, that get/dry_run require rule_id, and that describe returns the valid metric/operator/action-type catalog. The params object and profile_id are not expanded in the description, but the schema already documents them, so the parameter layer is well supported.

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

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

The description opens with a clear, specific declaration: 'V2 rule-based automation, READ-ONLY' and enumerates the supported actions (list, get, dry_run, describe). It also differentiates itself from the mutation counterpart by naming stage_automation_rule, so an agent can immediately understand this tool's scope and resource.

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 that mutations belong in stage_automation_rule, that describe should always be checked before building conditions, and that auto approval mode cannot be set from here. It also explains when to use list scopes and how dry_run differs from get, giving concrete routing and precondition guidance.

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

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

Annotations already establish that this is read-only and non-destructive, lowering the burden on the description. The description adds useful context by listing the exact data fields returned and clarifying what the tool is not about, without contradicting the annotations.

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

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

Two short sentences each earn their place: the first states the resource and its key fields, the second prevents confusion with a closely named sibling. The most important information is front-loaded with no filler.

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

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

For a simple read-only tool with one optional parameter and no output schema, the field list and sibling distinction provide adequate operational context. It could go slightly further by explicitly stating that it returns scheduled task configurations/status, but the current wording is sufficient 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?

Schema description coverage is 100%, and the only parameter, profile_id, is already fully explained in the schema, including its optionality and relation to account_profiles. The description adds no additional parameter-level detail, 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 clearly identifies the resource (scheduled tasks) and enumerates the returned attributes: type, cadence, enabled state, and last/next run times. It also distinguishes itself from automation_activity, though it lacks an explicit verb such as 'list' or 'retrieve'.

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 rules out the automation approval inbox and points to automation_activity as the alternative, which helps prevent a common mis-selection. However, it does not address other schedule-related siblings like automation_recent_tasks or automation_rules, so guidance is partial rather than fully comprehensive.

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

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

The annotations already declare readOnlyHint=true, so the description does not need to cover safety. It adds that results contain 'bought-with pairs and combination shares,' but it does not disclose pagination behavior, how weeks/period affect results, or whether output is aggregated across sellers.

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?

One sentence with no filler. The core behavior and output type are front-loaded, and every word contributes meaning.

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

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

With six parameters and no output schema, the description leaves too much unspecified: whether asin is required, what weeks or period mean, how limit/offset paginate, and what the returned data actually looks like. An agent could discover the tool but cannot confidently configure a correct 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?

Schema coverage is only 17% (only seller_connection_id has a description), so the description needed to compensate by explaining asin, limit, weeks, offset, and period. It only indirectly clarifies asin; the other parameters remain semantically undefined and must be guessed.

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 clear subject ('what customers buy together') and resource ('each ASIN'), and specifies the output concept ('bought-with pairs and combination shares'). It does not explicitly contrast sibling brand_* tools, but the market-basket idea is distinct enough for basic identification.

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?

No guidance is provided on when to use this tool instead of alternatives like brand_repeat_purchase, brand_search_catalog, brand_sqp, or brand_top_search_terms. There are no conditions, prerequisites, or exclusions to help an agent choose 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful context about the metrics and ASIN-level scope, but it does not reveal behavior around omitted parameters, defaults, or that 'week' is only one of several supported periods.

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 compact sentence with no filler. Every phrase contributes meaning: scope, metric type, and time granularity are all 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?

Given six parameters, no required parameters, low schema coverage, and no output schema, the description is too thin. It does not clarify what happens when `asin` is omitted, how `weeks` relates to `period`, or how repeat purchase is operationally defined, leaving too much for the agent to guess.

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

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

Schema description coverage is only 17%, and the description compensates for very little. It implies that `asin` is the grouping dimension and mentions weekly granularity, but it leaves `weeks`, `limit`, `offset`, and the full `period` enum unexplained, and it could even mislead by suggesting only weekly data when MONTH and QUARTER are allowed.

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 clear analytical focus: customer loyalty per ASIN, specifically repeat buyer share and repeat revenue by week. This is concrete enough to distinguish it from sibling brand tools such as brand_market_basket or brand_top_search_terms, though it lacks an explicit verb like 'returns' or 'reports'.

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?

No guidance is given about when to use this tool versus alternatives. There is no mention of exclusions, prerequisites, or related brand tools, so an agent must infer usage from the title and metric names alone.

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

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

The annotations already declare the operation as read-only and non-destructive, covering the safety profile. The description adds useful aggregation context, such as per-ASIN grouping and all-query scope, but does not disclose pagination behavior, time-window handling, or response shape. This is acceptable but not especially rich behavioral disclosure.

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

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

The description is a single dense sentence that front-loads the core resource and scope, followed by the relevant metrics. There is no filler, and every phrase contributes to understanding what the tool returns.

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 six parameters, only 17% schema coverage, and no output schema, the description leaves important invocation details unstated, such as whether asin is required, how weeks and period interact, and what pagination controls do. It is sufficient for a default call but incomplete for confident, varied use.

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

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

Only one of six parameters (seller_connection_id) has a schema description, so schema coverage is only 17%. The description hints that asin selects an ASIN and that no query filter applies, but it does not explain limit, weeks, offset, or period semantics. With such low schema coverage, the description should compensate more than it does.

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 identifies a specific resource: per-ASIN search funnel totals, and enumerates the metrics returned (impressions, clicks, cart adds, purchases, median prices). The 'query-less SQP' note and 'across ALL queries' clarify its scope, though it lacks an explicit verb like 'returns' and does not name the sibling it differs from.

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 phrase 'across ALL queries (query-less SQP)' implies this tool should be used for aggregate, query-less analysis rather than query-level search performance, which helps distinguish it from brand_sqp. However, it does not explicitly state when to use this tool versus alternatives like brand_top_search_terms or brand_sqp, nor does it mention prerequisites 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavioral traits beyond that: the ~2 week data lag, newest-week-first row ordering, the parent_rollup aggregation semantics, and the truncated=false termination condition for paging. This is meaningful operational context that an agent cannot infer from the annotations or schema alone.

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

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

Roughly 50 words carry a high density of information, with the core scope front-loaded ('organic search funnel per (ASIN, query) — impressions/clicks/cart-adds/purchases') before operational details. It is efficient, though it is structured as one long em-dash run-on sentence that slightly reduces scannability.

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 retrieval tool with no output schema, the description covers the essential envelope: data scope, metrics, aggregation mode, time-window semantics, data freshness, ordering, and the pagination loop. Remaining gaps are the interaction between weeks and the period enum, the expected format for asin, and semantics of the three undocumented parameters that appear to exist outside the visible properties.

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

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

With only 22% schema description coverage, the description carries a heavy burden and partially compensates: it explains weeks ('counts back from the LATEST STORED week'), parent_rollup ('aggregates the product family'), and offset (paging until truncated=false). But notable gaps remain: asin, limit, and period (WEEK/MONTH/QUARTER) get no semantic guidance, and the description's 'parent_rollup' naming does not obviously match the schema's 'aggregate' boolean, which could confuse tool selection.

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 specifies a precise resource ('organic search funnel per (ASIN, query)') and the exact metrics returned ('impressions/clicks/cart-adds/purchases with shares'), which clearly distinguishes it from sponsored-search siblings. The main shortfall is that the verb is implicit ('Search Query Performance' is a noun phrase rather than 'Retrieves…'), and no sibling tool is named, though the 'organic' qualifier does most of the differentiation work.

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 strong how-to-use guidance: how weeks are counted ('counts back from the LATEST STORED week'), that data lags ~2 weeks, that rows are newest-week first, and the pagination recipe ('page with offset until truncated=false'). However, it never states when to prefer this tool over alternatives such as ppc_search_terms, ppc_query, or brand_top_search_terms, nor any exclusions — the usage context is implied by 'organic' rather than explicit.

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 destructiveHint=false, so safety is covered. The description adds meaningful behavioral detail beyond annotations: WEEK/MONTH rows read the shared full-marketplace store once populated, and the response carries store=global. This is not derivable from the schema or annotations and helps set expectations about data scope.

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

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

The description is two sentences with the main output front-loaded and the scoping nuance second. It is mostly efficient, though phrases like 'shared full-marketplace store once populated' and 'response carries store=global' are slightly dense and could be simplified without losing meaning.

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

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

There is no output schema, and the description only summarizes return values as ASINs and click/conversion shares. With six parameters, only one of which has schema-level documentation, the description leaves important call-construction details unclear, such as date formats, filter behavior, pagination semantics, and the role of seller_connection_id.

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

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

Schema description coverage is only 33%, and the description does not explain the meaning or usage of limit, offset, week_start_date, search_term_contains, or seller_connection_id. It adds some context about period behavior by distinguishing WEEK/MONTH from DAY rows, but it does not compensate for the low schema coverage across the other parameters.

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

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

The description names a specific resource ('marketplace-wide top search terms'), states the output contents ('top-3 clicked ASINs and their click/conversion shares'), and clearly distinguishes its scope from account-filtered alternatives with 'complete term universe, not just this account's filtered slice.' This makes it easy for an agent to recognize what this tool returns and how it differs from sibling search term tools.

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

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

The description provides clear context for when the tool is appropriate: it returns marketplace-wide data from the shared full-marketplace store, especially for WEEK/MONTH periods. It contrasts with 'not just this account's filtered slice,' helping an agent avoid account-level tools, but it does not explicitly name alternative tools or state precise when-not-to-use 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?

Annotations already convey that this is not read-only and not destructive. The description adds the useful nuance that the proposal is pending and will not be executed, though it does not disclose whether cancellation is reversible or what side effects occur.

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

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

A single sentence with no wasted words. The verb and object are front-loaded, and the 'without executing it' qualifier earns its place by preventing confusion with confirm_staged_changes.

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 one-parameter tool with annotations, the description is mostly sufficient: it names the action, the target, and the key non-execution constraint. It omits alternative routing and post-cancellation behavior, but these are minor gaps for a simple cancel operation.

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 0%, so the description must compensate. It only references 'a pending proposal' and never explains what proposal_id is, where it comes from, or any format expectations beyond the parameter name.

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 ('Cancel') and a specific resource ('a pending proposal'), and adds the clarifying qualifier 'without executing it.' This distinguishes it from sibling tools like confirm_staged_changes that would apply the proposal instead.

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 use case is implied: an agent should call this when a pending proposal needs to be discarded. However, there is no explicit when-to-use guidance, no mention of confirm_staged_changes as the alternative for executing, and no exclusions or prerequisites.

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 destructive, and the description adds meaningful behavior beyond that: it is single-use, expires 60 minutes after propose, and approved_summary is surfaced in the client's permission prompt. It does not elaborate on rollback or post-execution effects, but the annotations plus these details give a solid safety picture.

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: execution trigger, user-consent precondition, approval-summary requirement, partial-approval mechanism, and single-use/expiry. Critical constraints are front-loaded before secondary details, making it easy for an agent to parse and apply.

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 confirmation tool, the description covers the when, the how, and the main edge case (partial approval), and the schema fills in overrides and full-refusal routing. The main gap is the absence of an output schema or any description of what the tool returns after execution, which would help an agent confirm success.

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 description adds real meaning to approved_summary (it appears in the permission prompt, so a bare proposal_id is never enough) and excluded_refs (partial approval mirroring dashboard checkboxes). With 75% schema coverage, the schema already documents overrides clearly; the description's added param context is useful but not exhaustive, leaving proposal_id sourcing implicit.

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 'EXECUTE a pending proposal', a specific verb and resource that immediately distinguishes this final-commit action from sibling tools that create or modify staged proposals. It also encodes the key precondition (user saw the diff and agreed), so the agent understands this is the confirmation step, not a staging or cancel action.

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

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

The description gives an explicit precondition: call 'ONLY after you have rendered the full diff to the user as text' and the user agreed. It also explains partial-approval handling via excluded_refs. However, it doesn't explicitly name cancel_staged_changes as the alternative for a full refusal; that routing appears only in the schema description of excluded_refs, not in the main description.

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 destructiveHint=false, so safety is covered. The description adds useful behavioral context that the tool returns a sample row and column metadata, and that the full dataset list is scoped to what data_query can access. No hidden side effects or contradictions are present.

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

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

Two sentences with no filler. The no-argument case is stated first, the argument case second, and each sentence earns its place by conveying a distinct operational mode. The structure is easy to parse and highly efficient.

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

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

For a simple read-only metadata tool with one optional parameter and no output schema, the description covers all essential information: invocation modes, what each mode returns, and the scope of available datasets. No critical gap remains for an agent to call it correctly.

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

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

Schema coverage is 0%, so the description carries the full burden of explaining the optional dataset_key parameter. It explicitly maps each parameter state to its behavior: absent means list all datasets, present means describe that dataset. This fully compensates for the schema's lack of parameter descriptions.

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

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

The description clearly states the tool's function with a specific verb: list available datasets when no arguments, or describe columns, column descriptions, and a sample row when a dataset_key is provided. It distinguishes itself from data_query by positioning itself as the metadata/schema exploration tool for datasets used by data_query.

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 conditional usage guidance: use without arguments to enumerate datasets, or with dataset_key to inspect schema details. It does not explicitly discuss when not to use it or name alternatives, but the two modes are clearly differentiated and the context is obvious enough for an agent to select it appropriately.

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 read-only and non-destructive behavior, and the description adds meaningful context about what the tool reports: freshness, row counts, date coverage, and backfill progress. It also clarifies how advertising data is scoped via the resolved profile and raw PPC datasets. No contradiction with annotations exists.

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

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

The description is two sentences with no unnecessary filler. The core purpose is front-loaded, followed by the intended use and scope. Every clause earns its place.

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

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

For a read-only metadata tool with two optional, well-documented parameters, the description provides enough context about what data is returned and which dataset families are covered. Since there is no output schema, the description's enumeration of freshness, row counts, date coverage, and backfill progress partially compensates, though a bit more detail on output shape would improve completeness.

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 parameters are already well documented in the input schema. The description adds only a small amount of extra meaning through 'for the resolved profile', which lightly connects to profile_id, but it does not meaningfully expand 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 clearly identifies the resource as per-dataset sync freshness and lists the specific data dimensions returned: row counts, date coverage, and backfill progress. It distinguishes itself from sibling data tools by explicitly covering both seller SP-API datasets and advertising datasets. However, it lacks an explicit verb such as 'retrieve' or 'list', which slightly weakens its action clarity.

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 phrase 'use to caveat answers correctly' gives an explicit intended use case, and the description clarifies the scope across seller and advertising datasets. It does not mention when not to use the tool or name alternative tools, but the use context is clear enough for an agent to select it appropriately.

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 destructiveHint=false, covering safety. The description adds meaningful behavior beyond that: the short-page pagination semantics for full retrieval, the ≤1000 limit, and automatic tenancy enforcement — the latter being a genuine behavioral guarantee an agent needs to know before invoking. 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?

One information-dense sentence that front-loads the core purpose before capabilities, then pagination behavior, then tenancy. Every clause earns its place: no filler, no repetition of schema field names, and the most important scoping fact (generic over any dataset) comes first.

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 10-parameter tool with low schema coverage and no output schema, the description covers the critical invocation decisions: what to query, how to filter, how to paginate, and that tenancy is automatic. The main gaps are the filter object structure, response format (since no output schema exists), and the boundary against ppc_query for PPC-specific needs — but an agent could successfully call this tool from the description alone.

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 only 10% (only seller_connection_id has a description), so the description must compensate — and it largely does. It maps capabilities to parameters: projection (columns), filters with explicit operator list, date bounds (date_from/date_to), ordering (order_by/order_dir), and the ≤1000 bound on limit. The residual gap is the internal shape of the filters objects and exact date formats, which remain undocumented.

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 (query) and resource (any warehouse dataset), and enumerates concrete capabilities: column projection, filter operators (eq/neq/gt/gte/lt/lte/in/contains), date bounds, ordering, and pagination. The word 'generic' distinguishes it from specialized query siblings like ppc_query, and the cross-reference to data_describe orients the agent on dataset discovery.

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 operational guidance: page with offset until a short page returns to retrieve FULL datasets, and mentions the ≤1000 limit. The 'see data_describe' hint routes the agent to the sibling for dataset discovery. However, it does not explicitly say when to prefer specialized siblings (e.g., ppc_query or pnl_* reports) over this generic tool, leaving the exclusion logic implied rather than stated.

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

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

Annotations already mark this read-only and non-destructive, and the description adds substantial behavioral detail: it counts FBA + AWD + inbound + open purchase orders, is lead-time-aware, is explicitly advisory, and directs the agent to repeat quote_rules caveats when presenting numbers. This goes well beyond the annotation baseline.

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

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

The description is dense with useful specifics and contains no filler, but it is packed into a single long sentence with many clauses. It is still understandable and front-loaded, though a two-sentence structure would improve parseability.

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 present, the description enumerates the main output categories: runout dates, reorder-by dates, suggested units, and the advisory affordability view. It also includes an explicit caveat-handling instruction, giving an agent enough context to invoke the tool and interpret results correctly.

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

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

The input schema covers both parameters with descriptions at 100% coverage, so the description does not need to repeat parameter details. It adds a helpful contextual clue about the seller-connection scope but does not materially extend the schema's 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 concrete deliverable: per-ASIN runout dates, lead-time-aware reorder-by dates, suggested units, and a specific affordability view. It also scopes the tool to one seller connection, distinguishing it from broader reporting siblings like forecast_report.

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

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

The description gives clear context: this is a single-seller-connection reorder planning tool with a specific advisory angle. It does not explicitly name alternatives or exclusions, but the scope is stated clearly enough to disambiguate from broader forecasting or inventory tools.

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

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

Annotations already provide readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavior beyond that: the forecast is grounded in stockout-repaired history, recovery is inventory-gated, first month anchors to actual MTD, and the engine runs nightly. This is strong context, though it doesn't fully elaborate on pagination mechanics or output size.

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

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

The description is dense and information-rich, with the core subject front-loaded. Each sentence adds a distinct fact: content, grounding, currency, pagination, and usage caveats. The ALL-CAPS emphasis and slightly breathless pace reduce scannability slightly, but no sentence is wasted.

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

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

For a read-only report with no output schema and nullable parameters, the description covers the essentials: what data is returned, how it is computed, how to paginate, how to scope currency, and what caveats to quote. The only notable gap is the exact shape/format of diagnostics.trend_check and quote_rules, but the description does enough to let an agent 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 only 25%, so the description carries most of the burden. It adds meaning for currency ('One currency per call (EUR spans the EU marketplaces)') and for offset/limit ('Page rows via offset/next_offset'). It does not explicitly explain limit/offset defaults or constraints, but it meaningfully compensates for the sparse 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 a specific resource: 'THE 12-month per-ASIN unit forecast (nightly engine)' and enumerates its contents: brand totals vs last year, seasonality index, diagnostics including trend_check, per-ASIN rows with inventory gate fields, and LOW STOCK flags. This clearly distinguishes it from siblings like forecast_reorder_report and data_query.

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 explicit usage directives: 'One currency per call (EUR spans the EU marketplaces)', 'Page rows via offset/next_offset', 'Monthly grain also queryable via data_query dataset forecast', and 'ALWAYS surface diagnostics.trend_check and quote_rules caveats when quoting numbers.' These are actionable when-to-use and how-to-use instructions, including an alternative path.

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

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

The description adds useful behavioral detail beyond the readOnlyHint annotation: alert_type is derived as OUT_OF_STOCK, LOW_STOCK, or AGED_STOCK when Amazon's restock report has no alert, and alerts_only=true filters to flagged SKUs. There is no contradiction with the annotations.

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

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

The description is a single dense sentence with no filler. The output categories are front-loaded, and the alert derivation/alerts_only nuance is appended efficiently without repeating title or schema information.

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

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

For a read-only report tool, the description covers the major output categories, the derived alert_type, and the alerts_only filter. Pagination behavior is already provided in the schema's offset description. Missing asin/limit semantics and explicit sibling differentiation are the only notable gaps.

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

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

The description adds real meaning for alerts_only by explaining it returns only flagged SKUs, and offset and seller_connection already have schema descriptions. However, asin and limit have no schema descriptions and are not addressed in the description, so with only 40% schema coverage the description only partially compensates for the gaps.

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 (FBA/AWD inventory health) and the core output categories: fulfillable/inbound/reserved units, aged inventory, restock recommendations, and AWD pool per SKU. It lacks an explicit retrieval verb and doesn't position itself against sibling report tools, so it stops short of a perfect 5.

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

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

The description conveys what the tool returns and explains the alerts_only flag, so an agent can infer its use for inventory/replenishment review. However, it does not explicitly state when to use this tool instead of related sibling tools like forecast_reorder_report or forecast_report, and no exclusions are given.

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

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

Annotations only declare readOnlyHint and destructiveHint; the description adds substantial behavioral context beyond them. It explains the three data sources being merged, how seed terms expand to ASINs, the volume_source variants with their calibration levels, the sort order, and the presence of standard pagination, giving a clear model of what the tool does step by step.

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 dense, single-paragraph run-on, but it is front-loaded with the core purpose (reverse-ASIN lookup) before diving into data sources and result semantics. Every clause contributes information, and the length is justified by the tool's complexity, though clearer structure would improve scannability.

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 adequately enumerates the result fields (matched_asins, match_count, volume, volume_source, search_frequency_rank, relevance_score) and sorting behavior. It still leaves gaps around the meaning of weeks and min_match_count and the exact response envelope, but it covers the essential return semantics for an agent to reason about outcomes.

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

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

Schema coverage is only 50%, and the description meaningfully explains the `terms` expansion and hints at offset/limit via 'standard pagination'. However, it does not clarify `limit`, `weeks`, `min_match_count`, or `offset` details, so it only partially compensates for the undocumented parameters.

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: 'every keyword phrase the input ASINs are known for', clearly framing a reverse-ASIN lookup. It distinguishes itself from sibling keyword tools by emphasizing multi-input, merged first-party sources, and competitor ASIN support, so an agent can immediately recognize its unique purpose.

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

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

Usage context is strongly implied by the reverse-ASIN angle and 'works for competitor ASINs', but the description never explicitly states when to choose this over related siblings like brand_sqp, brand_top_search_terms, or ppc_search_terms. There are no exclusions or alternative-routing statements, so an agent must infer the appropriate context.

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

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

Annotations already declare the operation read-only; the description adds the settlement-basis scope and the ordered waterfall stages, which are useful output expectations. It does not explain how multiple seller connections or omitted parameters behave, but the schema partially covers that, so this is adequate-with-gaps.

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 arrow-chain format is extremely compact and front-loaded. The duplicate 'net profit' step ('net profit → expenses → net profit') creates a minor ambiguity, otherwise this would be 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 metric chain is a useful partial return-value description, and the schema covers date defaults and seller_connection_id. However, a tool with this many P&L siblings needs clearer selection context, and currency semantics plus settlement-basis meaning are left unstated.

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 three of four parameters, so the description does not need to restate them. The uncovered currency parameter is never explained, and the tool description contributes no parameter-specific meaning beyond implying settlement-date scope.

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

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

The description names the resource (account) and the type of report (settlement-basis waterfall) and enumerates the metric chain, so it is clear this produces an account-level P&L breakdown. It does not use an explicit verb and does not differentiate itself from siblings such as pnl_summary or pnl_by_asin, but the 'account waterfall' wording is a clear purpose.

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

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

No explicit guidance for when to choose this tool over the many P&L siblings (pnl_summary, pnl_period_cards, pnl_by_asin, pnl_expenses). 'Settlement-basis' is a hint but not a directive, and no alternatives or exclusion conditions are mentioned.

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

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

The annotations already declare readOnlyHint=true and destructiveHint=false, so the tool is known to be safe. The description adds useful context about what the rows contain (sales, units, fees, COGS, margins, TACoS, stock) and the date-window scoping, but does not disclose aggregation behavior, currency handling, or output details.

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 compact sentence that front-loads the core resource and lists the important metrics. There is no filler or redundancy, and each phrase adds value.

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

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

For a six-parameter tool with no output schema and many sibling P&L tools, the description is adequate but not fully complete. It names returned metrics and the main optional filter, but omits group_by aggregation behavior, currency details, and guidance on when to prefer this over other pnl_* tools.

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

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

Schema description coverage is only 50%, so the description needs to compensate. It clarifies the date window and optional single-ASIN filtering, but does not explain group_by or currency semantics. This is partial compensation, not complete.

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 resource ('Per-ASIN P&L rows') and the key metrics included, making it clear this is a product-level profitability read. It does not explicitly differentiate itself from sibling tools like pnl_summary or pnl_breakdown, but the 'Per-ASIN' focus and title 'P&L: By product' give adequate direction.

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 implies usage when per-ASIN P&L data for a date window is needed, and optionally for a single ASIN. It does not explicitly state when not to use it or name alternatives among the many pnl_* siblings, so the guidance is implied rather than explicit.

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 destructiveHint=false, so the safety profile is covered. The description adds that the report covers custom operating expenses and their dimensions, but it does not disclose aggregation behavior, time period, or response format.

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 compact sentence with examples and facets front-loaded, containing no filler. It is slightly telegraphic, but the information density is appropriate for the tool's simplicity.

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?

Adequate for a read-only report with one optional parameter: it names the content area and the facets exposed. However, with no output schema and no mention of default time periods, aggregation, or how seller_connection_id affects results, some interpretation is left to the agent.

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%: the sole optional seller_connection_id is documented in the schema. The tool description does not add parameter-level detail, so the schema carries the burden and the baseline score 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 identifies the exact resource (custom operating expenses) and names representative categories plus the three reported facets: scope, recurrence, and amounts. It lacks an explicit verb but is clearly distinguishable from sibling P&L tools by its operating-expenses focus.

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

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

There is no guidance on when to use this tool instead of alternatives like pnl_summary or pnl_breakdown, and no mention of prerequisites or exclusions. The long sibling list makes the lack of selection criteria a meaningful gap.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false), so the bar is lower. The description adds useful result-content context (which metrics are totaled) but says nothing about return shape, aggregation granularity, currency handling, or pagination, and there is no output schema to compensate.

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

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

A single sentence with the channel scope front-loaded and a compact metric list; every word earns its place. The only weakness is the noun-phrase construction ('totals: ...') which omits an explicit verb, making it read slightly like a label rather than an instruction.

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?

Acceptable for a simple read-only tool with zero required parameters, but there are clear gaps: the currency parameter is undocumented both in the schema and description, no return format is described despite there being no output schema, and no guidance is given for routing to non-MCF P&L tools.

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

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

Schema description coverage is 75%, so the schema documents date_from, date_to, and seller_connection_id competently, including defaults and a pointer to account_sellers. However, the description itself adds no parameter-level meaning and does nothing to document the one uncovered parameter (currency), leaving a real gap.

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

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

The description names the specific resource (Multi-Channel Fulfillment/off-Amazon P&L), the metric set (units, orders, fulfillment fees, COGS), and the time window, which is enough to distinguish it from siblings like pnl_by_asin, pnl_expenses, or pnl_summary. It misses a 5 only because the verb is implicit (the noun 'totals' stands in for 'returns/gets').

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?

No statement of when to use this tool versus alternatives, and no exclusions. With roughly twenty P&L siblings on the same list (pnl_summary, pnl_breakdown, pnl_by_asin, pnl_period_cards, pnl_refunds, pnl_settlement_audit), the agent receives no routing help; the intended scope must be inferred from the name and title alone.

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 destructiveHint=false, so the safety profile is covered. The description adds the period breakdown and the 'mini/dashboard' nature, implying a compact high-level view, but it does not disclose behaviors like data freshness, timezone handling, or how currency affects the cards.

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, tightly packed phrase that front-loads the core concept ('dashboard mini-P&L cards') and lists the periods in parentheses. There is no filler or 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?

For a tool with no output schema and two optional parameters, the description says what periods are covered but omits what each card actually contains (e.g., revenue, profit, margin), how currency or seller_connection_id filter the data, and when to select this over other P&L tools. The large sibling set amplifies this gap.

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

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

Schema description coverage is only 50% (currency has no schema description). The tool description does not explain either parameter or how they influence the results, failing to compensate for the undocumented currency parameter. Only seller_connection_id has schema-level documentation.

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 identifies a specific resource, the dashboard mini-P&L cards, and enumerates the exact periods covered (Today / Yesterday / MTD / This-month forecast / Last month), which helps distinguish it from P&L tools like pnl_summary or pnl_breakdown. However, it lacks an explicit verb such as 'returns' or 'displays,' making the action slightly implicit.

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

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

There is no guidance on when to use this tool versus the many sibling P&L tools. The description does not mention alternatives, exclusions, or decision conditions such as 'use this for the dashboard cards' or 'use pnl_breakdown for detailed analysis.'

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 destructiveHint=false, so the safety profile is covered. The description adds useful context about the returned components (net amount, count, itemized lines) but does not disclose details such as whether itemized lines are always present, how currency is handled, or any aggregation quirks.

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

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

A single, front-loaded sentence that immediately communicates the resource and the main output fields. Every word earns its place, with no filler or repetition 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 read-only, no-required-parameter report, the description is largely sufficient: it names the core returned data and the annotations cover safety. The absence of an output schema is partially mitigated by listing the refund components, though the exact shape of itemized lines remains unspecified.

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 75%, so most parameters are already documented in the schema. The description reinforces the date-window concept, which maps to date_from/date_to, but adds no new meaning for currency or seller_connection_id beyond what the schema provides.

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

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

The description identifies a specific resource — refund components — and lists the key outputs: net refund amount, count, and itemized lines. It is clearly about refunds within a date window, which helps distinguish it from other pnl_* siblings, though it does not explicitly name any alternative.

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

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

The phrase 'for a window' implies date-range usage, and the title signals this is a refund detail report. However, there is no guidance on when to choose this over closely related siblings like pnl_breakdown, pnl_summary, or pnl_settlement_audit, and no exclusions or prerequisites are stated.

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

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

The annotations already provide readOnlyHint=true and destructiveHint=false, so the description's behavioral burden is reduced. It usefully adds that the calculation is a sales-weighted split of campaign-level SB spend, which is a meaningful methodology detail. It does not disclose output granularity, zero-attribution handling, or currency behavior, but these are less critical for a safe read-only tool.

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

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

The description is a single concise sentence that introduces the core concept and immediately adds the key methodological qualifier in parentheses. Every word earns its place, and the most important scoping information 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 simple read-only attribution tool with optional parameters, the description is largely sufficient. It clearly defines the result: per-ASIN SB cost attribution. It omits the expected output shape and potential edge cases like whether ASINs with zero attributed spend are included, and no output schema exists to pick up that slack.

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 date_from, date_to, and seller_connection_id, so 3 of 4 parameters have coverage. The description itself adds no parameter-level guidance, and the currency parameter's meaning remains undocumented. Since all parameters are optional and defaults are specified in the schema, the description does not need to compensate heavily.

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 concrete deliverable: per-ASIN Sponsored Brands cost attribution, with the clarifying detail that it is the sales-weighted split of campaign-level SB spend. Although there is no explicit verb like 'computes' or 'returns', the noun phrase is unambiguous. It is distinguishable from generic P&L/PPC siblings by naming Sponsored Brands, per-ASIN scope, and the attribution methodology.

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 intended use is implied: an agent would call this when it needs Sponsored Brands campaign spend allocated to individual ASINs. However, there is no explicit when-to-use or when-not-to-use guidance, and no alternative tool is named. Among a large sibling set, the agent must infer routing purely from the description.

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 read-only and non-destructive, and the description aligns with them. The description adds useful behavioral detail: it enumerates every distinct fee combination and classifies them, which conveys the result shape beyond just 'audit'. It does not detail output formatting, but the safety profile is already covered by 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 front-loaded sentence with no filler. It states the tool name, the action, the scope, and the purpose efficiently.

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 zero required parameters, the description provides enough context to understand what it returns and why it exists. The missing currency semantics and lack of alternative routing are gaps, but the schema partially covers seller_connection_id and the annotations cover safety.

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 only 50%: seller_connection_id has a description, but currency is undocumented. The description does not mention either parameter or explain acceptable currency values, defaults, or how the two parameters affect the audit. Since the description does not compensate for the schema gap, this dimension is weak.

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

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

The description names a specific verb ('audit') and resource ('settlement fee') and clarifies the exact scope: every distinct fee combination Amazon charged, classified into P&L buckets. This clearly distinguishes it from generic P&L summary or breakdown tools.

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

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

The phrase 'verify nothing is misclassified or missed' implies an audit use case, which gives some usage context. However, it does not explicitly state when to prefer this tool over siblings like pnl_expenses or pnl_breakdown, nor any exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only nature is covered. The description adds what the user will see, but it doesn't disclose sorting, grouping, or whether the summary is account-wide versus per seller connection. That is acceptable but not rich.

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?

One compact sentence, front-loaded with the resource and scope, and it lists concrete metrics instead of generic marketing language. No wasted words, though it is too brief to carry the missing parameter semantics.

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 six parameters, no output schema, and many closely related pnl_* siblings, a correct invocation depends on knowing what top_n, group_by, and currency do; the description doesn't provide that. A zero-argument default call is easy, but any deliberate parameter choice is under-specified.

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 date_from, date_to, and seller_connection_id, leaving top_n, currency, and group_by undocumented except for types/enum. The description repeats the date-window idea and mentions 'top product rows,' but it does not explain top_n, currency, or group_by, so it fails to compensate for the 50% schema coverage gap.

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

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

The description names the resource (P&L summary), the scope (date window), and the contents (account tiles plus top product rows), which is enough to understand what the tool returns. It does not explicitly contrast with pnl_breakdown or pnl_by_asin, so it earns a 4 rather than a 5.

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

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

No statement of when to use this summary over pnl_breakdown, pnl_period_cards, or pnl_by_asin; the 'date window' phrase only implies a time-based report. There are no exclusions or alternative tools named, so the agent cannot decide among the many pnl_* siblings from the description.

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 destructiveHint=false, so the safety profile is covered at a low bar. The description adds the metric list and account-level scope but discloses no further behavioral traits such as how aggregates are computed, profile-selection behavior with multiple tokens, or handling of date ranges with no data.

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

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

A single 17-word sentence with the verb and scope front-loaded ahead of the metric enumeration. Every word carries information; there is no filler or repetition 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?

The metric enumeration partially substitutes for a missing output schema, and annotations cover safety. However, with 0 required parameters and three undocumented date/profile parameters, the description leaves ambiguity about the minimum viable call (are start/end dates required? what does period_days do?) that an agent must resolve elsewhere.

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

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

Schema description coverage is only 25% — only profile_id is documented in the schema, and its description already covers its semantics. The description's 'for a date range' loosely maps to start_date/end_date/period_days but does not explain their formats or relationship (e.g., whether period_days substitutes for start/end dates), so it fails to compensate for the three undocumented parameters.

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 ('Get') and resource ('account-level aggregate metrics for a date range') and enumerates the exact metrics returned: total spend, sales, ACoS, ROAS, clicks, impressions, purchases. The 'account-level aggregate' qualifier distinguishes it from sibling tools at campaign, ad group, keyword, and daily-trend granularity (ppc_campaigns, ppc_ad_groups, ppc_daily_trend).

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 no guidance on when to use this tool versus alternatives — it never names a sibling or states when NOT to use it. In a sibling set of ~70 PPC tools (ppc_campaign_details, ppc_daily_trend, ppc_period_comparison, ppc_query), an agent gets no routing help beyond the implicit 'account-level' hint.

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 destructiveHint=false, and the description adds useful behavioral context: results are sorted by spend, and the specific metrics returned are enumerated. This goes beyond what the annotations alone convey without contradicting them.

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

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

The description is compact and front-loaded with the core purpose, then efficiently lists the returned metrics and supported filter dimensions. Every sentence contributes useful information with no filler or repetition 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 19-parameter tool with no output schema, the description lists the return metrics and main filters, but it omits important invocation context such as date-range handling, pagination behavior, and how SKU/ASIN/parent scoping filters interact. The undocumented date parameters are not addressed in the description.

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 84%, so the schema already documents most parameters. The description summarizes filter categories but does not add meaningful detail beyond the schema, and it does not compensate for the undocumented date parameters (start_date, end_date, period_days).

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

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

The description clearly states the specific resource ('ad group performance data within campaigns') and the action ('Query'), and lists the returned metrics and sorting behavior. It doesn't explicitly differentiate from sibling PPC tools by name, but the scope is specific enough to distinguish it from campaign-level or keyword-level tools.

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

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

The description implies the tool is for ad-group-level performance queries and mentions supported filters, but it provides no explicit guidance on when to choose this over siblings like ppc_campaigns, ppc_campaign_details, or ppc_keywords. No exclusions or alternative routing are given.

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 destructiveHint=false, so safety is covered. The description adds some transparency by revealing the output is aggregate metrics per ad type and includes campaign count, but it does not mention behaviors like date-range handling, grouping logic, or whether data is limited to a single profile.

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

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

Two sentences with no filler. The first sentence states the core function, and the second adds the key output detail. Every word earns its place.

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

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

For a tool with four parameters, no output schema, and only 25% schema description coverage, the description is too thin. It explains what is returned but not how the parameters shape the query, how date ranges are interpreted, or whether the result is limited to a single profile. An agent would need to guess or make an extra call to understand basic usage.

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

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

Schema description coverage is only 25%, with profile_id the only documented parameter. The description does not compensate by explaining start_date, end_date, or period_days, nor does it mention how date inputs affect the comparison. An agent must infer parameter semantics from names alone, which is insufficient given the low 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 opens with a specific verb and resource: 'Get performance comparison across ad types (SP vs SB vs SD).' It clearly names the three ad types, which distinguishes it from related breakdown tools like ppc_match_type_breakdown, and states what is returned: aggregate metrics including campaign count.

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 makes it clear this tool is for ad-type-level performance comparison, but it does not explicitly say when to prefer it over related tools such as ppc_match_type_breakdown or ppc_campaign_details, nor does it state any exclusions or prerequisites. Usage context is implied rather than spelled out.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: the SP+SD vs SB asymmetry (SB per-ASIN spend exists only in blended P&L), the sorting by spend, status classification, and the family_totals aggregation behavior. This is a meaningful addition, though it doesn't detail pagination or error cases.

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 sentence states the core query and data grain, second explains the return sorting and status classification, third covers input modes and family_totals. Every sentence earns its place with no filler, and the most important scoping information 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 read-only tool with 10 optional parameters and no output schema, the description gives sufficient context to invoke it correctly: supported lookup modes, the family aggregation path, the unique SB data limitation, and status classification. It could mention pagination behavior (offset/next_offset) explicitly, but the schema provides parameter hints and the core usage scenarios are well covered.

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

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

Schema coverage is 70%, so the schema documents most parameters. The description adds conceptual meaning beyond the schema by explaining the relationship between asins and family_totals, and notes that profile_id is optional when the token has exactly one. It also clarifies that SB per-ASIN spend is only in blended P&L, which affects interpretation of results. Some uncovered parameters (start_date, end_date, period_days, offset) lack detailed semantics, but the description's added context compensates well.

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 states a specific verb ('Query') and resource ('product/ASIN-level performance'), and distinguishes itself by noting the SP+SD/SB grain and the per-program split. It also contrasts with family aggregation via sibling ppc_product_family, helping an agent tell it apart from other ppc_* tools.

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

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

Provides explicit guidance on when to use single ASIN vs multiple ASINs vs SKU lookup, and references sibling tool ppc_product_family as a source for child ASINs. It also states the status classification behavior and the family_totals return when multiple ASINs are supplied, giving clear context for selection.

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 destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: the link expires in 1 hour, chat attachments cannot reach the server, file type/size limits, the upload_url/staged_file_id flow, and the video-size exception. 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 compact yet information-dense, with the core purpose front-loaded, then a flow, constraints, and an exception. Every sentence earns its place and there is no redundant 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?

Even without an output schema, the description names the key returned artifacts (upload_url and staged_file_id) and gives the complete handoff flow. It could be slightly more explicit about the exact response shape, but for a low-complexity tool the provided context is sufficient.

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

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

The single optional parameter profile_id is already fully described in the schema (100% coverage). The description adds no additional parameter-level detail, but because the schema carries the full burden, a baseline score 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 opens with a specific verb and resource: 'Mint a 1-hour browser-upload link.' It clearly distinguishes this tool from chat attachments and downstream stage_asset_upload, so an agent can understand exactly what action is being performed and why.

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

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

The description provides a clear step-by-step flow and states when this tool is appropriate (local file handover) versus when it is not (videos over 100MB must use a public URL). It does not explicitly name an alternative sibling tool for the public-URL case, so it slightly misses a fully explicit when-not-to-use comparison.

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 it read-only and non-destructive, and the description adds real behavioral detail: SB results are [range_start, range_end] with range_start as effective CPC floor; SP covers manual keywords and auto targeting groups; unsupported campaign types produce a warning; and the underlying reason is disclosed (no vCPM bid-rec API). This exceeds what structured fields alone convey.

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

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

The description is dense but every sentence earns its place: core purpose, SB/SP behavior, usage timing, and vCPM exception are each covered without dangling filler. Key constraints like 'NOT valid for' and 'needs ad_group_id' are front-loaded or highlighted.

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, the description covers a lot: return format for SB, warning behavior, valid/invalid campaign types, and SP targeting inputs. The main gap is ad_format, an undocumented enum that is not mentioned in the description, leaving the agent to guess how it applies. Otherwise the tool is well-specified.

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 description adds meaning for auto_targets by listing the four targeting groups, explains ad_group_id's conditional requirement, and clarifies that keywords refer to manual keywords. However, ad_format remains undocumented in both the schema and the description, and its role in SB productCollection/video vs SP is not explained. That keeps this from being a 5.

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: 'Amazon's suggested bid + range per keyword for a SPECIFIC campaign', and immediately distinguishes SB vs SP behavior. It makes clear this is a bid-recommendation retrieval tool, not a general campaign report or budget tool, and differentiates it from alternatives by routing campaign types.

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 'Check this BEFORE choosing bids', which tells the agent when to call it. It also explicitly states what it is NOT valid for (BRAND_IMPRESSION_SHARE/vCPM campaigns) and names the alternative round-trip pattern via KEYWORD_INVALID_BID. The ad_group_id condition is also provided as a usage rule.

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

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

Annotations already establish readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral detail beyond annotations: the exact threshold calculation, default threshold of 90%, and the conditional enrichment from Amazon's live budgetUsagePercent snapshot '(when available)'.

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

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

Two sentences with no filler: the first states the purpose and selection rule, the second explains the enrichment and points to the full-history alternative. The most important information 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 read-only tool with all parameters optional and output schema absent, the description conveys the core invocation semantics, default threshold, enrichment field, and where to get detailed history. Minor ambiguity remains around how start_date/end_date interact with period_days and average daily spend, but the defaults and optionality make successful invocation likely.

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 60%; the description clarifies threshold semantics ('default 90%') but not start_date/end_date semantics. threshold_pct gets useful meaning from the description, while period_days and profile_id are already covered in the schema. The uncompensated date parameters keep this at a mid score.

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 opens with a precise verb and resource: 'Find campaigns approaching or exceeding their daily budget.' It also specifies the selection rule (average daily spend >= threshold) and the enrichment field, making the tool's purpose unmistakable and distinct from generic campaign-list or search 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?

The description gives clear when-to-use context: budget alerts based on utilization threshold. It also points to an alternative for fuller data ('Full per-day usage history: ppc_query dataset budget_usage'), which helps an agent choose between snapshot alerts and detailed history, though it stops short of explicit exclusion wording.

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 read-only and non-destructive, and the description aligns with that. It adds useful behavioral context by describing its role as a pre-creation contract and listing lifecycle/safety topics, beyond what annotations convey.

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

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

Two sentences deliver strong signal: the tool's role, content scope, and exact invocation trigger. The imperative call-to-action is front-loaded, and there is no filler.

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

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

For a zero-parameter, read-only guide with no output schema, the description fully covers what the agent needs: what the tool is, what it contains, and when to call it. No important operational gap remains.

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

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

The tool has zero parameters and schema coverage is vacuously 100%, so parameter-level explanation is unnecessary. Baseline 4 applies; the description's content focus is appropriate for a guide tool.

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

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

Description clearly defines this as the verified contract/guide for creating campaigns via stage_campaign_create, enumerating the exact content areas it covers. It distinguishes itself from stage_campaign_create and other PPC tools by positioning itself as the prerequisite reference guide.

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 instructs the agent when to use it: 'CALL THIS FIRST whenever the user asks to create an SB campaign.' It also names the dependent operation (stage_campaign_create), making the workflow ordering unambiguous.

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

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

With no annotations, the description carries the full burden and does substantial work: it discloses grain differences (advertised_asins as current entity-synced state, product_ads per-ad, asins_served_in_window as report view), notes never-served ads, and flags source terminology. It omits response format and rate-limit details, but the key behavioral nuances are surfaced.

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

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

Two sentences, zero filler. The primary purpose is front-loaded, followed by a dense GRAIN clarification that earns its place, and the workflow statement closes efficiently. No information is repeated.

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 and several non-obvious semantics, the description covers the critical distinctions that would trip up an agent: what each data grain means, the SP-only limitation, and the intended sequencing after ppc_campaigns. It doesn't describe response shape or error behavior, but the most decision-relevant context is present.

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 only 40% (only profile_id is described in-schema). The description adds meaning for the date range via 'asins_served_in_window ... scoped to the requested range' and for campaign_ids via 'specific SP campaigns', but it does not explain date formats, optionality, or how the parameters map to the listed output categories. It partially compensates for the low schema coverage but leaves gaps.

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

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

The description states a specific verb+resource ('Get detailed data for specific SP campaigns') and enumerates the payload types (placements, advertised ASINs, placement modifiers, top keywords/targets). It also distinguishes itself from SB/SD tools and explicitly positions itself relative to ppc_campaigns ('drill in'), making sibling differentiation 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?

It gives a clear workflow cue ('Use this after ppc_campaigns to drill in') and an explicit exclusion ('SP only — SB/SD campaigns come back under notes with the right dataset to query'). It does not name the specific alternative tools for the SB/SD cases, so it is short of a full when/when-not matrix.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the read-only safety profile is covered. The description adds content-level context about what metadata is returned, but it does not disclose behavior beyond that, such as whether it returns a single campaign's metadata or how profile scoping works.

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 compact sentence that front-loads the resource name and uses a concise list of returned fields. It is efficient, though the missing verb makes it read more like a title than a clear instruction.

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 low-complexity read-only tool, the description is serviceable and lists key returned content. However, it leaves campaign_id semantics unspecified and does not clarify how this tool differs from the many sibling PPC tools, so an agent might not reliably select it.

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

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

The schema describes profile_id but leaves campaign_id completely undocumented, and the description does not mention either parameter. With only 50% schema description coverage, the description should compensate by explaining what campaign_id means or whether it is required, which it fails to do.

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 identifies the resource (campaign metadata) and enumerates specific content areas (bidding strategy, placement settings, goal/KPI, tags, notes), making the tool's purpose fairly clear. However, it uses a noun phrase rather than an explicit verb and does not distinguish it from sibling tools like ppc_campaign_details or ppc_campaigns.

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 implies when to use the tool: when the agent needs campaign configuration and user metadata. It provides no explicit alternatives, exclusions, or conditions such as 'use ppc_campaign_details for performance metrics instead.'

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

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

Annotations already report readOnlyHint=true and destructiveHint=false. The description adds meaningful behavioral context beyond that: default sort by spend descending, returned metrics, and the crucial rule that threshold queries must use min/max filters rather than relying on sorted output.

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

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

The description is compact and front-loaded, with the core purpose stated first and the critical usage warning placed at the end. Every sentence contributes necessary information 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?

For a tool with 24 optional parameters and no output schema, the description provides a solid overview of return values and key usage behavior. It relies on the schema for parameter details, which is appropriate given the 100% schema coverage.

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 every parameter. The description reinforces the threshold-filter concept but does not add meaningfully beyond the schema's per-parameter descriptions.

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

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

The description clearly states the tool queries campaign performance data and lists the returned metrics, with filtering mentioned. However, it does not explicitly distinguish this from close siblings like ppc_campaign_search or ppc_campaign_details.

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 context is clear: this is for querying campaign performance data with optional filters. The IMPORTANT note gives concrete parameter-usage guidance for threshold queries, but it does not contrast this tool with alternatives.

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

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

The annotations already establish readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context by disclosing the exact return scope: campaign names and IDs only, with no metrics. This is especially valuable because there is no output schema to communicate the return shape.

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

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

Two sentences, tightly packed with the core behavior, return scope, and usage intent. The key differentiator ('no metrics') is front-loaded, and every sentence earns its place without 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?

For a simple lookup tool with strong read-only annotations, the description covers the essential return values and the intended workflow. It does not mention pagination, result limits, or how ad_type filtering interacts with results, but given the schema covers parameters well and the tool is deliberately lightweight, the definition is largely complete.

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

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

Schema description coverage is 67%, with name_contains and profile_id already explained in the input schema; the ad_type enum is self-documenting to some degree. The description reinforces the search-by-name behavior but does not add significant new parameter 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?

The description clearly identifies this as a lightweight campaign name lookup that returns only campaign names and IDs, explicitly stating it excludes metrics. This distinguishes it from metric-heavy sibling tools like ppc_campaign_details or ppc_campaigns, and the stated goal of finding campaign IDs before calling other tools gives immediate purpose clarity.

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: use this tool to find campaign IDs before calling other tools. It also implicitly excludes metric-related use cases by saying 'no metrics.' However, it does not explicitly name an alternative tool or state when not to use it, so it falls just short of full alternative/exclusion guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is handled. The description adds output-content transparency (old values, new values, timestamps) but discloses no behavioral limits such as how 'recent' is defined, default time windows, or whether history coverage is restricted. 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?

Two sentences with no filler: the first front-loads the action and return contract, the second adds filter-relevant coverage. Every clause earns its place and provides information beyond 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?

Moderate-to-high complexity (9 optional parameters, no output schema, no enums, no required fields) with no defaults explained. The description conveys the core return concept but not how period_days interacts with start_date/end_date, what the default time window is, or how next_offset pagination behaves. Sufficient for a basic call, gappy for a precise one.

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 covers 5 of 9 parameters (56%); the description partially compensates by enumerating covered change types (bid, budget, status), which hints at values for field/change_type. However, start_date, end_date, period_days, and campaign_name_contains receive no meaning in either the schema or the description, leaving date-window semantics unexplained for a history tool.

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

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

States a specific verb ('Get') and resource ('recent campaign change history'), and specifies the return contract ('what changed, when, old values, and new values'). The history-with-old/new-values semantics clearly distinguish it from current-state siblings like ppc_campaign_details and ppc_campaign_metadata, even without naming them.

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

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

The use case (auditing what changed in campaigns) is implied by the wording, but there is no explicit when-to-use guidance, no exclusions, and no named alternatives. In a sibling set of roughly 90 tools, an agent gets no routing help beyond the implicit history-vs-state distinction.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds the specific funnel stages and rate calculations, which is useful. However, it does not clarify aggregation behavior, date handling, or how scope parameters affect results, and there is no output schema to compensate.

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, front-loaded sentence that communicates the core function, the funnel stages, and a primary use case without wasted words. Every element earns its place.

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

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

With 11 parameters, no output schema, and many closely related sibling tools, this description is too thin to fully orient an agent. It explains what the funnel contains but not how the parameters shape the result, what time range is used, or when a different PPC tool would be more appropriate.

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 description provides no parameter-level guidance. Schema coverage is 64%, meaning several parameters lack descriptions, and the description does not compensate for the gap. For example, it does not mention date range, ad type, or scoping semantics beyond the high-level funnel concept.

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

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

The description states a specific verb and resource: 'Get conversion funnel data' and clearly defines the resource as a funnel from Impressions to Clicks to Orders with conversion rates. This is more specific than the title alone, though it does not explicitly differentiate itself from sibling PPC analytics tools.

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

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

The description gives a usage context: 'Useful for health check analysis.' This implies when the tool is relevant, but it does not provide explicit guidance on when to choose this tool over alternatives such as ppc_daily_trend, ppc_period_comparison, or ppc_query.

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 and destructiveHint=false, lowering the burden. The description adds meaningful context by specifying the ad-grain fields returned and the effect of include_assets=true on asset-library inventory.

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?

Single sentence, front-loaded with tool scope and followed by a concrete flag behavior; no filler. The parenthetical field list is dense but compact enough to stay readable.

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 retrieval tool, the description conveys the data grain, included fields, and the optional include_assets behavior, which is enough to call it correctly. It does not detail response shape, pagination, or default behavior when include_assets is absent, but annotations cover the safety profile and no output schema is declared.

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 description directly explains include_assets and, by listing SB and SD creatives, hints at creative_type values. profile_id already has a schema description, but campaign_id and creative_type remain undocumented in both schema and description, leaving roughly half the parameters without added meaning.

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 identifies the tool as returning SB ad creatives at ad grain with a detailed field list, plus SD creatives, which distinguishes it from sibling tools like ppc_campaigns and ppc_ad_groups. However, it omits an explicit verb such as 'lists' or 'returns', relying on title and fragmentary phrasing.

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 implies this is the creative-level tool ('SB ad creatives at ad grain... plus SD creatives') and notes the include_assets toggle, giving an agent context for when to call it. It does not explicitly name alternatives or exclusion conditions, so usage routing depends on inference from the tool name and sibling set.

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