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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is fully covered. The description adds only the return shape (counts and drop-off rates), which the output schema already documents, so it contributes marginal behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences with zero filler; the core action and its output are front-loaded and nothing is wasted.

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 an output schema explaining returns and annotations covering the safety profile, the description need not restate those. It is nearly complete; the only gap is the absence of usage guidance relative to sibling funnel tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so parameters (steps, filters, dates, timezone) are already fully documented in the schema. The description mentions 'steps (page visits or events)' but adds no syntax or format detail beyond what the schema already states.

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 specific verb ('Analyze') and resource ('custom funnel') and clarifies the tool defines steps inline (page visits or events) and returns per-step visitor counts and drop-off rates. This clearly separates it from create/delete/list funnel siblings even though it never names them explicitly.

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 implies the tool is for an ad-hoc, inline-defined funnel rather than a stored one, but never states when to use it versus list_funnels or get_funnel_step_sessions, nor any prerequisites (e.g., a site must have data). No when-to-use or alternative routing is provided.

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

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

With annotations already declaring a non-read-only, non-destructive, non-idempotent write, the description adds real behavioral context: steps are evaluated in order and supplying reportId silently overwrites an existing funnel rather than creating one. That overwrite disclosure is important behaviour an agent would not infer from the annotations alone. It stops short of 5 because it says nothing about validation failures or permissions.

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 short sentences, front-loaded with the core action and then the two behavioural caveats. Every sentence earns its place with 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?

An output schema exists, so return values need not be explained, and the annotations cover the safety profile. The description supplies the essential create-vs-overwrite and step-ordering context, leaving only minor gaps such as error behaviour.

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 name, steps, siteId and reportId. The description re-states the reportId overwrite and step ordering, adding little beyond the structured fields; 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 verb and resource ('Save a new named funnel definition') and adds the evaluate-in-order and overwrite semantics, so an agent can distinguish it from rybbit_analyze_funnel or rybbit_create_goal. It does not explicitly name a sibling alternative, which keeps it just short of a 5.

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 implies two modes of use by describing the reportId branch ('overwrite that funnel instead of creating a new one'), giving useful conditional guidance. However, there is no explicit when-to-use/ when-not statement and no reference to sibling tools such as analyze_funnel or update paths.

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 declare this is a non-readOnly, non-idempotent, non-destructive, non-openWorld write operation, which is accurate. The description adds the meaningful distinction between path and event goals, but says nothing about auth requirements, whether goals can be duplicated, or what happens on conflict. It doesn't contradict 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?

Two short sentences, front-loaded with the core action and resource, then the key branching distinction. No waste.

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

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

Given a nested config object, enum goalType, 100% schema coverage, and an output schema, the description covers the essential branching. However, for a create/mutation tool it omits when to use it vs siblings and any prerequisite or conflict behavior. Adequate but with clear 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?

Schema coverage is 100%, so all four parameters (including the nested config object with its own descriptions and enum) are fully documented in the schema. The description mentions path vs event which maps to goalType, but adds no syntax or format details beyond what the schema already provides. 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?

States a specific verb (Create) and resource (conversion goal for a site), and distinguishes the two goal variants (path-based vs event-based). It doesn't explicitly differentiate from sibling tools like create_funnel or update_goal, but the resource is specific enough.

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 on when to use this versus update_goal, create_funnel, or list_goals. The description mentions two goal types but doesn't explain when each is appropriate beyond a one-line parenthetical. No prerequisites (e.g., site must exist) are stated.

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=false, idempotentHint=false and destructiveHint=false, so the mutation profile is known. The description adds a return-value note, but with an output schema present that is largely redundant, and it omits what an agent would want to know about duplicate domains or failure behavior for a non-idempotent create.

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 tight sentences, front-loaded with the action, then the type semantics, then the return value. No filler and nothing misplaced.

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 annotations, a full-coverage schema and an output schema, the description covers everything the agent needs to invoke the tool correctly. Minor gaps remain around organizational prerequisites and duplicate-handling behavior for a non-idempotent create.

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 enum semantics for 'type' and the organizationId lookup hint, so the schema already carries parameter meaning. The description restates the web/mobile/app type mapping rather than adding anything new, so the baseline of 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 verb and resource ('Create a new site in Rybbit') and immediately clarifies the resource's two variants. The operation is inherently distinct from siblings like delete_site, update_site_config and list_sites, but the description never explicitly differentiates itself from them.

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 useful guidance on how to choose the 'type' value (web for domains, mobile for package names), which is real usage help, but says nothing about when to create a site versus reusing an existing one or which organizational prerequisites apply. Usage is largely implied by the verb.

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 destructiveHint=true, readOnlyHint=false and idempotentHint=true, so the safety profile is covered structurally. The description adds the meaningful detail that deletion is permanent and irreversible, but says nothing about permissions, cascading effects, or error behavior on a missing ID.

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 sentences, with the destructive consequence front-loaded. Nothing is wasted and no reading is required past the first clause.

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?

An output schema exists so return values need not be described, and annotations carry the destructive/idempotent profile. However, for an irreversible mutation the description omits any note on required permissions or what happens if the funnel ID is invalid, leaving it minimally 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?

Schema description coverage is 100%: both siteId and funnelId are documented in the schema, including a pointer to rybbit_list_funnels for obtaining the ID. The description adds no parameter-level detail, so the baseline of 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?

Names a specific verb (delete) and resource (saved funnel) and states the effect is permanent. It is clearly distinguishable from siblings such as rybbit_delete_goal and rybbit_delete_site by resource, though it never explicitly contrasts them.

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 on when to use this versus alternatives such as archive/update, and no preconditions (permissions, confirmation) are stated. The only usage cue is the implied irreversibility of 'cannot be undone'.

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 destructiveHint=true and idempotentHint=true, so the safety profile is carried structurally. The description reinforces this with 'Permanently delete' and 'cannot be undone', but adds nothing about authorization requirements, behavior on a nonexistent goalId, or cascading effects on related goal/session records.

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 sentences with the destructive warning front-loaded in the first clause. Nothing is padded and nothing competes for attention.

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 two-parameter destructive tool with rich annotations and an output schema, the description is adequate but thin: it omits error behavior for an invalid or already-deleted goalId and any scoping/permission context. It is minimum viable rather than 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?

