pyxis-mcp

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

Annotations already declare read-only, idempotent, closed-world, non-destructive behavior, so the bar is lower, yet the description still adds value: the 400-day range cap, the 'to is at most today' time-zone-scoped rule, and the explicit warning that all reported text is raw visitor-supplied input (a data-provenance/injection caveat). The attribution rule defining source vs (ad click) vs (direct) further clarifies output semantics.

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?

Content is front-loaded: the first sentence states what the report contains, then attribution logic, then prerequisites/limits, then the data-provenance note. It is somewhat dense in the attribution paragraph but every sentence carries non-redundant 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?

With no output schema, the description does the work of describing the returned content (channels, sources, campaigns, conversions, ad clicks) and the key operational limits (400-day cap, today ceiling, time zone, list_projects dependency). It is close to complete, with only minor gaps around return shape/pagination.

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 already 100%, so the baseline is 3, but the description adds constraints the schema lacks: the range covers at most 400 days, dates are in the project time zone, and project_id/today must be sourced from list_projects. That meaningfully extends the three documented parameters.

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 names a specific verb-like resource (a per-day, per-channel acquisition report) and enumerates the channels it breaks out (paid, email, social, campaign, organic, referral, direct) plus the metrics it carries (visits, sources, campaigns, conversions, ad clicks). An agent can tell this is a traffic-attribution report, though it never explicitly contrasts itself with siblings like visits or overview.

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?

