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

The readOnlyHint annotation already signals safe operation. The description adds the default behavior ('Defaults to the last 30 days') and clarifies the read-only nature by describing a fetch operation. No contradictions or omissions of critical behaviors.

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, efficiently conveying the purpose, context, and default behavior without unnecessary 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?

The description provides enough context for a read-only query tool: it explains what it does, why it's useful, and the default behavior. It does not mention output format, but no output schema is defined, so that omission is acceptable.

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 input schema already provides comprehensive descriptions for all three parameters (date, period, site_id) with high coverage. The tool description adds minimal extra meaning beyond the schema, so the 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 the tool fetches annotations from Matomo's timeline and explains its purpose (correlating traffic changes with events). It distinguishes itself from sibling reporting tools by focusing specifically on annotations.

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 indicates when to use the tool (when needing to understand traffic changes via annotations) and notes the default date range. It does not explicitly contrast with sibling tools, but the purpose statement implies 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?

Annotations have readOnlyHint=false (mutation not specified), but the description itself warns it's an escape hatch for any method, implying raw access without checking safety. It adds context beyond annotations by clarifying scope ('ANY Matomo Reporting API method'), but it doesn't disclose behavioral traits like error handling, potential for side effects (some methods may write or manage segments), or rate limits. Since the openWorldHint=false and readOnlyHint=false are provided, the description carries some burden but doesn't fully address behavioral transparency beyond scope. This is a 3 because it adds useful scope context but omits operational traits like error handling or side-effect risk.

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 core purpose, then usage guidance, then discovery tip. Every sentence earns its place; zero waste. This matches the high calibration example's conciseness.

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?

The tool is complex (escape hatch for any method), but the description gives purpose, context, and discovery method. No output schema is present, but the tool returns arbitrary report data, so a detailed return description isn't feasible. Given the complexity, the description is adequate but could mention error handling or response format (e.g., JSON structure) to be fully complete; still, it's strong for a raw API wrapper.

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%: both `method` and `params` are described in the input schema (e.g., format examples). The description adds a bit of context for discovery (method='API.getReportMetadata'), but it doesn't add meaning beyond the schema for the parameters themselves. Baseline of 3 is appropriate since the schema does the heavy lifting, and the description adds one useful example.

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 calls any Matomo Reporting API method directly, functioning as an escape hatch for the dedicated matomo_* tools. It uses specific verbs ('escape hatch', 'call ANY', 'Discover') and explicitly distinguishes itself from siblings by listing examples of what dedicated tools don't cover (custom dimensions, funnels, heatmaps, segment management). This exceeds the mid-range calibration by naming an alternative method for discovery.

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 explicitly provides when-to-use guidance: 'Prefer the dedicated matomo_* tools; use this for reports they don't cover' and gives a concrete discovery method ('API.getReportMetadata'). This matches the high calibration example (get_calls) which named an alternative tool for filtering; here it names both the preferred alternatives and the fallback context, which is even stronger.

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 indicate readOnlyHint=true, so the agent knows it's a safe read operation. The description adds the set of available dimensions (e.g., devices, brands, browsers), which is useful but does not go further to explain output format, pagination, or any side effects. This meets the baseline given 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 a single, compact sentence that front-loads the purpose and lists key dimensions. There is zero redundant text, making it highly efficient and easy to parse.

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 reporting tool with a well-described schema and no output schema, the description is adequately complete. It covers the core dimensions and works with the schema's parameter details. It lacks an explicit note about output aggregations, but given the tool's simplicity and that all parameters are documented, this is 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 coverage is 100% with detailed descriptions for every parameter, so the baseline is 3. The description reinforces the dimension choices (matching the enum) but doesn't add substantive new meaning beyond what the schema already provides.

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 reports on visitor devices and technology, enumerating specific dimensions such as device types, brands, browsers, and OS. It distinguishes itself by focusing on device/tech metrics, though it doesn't explicitly contrast with sibling tools like matomo_visits_summary.

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 guidance is provided on when to use this tool versus alternatives. The description simply lists what it reports; there is no mention of scenarios, exclusions, or recommendations such as 'use for device breakdowns' or 'prefer this for technology analysis'.

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 provide readOnlyHint=true, so the description doesn't need to restate that. The description adds content specifics (revenue/order overview, best-selling products by product name, SKU, or category), which is useful beyond the schema's enum values. It doesn't contradict annotations, and it doesn't mention any side effects or limitations, but that's acceptable given the read-only hint.

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 a single, concise sentence that front-loads the core purpose. Every word adds value without redundancy or fluff.

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 readOnlyHint annotation and full schema coverage, the description is adequate. It explains what the tool returns (revenue/order overview and best-selling products) but doesn't mention any special behaviors like date filtering or segment support, though these are covered by parameters. The lack of an output schema means the agent must infer return format, but the description gives a reasonable overview. Overall, it's sufficient for a read-only reporting 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 parameters are already well-documented. The description adds minimal extra semantics beyond restating the report types (overview, products, skus, categories) which are already in the 'report' enum. Thus, it meets the baseline of 3 for full coverage but doesn't add significant value 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?