Schema description coverage is 100% and both parameters (goalId, siteId) carry their own descriptions, so the schema does the heavy lifting. The description mentions neither parameter and adds no format or constraint detail beyond the schema; 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?

The description gives a specific verb and resource ('delete a goal'), which cleanly separates it from sibling mutators like rybbit_delete_site and rybbit_delete_funnel. It does not, however, explicitly contrast itself with those siblings or with rybbit_update_goal; it relies on the tool name for 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?

There is a warning that the action is permanent, but no guidance on when to choose this over alternatives (e.g. rybbit_update_goal to modify rather than remove), no prerequisites, and no note about what happens to associated goal session data. The agent gets a warning but no routing logic.

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 destructiveHint=true, readOnlyHint=false and idempotentHint=false, so the safety profile is covered. The description adds genuinely non-redundant context beyond that: the deletion is permanent and cascades to replay data, telling the agent exactly what is destroyed.

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 short sentences, front-loaded with the action and impact, with the ID-lookup pointer last. 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 destructive single-parameter tool with an output schema and full annotation coverage, the description supplies the one thing the structured fields do not: the permanence and data-loss scope. Only auth/confirmation requirements are left unstated.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the single siteId parameter (numeric ID or domain identifier) is already fully documented. The description only points to sibling tools for finding the ID, which is useful routing but adds no format or constraint detail beyond the schema; 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?

"Delete a site from Rybbit" is a specific verb + resource, and the follow-up sentence sharpens the scope by naming what is removed (the site and its replay data). It is trivially distinguishable from sibling mutators like rybbit_delete_goal or rybbit_delete_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?

It gives a clear prerequisite/context: use rybbit_list_sites or rybbit_get_site_id to obtain the site ID before calling. There is no explicit when-not-to-use guidance or named alternative deletion path, so it stops short of a 5.

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 safety profile is covered. The description adds genuinely valuable behavioral context beyond that: it discloses that some dimensions are 'silently stripped due to upstream bugs' and that alternative tool suggestions are provided. It omits return format, but that is carried by the output 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?

Two sentences, zero waste, and the payload of what is returned is front-loaded before the timing advice. Every clause 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?

An output schema exists so return values need no explanation, and the description still summarizes the returned content (native support, stripped dimensions with alternatives, example values). Nothing an agent needs in order to call it correctly is missing.

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 a single parameter at 100% schema description coverage, the schema already documents the dimension name, case-sensitivity, and examples. The description's examples ('event_name', 'pathname', 'country') largely restate the schema, adding marginal value, 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 verb and resource ('look up which tools accept a given filter dimension') and enumerates the three things it returns: native support, silent stripping plus alternatives, and example values. No sibling tool performs this lookup, so it is unambiguous in context.

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

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

Explicitly says 'Use this before constructing a complex filters[] array,' giving a clear trigger condition. It does not name exclusions or a fallback for simple, non-array filters, but the positive guidance is unambiguous.

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, idempotentHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered. The description adds nothing beyond that (no scope, no auth requirements, no caching notes), but the bar is low given complete annotations and an output 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?

A single front-loaded sentence with no filler; every word earns its place for a no-argument 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?

An output schema exists, so the return shape need not be described, and annotations cover the safety semantics. For a zero-parameter read tool the description is sufficient, though one line on what 'configuration' entails would make it airtight.

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 baseline is 4. There is nothing for the description to document beyond the fact that the call is parameterless.

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 (get) and resource (Rybbit server version and configuration), which is clear and distinguishable from the analytics siblings like rybbit_get_overview. It does not explicitly differentiate itself from the similarly named rybbit_update_site_config, but the read vs. update verbs make the split inferable.

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 explicit when-to-use or when-not-to-use guidance, but usage is strongly implied for a no-argument diagnostic tool: call it to inspect server version/config. It offers no alternatives or preconditions, leaving the agent to infer the 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 already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds the non-obvious prerequisite that errorMessage is only obtainable after calling type='names', a behavioral dependency beyond the annotations. It does not add much else (pagination, output shape), which is expected with a rich schema and output 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?

A single front-loaded purpose clause followed by a tight three-step workflow; every clause earns its place. It is dense rather than padded, though the workflow duplicates schema-level requirements.

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 12-parameter, 3-mode tool that has an output schema and 100% schema coverage, the description supplies the mode-selection logic the schema cannot express. Date-range, bucket, filter and pastMinutes semantics are left to the (well-documented) schema, so nothing critical is missing.

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 the schema already documents the type enum and that errorMessage is required for events/timeseries and should be discovered via names. The description restates that dependency but adds no syntax or format detail beyond the schema, 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 verb+resource ('Get error tracking data') and immediately breaks the resource into its three concrete query modes (names/events/timeseries), so an agent knows exactly what the tool returns and can tell it apart from the many event/performance/overview analytics 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?

