Pirsch Analytics MCP by usefulapi

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

Annotations already cover the safety profile (readOnlyHint true, destructiveHint false, openWorldHint true). The description adds meaningful context beyond them: with no output schema, it discloses what the response contains (pages and countries of current visitors) and the underlying endpoint. It omits any note on freshness/caching or rate limits, hence not a 5.

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 compact sentences that are front-loaded with the core meaning and append the endpoint for reference. 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 two-parameter read-only tool with no output schema, the description covers purpose, returned content, and the lookback concept, which is close to sufficient. It stops short of stating prerequisites (a domain_id must be obtained via pirsch_list_domains) or how the real-time data relates to the other statistics 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 the schema already documents both `start` (1-3600, default 600) and `domain_id` fully. The description only alludes to the lookback window via 'in the past n seconds' and adds no format, default, or cross-reference detail, so the baseline of 3 applies.

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

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

States a specific verb+resource ('Visitors on the site right now') and distinguishes the tool from historical siblings with the real-time framing. It also names the returned facets (pages, countries), so an agent can tell it apart from pirsch_get_totals or pirsch_get_visitors_time_series without opening the schema.

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

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

The 'right now (or in the past n seconds)' phrasing implies the real-time use case, but there is no explicit when-to-use statement, no exclusions, and no naming of alternatives such as pirsch_get_visitors_time_series for historical data. Usage is inferable but not 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 declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description goes further by disclosing what the response contains (time zone, hostname, role, subscription state) and the underlying endpoint, which is genuinely useful given there is no output schema; it stops short of covering error/auth behavior.

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?

Very short and front-loaded: the returned-resource summary leads, followed by the raw endpoint. The endpoint fragment is telegraphic and adds little for an agent, but nothing is wasted or buried.

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-resource read with one required id and no output schema, the description covers the resource identity and the returned fields, which is most of what an agent needs. It lacks any note on failure modes (e.g., unknown id) or how the domain relates to subsequent calls.

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

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

There is one parameter with 100% schema description coverage, including a pattern, length bounds, and a pointer to where the id comes from. The description adds nothing beyond that for the id itself, so the baseline 3 applies.

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

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

The description states a specific verb+resource (fetch one Pirsch dashboard/domain by id) and enumerates the attributes returned (time zone, hostname, role, subscription state). It does not explicitly name the sibling it contrasts with (pirsch_list_domains), though the singular 'one ... by id' implicitly distinguishes it from a list 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?

There is no explicit when-to-use/when-not statement or named alternative in the description text. The schema parameter note ('Get it from pirsch_list_domains') does imply the list-then-get workflow, so usage is inferable but not stated by the description itself.

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=true, so the safety profile is covered. The description adds genuine value with the unit ('in seconds') and the underlying endpoints, but omits return shape, aggregation behavior or pagination. 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 tight sentences, front-loaded with the output meaning before the endpoint paths. The endpoint mention is marginally useful but slightly technical clutter; still efficient overall.

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 30-parameter statistics tool with nested objects and no output schema, the description is thin. Annotations carry the safety profile and the schema carries the params, but the description says nothing about the time-series shape or scale interaction that an agent would need to interpret 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 description coverage is 100%, so the schema already documents all 30 parameters including the kind enum and filter syntax. The description restates the kind semantics but adds no detail beyond the schema, which is the expected 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?

States a specific verb+resource ('Average session duration over time, or average time on page over time') and distinguishes the two modes via kind. It does not, however, differentiate itself from siblings like pirsch_get_visitors_time_series or pirsch_get_totals, so 4 rather than 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 explicit guidance on when to use this tool versus alternatives. The session/page split is described but framed as a data definition rather than a decision rule, and no exclusions or alternatives are named.

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=true, so the safety profile is covered. The description adds the underlying GET endpoint and the shape of the result, but says nothing about pagination behavior (limit/offset/next_offset), rate limits, or empty-result handling.

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 tight sentences that lead with what the tool returns, followed by the required-parameter note. The trailing raw endpoint string ('GET /api/v1/statistics/event/meta') adds little for an agent and is the one slightly wasteful element.

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 correctly compensates by naming the returned fields (count, visitors, conversion rate). For an 11-parameter read tool it is nearly complete, missing only notes on pagination and sorting behavior that the schema partially implies.

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 (including tz, sort, direction, limit, offset, search) is already documented in the schema. The description's only parameter remark, that event and event_meta_key are required, is redundant with the schema's required list, so 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 names a specific resource ('the values of one metadata key of one event') and enumerates the returned metrics (count, visitors, conversion rate), which tells an agent exactly what it gets. It is clear on its own but does not explicitly distinguish itself from close siblings like pirsch_get_tag_breakdown or pirsch_list_events.

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

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

