Simple Analytics MCP by usefulapi

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

Annotations only declare readOnlyHint=true, yet the description adds substantial behavioral context: a rows/2 MB cap, a 'truncated' flag signaling more data, a ~40k character JSON row limit, default robot exclusion, and a user-id requirement. This is exactly the beyond-annotation disclosure the tool 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?

Front-loaded with the core purpose, then dense but purposeful sentences on caps, date formats, and defaults. Every clause carries information, though the run of limit details is slightly packed.

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 export with no output schema, the description covers truncation behavior, size limits, date formats, and defaults well. It stops short of characterizing the row/field output shape, but the 'truncated' and field-set mentions give the agent enough to call it correctly.

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

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

Schema coverage is 100%, so the schema already documents all 8 parameters and the baseline is 3. The description reinforces date syntax and the max_rows cap and notes the default field set, but largely restates schema content rather than adding new semantics.

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

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

States a specific verb and resource: 'Raw, unsampled page views or events of one website for a date range.' The word 'raw' vs. the aggregate-oriented siblings (stats, timeseries, breakdown) implicitly positions it, but no sibling is named to make the distinction explicit.

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?

Offers operational guidance ('narrow the range' when truncated, hour-granularity rules), which is implied usage context. However, it never states when to choose this over simpleanalytics_get_stats or get_events, so the agent must infer the raw-export role.

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

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

Annotations only declare readOnlyHint=true; the description goes further by disclosing what each result row contains (pageviews and visitors per dimension value) and mapping the call to the underlying Stats API GET endpoint. It does not mention ordering, pagination beyond the schema's limit, or rate limits, so it is helpful but not exhaustive.

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

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

Two dense but well-ordered sentences: purpose and dimension list first, filter pointer and endpoint second. The raw endpoint string ('GET /<hostname>.json?fields=<dimension>') is the least valuable clause for an agent but it is short and confirms the dimension-to-field mapping.

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

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

For a 19-parameter tool with no output schema, the description covers the essential unknowns: what is being broken down, the full set of valid dimensions, that results carry pageviews/visitors, and where filter semantics live. Remaining details (defaults, formats, limits) are fully documented in the schema.

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 19 parameters, including enum values for dimension and device_type, so the schema carries the parameter burden. The description only reinforces the dimension choices and defers filter semantics to simpleanalytics_get_stats, adding little 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?

Names a precise operation (return top values of one dimension for one website and date range) and enumerates every dimension value the tool accepts. It also states the shape of each returned row (pageviews and visitors), which is a specific, non-tautological claim about the resource.

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

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

Usage is implied rather than stated: 'top values of one dimension' signals an aggregation/breakdown call, and it points at simpleanalytics_get_stats for filter semantics. However, it never says when to pick this over get_stats, get_timeseries or get_events, and gives no exclusions or prerequisites.

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

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

readOnlyHint=true already establishes this is a safe read. The description adds that omitting names returns all events with a 1000 cap, which is useful behavioral context, but it doesn't cover paging, result ordering, or how counts are grouped.

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-load the purpose and the key argument behavior, followed by the underlying API path. No filler; only the raw endpoint line is arguably expendable.

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

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

No output schema exists, and while 'how often' hints at counts, the description never confirms the return shape (counts keyed by event name) or ordering. For an 18-parameter tool the description is adequate but leaves return semantics to inference.

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 18 parameters, so the schema already documents everything. The description only reinforces the names default and adds the 1000-event cap, which is a modest increment over structured data.

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?

Clearly states a specific verb and resource: counting how often custom events occurred on one website in a date range. It distinguishes from siblings by semantics (events vs. stats/breakdown/timeseries) though it never names 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?

It explains the names argument semantics (pass names, or omit for all events) but gives no guidance on when to choose this tool over simpleanalytics_get_stats or simpleanalytics_get_breakdown. Usage is implied rather than contrasted.

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?