The numbered workflow is explicit when-to-use guidance for each mode: names to discover error types, then events or timeseries with errorMessage. It also encodes the required ordering (discover names first), which is precisely the kind of routing an agent needs.

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 safety (readOnly, idempotent, non-destructive). The description adds genuinely useful non-annotation behavior: the scan is capped and `hasMore: true` signals an incomplete result, with the remedy (narrow window or raise maxScan). That is exactly the kind of caveat an agent needs before trusting counts.

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 operation then the filtering/grouping order, then the output contract and its caveat. The embedded return-shape JSON is somewhat lengthy and partly redundant with the output schema, but it is compact and the hasMore caveat justifies its presence.

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 12-parameter analytics tool with a full output schema and read-only annotations, the description covers operation, filter order, and the result-truncation caveat. Since an output schema exists, restating the return shape is optional rather than required, so this is complete without being maximal.

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 a 3 is the baseline. The description earns above baseline by explaining the maxScan/hasMore interaction, which the per-parameter docs do not state, and by illustrating groupBy dimension syntax (properties.<name>) in context.

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 (aggregate) plus resource (events) and the mechanism (groupBy dimensions, event_name filter), which is precise enough to distinguish it from get_metric or get_event_timeseries. It stops short of naming the sibling tools it should be chosen over, so it lands just below the top band.

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 grouping/filtering description and the hasMore guidance gives a corrective action, but there is no explicit statement of when to choose this over sibling aggregates like rybbit_get_metric, rybbit_get_event_timeseries, or rybbit_get_event_properties. Adequate but leaves routing to inference.

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 this a safe, read-only, idempotent, closed-world operation, so safety disclosure is covered. The description adds that results include occurrence counts, but says nothing about the time window behavior (defaults for startDate/pastMinutesStart), result limits, or pagination for what is effectively an enumeration endpoint.

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 sentences, the core behavior front-loaded and no filler. The second sentence is a light restatement of the value of the occurrence counts, but it does add intent rather than pure 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?

An output schema exists so return shape needn't be explained, all seven parameters are documented in the schema, and annotations cover the safety profile. What remains thin is positioning relative to the many event-related siblings, which is a usage-guideline gap rather than a completeness one.

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 the description adds nothing param-specific, so the baseline applies; the phrase 'for a site' loosely signals siteId as the key input. The richer filter/date semantics live in the schema, which is adequate here.

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 ('Get all custom event names and their occurrence counts for a site'), which is enough to distinguish it from the aggregate/property/timeseries siblings by content. It stops short of explicitly naming which sibling to prefer, but the resource is 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?

'Useful for discovering what events are being tracked' gives an implied discovery use case, but there is no when-to-use vs. when-not guidance and no reference to alternatives like rybbit_list_events, rybbit_get_event_properties, or rybbit_get_event_aggregate, which an agent would plausibly confuse this with.

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 this a read-only, idempotent, non-destructive, closed-world operation, so the safety profile is covered. The description adds the output shape (distinct keys/values with counts), but says nothing about date-range defaults, filter scope, or pagination behavior for what is effectively an analytical read.

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 tight sentences, front-loaded with the action and followed by the return format. No filler or redundant restatement of the title.

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 a full input schema, an output schema, and complete annotations, the agent has enough to invoke correctly; the description need not explain return values. It is slightly thin on scoping behavior (time window, filter effects), but nothing essential is missing.

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 rich filter/enum documentation, so the schema does the heavy lifting and the baseline is 3. The description adds no parameter-level meaning (e.g., how filters constrain the property breakdown, or date vs pastMinutes precedence) beyond what the schema already spells out.

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 ('Get property breakdowns for a specific custom event') and clarifies the return contents ('distinct property keys and values with counts'). It is distinguishable in intent from siblings like get_event_aggregate or get_event_names, though it never explicitly names those alternatives.

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 when-to-use or when-not-to-use guidance, and no routing to alternatives such as get_event_names (to discover events) or get_event_aggregate (for totals). Usage can only be inferred from the phrase 'for a specific custom event'.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered externally. The description adds only that buckets are configurable and that this is for trend analysis, with no mention of default time windows, pagination, or data volume concerns.

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 sentences with the core capability front-loaded and zero filler. It is efficient, though it could have used the second sentence for routing information rather than a restatement of the obvious analytics use case.

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?

An output schema exists, so return values need not be explained, and the rich schema covers parameters. However, for a tool with 8 parameters, a filter system, and several near-identical timeseries siblings, the description omits the selection guidance an agent needs to pick 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 100%, so every one of the 8 parameters is already documented (enums, filter dimensions, pastMinutes alternatives). The description adds no parameter-level detail beyond that, which is the expected baseline when the schema carries the full burden.

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 ('get custom event counts as time-series data') along with a scope qualifier ('configurable buckets'). This distinguishes it reasonably from siblings like rybbit_get_event_aggregate and rybbit_get_overview_timeseries, though it never names those siblings explicitly.

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?

Only 'Useful for analyzing event trends over time' is offered as context. That is implied usage rather than explicit when-to-use guidance, and there is no indication of when to prefer this over rybbit_get_event_aggregate or rybbit_get_overview_timeseries.

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 safety profile is covered. The description adds useful behavioral detail about the grouping key (identified_user_id + traits.username), but says nothing about scan limits (maxScan) or how anonymous users are handled.

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 short sentences, with purpose and grouping front-loaded. The closing Czech example question is slightly unusual but functions as a compact use-case anchor 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?

An output schema exists, so return-format explanation is unnecessary, and parameter coverage is complete. Given that, the description is adequate, though it could mention defaults (topN=25, identifiedOnly=true) that affect the result.

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 all 11 parameters are already documented in the schema. The description only supplies example event names, adding little beyond the schema's own eventName description; baseline 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?

States a specific verb and resource ('Returns the top users for a given event') with concrete examples of the ranking (who sent the most pm_sent, who clicked the most ad_click). The grouping detail (identified_user_id + traits.username) helps separate it from aggregate-style siblings, but no sibling is named explicitly.

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

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

Provides example questions the tool answers ('kdo dnes poslal nejvíc vzkazů'), which implies usage, but offers no explicit when-to-use vs when-not guidance and does not point to alternatives like rybbit_get_event_aggregate or rybbit_get_user_event_breakdown.

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, and closed-world, so the safety profile is fully covered. The description adds no further behavioral context such as pagination behavior, result size, or what a session record contains, leaving it at the minimum viable level.

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 sentences, purpose front-loaded, zero filler. Nothing to trim.

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?