The only guidance is 'Both event and event_meta_key are required', which restates a schema constraint rather than telling the agent when to pick this tool over pirsch_list_events, pirsch_list_event_pages or the tag breakdown. No when-not conditions or alternatives are offered.

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, openWorldHint=true), so the remaining burden is low. The description adds a genuinely non-obvious behavior not present in the schema: filters are scoped to the first funnel step only, which materially changes how a caller interprets every filter parameter. It does not mention auth needs or rate limits, but those are not required given 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 tightly written sentences with the returned metrics front-loaded, followed by a short endpoint reference. Nothing is padded, though the raw GET path adds little for an agent that already has the tool binding and the definition is arguably very sparse for a 29-parameter tool.

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 usefully enumerates the three returned measures instead of leaving the return shape unknown. Given the 100% schema coverage and annotations, the main remaining gap is the absence of any guidance on how this differs from related statistics endpoints, which is minor for a tool whose resource is unique among its siblings.

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% across 29 parameters, so the baseline is 3 and the schema does the heavy lifting. The description adds meaning the schema cannot: that all filter parameters are applied to the first step rather than the whole funnel, which is a semantic constraint on how the filters should be used. That is a modest but real increment over 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 names a specific verb/resource pair (visitors per funnel step) and enumerates the returned metrics (visitors, share of the first step, drop-off between steps). No sibling tool (get_overview, get_totals, get_growth) produces funnel-step data, so an agent can disambiguate without opening any schema.

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

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

Usage is implied by the resource (funnel analysis over a period) but there is no explicit when-to-use vs when-not, no statement of prerequisites, and no routing to alternatives such as pirsch_list_funnels for obtaining the funnel_id. The one useful usage note, 'The filter applies to the first step', is a caveat rather than guidance on tool 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 cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the bar is lower. The description still adds genuinely useful behavior: it enumerates the six returned metrics and discloses that values are relative to the preceding period of equal length — semantics an agent cannot infer from 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, front-loaded with the metric list and comparison semantics. The trailing 'GET /api/v1/statistics/growth.' is filler for an agent that calls the tool rather than the HTTP API, but it costs little.

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 28 parameters but full schema coverage, the main gap is the absent output schema — the description names the metrics returned but does not say whether growth is expressed as a percentage, ratio or delta, nor whether per-metric values are signed. Adequate but not complete for a comparison 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% across all 28 parameters, so the schema fully documents filters, date formats, tz handling and the domain_id source. The description adds nothing parameter-specific, which is the correct baseline-3 case when the schema does the heavy lifting.

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

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

States a specific verb+resource (growth of visitors, views, sessions, bounces, time spent, conversion rate) plus the comparison basis (previous period of the same length) and the backing endpoint. An agent can distinguish it from absolute-value siblings like pirsch_get_totals, but the description never names those siblings 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?

Usage is only implied: 'compared with the previous period of the same length' tells the agent this is the deltas tool, not the raw-totals tool. There is no explicit when-to-use / when-not-to-use statement and no mention of pirsch_get_totals as the alternative for absolute numbers.

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, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior beyond that: the response is cached by Pirsch (implying possible staleness) and the endpoint is stateless with respect to date ranges and filters. It does not say how long the cache lasts, which is the main residual 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?

Two sentences, both front-loaded: what the tool returns first, then the behavioral quirks and the HTTP endpoint. No filler, no restatement of the title or of the schema, and every clause carries information the agent cannot get from structured fields.

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

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

There is no output schema, so the description must carry the return shape, and it does by listing the five returned components. Combined with annotations that cover the read-only safety profile and a cached/no-filter caveat, an agent has enough to call it correctly; only the granularity of the time series and cache freshness are left unspecified, which is a minor gap.

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

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

