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

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions 'absolute and % deltas' and keyword support, but does not detail side effects, output format, or whether it is read-only. This is moderate transparency for a comparison tool.

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 two sentences, front-loaded with the action and result, and contains no unnecessary words. It is efficient and clearly communicates the tool's purpose.

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?

Given the tool has 5 parameters, no output schema, and no annotations, the description is moderately complete. It explains the core functionality but lacks detail on output format, filter behavior, or how the deltas are presented. For a tool of this complexity, it is adequate but not comprehensive.

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 baseline is 3. The description adds that 'Both periods accept the same friendly keywords as date_range', but this is already detailed in the parameter descriptions. It does not provide additional meaning beyond what the schema already conveys.

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 clearly states the tool compares aggregate metrics between two periods with absolute and % deltas, and gives concrete examples like 'yesterday vs the day before', distinguishing it from siblings like get_stats (single period) and get_timeseries (time series).

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 provides explicit use cases (e.g., 'yesterday vs the day before', 'this week vs last week', before/after a deploy) and notes that both periods accept friendly keywords, which guides the agent on when to use. It does not explicitly mention when not to use or alternatives, but the context of sibling tools is available.

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?

No annotations are provided, so the description carries the full burden for behavioral transparency. It mentions that results are 'ranked rows', but does not disclose whether the operation is read-only, authentication requirements, rate limits, or any side effects. The minimal description leaves significant gaps for an AI agent.

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 extremely concise—only two sentences—and front-loads the core purpose. Every sentence contributes value with no 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?

With 7 parameters, no output schema, and no annotations, the description is too brief. It does not explain how filters or order_by work, what the output format looks like, or how this tool differs from the sibling 'query' tool. Agents would need additional information to use it correctly in complex scenarios.

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 baseline is 3. The description adds little beyond the schema: it lists example dimensions (e.g., 'top pages') that are already in the schema's parameter description. No additional semantic details are provided for other parameters like filters or order_by.

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 clearly states the tool's function: breaking down stats by dimensions like top pages, traffic sources, etc., and returns ranked rows. It uses specific verb 'break down' and lists example dimensions, effectively distinguishing it from siblings that aggregate or provide time series.

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 provides explicit use cases like 'top pages yesterday' and 'where did traffic come from last week', which helps agents understand when to invoke this tool. However, it does not explicitly mention when not to use it or compare with sibling tools like get_timeseries or query, but the use cases imply the appropriate context.

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?

With no annotations, description carries burden. It discloses the output (today, yesterday) and timezone dependency but lacks details on errors, rate limits, or idempotency. For a simple read tool, it's adequate but not comprehensive.

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: first defines purpose and output, second offers usage guidance. No filler, every sentence 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?

Given a single optional parameter, no output schema, and no annotations, the description covers the key aspects: what is returned (today and yesterday), the timezone context, and usage scenarios. Could mention read-only nature or date format, but overall sufficient.

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 already describes site_id as 'Site domain'. Description adds meaning by connecting the parameter to the timezone context: 'in a site's timezone'. This enriches understanding beyond 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?

Description clearly states verb 'Get', resource 'current date', and specifies context 'in a site's timezone (today + yesterday as concrete dates)'. This differentiates it from sibling tools like get_stats or get_timeseries, which are analytics-focused.

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 explicit when-to-use: 'Useful for grounding before analyzing recent data, or to double-check what 'yesterday' resolves to.' No explicit when-not-to-use or alternatives, but the usage context is clear.

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 description discloses the real-time nature and 5-minute window, but with no annotations, it carries the full burden. It does not clarify if the count is unique visitors or sessions, nor mention any other behavioral traits like response format or aggregation.

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?

A single concise sentence that immediately conveys the purpose and key detail (real-time, last 5 minutes). No redundant information, perfectly 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?

Given the simplicity (1 parameter, no output schema), the description is largely complete. It explains the output (number of people) and time window. Minor detail missing: whether the count is unique visitors or sessions, but not critical.

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% for the single parameter site_id, which already has a description. The tool description does not add any extra parameter meaning beyond what the schema provides, so baseline score of 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?

The description clearly states it retrieves the number of people currently on the site within the last 5 minutes, using a specific verb and resource. It distinguishes well from siblings like get_stats and get_timeseries by emphasizing real-time visitor count.

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 real-time usage but provides no explicit guidance on when to use this tool versus alternatives (e.g., get_timeseries for historical data). No exclusions or conditions noted.

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?

No annotations are provided, so the description carries the full burden. It implies a read-only operation by stating 'Get aggregate stats', but does not disclose any potential side effects, authentication requirements, rate limits, or return format details. The behavioral description is adequate but not comprehensive.

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 two sentences, front-loading the purpose and a usage example. Every word serves a function, and there is no redundant or extraneous information. This is concise and well-structured.

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?