An output schema exists, so return values need not be described. But for a 12-parameter, 4-required analytics tool, the description omits any mention of the mode/steps requirements or how this relates to the funnel-analysis workflow, leaving the agent to rely entirely on the schema.

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 the crucial mode enum ('reached' vs 'dropped') and the steps array definition, so the baseline is 3. The description contributes nothing about parameters beyond what the schema already documents.

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: 'Get the sessions that reached (or dropped off at) a specific funnel step,' which is concrete and distinguishable from list_sessions or analyze_funnel. It does not, however, explicitly contrast itself with the closest siblings (rybbit_analyze_funnel, rybbit_get_goal_sessions), 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?

'Useful for drilling into why users drop off at a particular funnel step' gives an implied usage context — post-funnel-analysis drill-down. But there is no explicit when-to-use/when-not framing and no named alternative; the only sibling linkage is the schema note that steps match rybbit_analyze_funnel.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds no behavioral context beyond annotations, such as pagination behavior, default ordering, or whether the goal must exist, leaving it at the minimum-viable level.

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 sentences, purpose front-loaded, no wasted words. It is efficient but very sparse given the tool's parameter richness.

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?

An output schema exists, so return-value explanation is unnecessary, and the schema fully covers parameters. For a straightforward read-only analytics query, the description plus structured fields is sufficient, though it could say more about when this beats sibling session tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema fully documents all 10 parameters, including goalId's pointer to rybbit_list_goals and the filter dimension list. The description adds no parameter meaning beyond this, 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 verb and resource ('Get sessions') plus a scope qualifier ('that completed a specific goal'), which distinguishes it from rybbit_list_sessions. It does not explicitly name siblings, but the goal-scoping makes the 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?

'Useful for analyzing which users and sessions triggered goal conversions' implies a use case but gives no when/when-not guidance or alternative routing (e.g., use rybbit_list_goals first, or use list_sessions for unfiltered data). Usage 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds that output is sequences of pages plus session counts per path, which is useful framing, but says nothing about cost, result size caps, or how the steps/journeyLimit interact at runtime.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the core action, no filler. The second sentence slightly restates the first (navigation paths vs sequences of pages) but does add the session-count dimension, so it 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?

The output schema exists, so return-value explanation is not required, and annotations cover safety. What is missing is routing guidance against the many sibling analytics tools (funnels, retention, metrics), which matters for a 9-parameter tool whose selection is ambiguous.

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 parameter meaning is fully documented in the schema (steps default 3, journeyLimit default 100, full filter dimension list, date and pastMinutes fields). The description adds no syntax, default, or interaction detail beyond that, 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 verb (Get) and resource (user journeys) and explains the analysis: navigation paths, page sequences, and session counts per path. This is clearly a flow/journey tool, though it never explicitly contrasts itself with the funnel siblings (analyze_funnel, get_funnel_step_sessions) that could also describe path-like 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?

No when-to-use statement, no prerequisites, and no alternatives named. The agent must infer from the sibling list whether journeys or funnels is the right tool when investigating drop-off or navigation behavior. Only the implicit framing as 'flow analysis' hints at usage.

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, closed-world behavior, so the safety profile is covered. The description adds the return shape (sorted list with counts, percentages, bounce rate, session duration), but that largely duplicates the existing output schema and omits pagination/limit behavior. Adequate, not rich.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the core action, followed by a dense but purposeful dimension map. No filler or restatement of the tool name; every clause carries routing 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 an output schema, rich annotations, and full schema coverage, the description needs only to establish purpose and dimension routing, which it does. Minor gap: no mention of pagination defaults or how filters interact with the breakdown, though those are schema-documented.

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 every parameter and the baseline would be 3. The description earns a notch above by adding semantic grouping of the `parameter` enum values into analytic categories, which gives the agent practical meaning beyond the raw enum list.

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+resource ('Get metric breakdown by dimension') and then enumerates the concrete dimension values grouped by analytic intent (pages, tech, geo, marketing, traffic, flow). An agent can tell this apart from siblings like rybbit_get_event_aggregate or rybbit_describe_dimension without opening the schema.

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 explicit routing logic: which parameter value to use for each analysis goal ('pathname' for top pages, 'country'/'city' for geo, etc.). This is genuine when-to-use guidance. It does not, however, state when NOT to use this tool or name a preferred alternative for overlapping cases (e.g., describe_dimension or event aggregates).

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 this is a safe read-only, idempotent, non-destructive operation, so the safety burden is covered. The description adds a small amount of behavioral context (it is click-tracking data about external URLs), but discloses nothing about scoping, empty results, or aggregation behavior beyond what the annotations and output schema 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?

Two short sentences with no filler, front-loading the core action and then the interpretation of the result. Efficient and well-ordered, though the second sentence borders on restating the first.

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 100% schema coverage, full annotations, and an output schema, most of the callable surface is already documented. What remains missing is usage context (when to reach for this over sibling metrics), which keeps it at a minimally adequate level rather than 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?

Schema description coverage is 100%, so all nine parameters (siteId, date range, pagination, filters, timezone) are fully documented in the schema itself. The description adds no extra meaning about parameter usage, so the baseline of 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?

The description states a specific verb and resource ('Get outbound link clicks tracked on the site') and adds clarifying scope ('which external URLs users are clicking and how often'). It is clear what the tool returns, but it never distinguishes itself from the many sibling analytics tools (e.g., rybbit_get_metric, rybbit_get_page_titles), so sibling differentiation is absent.

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 guidance on when to use this tool versus alternatives such as rybbit_get_metric or rybbit_get_page_titles, nor any prerequisites or exclusions. The description only says what it fetches, leaving tool selection entirely to inference from the name.

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 this as a read-only, idempotent, non-destructive operation, so the safety profile is covered. The description adds only that date ranges and filters are supported, which the schema also conveys, and offers no extra behavioral context such as aggregation granularity or default time window.

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 tight sentences, metric list front-loaded after the purpose, with no redundant or filler content.

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 an output schema present and full schema description coverage, the description does not need to explain return values or parameters. It names the metrics returned and notes range/filter support, which is sufficient for correct 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?