readOnlyHint=true already establishes the safety profile, and the description adds real value on top: it names the exact returned measures (notably 'median seconds on page' rather than an average) and maps the operation to the underlying GET /<hostname>.json endpoint. It does not mention rate limits, caching, or behavior for empty result sets, which keeps it short of 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?

Three sentences, front-loaded with the aggregate itself and then compressing a 15-filter surface into a single enumerable clause plus an endpoint pointer. Every sentence carries load and there is no repetition of schema detail.

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

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

With no output schema, the description correctly compensates by naming the returned metrics and their units. Filter coverage is fully delegated to a 100%-documented schema, and the hostname dependency is spelled out. It says nothing about result cardinality or whether the summary is a single object, a minor remaining 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 17 parameters, so syntax (date aliases like today-30d, prefix wildcards, 2-letter country codes, metadata key/value matching) is fully carried by the schema. The description only lists the filter categories, adding discoverability but no semantics beyond the schema — the correct baseline here is 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 concrete verb+resource ('Aggregated traffic for one website and date range') and enumerates the exact metrics returned (pageviews, unique visitors, median seconds on page), so the agent knows precisely what it gets. It does not name or contrast with the natural siblings — get_breakdown, get_timeseries, get_events — which all operate on the same hostname/date scope, so cross-tool discrimination is left implicit.

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

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

Usage is implied rather than stated: the tool is for a single aggregated summary, and the sentence about optional filters clarifies that narrowing is possible. There is no explicit 'use this instead of get_timeseries when you want a single total' guidance, and no exclusions, so the agent must infer when this beats its siblings.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the return content (pageviews and visitors per bucket) and the underlying API call (GET /<hostname>.json?fields=histogram), but says nothing about auth needs, rate limits, pagination, or response size, which for an 18-param analytics query would be useful.

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

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

Two compact sentences with the core purpose front-loaded before the API detail. Efficient overall, though the raw endpoint string is arguably incidental for an agent and could have carried more value as usage guidance.

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

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

For an 18-param read tool with a fully documented schema but no output schema, the description supplies the essential framing (metric names, bucketing, filter reference). It is close to complete, missing only return-shape detail and sibling differentiation.

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

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

Schema description coverage is 100%, so the schema fully documents all 18 parameters including defaults and formats, which sets the baseline at 3. The description only adds that filters behave 'as in simpleanalytics_get_stats' and names the interval granularity, which is largely duplicative of 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?

States a specific verb+resource (pageviews/visitors over time buckets) and scopes it to one website and date range, with 'time series for charts and trends' clarifying the shape. It does not explicitly differentiate itself from siblings like simpleanalytics_get_stats or simpleanalytics_get_breakdown, so an agent must infer the distinction.

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 references simpleanalytics_get_stats for the meaning of optional filters, which is a helpful routing hint, but it never states when to choose this tool over get_stats, get_breakdown, or export_datapoints. Usage is only implied via 'time series for charts and trends'.

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?

readOnlyHint=true already tells the agent this is a safe read, so the description doesn't need to re-establish that. It adds the underlying Admin API route (GET /api/websites), which hints at an API-key-admin surface but does not state auth requirements, pagination, or result size for accounts with many sites.

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 clauses, front-loaded with the action and immediately followed by the practically important note about how the result is used. 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 input parameters and no output schema, the description's job is mostly to explain the payload's role, which it does by identifying hostnames as the values fed to other tools. It stops short of describing the shape of each website record, though that is a minor omission for a discovery call.

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

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

The tool takes zero parameters, so there is nothing for the description to clarify beyond what the schema conveys; baseline for a parameterless tool 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 and resource (list websites of the Simple Analytics account) and adds the crucial semantic detail that the returned hostnames are what the other tools consume. This plainly distinguishes it from the stats/timeseries/breakdown siblings, which all operate on a hostname.

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?

"Good first call" is explicit sequencing guidance, and naming the return value as input for the other tools effectively tells the agent this is the discovery prerequisite. No sibling is named as a mutually exclusive alternative, but for a no-param discovery call there is little ambiguity to resolve.

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