Schema coverage is 100% and the single domain_id parameter is documented in the schema with a pointer to pirsch_list_domains, so the baseline is 3. The description earns a bump by explicitly stating that no date range or filter parameters exist, which prevents an agent from assuming the filtering inputs that every sibling statistics endpoint accepts.

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 concrete resource (an overview of a dashboard) and enumerates exactly what it returns: visitors, views, growth vs. previous period, a visitors time series, and team member count. It is clearly distinct in content from single-metric siblings like pirsch_get_totals or pirsch_get_growth, but it never names an alternative, so an agent must infer the routing rather than being told it.

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 establishes the context for use (a quick, one-shot dashboard snapshot) and states a real constraint — 'takes no date range or filters' — which tells the agent this is the wrong tool when a specific range or filter is required. It stops short of naming the sibling to use instead (e.g., pirsch_get_totals with a date range), so the when-not is present but the alternative is not.

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=true, so the safety profile is covered. The description adds the return shape (counts and shares per platform) and the backing endpoint, but says nothing about filtering behavior across the 28 parameters, permissions, or result limits. With annotations carrying the safety burden, a 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?

Two short sentences, front-loaded with what the tool returns, with zero filler. The endpoint reference is compact and useful for an API-aware 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?

For a 28-parameter analytics endpoint the schema is rich and the annotations cover safety, but the description omits how the many optional filters interact and when this report should be preferred over list_devices or get_totals. No output schema exists, though the description does state the return shape (counts and shares), which partly compensates.

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 all 28 parameters, including the tz semantics and the !/~ /^ filter prefixes, are fully documented in the schema. The description adds no parameter-level detail and does not need to, making the baseline 3 correct.

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 resource and the exact breakdown it returns: visitors on desktop, mobile and unknown platforms as counts and shares, plus the underlying endpoint. That is far more useful than the title alone and lets an agent tell it apart from most get_* siblings. It does not, however, disambiguate against pirsch_list_devices, which an agent might reasonably consider for platform/device questions.

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 explicit when-to-use or when-not-to-use guidance, and no alternative tool is named despite the crowded sibling set. The agent must infer from the name alone that this is the platform-split report rather than the device list or totals report.

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, openWorldHint=true and destructiveHint=false, so safety is covered. The description adds the useful traits that results are time-ordered and that ids are chained from list_sessions, but says nothing about pagination, limits, or what happens with a large session.

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 with zero filler; the result content and ordering are front-loaded and the id-source note follows immediately.

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 and a read-only annotation set, the description supplies the essential return expectation (page views plus events, time-ordered) and the prerequisite id source, which is enough for a 5-param drill-down call. Minor gaps around result size or pagination keep it from 5.

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 in the schema, including tz defaulting and date semantics. The description only adds id provenance, not syntax or format detail beyond the schema, matching 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?

States a specific resource (one session) and what it returns (all page views and events in time order), which clearly differentiates it from pirsch_list_sessions. It stops short of explicitly naming the sibling it contrasts with, but the 'one session' scoping makes the distinction inferable.

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?

'Both ids come from pirsch_list_sessions' tells the agent this is a follow-up drill-down call and where the required identifiers originate. No when-not conditions or exclusions are given, so it falls short of a 5.

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

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

Annotations already declare this as a read-only, non-destructive, open-world operation. The description adds useful behavioral detail by naming the underlying GET endpoint and the returned metrics ('views and share'), but does not cover pagination, time-range requirements, or rate limiting beyond what the schema provides.

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 three short sentences, front-loads the core purpose, and includes only high-value details such as the required tag key and endpoint. It avoids redundancy and is appropriately sized for the tool.

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 ten parameters and no output schema, the description is minimal. It correctly states the required tag filter and the returned metrics, but omits details about pagination, sorting/filtering behavior, or the shape of the response that might help an agent fully interpret 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 description coverage is 100%, so parameter meaning is already well documented. The description reinforces that the tag key is required and that the tool returns values for one tag key, but adds little semantic detail beyond what the schema already states.

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 ('one tag key') and the metrics returned ('views and share'), which is more than a restatement of the title. It does not explicitly differentiate from sibling tools such as pirsch_list_tags, but the core purpose is clear from the text.

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 notes that the tag filter (the key) is required, which gives some context for invoking the tool. However, it gives no explicit when-to-use guidance or alternatives, such as consulting pirsch_list_tags first, leaving the agent to infer the workflow.

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 (readOnly, non-destructive, open-world), so the bar is lower. The description still adds real behavioral detail not in those annotations: the weekday indexing convention (Monday is 0) and the one-day range requirement for minute granularity.

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 tight sentences: the breakdown modes first, then the value proposition, then the endpoints. Nothing is padded and the most decision-relevant 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?