Schema description coverage is 100%, including detailed filter dimension and operator docs, so the schema carries the parameter burden and baseline 3 applies. The description adds no format or syntax detail beyond 'date range and filters.'

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+resource ('Get aggregated overview metrics for a site') and enumerates the returned metrics, so the agent knows exactly what it produces. It does not, however, distinguish itself from close siblings like rybbit_get_overview_timeseries or rybbit_get_metric, leaving the boundary to inference.

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 only guidance is 'Supports date range and filters,' which describes capability rather than when to choose this tool over the many sibling analytics tools. There is no stated when-to-use, when-not-to-use, or named alternative.

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, non-destructive, and closed-world behavior. The description adds only that output is arrays of data points for charting, which is partly redundant with the output schema. No other behavioral traits such as auth, rate limits, or data retention are mentioned.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the core action and resource, and no wasted words. The return-shape note is brief and earns its place.

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

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

Given the 100% schema coverage, rich parameter descriptions, and an output schema, the description covers the essential purpose and bucket configurability. It does not explain filter/date/past-minute usage, but the schema compensates. Minor gaps remain around sibling selection.

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 eight parameters in detail. The description mentions configurable buckets, but its list is incomplete compared to the schema enum, and it adds no meaning beyond what is already in the parameter 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 and resource: 'Get overview metrics as time-series data'. It distinguishes the time-series shape from a plain summary, but does not explicitly name sibling tools like rybbit_get_overview or rybbit_get_event_timeseries.

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

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

No explicit when-to-use guidance or alternatives are provided. The phrase 'for charting trends' implies a use case but does not tell an agent when to choose this tool over rybbit_get_overview or rybbit_get_event_timeseries.

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 and destructiveHint=false, so the description only needs to add analytical context. It does: the result is ranked by viewership and split into pageviews vs unique sessions, which tells the agent what the output means. It does not mention result limits or default time window, but with an output schema present that is minor.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, zero filler, with the core purpose front-loaded and the sibling comparison second. Every clause 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 a rich output schema, full parameter documentation, and read-only annotations, the description needs only to convey purpose and routing, which it does. It could note the default time window or result-count behavior, but nothing critical for correct invocation is missing.

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% across all 7 parameters, so the schema fully documents siteId, date ranges, filters, and timezone. The description adds no parameter-level detail, which is acceptable given the schema does the work, but it means 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?

States a specific verb and resource ('Get the most-viewed page titles for a site') plus the breakdown dimensions (pageviews, unique sessions). It explicitly distinguishes itself from the sibling rybbit_get_metric, so an agent can select it correctly without opening either schema.

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?

Names the alternative (rybbit_get_metric with parameter='pathname') and the condition that selects this tool: when a human-readable title is wanted instead of just the path. No explicit exclusions or prerequisites are given, but the routing guidance is clear.

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

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

Annotations already declare this as a safe, idempotent, read-only operation, so the safety profile is covered. The description adds useful behavioral context by naming the exact statistics computed (p50/p75/p90/p99) and the available groupings, but it says nothing about default time window behavior, permission requirements, or result volume.

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 tightly written sentences with zero filler; the metric set and percentiles are front-loaded, and the optional breakdown is stated last where it belongs. Every clause carries 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 an output schema present, the description need not explain return values, and the annotations cover the safety profile. It adequately conveys what is measured and how results can be segmented, though the absence of any time-range hint (despite startDate/endDate/pastMinutes params) is a minor 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 all 8 parameters are already documented in the schema, including the filter dimensions and timezone handling. The description's mention of breakdown dimensions only echoes the existing 'dimension' enum values, adding no new syntax or format detail, 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 verb and resource ('Get Core Web Vitals performance metrics') and enumerates the exact metrics (LCP, CLS, INP, FCP, TTFB) plus the aggregation granularity (p50/p75/p90/p99). It does not, however, differentiate itself from the closely named sibling rybbit_get_performance_timeseries, so an agent must infer the distinction (snapshot percentiles vs. time series).

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

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

The phrase 'Optionally break down by page path, browser, or OS' implies when to use the dimension parameter, but there is no explicit guidance on when to choose this tool over rybbit_get_performance_timeseries, rybbit_get_metric, or rybbit_get_overview. Usage is implied rather than stated.

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 and destructiveHint=false, so safety is fully covered structurally. The description adds the trend/time-series framing but says nothing about bucketing behavior, date-range defaults, or the pastMinutes* alternative to date parameters, so it adds only modest context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with zero filler, so nothing needs trimming. It is slightly thin for an 8-parameter tool, but there is no redundancy or waste to penalize.

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 an output schema present and 100% schema coverage, the description does not need to explain return values or parameters, and its purpose statement is sufficient to call the tool. The main remaining gap is that it never positions itself against rybbit_get_performance in a large sibling set.

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 eight parameters, including bucket granularity, filters, timezone, and the pastMinutesStart/pastMinutesEnd date alternative. The description adds no parameter-level meaning beyond that, which is the baseline case.

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 (get), a specific resource (Core Web Vitals performance metrics), and the output shape (time-series data for trend analysis). It implicitly distinguishes itself from the sibling rybbit_get_performance (aggregate vs. time series) but never names that sibling explicitly.

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?

"For trend analysis" implies the usage context, but there is no explicit when-to-use vs. when-not, no mention of the aggregate sibling rybbit_get_performance, and no guidance on choosing bucket granularity even though the schema enumerates nine options.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful semantics (cohort retention over time) but says nothing about date-range requirements, granularity, or how start/end dates interact with the pastMinutes alternatives.

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 front-loaded sentence with no filler; the core purpose and output meaning are stated immediately.

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?

