StoreMetrics

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

The description adds no behavioral context beyond the readOnlyHint annotation. It does not disclose default dimension behavior, output format, or any limitations, all of which would be useful for a reporting 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?

A single, front-loaded sentence that states the core functionality without unnecessary words. Perfectly concise.

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 schema covers parameters well and annotations indicate read-only, the description is minimally adequate. However, without an output schema, the agent may not understand the response structure, and no guidance is given on default behavior when 'dimension' is omitted.

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 maps the 'dimension' parameter to its semantic options (device, browser, OS), providing mild clarification beyond the schema enum. However, with 75% schema coverage, the additional value is limited.

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: 'Visitor breakdown by device, browser, or operating system.' This uses a specific verb ('breakdown') and resource ('visitor') while distinguishing it from siblings like get_geo (geographic) and get_traffic_sources (sources).

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 use cases by listing dimensions, but it does not provide explicit guidance on when to use this tool versus alternatives. There is no mention of when not to use it or any contrast with 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?

The readOnlyHint annotation already signals safety. The description adds valuable context by stating that the response includes a definitions field explaining metric counting, which goes beyond the annotation.

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

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

The description is concise and front-loaded, with the primary purpose stated first and a useful note about the definitions field second. 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 simple read-only tool with two fully described parameters and no output schema, the description adequately covers the core functionality and response characteristics. The schema fills in remaining parameter details.

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 provides 100% coverage with descriptions for both parameters (site and range). The description adds no additional parameter-level detail, so 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 clearly identifies the tool as delivering the site's conversion funnel stages with per-stage conversion and drop-off. This is a specific, unambiguous resource that distinguishes it from sibling tools like get_overview or get_audience.

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 use case clear: when you need conversion funnel data. It does not explicitly list alternatives or exclusions, but the context is well-defined and easily understood.

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 annotation readOnlyHint=true already indicates a safe read operation, lowering the burden. The description adds that breakdown is by geographic levels, but it doesn't mention return format, pagination, or the need for a site parameter. These are partly covered by schema, so the description adds minimal behavioral context beyond the annotation.

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

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

The description is a single concise sentence of eight words, front-loading the core purpose. There is zero redundancy or filler, making it easy for an agent to parse quickly.

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 simple read-only nature and a fairly informative schema, the description is adequate but minimal. It lacks explicit usage comparison with siblings and does not describe the expected output structure, especially since there is no output schema. The description covers the essential purpose but leaves some gap for decision-making.

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% (site, limit, range have descriptions), so the baseline is 3. The description only repeats the enum values for dimension without adding extra meaning. It doesn't explain parameter dependencies or defaults 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 clearly states the tool's function: 'Visitor breakdown by geography' and lists the available dimensions (country, region, or city). This specific verb+resource+scope distinguishes it from sibling tools like get_traffic_sources or get_pages, making the purpose unambiguous.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention whether to prefer this over get_traffic_sources or get_audience, nor does it state any exclusions. The only implicit hint is the name and dimension list, which is insufficient for a tool with many 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, so safety is covered. The description adds useful behavioral context: it returns active visitors and recent events, and it ignores the range parameter, making the tool's real-time nature explicit. This goes beyond the annotation without contradicting it.

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 concise sentences, front-loaded with the core concept ('Real-time snapshot') and free of fluff. Every word contributes meaning, making it 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 one-parameter, read-only tool with no output schema, the description covers the essential behavior: what it returns, its real-time nature, and its range-ignoring behavior. It doesn't detail response formatting, but that isn't critical for this type of 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% for the single 'site' parameter, which is clearly described as 'Site handle from list_sites.' The description doesn't add further parameter detail, but the baseline 3 applies because the schema already fully documents the parameter.

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

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

The description clearly states a specific verb+resource: real-time snapshot of active visitors and recent events. It distinguishes itself from sibling tools by explicitly noting 'Ignores range,' which separates it from range-based analytics like get_overview and get_traffic_sources.

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 this tool: when you need a real-time snapshot without date filtering. It doesn't explicitly name alternatives or exclusions, but 'Ignores range' provides clear context that this is the live-data tool among range-parameter 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?

Beyond the readOnlyHint annotation, the description adds that the response includes a `definitions` field explaining metric counting, which helps the agent interpret returned values. It does not address rate limits or auth, but the read-only nature is disclosed.

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 the primary function front-loaded; 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?

The tool is a simple read-only query with only two parameters; the schema documents both, and the description enumerates the metrics plus the definitions field. This is sufficient for an agent to invoke it correctly.

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

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

Both parameters have full descriptions in the schema (100% coverage), so the description adds no additional parameter meaning. The tool description references 'site and range' but the schema already defines them.

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 concrete resource (a site and date range) and a clear verb ('get overview') with an explicit list of KPIs (visitors, pageviews, orders, etc.), making it distinct from siblings like get_live or get_funnel which focus on narrower scopes.

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

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

It says 'Headline KPIs for a site and range' which clarifies the intended use case as high-level metric retrieval. It doesn't explicitly discuss when not to use it, but the sibling context plus the metric list makes appropriate usage clear.

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

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

The annotations declare readOnlyHint=true, and the description does not contradict this. The description lists included metrics but does not disclose behavioral traits such as how 'top' is determined, default sorting, or any limitations. The read-only hint covers safety, but the description adds only minimal behavioral context beyond the annotation.

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

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