With no output schema, the description carries the burden of describing returns, yet it never indicates the shape of the result (e.g., a list of hour/minute/weekday buckets with visitor counts). The core invocation semantics are covered, but return-value context is missing for a 29-parameter statistics 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%, so baseline is 3, but the description adds meaning beyond the schema by documenting the weekday index origin (Monday is 0) and restating the by-mode semantics in the context of the API paths. It does not touch the 20+ optional filters, which the schema already documents thoroughly.

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

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

States a specific verb and resource (visitor counts broken down by hour/minute/weekday-hour) and pins down the semantic dimension, which separates it from pirsch_get_visitors_time_series and pirsch_get_duration. The API endpoint list reinforces exactly which resource is queried.

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 one usage constraint (minute breakdown requires from and to on the same day) and a motive ('shows when traffic peaks'), which implies the use case. However, no alternative is named and no when-not condition is stated, so an agent must infer when this beats the time-series or totals 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 establish the safe read profile (readOnlyHint=true, destructiveHint=false), so the description only needs to add semantics — and it does, disclosing the aggregation behavior that returning visitors are counted once. It does not describe response shape, but the metric enumeration covers most of what an agent needs.

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

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

Three short clauses front-load the returned metrics, then the aggregation caveat, then the endpoint. No filler, and the most decision-relevant information 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?

With no output schema, the description usefully enumerates the returned fields, and the aggregation note clarifies how to read them. For a 28-param, fully-documented filter surface, this is complete enough, though pagination/format details are absent.

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% across all 28 parameters, so the schema already documents filters, formats, and negation prefixes. The description adds no parameter-level detail, which is acceptable given the schema does the heavy lifting — baseline 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?

States a specific verb+resource (totals for a period) and enumerates the exact metrics returned (visitors, views, sessions, bounces, bounce rate, conversion rate). The 'not grouped by day' clause implicitly distinguishes it from the time-series sibling, though no sibling is named 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?

Usage is only implied through the 'not grouped by day' contrast with a day-series tool; there is no explicit when-to-use/when-not statement and no prerequisites beyond the required params. Adequate but leaves the agent to infer when totals beat the time-series alternative.

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=true, so the safety profile is covered. The description adds that results are bucketed per interval and points to the scale parameter, which is useful behavioral context. However, it says nothing about defaults, filtering semantics across the 26 optional filters, or result volume for long ranges.

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 short sentences: returned payload first, usage second, endpoint third. Front-loaded and waste-free, though the raw GET path adds little for an MCP agent and the "(see scale)" parenthetical is slightly awkward.

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 29 parameters, nested tag/event_meta objects and no output schema, the description should ideally sketch the return shape (e.g. one row per interval). It names the metrics but not how they are keyed or ordered, leaving a meaningful gap for a heavy time-series endpoint.

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% across all 29 parameters, so the schema carries full parameter documentation. The description only gestures at scale ("see scale"), adding no syntax or semantics beyond the schema. 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?

It names the specific metrics returned (visitors, views, sessions, bounces, bounce rate) and the granularity (per day/week/month/year), which is a concrete verb+resource statement. It is distinguishable from aggregate siblings like pirsch_get_totals, though it never names an alternative 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?

