Plausible: realtime visitors

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

Annotations already mark this as read-only and non-destructive, so the bar for extra disclosure is lower. The description adds meaningful behavior beyond annotations: it uses Stats API v2 over a UTC window and makes 1 or 2 requests depending on top_pages. This helps an agent understand side effects and cost without contradicting 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?

The description is compact and front-loaded: the core capability is in the opening sentence, followed by useful examples and a relevant implementation note. The sentence about request count earns its place because it warns about the extra call when top_pages is used. No redundant schema repetition.

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

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

For a simple read-only, zero-required-parameter tool with fully documented schemas, the description is largely complete. It covers the operation, examples, parameter behavior, response format choices, and request count. It does not explain authentication or error behavior, but those are likely covered by the wider Plausible integration context and the openWorldHint.

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 descriptions cover 100% of the parameters with defaults, ranges, and meaning, so the schema already does the heavy lifting. The description's examples add a little extra value by showing valid combinations, but they do not introduce meaning absent from the input 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 first sentence states a specific verb and resource: 'Get how many unique visitors are on the site right now (last few minutes)'. This clearly distinguishes it from siblings like plausible_get_aggregate, plausible_get_timeseries, and plausible_get_breakdown because it targets live visitors rather than historical analysis.

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

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

The description implies when to use it via the realtime framing and gives concrete examples, but it does not explicitly state when not to use it or name alternatives. An agent can infer the right context, but the tool does not explain how it differs from aggregate/timeseries/breakdown tools.

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