The description clearly states the tool's function: 'E-commerce performance: revenue/order overview, and best-selling products by product name, SKU, or category.' This specifies the resource (e-commerce performance) and the scope (revenue/orders, products, SKUs, categories), and distinguishes it from siblings like matomo_pages or matomo_goals by focusing on e-commerce-specific metrics.

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 (for e-commerce performance data) but does not explicitly contrast with alternatives or provide exclusions. It doesn't say 'use this for e-commerce analytics, use matomo_goals for goals' etc. The clear purpose gives context, but no explicit guidance on when not to use it.

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 description only needs to add contextual behavior. It adds examples of event types and grouping options, which is useful, but does not describe return format, pagination, or any caveats. The added value is moderate but not extensive.

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 a single sentence that is front-loaded with the core purpose and uses ellipsis to keep it concise. No wasted 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?

With full schema coverage and readOnly annotation, the description covers the core purpose. It does not describe the return structure, but for a simple read-only report tool with strong schema support, this is adequate. Slightly more detail on the response format would push it to a 5.

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 detailed descriptions for all 6 parameters. The tool description adds no extra parameter details beyond echoing the grouping concept. Baseline 3 is appropriate when the schema does the heavy lifting.

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 provides 'custom event tracking reports' with specific examples (clicks, video plays, form interactions) and mentions grouping by category/action/name. This distinguishes it from sibling report tools like pages, referrers, and goals.

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 the tool is for event tracking reports, but provides no explicit when-to-use guidance or exclusions. It does not mention alternatives or when not to use this tool, which would be helpful given the large sibling set.

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 and openWorldHint=false, meaning the tool is read-only and not open-world. The description does not contradict these and adds only the breakdown dimensions; it does not add extra behavioral context beyond what annotations provide.

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 a single, focused sentence. It avoids fluff and repeats only useful context from the title. The breakdown levels are listed compactly, making it easy to parse.

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 rich schema and read-only annotations, the description sufficiently completes the tool's context for a straightforward reporting task. It lacks an explicit mention of what metrics are returned (e.g., number of visits, percentages), which is minor because the word 'visits' already conveys the core metric.

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 six parameters individually described in the input schema. The description itself contributes no additional parameter insight, so it relies entirely on the structured schema, which is already clear.

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 role: 'visits broken down by country, continent, region, or city' – a specific resource (visitor locations) and breakdown dimensions. This differentiates it from sibling tools like matomo_visits_summary and matomo_pages, making its purpose unambiguous.

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 by the purpose, but there is no explicit statement of when to use this tool vs alternatives, nor any mention of when to choose another sibling. The parameter description for site_id suggests calling matomo_list_sites first, but the main description lacks direct 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?

The readOnlyHint annotation is true and the description doesn't contradict it, but the description adds minimal behavioral detail beyond the annotation. It doesn't mention potential side effects (none expected) or data access implications, but for a read-only report tool, the annotation suffices.

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, fitting the key info into a single sentence. It avoids fluff and focuses on the two report modes, making it efficient and easy to parse.

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 simple nature of the tool (a read-only report), the description covers the essential functionality and the main parameter behavior. It doesn't explain return formats or pagination, but the schema and sibling context imply a standard Matomo API response, so completeness is adequate.

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?