"Use it for traffic charts and trends" gives an implied usage context, but there is no when-not guidance and no routing among the many close siblings (get_totals, get_growth, get_time_distribution, get_overview). The agent must infer differentiation from the metric list 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, destructiveHint=false and openWorldHint=true, so safety is covered; the description adds genuinely new context by disclosing the result row shape (visitors, views, sessions, bounces, relative shares) and the underlying GET endpoints. It stays silent on pagination behavior and default sort, which the schema only partly covers.

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, front-loaded with what is returned and followed by filtering and result shape; almost every clause earns its place, though the endpoint URL list is mostly redundant with the title and 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 34-parameter, no-output-schema tool the description usefully covers the dimension choice, filter semantics and result fields, plus the required domain_id is documented in the schema with a pointer to pirsch_list_domains. Pagination (limit/offset/next_offset) and sort defaults are left to the schema, which is acceptable but not fully 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 100% across 34 parameters, so the schema already documents filters, prefix operators, dates and enums. The description only illustrates filter syntax with 'country=de, path=~blog', which restates what the schema already specifies, so 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 concrete resource breakdown ('visitors per browser, browser version, operating system or screen class') that maps directly to the dimension enum, so the agent knows exactly what the tool returns. It does not name or distinguish itself from the closest sibling, pirsch_get_platforms, which reports overlapping platform 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?

It gives filter usage context ('Filters narrow the data (for example country=de, path=~blog)'), which is implied guidance for narrowing results, but never says when to choose this tool over pirsch_get_platforms or the other breakdown tools, and lists no exclusions or prerequisites beyond the required params in the schema.

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 readOnly, non-destructive and open-world behavior, so the bar is lower; the description adds genuinely useful context by disclosing OAuth-scope-dependent results (one domain vs. all) and the underlying GET endpoint. It does not mention pagination or result limits, which is the remaining 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?

Three tight sentences, front-loaded with the core list action, followed by the crucial id-reuse instruction and scope caveat. Every sentence adds information 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?

With no output schema, the description compensates by naming the fields returned, and the annotations cover the safety profile. What is missing is any note on result size or pagination for a list endpoint, but otherwise it is sufficient 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 100% and the single 'search' parameter is fully documented in the schema, so baseline 3 applies. The description never references the search filter or explain its matching semantics beyond what the schema already says.

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 (List) and resource (Pirsch dashboards/domains) and enumerates the returned fields (id, hostname, display name, time zone, role). It is clearly distinguishable from siblings such as pirsch_get_domain or pirsch_list_hostnames.

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 downstream routing advice: 'Use the id as domain_id in every other tool', which tells the agent why to call this first. It also explains the scope difference between dashboard-level and account-level clients. It does not discuss when not to use it or how the optional search filter fits in.

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=true, so the safety profile is covered. The description adds only the raw endpoint path and a restatement of the required parameter; it says nothing about pagination behavior, rate limits, or how the rows are shaped beyond naming two metrics.

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 short sentences, front-loaded with the result content, no filler. The trailing raw endpoint and the redundant 'event name is required' line are the only wasted space.

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 analytics query with no output schema, the description is minimally adequate: it conveys the resource and the two headline metrics. It omits return shape, pagination semantics (next_offset), and any routing against the many sibling statistics 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 every parameter (dates, tz, sort, direction, limit, offset, search, domain_id) is already documented in the schema. The description adds no syntax or semantics beyond repeating that the event name is required, which is the baseline-3 case.

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

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

States a specific verb and resource: pages on which an event was triggered, including the metrics returned (visitors and views). This distinguishes it reasonably from pirsch_list_pages (all pages) and pirsch_get_event_breakdown, though it never names those siblings 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 only guidance is the prerequisite 'The event name is required', which the schema already enforces. There is no statement of when to use this tool versus pirsch_list_pages, pirsch_get_event_breakdown, or pirsch_list_events.

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=true, so the safety profile is covered. The description adds the underlying endpoint (GET /api/v1/statistics/events) and the metric set, which is useful, but says nothing about pagination behavior, rate limits, or how the 33 filters combine. 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 with no filler; the alternative-tool routing is placed after the resource statement in a logical order. The first sentence is a bare noun phrase lacking a verb, which is slightly abrupt, but nothing 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?

With 33 parameters and no output schema, the description usefully enumerates the returned metrics so an agent can judge relevance, and the fully documented schema covers inputs. Only pagination/result-envelope behavior is left unexplained, which is a minor gap.

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

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

Schema description coverage is 100%, including the offset hint about next_offset and the tag/event_meta pair semantics, so the schema carries the full parameter burden. The description contributes no parameter-level meaning beyond that. 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 names the concrete resource (custom events) and enumerates the metrics returned (count, visitors, views, conversion rate, average duration, metadata keys), so an agent knows exactly what comes back. It also separates itself from pirsch_get_event_breakdown. It never states the verb 'list' or a scope/filtering statement in the description text itself, only the title does, so it falls just short of 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?

