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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful non-obvious context — that the tool produces both aggregate totals and a visitor series, and that periods can be supplied two different ways — but it does not disclose how the comparison is presented (deltas vs side-by-side) or how named and explicit periods interact.

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 15-word sentence that front-loads the verb and resource and compresses both period-specification modes into one phrase. There is no filler, redundancy, or repetition of schema or annotation content.

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?

While the output schema and safety annotations cover return values and side-effect profile, the tool is highly complex (47 parameters, 0 required, 0% schema coverage) and the one-sentence description covers only the core concept. An agent still cannot determine which parameters form the primary versus comparison period pair, how 'period' interacts with explicit date ranges, or what most optional parameters mean, so the description is insufficient for confident 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?

With 0% schema description coverage across 47 parameters, the description must carry semantic weight. It contributes the central concept that two periods are involved and can be expressed by name (mapping to 'period') or explicitly (mapping to from/to plus compareFrom/compareTo). Yet it never names these parameters or clarifies the remaining filter/dimension parameters, leaving the agent to infer their roles from their names alone.

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

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

The description names a specific verb ('Compare'), a concrete resource ('Pirsch totals and visitor series'), and a scope ('a named or explicitly supplied pair of periods'), going well beyond the title. It also implicitly differentiates from siblings like pirsch_list_domains (listing), pirsch_query_statistics (single-scope querying), and pirsch_list_filter_options (enumerating options), since comparison is a distinct 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 use case is implied rather than stated: invoke this tool when a two-period comparison is needed, and choose between a 'named' period or an explicit date pair. However, it never explicitly routes away from pirsch_query_statistics for single-period needs or states when not to use this tool, leaving the agent to infer the decision boundary.

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 readOnlyHint=true and destructiveHint=false, so the description's 'safe summaries' and 'read-only OAuth client' reinforce but don't heavily extend that. It adds some context about the nature of the output (safe summaries) and authentication, but doesn't disclose behaviors like pagination, rate limits, or output format beyond what the schema already provides. This is consistent with the bar set 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, well-formed sentence that front-loads the primary action and resource. It is concise with no wasted words, and all information is relevant to the tool's core function.

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

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

Given the tool has no parameters and an output schema exists, the description doesn't need to detail return structure. It mentions the OAuth client and 'safe summaries,' which provides sufficient context for an agent to know what it will get. Minor lack of detail about what 'safe' means is acceptable since the output schema can clarify.

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 100%, so the baseline is 4. The description doesn't need to add parameter meaning; 'safe summaries' is the only behavioral nuance and is not tied to any 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 ('List') and resource ('safe summaries of domains'), and it distinguishes itself from siblings like pirsch_query_statistics by focusing on domain listing. The phrase 'configured read-only Pirsch OAuth client' adds precision about the 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 implies when to use the tool—when you need to list domains available to the configured client—but does not explicitly name alternatives or exclusions. However, the context is clear and the sibling tools (statistics, filter options, compare periods) are obviously different in purpose, so it provides adequate guidance without explicit 'when-not-to-use'.

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, openWorldHint=true, and destructiveHint=false, covering safety and mutation semantics. However, the description adds no behavioral context beyond a bare 'list' operation. It does not describe the return format (e.g., an array of strings), any pagination behavior, or that the results are dependent on the 'option' parameter. The description provides minimal value over 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, focused sentence with no filler or redundancy. It front-loads the core purpose and uses precise terminology. This is appropriately concise for a simple listing operation, despite lacking depth.

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 complexity (45 parameters, 5 enums, no output schema shown), the description is severely under-specified. It does not explain how to select among the many optional parameters, nor does it mention that different 'option' values may accept different filters. An agent would struggle to call this tool correctly without additional documentation or schema exploration.

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% – the description explains none of the 45 parameters, not even the required 'option'. The description does not clarify how to use the additional filter parameters (e.g., country, city, page) or that they are contextual depending on the chosen option. An agent cannot infer parameter purpose from the description, which is a critical gap for a tool with dozens of properties.

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 exactly what the tool does: 'List supported values for one documented Pirsch Analytics API v1 filter dimension.' It clearly identifies the verb (list), the resource (supported values for a filter dimension), and the domain (Pirsch Analytics API v1). This distinguishes it from sibling tools that operate on domains, statistics, or period comparisons.

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 no guidance on when to use this tool versus alternatives. It does not mention that it should be used to fetch allowed values before constructing a filter query, nor does it contrast with pirsch_query_statistics or pirsch_compare_periods. The agent is left to infer the use case from the tool name and description 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 agent knows this is a safe read operation. The description adds that the metric must be documented and the domain explicitly selected, which is useful scope context. It does not describe pagination, rate limits, or error behavior, but with annotations covering safety, this is acceptable.

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 with no fluff, front-loading the action 'Read'. It is concise, clear, and every word contributes to 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?

For a tool with 45 parameters and zero schema descriptions, the description is severely under-specified. It does not explain the relationship to sibling tools, the role of domainId despite being optional, or how to combine filters. The output schema and annotations reduce some burden, but an agent would need external documentation to invoke the tool correctly.

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

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

Schema description coverage is 0% across 45 parameters, and the description fails to compensate. It does not explain how to specify the metric, how to select the domain via domainId, which parameters act as filters, or any mutual exclusivity. The only hint is 'explicitly selected domain', which is vague and not mapped to the schema (domainId is optional, only metric is required).

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 'Read' and clearly identifies the resource as a Pirsch Analytics API v1 metric, with constraints that it handles one metric for an explicitly selected domain and filter. This distinguishes it from siblings like pirsch_list_domains and pirsch_compare_periods, though it does not name them explicitly.

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 single-metric queries by saying 'one documented metric' and 'explicitly selected domain', which hints at prerequisites like selecting a domain and providing filters. However, it does not explicitly state when to use this tool over pirsch_list_domains or pirsch_compare_periods, nor does it mention needing domain IDs from list_domains.

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