An output schema exists, so return-value explanation is unnecessary, and the schema documents all inputs. The only gap is guidance on the temporal scope and how date parameters are expected to be used for a cohort analysis, which is minor.

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 seven parameters (siteId, date range, timezone, filters, pastMinutes overrides) are already fully documented in the schema. The description adds no parameter-level meaning of its own, which is acceptable given 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?

States a clear verb and resource ('Get user retention cohort analysis') plus the semantic content of the output ('how many users return over time periods'). It is distinguishable from analytics siblings like rybbit_get_overview or rybbit_analyze_funnel, but it never names or contrasts with those alternatives.

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 guidance, no prerequisites, and no mention of how this differs from funnel, session, or overview tools in the sibling list. The agent must infer the use case entirely from the phrase 'cohort 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 already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is fully covered. The description adds the prerequisite workflow (list first) but doesn't mention output shape or pagination, though an output schema exists and covers returns.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences: the first lists contents, the second gives the ordering prerequisite. Front-loaded and 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?

For a simple read tool with full annotation coverage, complete schema, and an output schema, the description plus structured fields suffice. The only minor gap is not mentioning rate limits or latency, but that's not expected here.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% for both parameters (siteId and sessionId) with clear descriptions. The description adds no parameter-level meaning beyond what the schema already documents, so baseline 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?

States a specific verb (Get) and resource (session information) with enumerated contents including page views, events, user traits, device, location, and timeline. Clearly distinguishable from siblings like rybbit_list_sessions or rybbit_get_session_locations, though the enumeration is somewhat listy.

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

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

Explicitly directs the agent to use rybbit_list_sessions first to find session IDs, which is a concrete workflow prerequisite. No explicit exclusions or when-not-to-use guidance, but the prerequisite is actionable.

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, and destructiveHint=false, so the safety profile is fully covered by structured fields. The description adds the shape of the payload (lat, lon, city, country, session count) but nothing about scoping, grouping, or pagination behavior beyond what the schema carries.

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 tight sentences, zero padding, with the core capability front-loaded before the return-value detail. Nothing in it is wasted.

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 an output schema present, annotated read-only behavior, and full schema coverage across 9 parameters, the description supplies everything needed to decide to call it and what to expect. Only the lack of sibling routing keeps it from 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% and the rich filters parameter documents its own dimensions and operators, so the schema does the heavy lifting. The description adds no parameter-level detail (e.g., how siteId or the pastMinutes range pairs are used), which is the expected baseline 3 when coverage is complete.

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 ('Get geographic session location data with coordinates') and enumerates the returned fields, so the agent knows it is about geo-located session aggregation rather than raw session listing. It does not explicitly differentiate itself from siblings like rybbit_list_sessions or rybbit_get_metric, which slightly caps the score.

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 'for map visualization and geographic analysis' implies the intended use case but stops short of stating when to pick this over rybbit_get_metric or rybbit_list_sessions, and offers no exclusions or prerequisites. Usage is inferable rather than explicit.

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 safety profile is covered. The description adds real behavioral value by disclosing the return type (numeric) and the important cross-tool nuance that SDK tracking uses a different, hash-form siteId from rybbit_create_site.

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 tight sentences: purpose first, return value second, caveat last. No filler, and the most decision-relevant routing note is retained rather than padded.

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

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

For a single-parameter, read-only lookup with an output schema and full annotation coverage, nothing an agent needs in order to call it correctly is missing; return-format detail is legitimately delegated to the output schema.

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?

Only one parameter with 100% schema description coverage, including the partial-match behavior, so the schema does all the work. The description adds no syntax or matching detail beyond it, making the baseline 3 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?

States a specific verb and resource ('look up a site by domain name') and clarifies the return value ('numeric siteId'). The note explicitly distinguishes this tool's output from the hash siteId produced by rybbit_create_site, though it does not differentiate from rybbit_list_sites, which also surfaces 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?

Gives clear context ('used for analytics API queries') and an explicit when-not with the named alternative for hash-based SDK tracking setup. It stops short of stating when to prefer this over rybbit_list_sites or whether it must be called before other siteId-taking 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds the categories of data returned, but since an output schema exists this is marginal added value rather than deep behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single efficiently written sentence that front-loads the operation and the resource. Every clause earns its place by enumerating the returned content without 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?

For a two-parameter read tool with a rich output schema and full annotation coverage, the definition supplies enough to call it correctly. The only meaningful gap is routing guidance against overlapping user-detail siblings, which is minor given the low complexity.

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 both parameters (siteId, userId) are documented in the schema, including alternate identifier forms. The description adds no syntax or format detail beyond what the schema already provides, so 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 verb and resource ('Get detailed information about a specific user') and names the content returned (traits, session history, activity summary). It implicitly distinguishes from list_users by requiring a specific user, but does not differentiate from siblings like rybbit_get_user_traits or rybbit_list_sessions that cover overlapping slices.

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, no prerequisites, and no mention of alternative tools such as get_user_traits or get_session. The name implies a detail lookup, but nothing routes the agent among the many user-related siblings.

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, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely useful behavioral context beyond them: the userId parameter resolves either a device hash or an app-provided identified_user_id, and both are checked. It does not discuss pagination or result limits, but no false claims are made.

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 action and output shape, followed by the ID-resolution note and a usage hint. Efficient overall; the trailing 'etc.' example clause is slightly loose but still earns its place by illustrating the event_name dimension.

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?

An output schema exists, so return values need not be explained, and the annotations cover safety. The description supplies the essential per-user framing and ID semantics; the only gap is the absence of any routing guidance toward the many sibling event/user tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all eight parameters including the dual meaning of userId. The description restates the userId resolution behavior, which reinforces but does not extend the schema, and says nothing about filters, date windows, or pastMinutes alternatives. Baseline 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 states a specific verb+resource: 'Get event count breakdown for a specific user' and clarifies the output shape ('how many times each event_name was triggered'). It is clear without opening the schema, though it never names the sibling tools it must be distinguished from (e.g. rybbit_get_event_aggregate, rybbit_get_event_user_leaderboard), 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?