It gives an explicit routing rule: use pirsch_get_event_breakdown when you want the values of one metadata key, otherwise use this tool. That is a clear alternative for the most likely confusion case. It offers no negative conditions or prerequisites (e.g. that domain_id comes from pirsch_list_domains), but the single routing sentence is solid.

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 scoping and exposes the backing endpoint, but says nothing about return format, pagination, or volume limits for a value-listing call.

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 concise sentences plus the endpoint path, front-loading what the values are and the primary use case. Efficient with no filler, though the naked endpoint reference is marginally redundant with the rest.

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 listing tool with 100% schema coverage and no output schema requirement, the description covers what the tool does and when to use it. It is complete enough for correct invocation, with only minor gaps around result shape.

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 (including the dimension enum and tz) is already documented in the schema. The description only reinforces the dimension concept with examples, adding little beyond the schema; baseline 3 is appropriate.

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

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

States a specific verb (list) and resource (values that exist for a filter/dimension in a period), with concrete examples like page paths, referrers, countries. It is clear what the tool returns, though it does not explicitly contrast itself with specific-value siblings such as list_pages or list_referrers that appear to overlap.

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 states the use case: 'Use it to find valid values before filtering,' which tells the agent when this tool is appropriate. It does not, however, name when to prefer a narrower sibling or note exclusions, so it falls short of a full 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered elsewhere. The description usefully discloses that results include steps and step filters and names the underlying endpoint (GET /api/v1/funnel). It says nothing about pagination, result caps, or ordering, which matters for a list endpoint.

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 compact sentences, front-loaded with what is returned, followed by the routing hint. Little waste. The trailing raw endpoint string 'GET /api/v1/funnel' is the weakest element and contributes little to agent decision-making.

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

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

With no output schema, the description carries the burden of describing the return shape and does so at a summary level (funnels plus their steps and step filters). For a simple two-parameter read-only listing that is largely sufficient, though depth of the nested step payload is left 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 description coverage is 100%, so both domain_id and search are fully documented in the schema (including the 'contains this text' matching semantics), which sets the baseline at 3. The description implies dashboard scoping ('defined for a dashboard') but adds no syntax 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?

Names the resource (the funnels defined for a dashboard) and adds distinguishing scope: the listing includes each funnel's steps and step filters. That detail separates it from sibling list tools and from pirsch_get_funnel. It never states a verb, though the name 'List funnels' supplies it.

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 an explicit handoff: take a funnel id from this listing and pass it to pirsch_get_funnel. That is real routing guidance between two closely related siblings. It stops short of saying when not to use it (e.g. if you already have the id) or how results behave.

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, openWorldHint=true and destructiveHint=false, so safety is covered. The description adds genuine context beyond that: the shape of each returned row (visitors, views, sessions, bounces, relative shares) and the four backing endpoints, which matters since 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?

Three compact sentences, front-loaded with what the tool returns. Every sentence carries information; the endpoint trailer is slightly operational but nonetheless informative, and nothing is padded.

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 34-parameter aggregation tool with no output schema, the description usefully compensates by naming the returned metrics and confirming the dimension-driven breakdown. It omits mention of pagination/next_offset behavior, which is the one gap an agent might care about.

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 34 parameters including the !, ~, ^ filter prefixes. The description's country=de and path=~blog examples merely illustrate what the schema already spells out, so it does not materially exceed 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?

States a specific resource breakdown ('Visitors per country, region, city or language') that maps directly to the dimension enum, and the endpoint list confirms it is a statistics read. An agent can tell it apart from pirsch_get_platforms, pirsch_list_pages, and pirsch_list_utm purely from the stated 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?

Provides illustrative filter usage (country=de, path=~blog) which implies the tool is a filtered aggregation query, but never states when to pick it over siblings or any exclusions. Usage is inferable from the dimension parameter rather than articulated.

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=true, so the safety profile is covered by structured data. The description adds the return shape (definition fields plus visitors/views/conversion rate), which is genuinely useful, but says nothing about auth requirements, pagination, or rate limits.

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 compact sentences that front-load the returned data and end with the endpoint path. No filler or redundancy, though the raw 'GET /api/v1/statistics/goals' fragment adds little for an agent choosing a tool.

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 33 parameters, no output schema, and nested objects, the description is only adequate. It helpfully describes the returned metrics in lieu of an output schema, but omits required-parameter expectations, pagination behavior, and filter semantics that an agent would need 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%, so every one of the 33 parameters is documented in the schema itself. The description adds no parameter-level detail (e.g., required domain_id/from/to, filter syntax), so the baseline of 3 applies.

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

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

