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

The description adds value beyond annotations by disclosing parallel fetching, leaderboard ranking, and non-blocking error handling. No contradiction with annotations (readOnly, idempotent). This fills gaps that annotations alone do not cover.

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

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

Two well-structured sentences: first states core functionality, second adds critical fault-tolerance behavior. No redundant 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?

Given no output schema, the description sufficiently hints at return format (leaderboard with errors). All six parameters are covered in schema; description adds behavioral context (parallel, non-blocking). Complete for its complexity level.

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

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

Schema coverage is 100%, and the description does not add new meaning beyond what schema descriptions already provide. The mention of 'chosen metric' is echoing the sort_by enum. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Fetches') and resource ('per-domain performance'), and highlights the unique parallel leaderboard aspect, clearly distinguishing it from siblings like grips_get_domain_performance (single domain) and grips_get_daily_performance (daily 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 implies usage for comparing multiple domains side-by-side, and the fault-tolerance note ('one thin or unknown domain won't block') provides context. However, it does not explicitly state when to avoid this tool or suggest alternatives.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds context on the output format (monthly timeseries + roll-up), which complements the annotations without contradiction.

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

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

Two sentences, front-loading the return value and purpose. Every sentence adds value, with no redundancy or fluff.

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

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

Given the well-documented schema and annotations, the description covers the essential context: what data is returned and in what structure (monthly timeseries + roll-up). Could briefly mention pagination or limitations but overall 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 100%, so the schema already documents all parameters. The description adds general context about the return values but does not provide additional parameter-specific semantics beyond what the schema offers.

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 returns paid-media spend, ad clicks, and CPC for domains as monthly timeseries plus a roll-up. It distinguishes itself from sibling tools by specifying the exact metrics and output structure.

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 lists use cases: evaluating paid-spend trends, auction-cost inflation, or total investment. Does not include when-not-to-use or mention alternatives, but the guidance is clear enough for an agent.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds that the response includes a monthly timeseries and an aggregated roll-up, which provides useful behavioral context beyond annotations.

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

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

Three sentences effectively convey the output, use cases, and response structure. Every sentence adds value, with no redundancy or fluff.

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

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

Given the rich annotations (readOnly, idempotent) and the detailed explanation of the response structure (monthly timeseries + roll-up), the description is largely complete for a read-only aggregate report. No output schema exists but the description covers the important aspects.

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

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

Schema description coverage is 100%, so every parameter is already documented. The description does not add significant new meaning for parameters beyond what the schema provides, meeting the baseline for high coverage.

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

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

The description explicitly states the tool returns revenue, sessions, transactions, CR, and AOV broken out by marketing channel for one or more domains, listing specific channels. It also provides use cases, clearly distinguishing it from sibling tools like grips_get_devices or grips_get_daily_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 advises when to use the tool (understand channel mix, evaluate paid-vs-organic balance, spot channel shift) but does not explicitly mention when not to use it or provide alternatives among siblings. This is clear context for use, but lacks explicit 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 provide safety and idempotency hints. The description adds value by noting the default format (markdown) and the empty result behavior for smaller domains, but doesn't cover auth or rate limits. Burden partially shared with annotations.

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

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

Three concise sentences, front-loaded with the main action, followed by use cases and a critical caveat. No wasted words.

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

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

Despite lacking an output schema, the description adequately explains the return shape (daily timeseries of specific metrics) and important caveats (empty results). For a straightforward time-series tool, 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 covers all 5 parameters with 100% coverage, so baseline is 3. The description adds minimal extra meaning beyond the schema, such as implying daily granularity and the empty result hint, but does not significantly enhance parameter understanding.

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 states the tool returns a daily timeseries of revenue, transactions, and sessions for one or more domains, with specific use cases (spike/dip detection, promo windows, day-of-week patterns). It distinguishes from siblings like grips_get_domain_performance (likely aggregate) and grips_compare_domains (comparison).

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 use cases and notes data availability limitations ('smaller sites often return empty'), but does not name alternative tools for exclusion. The context helps an agent decide when to use this tool.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds specific metrics returned (revenue, sessions, etc.) and the aggregation over a date window, which extends 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 two sentences with no wasted words. The first sentence states functionality, the second provides usage context.

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 tool lacks an output schema, but the description lists the key metrics. No mention of pagination or date range limits, but overall it is sufficiently complete for a read-only data retrieval tool.

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

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

Schema coverage is 100% with descriptions for all 5 parameters. The description does not add new parameter details beyond the schema, so it meets the baseline.

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

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

The description clearly states it returns device-level metrics (revenue, sessions, transactions, CR, AOV) for domains over a date window, and explicitly says 'Use this to understand where a competitor's traffic and conversions come from', which distinguishes it from siblings like grips_get_domain_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 provides clear when-to-use guidance ('Use this to understand where a competitor's traffic...') but does not explicitly mention when not to use or list alternative 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, destructiveHint, idempotentHint, and openWorldHint, covering safety and idempotency. The description adds useful context about default output format ('Default to markdown output; pass format='json' for structured data') and the metrics included. No contradictions with annotations, but no additional behavioral specifics (e.g., rate limits, data source constraints) are provided.

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 concise two sentences: the first defines core functionality, the second provides usage examples and a format option. No unnecessary words, front-loaded with key information, and each sentence serves a purpose. Ideal brevity for an AI agent.

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

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

With 100% schema coverage, rich annotations, and no output schema, the description covers the key aspects: what metrics are returned, how to query (examples), and format options. It does not detail the JSON response structure, but that is acceptable without an output schema. The tool is relatively simple, and the description is sufficient for effective 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?

Input schema has 100% description coverage, with each parameter already well-documented (e.g., domains stripping protocol, date format, country enum). The description adds minimal extra meaning—only the format parameter hint about human-readable vs. machine-parseable output is slightly beyond the schema's 'description'. Baseline 3 is appropriate given the schema's thoroughness.

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 returns a monthly timeseries of key e-commerce metrics (revenue, sessions, etc.) for one or more domains over a date range. Examples of natural language queries are provided, and the title includes 'monthly' to distinguish from daily granularity. The purpose is specific and unambiguous.

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

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

The description offers concrete usage examples ('how did adidas.com perform in Q1 2024', 'compare nike.com and puma.com session volume YoY'), which help the agent understand when to invoke this tool. However, it does not explicitly mention when not to use it (e.g., for daily data should use grips_get_daily_performance) or compare with 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, destructiveHint=false, idempotentHint=true, so no behavioral surprises. The description adds that the response is returned verbatim with no formatting, which is useful beyond annotations.

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

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

Three sentences, each serving a distinct purpose: what it does, when to use, and what to expect. No filler, well-organized.

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

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

Given no output schema, the description explains the raw JSON response and the user's responsibility for parsing. It also provides a link for further schema details. Covers all necessary aspects for an escape hatch tool.

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

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

Schema coverage is 100%, but the description adds valuable context: it explains that 'query' is a Grips-flavored GraphQL-like string with a link to the schema, and that 'variables' often expects filters with domain, date, and country. This goes beyond the schema.

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

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

The description clearly states it sends an arbitrary Grips query and returns raw JSON, and explicitly distinguishes from sibling tools by positioning itself as an escape hatch when purpose-built tools don't suffice.

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 'use this only when the purpose-built tools... don't cover what you need', providing clear when-to-use and when-not-to-use guidance, and mentions that the user is responsible for parsing the response.

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