Plausible MCP by usefulapi

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 only adds that it maps to a dimensions-less query endpoint—useful but thin. It says nothing about response shape, pagination, or result limits, which the annotations do not cover.

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

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

Two tight sentences with the core purpose front-loaded and the API mapping trailing as supporting detail; no filler. Slightly more value could have gone into routing guidance instead of the endpoint path.

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?

A simple read-only tool with 4 fully documented parameters and annotation-covered safety; the agent has enough to call it correctly. The one gap is explicit routing to the dimensioned sibling tool, which would make the toolset selection unambiguous.

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%, and the description adds no parameter detail beyond restating that metrics and a date range are involved. Per the rubric, a 3 is the baseline when the schema already documents every parameter.

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

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

States a specific verb and resource ('aggregate totals for the given metrics over a date range') and pins the underlying endpoint (POST /api/v2/query with no dimensions). The '(no group-by)' qualifier implicitly distinguishes it from an ungrouped-vs-grouped pair, but it never names the sibling that does group-by, so the differentiation 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?

The '(no group-by)' parenthetical and the 'Convenience' framing imply this is the tool to reach for when you only want grand totals, but no alternative tool is named and no when-not-to-use condition is stated. Usage is implied rather than directed.

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 usefully discloses that this maps to POST /api/v2/query with dimensions=[property], clarifying it is a convenience wrapper over the raw query endpoint, but adds nothing about return shape or result limits beyond the schema's limit field.

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 purpose and closed with the underlying API mapping. No filler, every clause earns its place.

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 7-parameter read-only breakdown tool with full schema coverage and no output schema, the description covers the core purpose but omits routing guidance versus its many siblings, leaving the agent to infer when this is the right 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%, so every parameter is already documented in the schema. The description only reinforces the 'property' param with examples the schema itself already supplies, so 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 and resource — 'break metrics down by a single property (dimension)' — and gives concrete examples (visit:source, event:page). It implicitly contrasts with aggregate/timeseries by emphasizing 'a single property', but never names a sibling, so it stops short of full differentiation.

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 guidance. The word 'Convenience' hints it is a shorthand wrapper, but the description never says when to prefer it over plausible_aggregate, plausible_timeseries, or plausible_query_stats.

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

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

The readOnlyHint annotation already establishes this as a safe read, so the bar is lower. The description goes beyond it by disclosing the enterprise-plan prerequisite and the exact API endpoint, both of which affect whether the call will succeed.

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 with no filler; the core action is front-loaded and the plan constraint and endpoint follow compactly. Every clause earns its place.

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-parameter read tool with no output schema, the description covers purpose, a prerequisite, and a hint at returned fields ('timezone, etc.'). Nothing critical is missing, though it could say more about the returned 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 coverage is 100%, so the site_id parameter is already documented with format and example. The description only reiterates 'by its domain' without adding semantics, 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?

States a specific verb and resource ('Get a single site by its domain'), and the phrase 'a single site' implicitly contrasts with the list variant. It does not name the sibling alternative explicitly, so it falls 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?

Usage is only implicitly conveyed through 'a single site' versus the sibling plausible_list_sites, which is never named. It does add a genuine prerequisite ('Requires an enterprise plan'), which is useful context, but there is no explicit when-to-use/when-not guidance.

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 as a safe read. The description adds the enterprise-plan prerequisite and identifies the underlying endpoint (GET /api/v1/sites/goals), which is modest extra context. It does not disclose whether results are paginated, whether goals can be archived/filtered, or what the response shape looks like.

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 that front-load the action and resource, then the constraint, then the endpoint. Efficient overall, though the raw endpoint reference is marginally redundant filler for an 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 read-only, single-parameter list tool with a fully documented schema and no output schema, the description covers purpose, access prerequisite, and endpoint — enough to call it correctly. Return-value expectations and any pagination behavior remain 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% and the single parameter site_id is fully documented in the schema (domain format plus example), so the description correctly need not restate it. Baseline 3 applies since the description adds no parameter-level meaning.

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 the goals (conversions) configured for a site') with a helpful gloss that conversions and goals are the same concept. It is clear on its own, though it never names or contrasts with any sibling tool.

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?

'Requires an enterprise plan' is a genuine gating condition that tells the agent when this call will fail, which is more than most descriptions offer. However, there is no guidance on when to reach for this tool versus the stats-oriented siblings, and no notion of what to do instead if the plan requirement is unmet.

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, but the description adds substantive behavior beyond that: the result scope is limited to what the API key can access, cursor pagination is used, and an enterprise plan is required. No rate limits or permission-error behavior are covered, so it is useful context rather than 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?