It states a real prerequisite — 'The project id and the project's today come from list_projects' — and constraints on the date range, which is useful workflow context. However, it never says when to pick acquisition over the other reporting siblings (visits, overview, funnel), so selection guidance is only implied.

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 cover read-only, idempotent, and non-destructive behavior. The description adds substantial context beyond that: top-10/top-20 geo truncation with other and null buckets, city privacy gating via city_enabled, how reach treats unknown places, the 400-day maximum range, and a caveat that visitor-supplied text is reported as received.

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 purpose is front-loaded, but the description is a dense run-on paragraph. Some detail is justified because there is no output schema, yet the final sentence about event names, page paths, sources, campaigns, and routes is generic and does not map clearly to the device/geographic report dimensions.

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 complex analytics report with no output schema, the description explains geographic return semantics and reach behavior in detail. It still omits the return structure or limits for the core device, browser, OS, and conversion breakdowns, leaving an important gap for correct interpretation.

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. The description still adds useful semantics by specifying dates are in the project time zone, that to is at most today, that ranges cover at most 400 days, and that project_id and today come from list_projects.

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 an analytics report of visits and conversions broken down by device type, browser, operating system, and geography, plus reach. It does not explicitly distinguish the tool from siblings such as overview or visits, so it is clear but not fully differentiated.

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 guidance or named alternatives. However, the report dimensions imply its use for device and geographic breakdowns, and it supplies prerequisites such as obtaining project_id and today from list_projects plus date-range constraints.

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 establish the readOnly/idempotent/non-destructive safety profile, so the bar is lower. The description still adds real behavioral context the annotations lack: the range cap of 400 days, the constraint that 'to' is at most today, and the caveat that event names, paths, property values, sources and campaigns are raw visitor-supplied text.

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 most important sentence — what the report contains — is front-loaded, followed by sourcing/date constraints and then the raw-text caveat. Three short paragraphs, essentially no filler, though the raw-text note could be tightened.

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 carries the return-value burden and does list the report's components (entry/exit pages, single-page visits, duration median and buckets). It omits response format and pagination, but for a 3-parameter read-only report this is close to 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%, so the baseline is 3. The description goes beyond the schema by adding the 400-day maximum range and restating the project-time-zone framing of dates, which the schema does not encode.

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 names the specific contents of the report — top entry/exit pages, single-page visits (bounce), and visit duration with median and buckets — which is more than a restatement of the name. It does not, however, differentiate itself from nearby siblings such as 'visits' or 'overview', so an agent must infer the boundary.

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 implied by the report contents. There is a useful prerequisite pointer ('The project id and the project's today come from list_projects'), but no explicit when-to-use-this-vs-alternatives guidance against siblings like visits, overview, or acquisition.

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 cover read-only, idempotent, non-destructive, closed-world behavior. Beyond that the description discloses a real behavioral trait not in the annotations: output is truncated to the ten most frequent values per key with a residual count, and that event/page/property values are raw visitor-supplied text reported as received (i.e., potentially dirty data). It does not mention pagination or limits on property keys.

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 with what the report contains, followed by data sourcing, date rules, and a data-quality caveat. Three tight sentences with no filler, though the final sentence about raw visitor text is somewhat peripheral to invoking the tool.

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 carries the return-shape burden and does so by enumerating keys, top-ten values, counts, visits, and the remainder count. It also covers id sourcing and date-range limits, leaving only edge behavior (empty events, error cases) unstated for a simple four-parameter read 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 (project_id, from, to, event) is already documented with format and constraints. The description restates the date bounds and the list_projects sourcing rather than adding syntax or semantics the schema lacks, 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 resource (property values of one named event) and exactly what it returns: per property key the ten most frequent values with counts and visits, plus the count of the rest. This is distinct from siblings like overview, features, or engagement, which an agent can tell apart 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?

Gives a workflow prerequisite ('the project id and the project's today come from list_projects') and a hard usage constraint (to at most today, range at most 400 days). However, it never says when to choose this tool over siblings such as overview or features, nor any when-not condition, so usage is only implied by the output description.

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 readOnly/idempotent/non-destructive/openWorld=false, so safety is covered. The description adds genuinely new behavioral context: the 400-day maximum range, that 'to' cannot exceed the project's today (a failure condition), that results are daily-granularity counts, and that names/paths/sources are raw visitor-supplied text, which warns the agent about data quality.

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 report's identity, then constraints, then a data-quality caveat. The final sentence is long but carries non-obvious information about input text provenance rather than 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?

With no output schema, the description usefully states the return shape ('daily counts' of ranked features), the hard range limits, and the time-zone convention. Missing only things like ordering guarantees, result-size caps, or rate limits, which are minor for a read-only report tool whose annotations already cover safety.

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, but the description goes beyond it: it anchors dates to the project time zone (not stated in the schema), restates the inclusive YYYY-MM-DD format with the 400-day constraint, and ties project_id's provenance to list_projects. The kind enum is already documented 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?

States a concrete resource and scope: 'the most used named events or screens (page templates) of a range, with their daily counts.' An agent can tell it produces a ranked feature report, distinct from siblings like event_properties or overview. It stops short of naming which sibling to use for adjacent questions, so no explicit 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?

Usage context is implied rather than stated: the agent learns the project_id and the project's today must come from list_projects, and that ranges are capped at 400 days ending at today. There is no explicit when-to-use/when-not guidance versus overview, events-related siblings, or event_properties.

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 a safe read-only, idempotent, closed-world operation, so the bar is lower. The description adds real value beyond them: the hard 400-day range limit, the to<=today ceiling, the project time-zone convention for dates, and a data-quality caveat that event/page/property text is reported verbatim as visitors sent it.

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 with what the report produces, then constraints, then the data caveat. Efficient overall, though the final paragraph about text fidelity is tangential to invoking the tool and could be trimmed.

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?

There is no output schema, so the description must convey returns, and it does: per-step counts plus median transition times and whole-funnel time. Combined with the date-range and time-zone rules, an agent has what it needs; the remaining gaps are the funnel_subjects/funnel_segments routing decision.

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 step object oneOf variants, mode semantics and the 2-8 step limit, so the baseline is 3. The description's only added detail is the verbatim-text caveat; its list of 'property values, sources, campaigns and routes' actually names dimensions this tool has no parameters for, which adds no usable per-parameter 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: counts of visits/people reaching each funnel step, ordered, with median time-to-next and through the whole funnel. An agent can tell this is an ordered multi-step funnel report. It does not, however, name or distinguish itself from the sibling tools funnel_subjects and funnel_segments, which likely report on the same funnel.

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 implied: 'The project id and the project's today come from list_projects' plus the range constraints (at most 400 days, to at most today). There is no explicit statement of when to pick this over funnel_subjects or funnel_segments, so the agent must infer from the sibling names.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely useful operational context: the project's today comes from list_projects, ranges cap at 400 days, `to` cannot exceed today, and the reported text is raw visitor-supplied data. The segments summing to the whole funnel is a real semantic guarantee not present in the schema.

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 tool's core semantics before the boilerplate date/privacy caveats. The date sentence duplicates schema constraints, but the 400-day cap and timezone framing are new information and earn their 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 analytics query with no output schema, the definition supplies everything an agent needs before calling: how the funnel is segmented, where project_id and today come from, the date window limits, and a data-quality caveat about raw text values.

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, including `by`'s device/channel enum and the 2-8 step limits. The description largely restates the date and timezone rules already in the schema and adds no per-parameter meaning, 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 the resource (a funnel) and its distinguishing dimension (per device type or per channel of the visit), which implicitly separates it from the unsegmented `funnel` and from `funnel_subjects`. It does not name those siblings explicitly, so an agent must infer the contrast rather than read it.

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 — pick this when you want the funnel broken down by device or channel — but there is no explicit when-to-use statement, no when-not to use it, and no pointer to `funnel` or `funnel_subjects` as the alternative for a single whole-funnel figure.

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 cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds real value: ordering (newest first), pagination via cursor ('a page at a time'), timestamp format with UTC offsets and the fallback to +00:00, the 400-day range cap, and the caveat that reported values are raw text sent by visitors. Only the shape of returned records is left unstated.

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 purpose and ordering come first, followed by timezone/range rules and a data-provenance note; nearly every clause carries information. The opening sentence is an awkward run-on ('who reached one funnel step, or who reached the step before it and never this one'), costing a bit of clarity, but there is 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 an 8-parameter, read-only analysis tool with no output schema, the description covers ordering, pagination, timezone handling, date bounds, and data trustworthiness. The main remaining gap is that it never indicates what fields identify each returned subject, which an agent would need to know to use the response.

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, but the description adds constraints the schema does not state: dates are interpreted in the project time zone, to may not exceed the project's today, a range spans at most 400 days, and the project id's source is list_projects. These are substantive semantics beyond the field-level descriptions.

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 verb+resource: it returns the visits or identified people that reached a given funnel step, or dropped before it, newest first and paginated. That is far more than a restatement of the title. It does not, however, explicitly distinguish itself from sibling tools like funnel or funnel_segments, which likely return aggregated counts.

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 through the reached/dropped outcome and the 'one funnel step' framing, and it helpfully notes that project_id and the project's today come from list_projects. But there is no explicit statement of when to choose this over funnel/funnel_segments, nor any stated exclusions or prerequisites beyond that pointer.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed world), and the description adds real substance on top: results are auth-scoped to the token, timestamps carry the project's time-zone offset with a stated UTC fallback when the Node lacks the zone. That fallback is a behavioral quirk an agent could never infer from the schema.

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 core statement is front-loaded and the prerequisite rule follows logically. The closing ISO-8601 offset example is useful but verbose, making the third sentence heavier than it needs to be for what is essentially 'times are local with offset, or UTC if unknown'.

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 carries the burden of describing the return shape and does so field by field, including timestamp format and the UTC fallback. It leaves minor gaps such as result ordering and magnitude, but nothing an agent needs in order to call it correctly.

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 takes zero parameters, so the schema has nothing to explain and there is no parameter semantics to add. The baseline for a no-parameter tool 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 plus the scope restriction ('the Pyxis projects this token can read') and enumerates exactly what each entry contains. It also implicitly separates itself from the analytics siblings by declaring that 'every other tool takes a project id from here', so an agent knows this is the discovery root rather than another report.

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?

Gives an explicit call-order rule: take the project id from this list, and use dates no later than the project's today. That is strong prerequisite guidance, though it never states when this tool should not be used or what to do with zero visible projects.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds behavior the annotations cannot: the partial-day comparison rule for ranges ending today, a hard 400-day range cap, timezone semantics, and a data-fidelity caveat that event/page/property text is reported exactly as visitors submitted it (a real signal about unvalidated content).

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 with what the report returns, then comparison semantics, then input sourcing and constraints. Four compact sentences with no filler. The closing note on visitor-supplied text is slightly tangential but is a legitimate data-quality warning rather than padding.

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 carries the burden of describing returns and does so at the metric level, plus it covers the range cap, timezone, and comparison window. It stops short of describing the response structure (field names, grouping, pagination), which is the main residual gap for a report 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 coverage is 100% and each parameter is documented, so the baseline is 3. The description goes further by supplying constraints absent from the schema — the 400-day maximum range length, the 'at most today' upper bound, and the project-time-zone interpretation of the dates — which meaningfully changes how an agent constructs the call.

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 names the concrete outputs (visits, identified users, conversions, failed writes, daily activity, top pages and events) and the period-over-period comparison, which is far beyond restating the title 'Overview'. It does not, however, name or distinguish itself from near-siblings such as visits, engagement or acquisition, so an agent still has to infer the boundary.

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?

It gives one concrete routing hint — the project id and the project's 'today' come from list_projects — which is genuinely useful for chaining calls. But there is no statement of when to choose this report over visits, engagement or acquisition, and no exclusions; usage is implied rather than prescribed.

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 readOnly/idempotent/non-destructive, so the description earns credit for what it adds: timestamps are rendered in the project's time zone with an explicit UTC offset and fall back to +00:00 when the Node lacks the zone, and secret keys are never returned (only their creation dates). That privacy and formatting detail is real behavioral context an agent cannot get from 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?

One long run-on sentence packs a field inventory plus a timezone caveat; the scoping statement is front-loaded, but the comma-spliced field list is hard to scan and the offset example (2026-10-13T22:41:41.638-03:00) is verbose relative to the point it makes.

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?

There is no output schema, so the description carries the burden of declaring what comes back, and it does so field by field, plus the time-zone rendering rule and the secret-key exclusion. Missing only an auth/failure note (e.g., behavior for an unknown project_id) to be 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?

With one parameter at 100% schema description coverage, the schema already explains project_id ('from list_projects'), and the description adds nothing about it. Baseline 3 for a fully documented single 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?

The description identifies the resource ('the settings of one project') and enumerates exactly which settings are returned, which clearly separates it from the analytics siblings (visits, funnel, overview). It lacks an explicit verb, so the read intent is only implied, but the noun-plus-field-list makes the purpose unmistakable for an agent comparing siblings.

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 when-to-use or when-not-to-use guidance; the description never says 'call this to discover configuration before calling analytics tools' or names any alternative. The only routing hint ('from list_projects') appears in the parameter schema, not in the description.

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?

Beyond the read-only/idempotent annotations, it discloses important behavior: only events whose property is a JSON number count, figures are null when none qualify, 'by' returns the top 10 values plus other_count, and events lacking the property appear in overall only. It also states date bounds (to <= today, max 400 days) and warns that names/paths/values are visitor-supplied text.

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?

It is front-loaded with the core computation before filtering and date caveats, and each sentence carries information. The closing paragraph on visitor-supplied text is a bit of an aside but still earns its place as a data-provenance warning.

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 20-parameter aggregation tool with no output schema, the description explains the key result shape (overall.events, groups, other_count) and filtering semantics well. It stops short of describing the full output structure or parameter interactions for every visit filter, leaving some gaps.

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?

Despite 75% schema coverage, the description adds semantics the schema lacks: 'by' produces top-10 groups with an aggregated other_count, visit filters are conjunctive ('keep only the events of the visits that match all of them'), and the date/time-zone rules are spelled out. This meaningfully extends the parameter documentation.

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 gives a concrete computation (median, 25th and 75th percentiles of one numeric property of a named event) plus its scope (overall and split by another property), which lets an agent tell it apart from a plain counts tool. It never names a sibling, so differentiation is implicit rather than explicit.

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?

It frames the tool around concrete questions ('how long people read each article') and points to list_projects for the project id, which gives clear usage context. It offers no explicit when-not conditions or named alternatives among the many sibling report tools.

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?

While annotations cover safety, the description adds crucial behavioral context regarding timezone handling and the origin of the data. This informs the agent about the temporal constraints and data reliability of the 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 highly dense and verbose, but every sentence provides highly valuable operational or constraint information. It sacrifices conciseness for maximum functional clarity, which is justified by the complexity of the tool.

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 multi-faceted nature of the data (routes, screens, time zones, and call types), the description is exceptionally complete, leaving no ambiguity regarding the tool's scope or data origin.

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?

Despite 100% schema coverage, the description provides significant added meaning, defining the operational semantics of the 'reads' and 'writes' parameters, and setting strict temporal limits on the date parameters.

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 resource (site calls to the backend) and the granular data it returns (statuses, durations, error codes). It further differentiates the tool by detailing the specific metrics and scopes covered.

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?

It provides specific usage constraints, such as the date range limit (400 days) and the requirement that the project ID is derived from list_projects. It also defines the operational logic for the 'reads' vs 'writes' kind.

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 cover readOnly/idempotent/non-destructive/closed-world, so the bar is low, and the description adds real context: the 400-day range cap, dates in the project time zone, and a provenance caveat that event names, paths, property values, etc. are raw visitor-supplied text 'reported as it arrived.' That provenance warning is genuinely useful beyond the structured fields.

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 purpose sentence is front-loaded and each paragraph carries distinct information (what it is, parameter sourcing/constraints, data provenance). Slight waste in the awkward phrasing 'The visits of the range by the weekday,' but overall it is tight and well-ordered.

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 report with full schema coverage and annotations, the description covers purpose, constraints, and data caveats. With no output schema, it conveys the grouping shape (weekday × hour) but does not describe the returned fields or metrics, a minor remaining gap.

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. The description restates some schema facts (to at most today, project id from list_projects) but does add two details not in the schema: the project time zone and the 400-day maximum range. That is modest added meaning over the already-complete 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 names a concrete resource and breakdown dimensions: 'The visits of the range by the weekday and the local hour they started.' An agent can infer this is a time-of-day visit report, not a raw list. However, it never distinguishes itself from siblings like visits, overview, or engagement, which also surface visit 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?

Usage is only implied by the report's nature; there is no explicit 'use this when you want X, otherwise use visits/overview' routing. It does provide useful setup context (project id and today come from list_projects), but that is parameter sourcing rather than when-to-use 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 cover readOnly/idempotent/non-destructive, so the description uses its space well: it discloses ordering (newest first), page size (50), cursor-based pagination, time-zone offset behavior including a UTC fallback when the host lacks the zone, that city is null unless the project retains it, and that filterable text is visitor-supplied and reported verbatim. These are real behavioral traits an agent could not infer from structured fields.

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 with the core answer (what you get, in what order, at what page size), followed by constraints and then caveats. The opening sentence is long because it enumerates every returned field, which borders on dumping schema-level detail into prose, but nothing is truly redundant.

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 17-parameter, no-output-schema read tool, the description covers scope, ordering, pagination, time-zone semantics, and data-quality caveats. It stops short of explaining how next_cursor is surfaced in the response or how filters compose (AND vs OR), which an agent must know to page and combine filters correctly.

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 82%, so the schema already documents nearly every one of the 17 parameters, including the cross-field dependencies (city needs region, property needs event). The description adds only the provenance of project_id/today and the date format/limit, which is modest value on top of an already well-documented schema — baseline 3.

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 precisely what is returned: visits over a range, newest first, 50 per page, with an explicit enumeration of the fields each visit carries plus the match total. It is clearly a paginated visit-listing tool, distinguishable from aggregation siblings like acquisition or devices, though it never names a sibling to clarify boundaries.

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?

It supplies real operating context — project id and the project's today must come from list_projects, dates are YYYY-MM-DD in project time zone, to is capped at today, ranges max 400 days. What is missing is when-to-use-this-vs-alternatives guidance: an agent cannot tell from the description why it would pick visits over requests, visit_timeline, or acquisition.

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?

It goes significantly beyond the structured data by detailing behavioral constraints not captured in schemas or annotations, such as the sorting ('newest first'), pagination ('20 visits a page'), and how time is handled (project time zone vs. UTC offset).

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 quite dense and verbose, covering many details (data content, timezones, pagination, ID selection). While comprehensive, some sentences could be tightened without losing necessary context.

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 exceptionally complete, covering not just what is retrieved (events/visits), but also how the data is structured (country/region included, null handling for cities), how it's paginated, and the critical behavioral trait of time zone management.

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?

Although the schema is comprehensive (100% coverage), the description adds critical semantic meaning by clarifying that the input IDs ('session_id' or 'user_id') reference specific entities within the measurement system ('visits' or 'funnel_subjects').

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 purpose is clearly stated: to retrieve every event or visit for a specific user or session. It distinguishes itself by focusing on granular visit data rather than high-level summaries, which aligns with its functional scope compared to siblings like 'overview' or 'visits'.

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 strong usage guidance by explicitly stating the mutual exclusivity of inputs: 'It takes exactly one of session_id... or user_id.' This helps the agent avoid incorrect input combinations.

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