'Useful for analyzing per-user behavior like ad_click, chat_message_sent, etc.' gives implied usage context and example events, but there is no explicit when-to-use/when-not and no mention of the sibling tools that also aggregate events. Usage is suggested 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 readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is fully covered without the description. The description adds the per-day aggregation grain, which is genuine behavioral context, but says nothing about pagination, empty-day behavior, or timezone effects. Adequate but not rich.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, zero filler, and the core operation is front-loaded before the use-case example. Nothing is repeated from the title or schema.

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?

An output schema exists, so return-value shape need not be explained. However, for a 7-parameter tool with an uncovered pastMinutes pair and timezone semantics, the description does not say how relative-minute ranges interact with startDate/endDate. It is enough to call the tool correctly for the common case, not for the full parameter space.

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 71%, so most parameters (siteId, userId, dates, timezone) are documented in the schema itself. The description adds only an implied time-range constraint ('across the requested time range') and gives no clarification of the ambiguous pastMinutesStart/pastMinutesEnd pair, which are the only undocumented parameters. Baseline 3 fits.

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: 'per-day session count for a single user across the requested time range.' The per-day granularity and single-user scoping make the operation concrete. It stops short of naming the nearest siblings (get_user_event_breakdown, get_user_traits) that an agent would otherwise have to differentiate by schema alone.

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 clause 'Useful for plotting user engagement intensity (calendar heatmap or sparkline)' gives one intended context, so usage is implied rather than explicit. There is no guidance on when to prefer this over get_user_event_breakdown, list_sessions, or get_retention, which is a real gap given the crowded user/session 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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral detail beyond them: case-insensitive matching in users mode and the implicit mode-default logic. It doesn't mention pagination behavior despite the limit parameter.

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 short sentences, front-loaded with the overall purpose, then one clause per mode. No filler or repetition; every sentence carries distinct 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?

An output schema exists, so return-value detail is not required, and annotations cover safety. The description covers all modes and their triggers, leaving only sibling differentiation (vs. rybbit_get_user / rybbit_list_users) unaddressed.

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 the schema already documents mode semantics, key/value requirements, and limit. The description restates the mode/key relationship, adding only the case-insensitivity note for value matching, so baseline 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?

States a specific verb (Get) and resource (user trait keys/values/users), then enumerates the three operating modes so an agent knows exactly what surface the tool covers. The functional scope is unambiguous even without naming a sibling.

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 explains when each mode applies and even documents the default resolution rule ('values' when key is provided, otherwise 'keys'). What's missing is routing against siblings like rybbit_get_user or rybbit_list_users, which could plausibly overlap.

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 safety is covered. The description adds genuine behavioral nuance: that event_name filtering narrows to matching events rather than whole sessions, which is not expressible via 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?

Three sentences, front-loaded with purpose, then filter caveat, then pagination recipe. No filler and each sentence carries actionable 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?

An output schema exists, so return values needn't be re-explained, and the description still summarizes them. For a 12-parameter filtered-list tool with full schema coverage, it is complete; only explicit sibling disambiguation is absent.

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 baseline is 3. The description goes beyond by tying beforeTimestamp to the prior response's cursor.oldestTimestamp and spelling out the event_name-vs-filters distinction, adding cross-parameter semantics the schema does not state.

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 ('List raw events for a site') and enumerates the returned record shape. The word 'raw' implicitly distinguishes it from aggregate siblings like get_event_aggregate, but no sibling is named explicitly.

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 concrete mechanics — event_name filtering returns only matching events, and beforeTimestamp/cursor.oldestTimestamp drives backward pagination. However, it never says when to choose this over list_sessions or the event-aggregate tools, so sibling routing is left to inference.

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 and determinism are covered. The description's only added behavioral note is that step definitions come back with each funnel, which is modest extra context; nothing about pagination, ordering, or empty-state behavior.

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 sentence, front-loaded with the verb and resource, with no filler. Every clause 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?

An output schema exists, so return-shape detail is not required, and with a single fully documented parameter this definition is nearly sufficient. The only gap is not routing the agent away from the similarly named analyze_funnel sibling.

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 siteId is fully documented in the schema as a numeric ID or domain identifier, so the baseline applies. The description adds no format, default, or filtering semantics beyond what the schema already states.

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 (List) and resource (saved funnels) plus scope (for a site) and return content (step definitions). It is readable against most siblings, though it doesn't explicitly distinguish itself from rybbit_analyze_funnel or rybbit_create_funnel, which an agent may conflate.

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?

"List all saved funnels" implies a discovery/configuration-reading context, but there is no explicit when-to-use guidance and no mention of alternatives such as analyze_funnel for metrics or create_funnel for adding one. Usage is only inferable.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered without the description. The description adds only that conversion metrics and configuration are included in the result, which is thin given an output schema exists.

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 sentence, front-loaded with the verb and resource, and no filler. It could arguably be tightened further or expanded to mention filtering, but 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?

For a read-only list tool with a full output schema, complete input schema coverage, and clear annotations, the definition is sufficient to invoke correctly. The only omission is any mention of the filter capability, which the schema fully documents, so it is a minor 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%, including the detailed filter dimension enumeration and date/timezone formats, so the schema carries the full parameter burden. The description adds nothing beyond a site scoping hint, making the baseline 3 correct.

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?