The description is a single sentence of about 15 words, front-loaded with 'Top pages'. Every word earns its place; there is no filler, repetition, or unnecessary detail.

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 required parameter, the description covers the core output purpose. However, without an output schema, it doesn't explain return shape, default ordering, or the relationship to list_sites. Some context is missing, though the tool's simplicity limits the gap.

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

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

Schema coverage is 75%, so the schema already describes all four parameters. The description lists metrics that map to some sort_by values, but it doesn't add new parameter semantics. It even introduces 'add-to-cart' which is not in the sort_by enum, creating slight ambiguity. With high schema coverage, 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 identifies the resource (top pages) and specifies the exact engagement metrics included (visitors, pageviews, product views, add-to-cart, checkout starts). It lacks an explicit verb, but the tool name and title 'Get' compensate. It distinguishes from sibling tools by focusing on top pages with engagement data, though it doesn't explicitly contrast with alternatives.

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 vs alternatives. The description does not mention sibling tools like get_overview or get_traffic_sources, nor does it state any exclusions or conditions. Usage context is entirely absent.

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 safety profile is known. The description adds the 'data caveats' aspect and instructs to call only once, but it doesn't disclose more subtle behaviors like whether repeated calls return stale data or if any side effects occur beyond a read.

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 concise sentences, front-loaded with the core purpose and immediately followed by actionable usage guidance. Every sentence earns its place, with no 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 simple one-parameter read-only tool, the description adequately covers what it does, when to call it, and why it matters. It doesn't describe the return format, but no output schema exists and the response is a straightforward context object. The mention of 'data caveats' hints at nuances, which 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 schema description for the only parameter 'site' is fully covered ('Site handle from list_sites.') and the description adds no additional meaning about the parameter. Since schema coverage is 100%, 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 states the tool's verb and resource: 'Get a site's timezone, currency, locale, and data caveats.' This distinguishes it from sibling tools like get_audience or get_funnel, which focus on specific metrics.

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 includes explicit guidance: 'Call this once before answering questions so you interpret dates and money correctly.' This tells the agent when to use it, though it doesn't mention alternatives or exclusions explicitly. It implies this is a prerequisite for other data-getting 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?

With readOnlyHint=true already provided in annotations, the description adds little behavioral context beyond the purpose. It doesn't mention pagination, rate limits, or timezone handling, but the annotation already covers the safety profile, so this is not a significant gap.

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: 'Where visitors came from (referrer/source), with share of traffic.' It is concise, contains no redundant words, and immediately communicates the core purpose.

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, well-documented input schema, and read-only annotation, the description is adequately complete. It conveys the essential output concept (source breakdown with traffic share) even though no output schema exists. A slightly more detailed description of the response structure could improve it, but it is sufficient for the tool's complexity.

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 has 100% description coverage, with all three parameters (site, limit, range) fully documented. The description itself adds no extra parameter-specific semantics, so it stays at the baseline of 3.

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

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

The description clearly states that the tool reports where visitors came from (referrer/source) with share of traffic. This specific resource type distinguishes it from sibling tools like get_geo, get_pages, and get_audience, which target different analytics dimensions.

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 to use the tool (when needing visitor source/origin data), but it does not explicitly mention alternatives or when not to use it. This is slightly below the highest level because it lacks direct exclusions or cross-references to 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 only declare readOnlyHint=true, and the description adds that the report includes deltas, top traffic source/page, and a definitions field explaining metric counting. This adds meaningful behavioral context beyond the safety hint.

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 front-loaded summary of the report contents and a usage tip. Every sentence earns its place with no unnecessary detail.

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 no output schema, the description explains the comparison window, specific metrics, and mentions the definitions field. For a single-parameter report tool, this is sufficient context for an agent to select and invoke it correctly.

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

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

The schema already documents the single site parameter with 100% coverage, referencing list_sites. The description adds no additional parameter semantics, so the schema carries the full burden and baseline 3 applies.

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

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

The description states a specific verb+resource: it retrieves a weekly report comparing last 7 days to prior 7 days with named metrics. It clearly distinguishes from siblings like get_overview or get_audience by the comparative time window and included metrics.

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 instructs to use this to answer 'how did my store do this week?', providing a clear use case. It does not name alternative tools or exclusions, so it's not a full 5, but the scenario gives enough context for when to use it.

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

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

The readOnlyHint annotation already signals a safe read operation. The description adds valuable context by explaining the return value (a site handle) and its intended use, but doesn't disclose additional behavioral details like ordering or empty-list behavior, which are unlikely to be critical for such a simple 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 two sentences, front-loaded with the core purpose, followed by actionable guidance. Every sentence earns its place with no redundant 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?

Given the tool's simplicity (no parameters, no output schema), the description fully covers what it does, when to call it, and what it returns. It is a complete and self-contained explanation.

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 the schema fully covers parameter semantics. The description doesn't need to explain parameters, and it appropriately focuses on the return value and usage, matching the baseline for a 0-parameter 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?

The description clearly states the tool lists accessible analytics sites, which is a specific verb+resource. It also differentiates itself from sibling get_* tools by being the discovery endpoint that returns a site handle.

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 instructs to call this first if a site handle is not already available, providing clear when-to-use guidance. This also implies alternatives (the get_* tools) require the handle, distinguishing it from siblings.

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