All six parameters have schema descriptions that cover their meaning and defaults. The description reinforces the 'report' parameter's two modes, adding clarity. The descriptions for date, period, and segment are standard and sufficient.

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: reporting goal conversions or listing goals. It distinguishes between the two modes via the 'report' parameter, making the purpose specific. It doesn't mention alternative tools, but the resource (goals) is clear.

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 usage for goal-related analytics but doesn't explicitly state when to prefer this over sibling tools like matomo_pages or matomo_events. It lacks explicit guidance on when not to use it, though the purpose is clear enough for basic scenarios.

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 and openWorldHint=false already establish the read-only nature and scope. The description adds modest context about token-based access and the three returned fields, but little else about behavior or limitations.

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 short, front-loaded sentences convey the action, result contents, and usage guidance without unnecessary detail or repetition of schema metadata.

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 list tool with one optional parameter and no output schema, the description provides sufficient context: what it lists, what it returns, and when to call it. No critical gaps remain.

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 input schema documents the only parameter (limit) with type, default, and description, achieving 100% coverage. The description does not add any additional parameter meaning, so the 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 uses a specific verb ('List'), identifies the resource ('all websites in Matomo'), and states the scope ('that this token can access') plus the returned fields (ID, name, main URL). This clearly distinguishes it from sibling reporting tools that operate on individual sites.

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 instruction 'Call this first whenever the site_id is unknown' gives explicit when-to-use guidance. However, it does not mention when not to use it or name alternative tools for known site_id scenarios.

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 adds a behavioral detail that the data is aggregated 'across pageviews', which goes beyond the read-only annotation. However, it does not disclose any side effects, rate limits, or other runtime behaviors.

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 a single, focused sentence that immediately states the purpose and key outputs. It is concise, free of fluff, 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?

The description covers the metric types but leaves ambiguity about the output granularity (e.g., per-page vs. overall averages) and does not mention any grouping or filtering implications. Given the absence of an output schema, more explicit detail would improve completeness.

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 input schema already provides exhaustive descriptions for all four parameters. The tool description does not add any further meaning or clarify parameter usage, so it adheres to the baseline for high schema coverage.

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 indicates it provides page load performance metrics and lists the specific types of times (network, server, etc.). It distinguishes from sibling tools by focusing on performance, though it doesn't explicitly state an action like 'get' or 'retrieve'.

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 no guidance on when to use this tool versus the sibling tools (e.g., 'pages' or 'visits_summary'). It fails to mention scenarios where this report is more appropriate.

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 mark the tool as read-only, and the description adds useful behavioral context: URLs are returned flattened as full paths and sorted by visits. This goes beyond the annotation for report-specific behavior and avoids surprises.

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 comprises two sentences: the first front-loads the tool purpose and report list; the second covers output formatting. There is no filler, and each sentence contributes essential user information.

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 there is no output schema, the description still communicates the nature and shape of the returned data (page URLs/titles, entry/exit, downloads, outlinks, full paths, sorted by visits). It could go deeper into per-report row shapes, but the combination of schema descriptions and this context is sufficient for basic invocation.

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 schema describes 100% of parameters with defaults and enums. The description adds meaning by mapping report types to the output behavior (most visited URLs/titles, entry/exit pages, downloads, outlinks) and clarifying URL flattening and sort order, which improves parameter comprehension.

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 identifies the tool as returning page-level analytics reports and enumerates the specific report types (most visited URLs/titles, entry/exit pages, downloads, outbound links). It is distinct from siblings like matomo_visits_summary and matomo_referrers, though it lacks a strong imperative verb such as 'list' or 'get'.

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 says 'Page-level analytics reports' and lists what it covers, which gives context for when to use it. However, it does not explicitly mention when not to use it or point to alternatives like matomo_page_performance or matomo_visits_summary.

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, and the description adds the two output modes and time-window behavior. It does not disclose response structure or potential data-delay caveats, but it does not contradict 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 a single sentence, front-loaded with 'Real-time analytics', and efficiently separates the two report modes with a semicolon. Every phrase contributes useful information 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?

For a read-only analytics tool with no output schema, the description adequately describes both output families and the time-window parameter. It leaves exact return fields to inference, but the high-level output types are clear.

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 documents all five parameters. The description reinforces the meaning of report and last_minutes but adds no new parameter syntax or format details 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?