Clear verb (List) plus resource (goals), scoped to a site, and states the returned content ('current conversion metrics and configuration'). It does not explicitly differentiate itself from siblings like rybbit_get_goal_sessions or rybbit_list_funnels, but an agent can tell what it retrieves.

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 when-to-use guidance and no alternatives named. With create_goal/update_goal/delete_goal/get_goal_sessions as siblings, the description never says when listing is the right choice versus calling rybbit_get_goal_sessions for per-session data.

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 readOnly/idempotent/non-destructive, so the bar is lower. The description adds genuinely useful behavioral context: the enumerated return fields, the conditional presence of IP address gated on the site's trackIp setting, and the caveat that IP filtering happens client-side. These are traits an agent cannot infer from the annotations or schema alone.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the core action and followed by the return-shape detail. Dense but every clause adds information; no filler or restated title.

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 an output schema present, the description needn't document return values in depth, yet it summarizes them usefully. All 12 parameters are covered by the schema at 100% coverage, and the description adds the one non-obvious behavioral constraint (trackIp-gated IP field, client-side filtering). Nothing an agent needs to call this correctly is missing.

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 12 parameters thoroughly, including the filter enum values and parameter dimensions. The description's only additional param-related signal is the client-side nature of IP filtering and the trackIp prerequisite, which is marginal over the schema. Baseline 3 applies when the schema carries the load.

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 ('List sessions for a site') plus scope modifiers (filtering, pagination). An agent can distinguish it from the singular sibling rybbit_get_session by the plural session scope, though the description never names that sibling explicitly.

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 ('for a site with filtering and pagination') but there is no explicit when-to-use vs. when-not guidance or reference to the alternative rybbit_get_session for a single session. It notes the client-side IP filtering capability, which hints at a use case but does not route the agent between 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?

The annotations already declare readOnlyHint, idempotentHint, non-destructiveHint and a closed world, so the safety profile is covered. The description adds one genuine piece of context the annotations do not: results are constrained to what the authenticated user can access. It says nothing about ordering, aggregation across organizations, or pagination.

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 front-loaded sentence with no filler; the scope constraint is embedded rather than buried after preamble. Every clause 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 an output schema present, return values need not be described, and the annotations cover the safety profile, leaving little for the description to carry. The one remaining gap is the shape of the results (flat list vs. organizations nesting sites), which the agent would have to infer.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there is no parameter semantics to document and the baseline for a parameterless tool applies. Nothing in the description misleads about inputs.

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 clear verb ('List') and resources ('sites and organizations') scoped to the authenticated user, so the agent knows exactly what comes back. It does not explicitly contrast itself with nearby siblings such as rybbit_list_users or rybbit_get_site_id, which keeps it short of a 5.

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 statement of when to reach for this tool versus the many alternatives (rybbit_get_site_id, rybbit_create_site, rybbit_list_users), nor of any prerequisites. The usage is only implied by the name and the word 'List'.

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/no-destructive, but the description adds genuinely non-obvious behavior beyond them: the event_name filter is silently STRIPPED because the backend returns HTTP 500, plus a description of the return payload. That surfaces a hidden failure mode the agent would otherwise hit blind.

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 purpose and returns, then the critical event_name gotcha and the routing pointer. It is dense with multiple directives but each sentence earns its place; only minor tightening would help.

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 14-parameter, read-only list tool with an output schema present, the description covers what it returns, how to search, how to filter, and the one dangerous filter pitfall. Nothing essential for correct invocation is missing.

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 3 baseline applies, but the description goes further by clarifying the search param uses case-insensitive partial matching, positioning searchField as its companion, and flagging the event_name filter behavior tied to a specific 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 states a specific verb and resource ('List users for a site') and enumerates the returned fields (user IDs, session counts, first/last seen, traits), letting an agent distinguish it from siblings like rybbit_get_event_user_leaderboard and rybbit_list_sessions without opening a schema.

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 explicit routing: use 'search' to find users by username/email/name, use rybbit_get_event_user_leaderboard when ranking by a specific event, and call rybbit_describe_dimension to learn filter capabilities. It also states the case that breaks (event_name filter) with the alternative to use instead.

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, and destructiveHint=false, so the safety profile is covered. The description adds the freshness semantics ('current', 'real-time'), which is genuine behavioral context beyond the annotations, but it says nothing about return shape or latency despite an output schema existing. Modest added value over structured data.

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 tight sentence with the resource and its real-time nature front-loaded. No filler, 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 one-parameter, read-only metric tool with full schema coverage, an output schema, and annotations covering the safety profile, the description is sufficient to invoke correctly. A brief note on what the count represents (e.g., distinct users in a rolling window) would make it 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?

Only one parameter (siteId) and the schema already documents it fully with 100% coverage, including the numeric-ID-or-domain nuance. The description adds no additional meaning about siteId, so the baseline 3 applies when the schema does all the work.

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 (Get) and resource (current number of live/active users) with a real-time qualifier, which cleanly separates it from the sibling rybbit_list_users (which enumerates users rather than counting them). It does not name the sibling explicitly, so it falls just short of a 5.

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 'in real-time' implies the tool is for live monitoring rather than historical analysis, which is a usable contextual cue. However, there is no explicit when-to-use/when-not guidance and no named alternative (e.g., rybbit_list_users or rybbit_get_overview), leaving usage to inference.

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, closed-world behavior, covering the safety profile. The description adds only the semantic scope of the check ('tracking events yet') and a use case; it does not disclose side effects, auth needs, or limits beyond what annotations provide. A 3 reflects modest added value.

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 tight sentences, front-loaded with the core purpose and followed by a usage note. No redundant or filler content; appropriately sized.

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 single-parameter, read-only check with an output schema and rich annotations, the description covers what the tool does and when to use it. No critical information for correct invocation is missing.

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 one required siteId parameter, so the schema fully documents the parameter. The description adds no syntax, format, or constraint details beyond what the schema provides, 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?

States a specific verb ('Check') and resource ('whether a site has received any tracking events'), and the 'before drilling into analytics' phrasing implicitly distinguishes it from the many analytics-query siblings. It does not name a sibling explicitly, so a 4 rather than 5.

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

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

Provides a clear when-to-use context ('verifying SDK integration before drilling into analytics'), but gives no when-not-to-use guidance or named alternatives. This is clear context without exclusions, matching a 4.

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