Three short, front-loaded sentences with no filler; the scope and returned fields come first. The trailing API endpoint reference ('Plausible: GET /api/v1/sites') is doc cross-reference rather than invocation guidance, which costs it a point.

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 names the shape of each returned record (domain + timezone) and how to page through results. It does not mention the pagination meta fields or approximate result counts, but nothing essential for correct invocation is missing.

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%: after, before, and limit each carry their own documentation including where cursors come from (meta.after/meta.before). The description's 'cursor pagination' phrase restates rather than extends that, so the baseline 3 is 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 verb+resource ('List the sites') plus the scope ('the API key can access') and the returned fields ('domain + timezone'). This clearly separates it from the single-site sibling plausible_get_site without needing to open either 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?

Names a real gating condition ('Requires an enterprise plan') and explains the pagination mode, which tells the agent when the call is viable. It stops short of explicitly routing to alternatives such as plausible_get_site for a single site, so it is clear context rather than full when/when-not guidance.

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, non-mutating read, so the bar is lower. The description adds that it is a POST query endpoint (useful, since POST might otherwise suggest a write) and mentions pagination and includes exist, but says nothing about result-size limits, rate limits, or cost of large dimension cardinality queries.

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

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

Two sentences, front-loaded with the capability statement and followed by grouping/filter/ordering/pagination details in one breath. The trailing 'Plausible: POST /api/v2/query.' is minor implementation trivia but compact enough not to bloat the definition.

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 8-parameter tool with nested objects and no output schema, the description covers the request shape adequately but is silent on response structure and on the decision boundary against its seven siblings. Given the rich schema it is minimally sufficient, though an agent choosing among the query tools still lacks 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%, including detailed filter syntax, dimension enumerations, metric lists and date-range shortcuts, so the schema carries the semantics. The description only recaps the categories of parameters (dimensions, filters, ordering, includes, pagination) without adding format or constraint detail 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 concrete verb and resource: compute metrics over a date range with grouping, filters, ordering and pagination, backed by the concrete endpoint POST /api/v2/query. The phrase 'full-power' hints it is the superset of its siblings, but it never names them, so an agent cannot fully distinguish it from plausible_aggregate or plausible_breakdown without opening schemas.

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?

Calling itself 'the full-power Stats API query' weakly implies 'use this when the simpler tools are not enough', but there is no explicit when-to-use, when-not-to-use, or named alternative among plausible_aggregate, plausible_breakdown and plausible_timeseries. Usage must be inferred from the label 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, so the safety profile is covered. The description adds genuinely useful context beyond that: the 5-minute activity window, the single-integer return shape, and the underlying API endpoint for traceability.

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, zero filler, with the purpose and time window front-loaded. Every clause earns its place.

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 one-parameter read tool with no output schema, the description is nearly self-sufficient: it states the return is a single integer, compensating for the missing output schema. Only sibling-oriented usage guidance is 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%, so the single site_id parameter (domain format) is fully documented in the schema. The description contributes no additional parameter meaning, which is the expected baseline here.

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 ('Get the number of current visitors on a site') plus a precise scope ('active in the last 5 minutes') and return type. An agent can distinguish this from plausible_aggregate or plausible_timeseries 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?

The 'realtime / last 5 minutes' scope implies when this tool applies, but no explicit alternative is named (e.g., use plausible_aggregate for historical counts). Usage is inferable rather than 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, so the safety profile is covered. The description adds real value by disclosing that this is a convenience wrapper over POST /api/v2/query with dimensions=[interval], which tells an agent the underlying semantics. It says nothing about result length, pagination, or rate limits on the query 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 with the purpose front-loaded and no filler. The second sentence adds the implementation mapping rather than padding, so every clause earns its place.

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 query tool with 100% schema coverage, the parameters are adequately covered. However, there is no output schema, and the description does not describe the shape of the returned timeseries (timestamp buckets with metric values), leaving an agent to guess at the response format.

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%, with documented enums for interval, metrics, and date_range formats, so the schema carries the parameter burden. The description restates the interval grouping but adds no syntax, default, or format detail beyond what the schema already provides. Baseline 3 is 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 (metrics) and scope (over time, grouped by a time interval), which is genuinely distinct from plausible_aggregate and plausible_breakdown. It also reveals the underlying API call, POST /api/v2/query with dimensions=[interval]. It stops short of naming siblings directly, so an agent must infer the boundary itself.

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 when-to-use or when-not-to-use guidance, and no mention of the sibling tools an agent must choose between. The only signal is the implicit 'grouped by a time interval' framing, which does not say when plausible_timeseries is preferable to plausible_breakdown with a time dimension.

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