The description identifies a specific resource (conversion goals) and enumerates what it contains: the definition (page pattern, event, targets) plus visitors, views and conversion rate. The 'list' verb is implied rather than stated, but the resource is unique and no sibling overlaps, so an agent can pick it out.

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 explicit when-to-use or when-not-to-use guidance and no alternative tool is named. The only usage signal is implicit (it returns per-period statistics, so a date range is expected), leaving routing entirely to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds that this is a GET statistics endpoint returning aggregated traffic, but says nothing about pagination, result shape, or row limits beyond what the schema states.

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 short sentences, front-loaded with the purpose before the usage hint. The raw endpoint path ('GET /api/v1/statistics/hostname') is of marginal value to an agent and is the only near-wasteful element.

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 33 parameters, no output schema, and annotations covering only safety, the description is adequate but thin: it never characterizes the returned rows or pagination behavior, which the agent needs for a list/statistics tool. The rich schema compensates for the parameter side, keeping this at minimum viable.

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% across all 33 parameters, so the schema fully carries parameter meaning. The description adds no filter semantics, defaults, or syntax guidance beyond that 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 states a specific resource and metric: 'Traffic per hostname', which tells the agent this returns an aggregated hostname breakdown rather than raw events. It is clear on its own but does not name any sibling (e.g., pirsch_list_referrers or pirsch_list_pages) to anchor differentiation among the many near-identical list 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?

'Mostly useful for rollup views that combine several hostnames' gives a real when-to-use scenario, which is more than most siblings offer. However, it provides no exclusions and no pointer to alternative list endpoints, so an agent choosing among the ~27 list tools still has to infer the rest.

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, openWorldHint, destructiveHint=false), so the description only needs to add context. It does: it names the returned row fields and shares ('rows with visitors, views, sessions, bounces and relative shares') and maps to the underlying GET endpoints, which matters since 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?

Four short sentences, front-loaded with the returned metrics, then the type variants, then filtering, then the endpoint mapping. Nothing is padded, though the trailing endpoint list is auxiliary for an agent that will call the tool by name.

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 35-parameter analytics query tool with no output schema, the description covers the essentials: what is returned, the type distinction, filter behavior, and endpoint mapping. Pagination guidance is left to the schema's limit/offset descriptions, which is reasonable but a small 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 100% across 35 parameters, so the schema already documents every filter, enum, and the !/~/^ prefix modifiers. The description only restates type semantics and echoes a couple of filter examples, adding marginal value beyond the structured fields; baseline 3 is appropriate.

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

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

States a specific resource (top pages) plus the exact metric set it returns, and disambiguates the type variant by naming entry vs exit pages. An agent can distinguish it from siblings like pirsch_list_event_pages or pirsch_list_hostnames from the description alone.

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?

Explains the type parameter's semantics (entry = landing pages, exit = exit pages) and shows how filters narrow results with concrete examples (country=de, path=~blog). It stops short of saying when to prefer this over siblings like pirsch_list_filter_values or pirsch_get_overview, so it is clear context without 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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuine value by disclosing the return rows (visitors, views, sessions, bounces, relative shares), but says nothing about pagination or rate limits.

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

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