Given the tool's moderate complexity (4 parameters, no output schema, no annotations), the description adequately explains what the tool does and when to use it. It covers the return type ('single totals') and provides example metrics. However, it could be more complete by explicitly stating that the result is a single object (not time series) and mentioning the relationship to sibling 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%, with all four parameters described in the schema. The description adds minimal new meaning beyond what the schema provides (e.g., listing example metrics). It does not explain parameter interactions or provide additional context that would help the agent construct correct arguments.

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 explicitly states that the tool retrieves aggregate stats (single totals) for a site over a period, listing example metrics like visitors, pageviews, etc. It also provides a concrete use case ('how did we do yesterday?'). However, it does not explicitly differentiate from sibling tools like get_timeseries or get_breakdown, though the phrase 'single totals' hints at 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?

The description provides a clear usage context: 'Use for overview/summary questions like how did we do yesterday?'. This tells the agent when to use the tool. However, it does not mention when not to use it or suggest alternative tools for different scenarios (e.g., get_timeseries for 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?

With no annotations provided, the description must disclose behavioral traits but only gives minimal information about the output format (series of points) and granularity. It omits details like authentication needs, rate limits, whether the operation is read-only, or any side effects. The agent lacks critical behavioral context.

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 extremely concise at two sentences, with the purpose front-loaded in the first sentence and use cases in the second. No wasted words, and every sentence adds value.

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?

Given the tool's moderate complexity (5 parameters, no output schema, no annotations), the description is adequate for basic understanding but lacks details on return value structure, prerequisites, and safe usage. It covers the main use case but leaves gaps that an agent might need to infer.

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 fully documents each parameter. The tool description adds little beyond the schema, just mentioning granularities that match the interval enum. Baseline score of 3 is appropriate as the description does not degrade or enhance parameter understanding.

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 clearly states the tool retrieves traffic over time as a series of points with granularities per hour, day, week, or month. It specifies use cases for trends and charts, differentiating it from siblings like get_breakdown (dimension breakdown) and compare_periods (comparison) by emphasizing time-series output.

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 provides explicit context for when to use the tool: 'Use for trends, charts, and 'how did traffic change over the last N days''. However, it does not mention when not to use it or explicitly contrast with sibling tools such as compare_periods, leaving some ambiguity.

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?

With no annotations provided, the description carries the full burden. It explains the tool's output (list of sites with timezones), the self-hosted caveat, and explicitly states that it does not affect stats queries, which is important for understanding its read-only nature.

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 concise (two sentences) and well-structured. The first sentence states the core function, and the second adds important edge-case context. No unnecessary words.

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?

Given the tool has no parameters, no output schema, and a simple purpose, the description is complete. It covers what the tool does, when it might behave differently (self-hosted), and clarifies it is harmless to stats.

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 has no parameters, and schema description coverage is 100%. The description adds value by specifying that the output includes timezones, which is not evident from the empty 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 clearly states the tool lists all Plausible sites accessible by the API key, including timezones. It distinguishes from sibling tools like get_stats or get_timeseries, which focus on analytics 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?

The description provides context on when to use the tool (to list sites) and addresses a common self-hosted scenario where the API may be disabled, guiding the agent to fall back to a default site. It also clarifies that the tool does not affect stats queries, preventing misuse.

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?

No annotations provided, so description carries full burden. It discloses that date keywords are resolved in the site's timezone, which is useful. However, it does not mention auth requirements, rate limits, error handling, or the impact of running raw queries. For a powerful tool, more behavioral context would be expected.

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 with no extraneous information. Front-loaded with purpose and specific examples. Every sentence adds value.

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, so description should hint at return format or behavior. It does not mention what the query returns or how to interpret errors. For a tool with 8 parameters and nested objects, more completeness would be helpful, but the description is adequate for its core purpose.

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 75%, so description adds value beyond schema. It explains the date_range parameter in detail, including friendly keywords and timezone resolution. Other parameters (e.g., metrics, dimensions) are not elaborated beyond what the schema provides. Baseline 3 is appropriate because description adds some value but not comprehensive.

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?

Description clearly states it runs a raw Plausible Stats API v2 query for scenarios not covered by other tools. It lists specific use cases (custom property breakdowns, multi-dimension + time series, comparisons, imports, behavioral filters), distinguishing it from siblings like get_breakdown or get_timeseries.

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 says to use for 'anything the other tools don't cover' and provides examples, implying when to choose this over siblings. Lacks explicit when-not-to-use or prerequisites, but the context of sibling tools and the phrase 'for anything the other tools don't cover' gives clear guidance.

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