query_visits

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

With no annotations, the description carries the burden and delivers useful behavioral context: 'Only counts are returned' sets return expectations (no raw rows), and 'the site stores no IP addresses or user agents' prevents futile queries for that data. It omits auth/permission and rate-limit behavior, but for a clearly read-only analytics query this is solid disclosure.

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 purpose statement followed by four compact, parallel examples and a closing caveat. Every sentence earns its place; the examples are somewhat dense but directly actionable and not 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 an 11-parameter tool with no output schema or annotations, the description adequately covers intent, parameter combinations, and return scope ('only counts'). No output schema exists so return-value detail need not be elaborated, though auth/error behavior is left unstated.

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 baseline is 3, but the examples add genuine value by demonstrating how parameters combine (os=iOS + country=US; browser=Firefox + group_by=source; event=signup + group_by=country; page=/pricing + group_by=day). This shows interaction patterns the schema alone does not.

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 behavior: counting pageviews/custom events and unique visitors matching filters, optionally grouped. It is clear and concrete, but it does not distinguish itself from overlapping siblings like get_timeseries, get_overview, or top_pages/top_sources/top_countries, which this tool can effectively emulate via group_by.

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 conveyed only through worked examples (iOS US visitors, Firefox source breakdown, signups per country, page views per day). There is no explicit statement of when to choose this tool over the sibling top_* / get_timeseries tools, and no exclusions or prerequisites, so the agent must infer the boundary.

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