The description clearly identifies the tool as real-time analytics and specifies two distinct report modes: live counters and recent visit logs. This distinguishes it from the historical report siblings like matomo_visits_summary and matomo_pages.

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 establishes clear usage context through phrases like 'live', 'last N minutes', and 'most recent individual visits', implying use for real-time monitoring. However, it does not explicitly name alternative tools or state when not to use this tool.

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 does not disclose any behavioral aspects beyond stating it provides data. However, the annotation indicates read-only, so no side effects are expected. The description itself does not add any behavioral transparency.

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 a single, clear sentence that efficiently lists the types of referrer data available, with 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?

The description is concise but covers the main categories of referrer data. However, it does not mention any limitations, required permissions, or how the output is structured, so it is not fully complete.

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 description does not elaborate on the parameters beyond what is already in the schema. The schema descriptions cover each parameter, so the tool description adds no additional parameter 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?

The description clearly states that the tool provides referrer traffic data, listing various types such as channel overview, search engines, etc., which gives a clear understanding of its purpose.

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 does not provide any guidance on when to use this tool versus alternative tools, nor does it mention any prerequisites or contexts where it is appropriate.

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 annotations declare readOnlyHint=true, and the description is consistent with a read-only analytics operation. The description adds some context about what the tool reports but does not disclose behavioral traits like response shape or additional side effects. No contradiction with 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?

A single, focused sentence that is front-loaded with the tool's purpose and enumerates the three report types without redundancy. Every word 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?

With strong annotations, a complete parameter schema including useful hints (e.g., call matomo_list_sites for unknown site_id), and no output schema, the description provides enough context for an agent to select and invoke the tool. It could go further in describing the return structure, but overall is quite complete.

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?

All parameters have 100% schema coverage, so the baseline is 3. The description adds value by explaining the meaning of the report parameter's enum values (keywords, no_result_keywords, categories) in a way not present in the schema's terse 'Which site-search report to fetch' description.

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 uses a specific verb+resource structure: 'Internal site-search analytics' followed by the three report output types (searched terms, no-result searches, search categories). This clearly distinguishes it from sibling tools like matomo_pages or matomo_referrers, which cover different analytics areas.

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 the use case: site-search analytics for understanding visitor search behavior. However, it does not explicitly state when to use this tool versus alternatives, nor does it mention exclusions or reference any sibling tools. This is adequate but lacks explicit 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the agent knows this is a safe, closed read operation. The description adds value by disclosing the exact aggregate metrics returned, which is especially helpful since no output schema is provided.

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 concise sentences: the first compactly lists the metrics, and the second gives the canonical use case. It avoids repeating schema details and has 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?

For a simple read-only summary tool, the description plus a fully described four-parameter schema is sufficient for an agent to select and invoke it correctly. The listed metrics compensate for the absent output schema, and the schema also covers site_id discovery via matomo_list_sites.

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 each parameter already carries a good description including date syntax, period enum, segment syntax, and site_id lookup guidance. The tool description adds little parameter-level meaning beyond framing the metrics around a site and period, so it stays at the baseline.

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 says this tool returns key traffic metrics for a site and period, listing visits, unique visitors, actions, bounce rate, actions per visit, and average visit duration. It is unmistakably the traffic-summary tool and is differentiated from more specialized siblings like matomo_pages or matomo_referrers.

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 phrase "The go-to tool for 'how much traffic did we get?'" provides a clear, memorable use case for when to select this tool. It does not explicitly enumerate when to avoid it or name alternative tools, but the guidance is strong enough for typical traffic-summary questions.

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 indicates a safe read operation. The description adds no additional behavioral details (e.g., pagination, data limits) beyond the annotation, so it neither enhances nor contradicts transparency.

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, using a single sentence to convey the core functionality. It is well-structured and free of unnecessary detail or 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?

Given that the schema and annotations provide sufficient parameter and safety context, the description adequately completes the picture. It could mention the output format or typical use cases, but those are not essential for basic understanding.

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 schema covers all parameters with descriptions, so the description adds no new information about parameters. It briefly mentions 'day of week' and 'hour of day' which map to the dimension parameter, but all parameter meanings are already explicit in 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?

The description clearly states the tool's function: reporting visit times broken down by day of week or hour of day, with server or local time. It is distinct from sibling tools like visits_summary or pages, which focus on different metrics.

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 usage for time-based traffic analysis but does not explicitly contrast with alternatives or state when to prefer it over other reports. It lacks guidance on selection scenarios.

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