Four compact sentences that lead with purpose and modes before filters and results. No filler, though the trailing endpoint path is low-value for an agent that already has the tool name.

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 34-parameter, no-output-schema tool the description does the essential work: it defines the two output modes and describes the returned row fields. Pagination is left to the schema, which is acceptable since offset's description references next_offset.

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 34 parameters, seating the baseline at 3. The description lightly reinforces this by mapping by=referrer/channel and showing filter syntax (country=de, path=~blog), but adds no semantics beyond the schema for the many other filters.

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 disambiguates its two modes ('referrers (by=referrer) or traffic channels such as Organic Search and Paid Search (by=channel)'). It also names the underlying endpoints. It never names a sibling tool, though, so the boundary with pirsch_list_utm or pirsch_get_overview is left to inference.

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 implies when the tool applies ('Where visitors come from') and explains the by-parameter choice, but gives no explicit when-not guidance and no routing to alternatives like pirsch_list_utm for campaign detail. The filter examples hint at usage without stating 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 declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds a useful data note (visitor_id is a string representing a 64-bit number) and the endpoint path, but says nothing about paging behavior or result ordering beyond what the schema implies.

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 tight sentences with the resource and returned fields front-loaded, followed by the disambiguation and endpoint. The field list is dense but every item maps to a real returned column, so it earns its space.

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 compensates by enumerating the returned session fields, which is exactly what an agent needs to know about the response shape. Combined with the sibling routing note, it is nearly complete; only explicit pagination guidance is missing, though the schema's offset description covers 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?

Schema description coverage is 100% across all 33 parameters, including filter-syntax conventions, enums, and the next_offset paging hint, so the schema carries the parameter burden. The description adds no parameter-level detail (no mention of date range, filters, or limit) and only notes the visitor_id type, which concerns returned data rather than inputs. Baseline 3 is appropriate.

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

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

States the specific resource (individual visitor sessions) and enumerates the per-session fields it returns, plus the backing endpoint. It does not open with a crisp verb+scope sentence, but the resource and the sibling it is not (pirsch_get_session) are both explicit, so an agent can tell it apart from the aggregate statistics 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 names the alternative explicitly: 'Use pirsch_get_session for one session's page views and events.' That is clear routing guidance. It does not, however, say when to prefer this list over aggregate tools like pirsch_get_totals or pirsch_list_pages, so guidance is clear but incomplete.

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=true, so safety is covered. The description adds the underlying REST endpoint (GET /api/v1/statistics/tags), which is minor context, but says nothing about pagination behavior despite limit/offset parameters existing.

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 with zero filler: purpose first, then the alternative tool, then the endpoint. The endpoint reference is arguably redundant for an agent but does no harm.

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 33 parameters, nested objects, and no output schema, the description is thin: it never characterizes the result shape (e.g. next_offset for pagination) even though the schema instructs callers to pass the previous reply's next_offset. The fully-documented schema and annotations carry most of the load, making this adequate but with clear 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?

Schema description coverage is 100%, so every one of the 33 parameters, including filters such as tags, event, and the prefix operators, is already documented in the schema. The description adds no syntax or meaning beyond that, so the baseline 3 applies.

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

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

The description states the resource and payload precisely: tag keys with views and share. Combined with the name pirsch_list_tags, an agent knows this lists tag keys with metrics. It is somewhat telegraphic but effectively distinguishes the resource from siblings.

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

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

It explicitly names the alternative for a related task: 'Use pirsch_get_tag_breakdown to see the values of one key.' That routes the agent between discovering keys and drilling into one. There is no general when-to-use or prerequisite guidance, but the key routing decision is covered.

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 goes beyond that by disclosing the return shape ('rows with visitors, views, sessions, bounces and relative shares'), which is genuinely valuable given there is no output schema, plus the filter-operator syntax.

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 tight sentences: metric definition first, then filtering, then result shape, ending with the endpoint. Front-loaded and waste-free, though the raw endpoint string adds little for an agent already given the tool name.

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 34-parameter, no-output-schema aggregation tool, the description covers the metric, the dimension axis, filtering behavior and the return columns, which compensates for the missing output schema. Param details are fully carried by the schema, so the remaining gap is only routing guidance.

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 all 34 parameters (including the dimension enum) are already documented in the schema. The description adds the meaning of dimension ('visitors per UTM source, medium...') and the operator prefixes in filters, but does not substantially extend beyond the schema. 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?

States a specific verb+resource: visitors broken down by one of five UTM parameters, with the endpoint GET /api/v1/statistics/utm/{dimension}. This clearly separates it from non-UTM siblings like pirsch_list_pages or pirsch_list_referrers, but it never explicitly names an alternative, so differentiation is implicit rather than stated.

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 is only implied: 'Filters narrow the data (for example country=de, path=~blog)' hints at the filtering workflow but gives no when-to-use/when-not guidance or named alternatives among the many sibling breakdown tools. Adequate but leaves the agent to infer routing.

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