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

Annotations already carry readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is fully covered. The description adds that the tool returns counts and drop-off rates, which is useful, but it doesn't elaborate on how drop-off is calculated, data freshness, or any limits. With annotations covering behavior, this is acceptable 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?

A single sentence with no filler. It front-loads the action and resource, then immediately states the return value. 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?

Despite having no output schema, the description states the high-level return shape (visitor counts and drop-off rates per step). Combined with the fully-described input schema and safety annotations, an agent has enough context to invoke and interpret basic results. It lacks mention of result limits or date-range behavior, but those are minor for a read-only analysis tool.

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

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

Schema coverage is 100%—every parameter has a description, so the description doesn't need to repeat parameter details. It does reinforce the meaning of the `steps` parameter by mentioning page visits/events, but adds no nuance beyond the schema (e.g., date range semantics, filter behavior). 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 ('Analyze'), a specific resource ('a custom funnel'), and the key output ('visitor counts and drop-off rates'). The word 'custom' distinguishes it from sibling tools like list_funnels or create_funnel, making it clear this is for ad-hoc funnel analysis rather than interacting with saved funnels.

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

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

The description implies when to use this tool: when you need to analyze a funnel by defining steps on the fly. It doesn't explicitly name alternatives or exclusion conditions (e.g., 'use get_funnel_step_sessions for saved funnels'), so it lacks the strongest possible routing guidance, but the context is clear enough to separate it from most 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 only convey read/write/destructive flags (readOnlyHint=false, destructiveHint=false), so the description carries the burden of execution semantics. It discloses three non-obvious behaviors: sequential creation to respect rate limits, independent partial failures ('If one fails, the others still proceed'), and a success/failure summary return. This goes beyond the structured fields, though it doesn't touch idempotency consequences (re-running creates duplicates, consistent with idempotentHint=false).

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, each earning its place: what it does, how it executes, and what it returns. The key scoping phrase ('at once') and the failure behavior are front-loaded. Zero 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 mutation tool with two well-documented parameters and no output schema, the description covers the essential operational facts: batching, rate-limit handling, partial failure, and the success/failure summary. The exact return shape is unspecified, but the description at least names the summary concept that an output schema would otherwise carry. The only notable omission is guidance on duplicate-call consequences given idempotentHint=false.

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% — siteId and funnels, including nested step fields, enums, wildcard semantics, and min/max constraints, are all fully documented in the input schema. The description adds no parameter-level detail, but it doesn't need to. 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 uses a specific verb+resource pair ('Create multiple funnels at once') that states exactly what the tool does. It is immediately distinguishable from the sibling rybbit_create_funnel via the quantity/batching semantics, and from rybbit_batch_create_goals by the resource type. No ambiguity remains.

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 opening phrase 'Create multiple funnels at once' establishes the batch-use context and implies this tool over the single-record sibling rybbit_create_funnel, while the rate-limit and partial-failure sentences tell the agent when batching is the safer choice. However, it never explicitly names the single-create alternative or states an exclusion condition, 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?

Beyond the annotations, the description discloses key runtime behavior: goals are created sequentially to respect rate limits, failures do not abort the batch, and the response is a summary of successes and failures. This is exactly the kind of behavioral context that helps an agent predict side effects and handle partial failures.

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

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

The description is four short sentences with no filler. It front-loads the core purpose, then adds sequential execution, partial-failure behavior, and return summary—each sentence earns its place.

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

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

Despite having no output schema, the description tells the agent what to expect (a summary of successes and failures), which is sufficient. The input schema fully documents the nested goal configuration, and the description covers the behavioral aspects that schema cannot.

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 parameters (siteId and goals) are already fully documented. The description adds no parameter-level detail, which is acceptable; the baseline of 3 applies because the schema carries the 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?

The description opens with a specific verb and resource: 'Create multiple conversion goals at once.' It clearly distinguishes this batch operation from the sibling rybbit_create_goal by emphasizing multiplicity, and the behavior is immediately understandable.

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

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

The description clearly implies this tool is for creating multiple goals in one call, and the sequential execution note provides practical context. It does not explicitly name rybbit_create_goal as the alternative for single-goal creation, 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 this as read-only, idempotent, and non-destructive. The description adds clarity by stating the tool returns a boolean and frames its behavioral role as a verification step, which is useful beyond the annotations 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?

The description is two sentences with no wasted words. It front-loads the core function and return type, then adds the practical use case, making it easy for an agent to scan and act on.

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 boolean check with strong annotations and full schema coverage, the description provides everything an agent needs: what it checks, what it returns, and when to use it. There are no meaningful 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?

The input schema fully documents the only parameter, siteId, including its type and acceptable forms. The description does not need to add parameter details, so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool checks whether a site has any recorded events and that it returns a boolean. It names a specific resource and outcome, though it does not explicitly distinguish itself from related siblings like rybbit_get_site_event_count or rybbit_list_events.

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

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

The description provides a concrete use case: verifying that the tracking script is properly installed before querying analytics. It implies when to use this tool but does not mention alternatives or exclusion conditions, so it stops short of full routing guidance.

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

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

Annotations already indicate this is a non-read-only, non-idempotent mutation, and the description confirms that by stating it creates and saves a new funnel. It adds useful validation context such as the 2-step minimum and step type rules, but does not disclose details like duplicate-name handling, returned identifiers, or whether the site must already exist.

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, no filler, with the core purpose stated first and the verification tip last. Every sentence contributes 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?

For a creation tool with no output schema, the description provides the key invariants, step type semantics, and a verification step via rybbit_list_funnels. It is adequate given the schema covers parameter details, though it could mention what the created funnel resource returns or how duplicates are handled.

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 input schema already documents siteId, name, steps, and all nested step properties thoroughly. The description adds little beyond restating the 2-step minimum and wildcard support, which the schema also covers, so it stays at the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description opens with a specific verb and resource: 'Create and save a new funnel in Rybbit.' It clearly distinguishes itself from sibling list/update/delete/analyze funnel tools by focusing on creation and by directing the agent to use rybbit_list_funnels afterward.

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

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

The description gives clear context and prerequisites: requires a name, at least 2 steps, and defines the two step types. It also advises verifying with rybbit_list_funnels afterward, though it does not explicitly contrast this with batch_create_funnels or state when not to use it.

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

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

Annotations already convey the mutation profile (readOnlyHint=false), non-idempotence, and non-destructive nature. The description adds the useful behavioral context that creation is scoped to path-matching or event-matching conversion tracking, and it tells the agent to verify with list_goals. No contradiction with annotations.

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

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

Three tightly worded sentences: purpose, actionable configuration rules, and verification step. All content earns its place, and the goal-type conditional is front-loaded immediately after the definition.

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?

Despite having no output schema, the description compensates by instructing the agent to verify creation with rybbit_list_goals, and the schema already handles nested optional fields and additionalProperties constraints. For a create tool with conditional configuration, the combination is sufficient for a correct call.

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 75% schema coverage, the schema documents most parameter names, but the description resolves the key cross-field dependency that the schema cannot express: goalType='path' requires config.pathPattern, while goalType='event' requires config.eventName, each with concrete examples. It does not add much for propertyFilters or eventPropertyKey/Value, but the schema covers those.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence names the exact action and resource ('Create a new conversion goal in Rybbit') and defines what a goal does ('tracks conversions when users visit a specific page path or trigger a custom event'). This clearly separates it from the dozens of read/analysis siblings and from create_site/create_funnel, while the singular 'a new' distinguishes it from rybbit_batch_create_goals.

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

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

The description gives explicit conditional instructions for path goals ('set goalType='path' and config.pathPattern') and event goals ('set goalType='event' and config.eventName'), plus a verification workflow via rybbit_list_goals. It does not, however, call out rybbit_batch_create_goals as the alternative for creating many goals, so there is a small routing gap.

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 the operation as mutating, non-idempotent, and non-destructive. The description adds the useful behavioral detail that the created site and its siteId are returned, which is valuable since there is no output schema. It does not disclose edge behaviors such as duplicate-domain handling or validation, but for a simple create operation this is not a critical gap.

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

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

The description is two short sentences with no filler. The primary action is front-loaded, and the second sentence earns its place by clarifying the return value and its role in tracking integration.

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 three-parameter create operation with fully described schema properties, the description is largely sufficient. The lack of an output schema is mitigated by explicitly stating that the created site and siteId are returned. It does not address potential duplicates or validation, but nothing suggests those are essential for an agent to select and invoke this tool correctly.

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

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

The schema already documents all three parameters with useful descriptions, including the domain format example and the pointer to rybbit_list_sites for finding organization IDs. The tool description itself does not add any parameter-level meaning beyond what the schema provides. With 100% schema coverage, this is an acceptable baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Create') and a clear resource ('a new site in Rybbit'), immediately identifying the action. It also differentiates this tool from the many sibling site tools by focusing on creation rather than get/update/delete/list operations. The brief reference to returning the siteId also helps position the tool's role.

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

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

The description gives a clear context for use: when a new site should be created. However, it provides no explicit when-not guidance or routing to alternatives, even though sibling tools like rybbit_update_site_config and rybbit_delete_site exist. Usage is therefore implied rather than explicitly guided.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds the key behavioral detail that deletion is permanent and irreversible, which is useful beyond the structured annotations. No contradiction with annotations.

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

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

The description is only two sentences, front-loads the permanent deletion, and includes the essential warning and prerequisite without any filler. Every word contributes value.

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

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

For a simple destructive delete operation with two well-documented parameters, the description gives the agent enough to proceed: what it does, that it is irreversible, and how to find the required ID. No output schema exists, but return value expectations are not critical 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% and both parameters have clear descriptions. The tool description adds little beyond restating that rybbit_list_funnels should be used to find funnel IDs, which is already present in the schema, so it matches the baseline without adding new meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description uses a specific verb (permanently delete) and resource (saved funnel), and explicitly warns the action cannot be undone. This clearly distinguishes it from other tools such as rybbit_update_funnel or rybbit_delete_site.

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

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

The description instructs the agent to use rybbit_list_funnels to obtain funnel IDs, providing a clear prerequisite. It does not explicitly mention when not to use this tool, but the destructive nature is made obvious by the wording.

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

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

Annotations already mark the tool as destructive and non-idempotent. The description adds meaningful behavioral context by stating 'This cannot be undone,' which emphasizes irreversibility beyond what the annotations alone communicate.

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

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

The description is two short sentences with no filler. It front-loads the core action and irreversibility, then provides the practical ID-discovery guidance.

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 simple parameter set fully covered by the schema, explicit destructive annotations, and a clear prerequisite for obtaining goal IDs, the description provides everything an agent needs to invoke this tool correctly. No output schema is present, but none is required for this straightforward delete operation.

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 both goalId and siteId. The description reinforces that goalId should come from rybbit_list_goals, but this is already present in the schema's goalId description, so no significant extra meaning is added.

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 action—'Permanently delete a conversion goal'—with a clear resource and effect. It is immediately distinguishable from sibling tools like update_goal and list_goals.

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

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

The description gives clear context for use and provides a key prerequisite: use rybbit_list_goals to find goal IDs. It does not explicitly contrast with update_goal or create_goal, but the destructive framing makes the appropriate use case evident.

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 signal destructiveHint=true and readOnlyHint=false, but the description adds important detail: deletion is permanent and removes replay data too. This goes beyond the annotation by specifying exactly what will be destroyed, which is valuable for an agent deciding whether to proceed.

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 carry the operation, the permanent consequence, and the ID-lookup guidance with no filler. The most important information is front-loaded, making it easy for an agent to scan and act on.

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 one well-documented parameter, no output schema, and annotations covering destructiveness and idempotence, the description provides everything needed to call the tool correctly. It even tells the agent where to obtain the required ID, which closes the only likely ambiguity.

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

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

The input schema already documents siteId at 100% coverage with the description 'Site ID (numeric ID or domain identifier)'. The tool description adds no new parameter-level semantics, so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Delete'), a clear resource ('a site from Rybbit'), and a precise scope ('permanently removes the site and its replay data'). This distinguishes it from sibling tools like rybbit_update_site_config or rybbit_create_site without any ambiguity.

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

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

The description gives clear context by labeling the operation as deletion and explicitly tells the agent to use rybbit_list_sites or rybbit_get_site_id to find site IDs. It does not enumerate alternative tools because none are direct alternatives, but the prerequisite guidance is actionable and sufficient.

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, covering the safety profile. The description adds that the tool returns version and configuration details, but does not mention response format or any other behavioral nuances; this is acceptable for such a simple parameterless read operation.

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

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

The description is a single, front-loaded sentence with no filler. Every word contributes meaning, and it is appropriately sized for a parameterless configuration-read tool.

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

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

Given the tool has no parameters, no output schema, and annotations that fully convey its safe read-only nature, the description is complete enough for an agent to invoke it correctly. No critical missing context is apparent.

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

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

The tool has zero parameters and the input schema is fully covered, so there is no parameter documentation burden on the description. The description correctly implies the tool takes no inputs and returns server-level information.

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 ('Get') and a clear resource ('Rybbit server version and configuration'). The word 'server' distinguishes this from site-level configuration tools like rybbit_get_site_details and rybbit_update_site_config, so an agent can identify the correct tool 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?

The description implies when to use this tool: when the agent needs the server version or global configuration. However, it does not explicitly state when not to use it or name alternative tools for site-specific configuration, leaving some 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 establish read-only, idempotent, non-destructive behavior, lowering the burden on the description. The description adds useful operational context beyond annotations: the three distinct response perspectives (summaries, stack-trace instances, and trends) and the dependency between type and errorMessage. It does not 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?

The description is compact and efficient: one lead sentence plus a numbered workflow. Every phrase earns its place, and the most important operational information is front-loaded. No fluff or redundancy.

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

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

Given the 12-parameter schema with 100% description coverage and annotations covering safety, the description fills the main remaining gap: the recommended call sequence and the errorMessage dependency. Without an output schema, a bit more about expected return shape would help, but the combination of workflow and rich schema descriptions is largely sufficient.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does reinforce the relationship between 'type' and 'errorMessage', but this information already appears in the schema's parameter descriptions. It adds no genuinely new parameter semantics beyond what the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description states a specific verb and resource ('Get error tracking data') and immediately clarifies the three modes (names, events, timeseries), giving an agent a concrete idea of what the tool returns. It does not explicitly compare itself to sibling tools like rybbit_get_event_timeseries or rybbit_get_metric, but the 'error tracking' scope and workflow distinguish it well 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?

The workflow gives clear in-tool guidance: call type='names' first to discover error messages, then use events or timeseries with an errorMessage. This explicitly teaches the proper sequence and prerequisites. It does not discuss when to prefer alternative sibling tools, but it provides strong usage context within the tool itself.

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 fully describe the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the description's additive burden is low. It does add the useful scope qualifier 'custom event names' and the 'occurrence counts' output concept. However, it does not disclose default date-window behavior when no dates are supplied or whether built-in events are excluded, leaving some residual behavioral uncertainty.

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

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

Two sentences with the core purpose front-loaded in the first: verb, resource, and output in a single clause. The second sentence, 'Useful for discovering what events are being tracked,' is slightly redundant with the first since retrieving event names inherently enables discovery, but it is short and adds a mild use-case signal. No fluff or repetition of schema 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?

For a read-only list tool with strong annotations and a fully documented 7-parameter schema, the essentials are present: what it returns, at what scope, and how parameters work. Gaps remain: there is no output schema and the description only sketches the return shape without format detail, and in a 40+ sibling namespace with four event-related neighbors, the absence of routing guidance is a real completeness shortfall.

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 itself is unusually rich: siteId explains the accepted formats, filters enumerates all filter dimensions and provides a concrete example array, and timeZone and pastMinutes params include defaults and examples. The description adds no parameter-level detail, but at full coverage the baseline 3 applies — the schema fully carries this 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?

The description uses a specific verb ('Get') with a clear resource ('all custom event names') and specifies the return payload ('occurrence counts') scoped to a site, which unambiguously conveys the core function. It does not, however, explicitly differentiate itself from the event-related siblings (rybbit_list_events, rybbit_get_event_properties, rybbit_get_event_timeseries), which occupy a crowded namespace — the qualifier 'custom event names' only partially disambiguates.

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 'Useful for discovering what events are being tracked' gives an implied discovery use case, which is real guidance but not explicit. It provides no when-not-to-use conditions and names no alternatives, which is a notable gap given the presence of four adjacent event-focused siblings (list_events, get_event_properties, get_event_timeseries, get_user_event_breakdown) that an agent could plausibly confuse.

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 a modest behavioral detail about the return shape, but does not disclose anything like response limits, count semantics, or other operational behavior beyond what the annotations imply.

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 sentence that front-loads the action ('Get property breakdowns') and states the output. No filler or redundancy.

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

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

With no output schema, the description gives only a minimal return-shape statement and does not clarify whether counts are event counts, unique users, or something else. The 8-parameter schema is covered, but for a read-only analytics tool the description could offer more context on date-range behavior and response semantics.

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. The description adds no parameter-specific meaning beyond confirming the 'eventName' is a custom event, so it stays at the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb and resource ('Get property breakdowns') and clarifies the output ('distinct property keys and values with counts'), so an agent knows what the tool returns. It is clear but does not explicitly distinguish itself from similar siblings like rybbit_get_event_timeseries or rybbit_get_user_event_breakdown.

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

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

The description implies the tool is for retrieving property-level breakdowns for a named custom event, but it provides no explicit when-to-use vs alternatives or exclusion criteria. An agent must infer the appropriate context from the resource wording.

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, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds no behavioral detail beyond the schema: it says nothing about return format, defaults, sparse or zero-filled buckets, timezone behavior, or how the 'open world' event set is 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?

The description is only two sentences, front-loads the action, and contains no verbose filler. The second sentence is a somewhat generic use-case statement, but it does not meaningfully hurt clarity.

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?

This is an 8-parameter tool with nested filter objects and no output schema, yet the description gives no hint about the response shape, what 'custom events' means in this product, or default date/bucket behavior. The schema compensates for parameters, but the absent output schema leaves a significant gap that the description does not fill.

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 provides detailed guidance on bucket granularity, filters, dates, and timeZone. The description's 'configurable buckets' merely restates the schema and adds no new parameter meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a clear verb and resource: 'Get custom event counts as time-series data with configurable buckets.' This distinguishes it from non-timeseries event-count tools like rybbit_get_site_event_count and from overview/performance timeseries, though it does not explicitly name any 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?

The phrase 'Useful for analyzing event trends over time' implies a use case, but it does not explain when to prefer this over sibling tools like rybbit_get_overview_timeseries or rybbit_get_metric, nor does it give exclusion criteria.

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 non-destructive behavior, so the description only needs to add semantic context. It adds that the data relates to tracking exclusions and compliance, but it does not detail output format, ISO standard, pagination, or empty-response behavior. This is acceptable but not exceptional.

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, no filler, and the action is front-loaded. Every sentence earns its place: one states what the tool returns, the other explains why it matters.

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 one-parameter, read-only tool with strong annotations, the description is largely complete. It states the return content in plain terms ('list of country codes') and a concrete purpose. It leaves out minor details like the exact country code format, but nothing that would likely prevent 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%, with siteId already described as 'Site ID (numeric ID or domain identifier).' The tool description does not add parameter-level detail beyond referring to 'for a site,' so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb and resource: 'Get the list of country codes excluded from tracking for a site.' This clearly distinguishes it from siblings like rybbit_get_excluded_ips and other site-level read tools by naming the exact data returned.

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

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

The description gives a clear use case: 'Useful for compliance auditing (GDPR, etc.).' It does not explicitly mention alternatives or when not to use it, but the context is direct enough for an agent to understand when this read operation applies.

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

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

Annotations already cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the description does not need to repeat it. It adds useful scoping semantics ('from tracking for a site'), but it does not mention return format, pagination, or whether the list could be empty.

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, both earning their place: the first states the core action and resource, and the second gives a practical audit context. No filler or redundancy.

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

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

For a one-parameter, read-only, idempotent getter, the description is complete enough. It identifies the returned concept (list of excluded IPs), the scope (site), and a use case (tracking config audit), while the schema and annotations cover the parameter and side-effect profile.

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 siteId parameter is already documented as 'Site ID (numeric ID or domain identifier)'. The description only reinforces the 'for a site' scope and adds no new parameter-level meaning, so the schema carries the 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?

The description states a specific action and resource: 'Get the list of IP addresses excluded from tracking for a site.' This clearly distinguishes it from siblings such as rybbit_get_excluded_countries and other read-only getters by naming the exact data returned.

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 'Useful for auditing tracking configuration' gives a clear context for when to invoke the tool, but it does not explicitly compare it to alternatives or state when not to use it. This is clear guidance with no exclusions, rather than a fully specified routing rule.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, idempotentHint=true), so the description does not need to restate that this is a safe read. It adds the semantic distinction between reached and dropped sessions, but does not disclose additional behavioral details such as response structure, pagination defaults, or date handling. This is acceptable 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 short sentences with no filler. The core action and result scope come first, and the use case is stated second. Every sentence earns its place.

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

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

For a 12-parameter read tool with no output schema, the description conveys the core purpose and use case, while the schema covers parameter semantics comprehensively. The main gap is that the description does not hint at the response shape or emphasize that the steps array must match the funnel definition, but the schema's reference to rybbit_analyze_funnel mitigates this.

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 every parameter including mode, stepNumber, steps, filters, dates, and pagination. The description adds no parameter-level meaning beyond what the schema already provides, so the 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 names a specific verb ('Get'), a specific resource ('sessions'), and the exact scope: sessions that reached or dropped off at a specific funnel step. It clearly distinguishes this from sibling tools like rybbit_analyze_funnel by focusing on session-level drill-down rather than funnel-level analysis.

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

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

The description states the intended use case: 'drilling into why users drop off at a particular funnel step.' This gives clear context for when to use the tool, though it does not explicitly name alternatives or state when not to use it.

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

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

Annotations already cover safety (readOnlyHint, idempotentHint, destructiveHint, openWorldHint), so the description only needs to add selection behavior. It states that only sessions completing a specific goal are returned, which is useful, but does not disclose response format, pagination, or time-range 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?

Two sentences, front-loaded with the action and scope, with no redundant phrases. The second sentence adds a genuine use case without bloat.

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 filtered-list tool, the description plus schema covers required params, pagination, filters, and date handling. It lacks an explicit return-shape statement, but the absence of an output schema is mitigated by the straightforward 'sessions' result type.

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 every parameter (siteId, goalId, page, limit, dates, filters, timeZone, pastMinutes) already has a description. The tool description adds no parameter-level detail beyond the schema, so it stays at the baseline 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Get'), resource ('sessions'), and a clear scope ('that completed a specific goal'), which differentiates it from generic list_sessions or single-session tools. It does not explicitly name a sibling alternative, but the goal-specific qualifier makes the tool's role 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' provides a clear analytical context. It does not list exclusions or explicitly point to alternatives, but the stated use case is direct enough for an agent to select this over generic session 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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful analytical context about the output (page sequences and session counts) but does not disclose behavior such as default steps, journey limits, or aggregation specifics. No contradiction with annotations.

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

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

Two concise sentences with no waste. The core purpose is front-loaded in the first sentence, and the second sentence explains the deliverable without repeating schema 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?

The schema is rich and fully documented, annotations cover the operational profile, and the description conveys the output shape (page sequences and session counts) despite the absence of an output schema. It could mention defaults or edge cases, but the combined description and schema are sufficient for a competent agent to invoke the tool correctly.

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

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

The input schema has 100% parameter description coverage across all 9 parameters, so the schema itself documents the parameters fully. The description does not add parameter-specific meaning beyond what the schema already provides, so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific verb and resource: it retrieves user journey/flow analysis showing the most common navigation paths through the site, including sequences of pages and session counts. This distinguishes it from analytics siblings like overview or funnel tools by emphasizing navigation paths and per-path session counts.

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

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

The description implies when to use the tool: when you want common navigation paths and page sequences. However, it does not explicitly contrast it with alternatives like rybbit_analyze_funnel or rybbit_list_sessions, nor does it state exclusions. Usage context is present but left implicit.

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 carry the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower. The description adds useful return-shape context ('sorted list with counts, percentages, bounce rate, and session duration') beyond the annotations, but does not disclose the sort order, default date-range behavior, or pagination semantics — minor given the schema covers page/limit defaults.

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, purpose first, followed by the dense parameter-mapping guide and the return format. No filler or repetition of schema content. The middle sentence is a long enumeration, but each mapping earns its place; a table might be marginally cleaner but the prose is efficient.

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 breakdown tool with 10 parameters and full schema coverage, the description covers the essential decision points: what the tool does, which parameter to use for which intent, and what the response contains (important since there is no output schema). The only notable gap is unspecified default date-range behavior when no dates are supplied, though the schema documents the mechanics of the date parameters.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds genuine semantic value by grouping the parameter enum into intent-based categories, helping an agent choose the right dimension for a given analytical question rather than just listing allowed values. This is exactly the kind of meaning the raw schema cannot convey.

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 operation — getting a metric breakdown by a chosen dimension — and enumerates the dimension categories, which clearly conveys the resource and scope. However, it does not explicitly distinguish itself from overlapping siblings like get_page_titles, get_session_locations, or get_user_event_breakdown, so an agent could hesitate about which tool to pick for page or geo 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?

Provides unusually strong parameter-level guidance: it maps intents (top pages, tech stats, geo, marketing, traffic sources, user flow) to specific parameter values, which is exactly the kind of when-to-use instruction agents benefit from. It stops short of a 5 because it gives no tool-level selection guidance (when to prefer this over get_overview, get_page_titles, or get_session_locations).

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, openWorld, and non-destructive behavior. The description adds useful context about daily aggregation and event-type breakdown, but it does not disclose return format, count semantics, or default date-range behavior. This is similar to other read-only tools that add only modest behavioral detail beyond 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 sentences with no wasted words. The primary action is front-loaded, and the helpful cross-tool pointer is placed second without bloating the description.

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

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

For a simple read-only tool with one required parameter and a fully documented schema, the description is mostly sufficient. It explains the output shape (daily counts, event-type breakdown) and scope, though it omits details like default date ranges or exact response structure. Given the annotations and schema, this 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 the schema already documents all four parameters. The description repeats the organizationId lookup hint from the schema but does not add new parameter-level meaning, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Get aggregated daily event counts across all sites in an organization.' The 'across all sites' phrasing and the event-type breakdown make the purpose concrete and distinguish it from site-level tools like rybbit_get_site_event_count.

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

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

The description clearly conveys the org-wide scope ('across all sites'), which implies when this tool is appropriate, and provides onboarding guidance via rybbit_list_sites. It does not explicitly name alternative tools or state when not to use it, but the context is clear enough.

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 carry the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), and the description aligns with them. It adds domain context — clicks on external URLs with frequency — but not deeper behavior such as how outbound clicks are attributed, aggregation granularity, or whether data is sampled.

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: the first delivers the action and resource, the second explains the return value. The core scoping phrase 'external URLs' is front-loaded.

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

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

For a filtered-list reporting tool, the description plus the rich 100%-covered schema and safety annotations cover the essentials: data domain, common params, and safety profile. Minor gaps remain — no output schema means the response shape is only hinted at ('external URLs... how often'), and there's no note on how outbound link tracking is configured or enabled.

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 docs for siteId, page/limit, date alternatives (startDate/endDate vs pastMinutesStart/pastMinutesEnd), timeZone, and the filter dimension enum with a user_id caveat. The description adds no parameter-specific meaning beyond the schema, 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 outbound link clicks tracked on the site,' and clarifies the value with 'Shows which external URLs users are clicking and how often.' The resource (external link clicks) is semantically distinct from the 47 sibling analytics tools like get_overview and get_metric.

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 use case is implied by the domain — outbound link click analytics — but the description never explicitly says when to prefer this over siblings such as get_metric, get_events, or get_overview, nor does it state exclusions. An agent must infer the boundary from the term 'external URLs' alone.

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 disclosed and the bar is lower. The description adds some value by naming the exact metrics returned, but it does not disclose date-default behavior when startDate/endDate are omitted, how pastMinutesStart/pastMinutesEnd interact with date ranges, or any aggregation semantics. Moderate additional context over 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 sentences with zero waste: verb and resource are front-loaded, the metric list is compact but complete, and the capability statement ('Supports date range and filters') is a single closing clause. 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 tool with 1 required parameter, 100% schema coverage, and full safety annotations, the essentials are covered, and the metric enumeration meaningfully compensates for the absent output schema. The only notable gap is sibling-routing guidance, which is already penalized under usage_guidelines; an agent can otherwise call this tool 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 the baseline is 3. The description's 'Supports date range and filters' only echoes what the schema already documents in richer detail (filter comparison types, example array, the user_id dual-check note, IANA timezone guidance). No parameter meaning is added beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description states a specific verb ('Get') and resource ('aggregated overview metrics for a site') and concretely enumerates the six metrics returned (sessions, pageviews, unique users, etc.). It distinguishes from siblings implicitly — 'aggregated' contrasts with get_overview_timeseries and the multi-metric list contrasts with get_metric — but no sibling is named explicitly, so it falls just short of the 5-level bar.

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

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

No guidance is given on when to use this tool versus the many overlapping siblings: get_overview_timeseries, get_metric, get_site_details, and get_retention all sit nearby. There is no when-to-use statement, no exclusions, and no mention of alternatives; an agent must infer routing solely from the word 'aggregated', which is weak signal.

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 communicate that the operation is read-only, idempotent, and non-destructive. The description adds that it returns arrays of data points, which is useful but does not explain output structure or default behavior such as date-range fallbacks. It does not contradict the annotations.

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

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

The description is short, front-loaded with the verb and resource, and has no filler. The parenthetical bucket list is somewhat redundant with the schema and omits valid enum values, which slightly reduces its value, but overall it is concise and readable.

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

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

The tool has eight parameters and no output schema, yet the description only vaguely says it returns 'arrays of data points.' It does not clarify what each data point contains, how date parameters combine, or how this differs from sibling timeseries tools. The rich schema mitigates this, but the description alone is only minimally 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 the schema fully documents parameters and enums. The description adds no substantive parameter meaning beyond naming a few bucket options, and it omits several valid bucket values like five_minutes and year. This meets the baseline for fully documented schema parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource: get overview metrics as time-series data. The time-series qualifier distinguishes it from the non-timeseries sibling rybbit_get_overview, and 'overview metrics' separates it from event-specific or performance-specific timeseries siblings. The intent is immediately clear.

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

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

The phrase 'for charting trends' implies the main use case, but the description does not explicitly say when to choose this tool over alternatives like rybbit_get_overview or rybbit_get_event_timeseries. No when-not-to-use guidance or exclusions are 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?

Annotations already carry the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the bar is lower. The description adds value by disclosing the return shape ('Returns title, pathname, visits, percentage, and avg time') absent an output schema. However, it does not disclose behavioral quirks such as pagination defaults, the date-range vs. pastMinutes alternative, or the UTC default timezone. No contradiction with annotations.

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

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

Three short sentences with the core purpose front-loaded, followed by usage context and return shape. Each sentence earns its place, though 'Useful for understanding content engagement' is the weakest of the three and only modestly informative. Overall appropriately sized with 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 9-parameter read-only tool with no output schema, the description plus fully-covered schema handles most essentials. Gaps remain: return value units/formats are unspecified (percentage scale, avg time unit), no routing guidance among sibling reporting tools is given, and the date/pastMinutes exclusivity and timezone default are left to the schema. Adequate but not complete for an agent choosing among many analytics endpoints.

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

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

Schema description coverage is 100%, so the baseline is 3; the schema already documents defaults, formats, the filter dimension enum, and a worked filter example. The description adds nothing about parameters beyond naming the output fields, which does not compensate or extend the schema. A 3 is correct since the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Get'), identifies the resource ('page titles'), and enumerates the metrics returned (visit counts, percentages, average time on page) plus the exact return fields (title, pathname, visits, percentage, avg time). This is clear and distinct from most siblings, though it does not explicitly differentiate itself from overlapping reporting tools like get_overview or get_metric, which keeps it from 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?

'Useful for understanding content engagement' provides an implied usage context, but there is no explicit guidance on when to choose this over the many sibling analytics tools (get_overview, get_metric, get_session_locations, get_outbound_links). No alternatives are named and no exclusions are stated, leaving the agent to infer when page-level engagement reporting is the right call.

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

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

Annotations already cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the bar is lower. The description adds useful return-shape context by disclosing the percentile levels, which matters since there is no output schema. However, it does not disclose default time-window behavior when no dates or pastMinutes are supplied, nor how the filters interact with the dimension breakdown. It adds some value beyond annotations but not rich 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 sentences totaling roughly 30 words with zero filler. The core function (metrics + percentiles) is front-loaded, and the optional breakdown capability follows. Every phrase earns its place, and nothing from the schema is redundantly repeated.

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

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

For an 8-parameter tool with no output schema, the description partially covers return values (metric names and percentiles) and the optional dimension behavior. The main gaps are the default time-range behavior when neither date range nor pastMinutes is provided, and the lack of an explicit pointer to the rybbit_get_performance_timeseries sibling for time-series needs. It is adequate but leaves an agent guessing about a key runtime default for a moderately complex query tool.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema carries the documentation burden. The description's 'break down by page path, browser, or OS' loosely maps to the dimension enum values (pathname, browser, operating_system), which is mildly helpful but largely restates what the schema already says via 'Break down performance by dimension.' No additional parameter semantics are contributed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Get') with a precise resource ('Core Web Vitals performance metrics') and enumerates the exact metrics (LCP, CLS, INP, FCP, TTFB) and percentile levels (p50, p75, p90, p99). This clearly separates it from siblings like rybbit_get_errors or rybbit_get_overview, and the percentile framing hints at an aggregated distribution rather than the time-series shape of rybbit_get_performance_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?

The description implies when to use the tool (when you need Core Web Vitals percentile data, optionally broken down by dimension), but it offers no explicit when-to-use vs. alternatives guidance. It never names rybbit_get_performance_timeseries or rybbit_get_metric as alternatives, nor states exclusions such as 'use the timeseries sibling for trend data over time.' The context is clear but entirely 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=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the context that the data is time-series oriented around Core Web Vitals, which is useful, but it does not disclose behavioral details such as output shape, metric list, or time range handling.

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

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

The description is a single, front-loaded sentence that communicates the core action, metric domain, data format, and purpose without any filler. Every word contributes value.

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

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

With no output schema, the description should partially compensate by explaining what the returned time-series contains or how metrics are presented, but it only says 'performance metrics' in general. The parameter schema is complete, so invoking the tool is feasible, but an agent lacks detail on expected return values and exact metric coverage.

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 8 parameters including bucket, dates, and filters. The description does not add meaning beyond the schema, which matches the baseline expectation. No additional parameter nuance or examples are needed beyond what is already provided.

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 Core Web Vitals performance metrics as time-series data.' This clearly identifies the tool's purpose and differentiates it from generic list or overview tools. However, it does not explicitly distinguish itself from sibling tools like rybbit_get_performance or rybbit_get_overview_timeseries, so the differentiation is left to the agent.

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 trend analysis' implies the tool is intended for analyzing performance over time, providing some usage context. There is no explicit guidance on when to choose this tool over alternatives, nor any mention of exclusions or when not to use it.

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

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

Annotations already carry the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the bar is lower. The description adds the cohort-based behavioral context — grouping users and tracking returns over periods — which is genuinely useful beyond the annotations. However, it doesn't disclose cohort bucketing granularity (daily/weekly/monthly), default period behavior, or how openWorldHint sampling might affect the numbers.

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 13-word sentence that is front-loaded with the verb and resource, with every word earning its place. It is appropriately sized and readable, though it achieves brevity by omitting usage guidance that other dimensions 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?

There is no output schema, so the description carries the burden of explaining what the tool returns. It only hints 'how many users return over time periods' — an agent won't know whether the response is a cohort table, a time series, period-over-period retention rates, or how cohorts are bucketed. For a complex analytical tool with 7 parameters and no output schema, this is a real completeness gap.

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

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

Schema description coverage is 100%, so the baseline of 3 applies. The description itself adds nothing about parameters — 'over time periods' is the only hint at date usage — but the schema fully documents siteId, date ranges, pastMinutes alternatives, timeZone, and the detailed filters object including the user_id dual-hash note. The schema carries the burden adequately.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource — 'get user retention cohort analysis' — and defines the output: how many users return over time periods. The cohort-retention concept is distinctive enough that an agent can separate it from the 49 siblings (overview, metric, journeys, sessions) without opening the schema. It falls short of a 5 only because it doesn't explicitly contrast with any sibling to reinforce 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?

The description gives zero when-to-use guidance: no exclusions, no alternatives, no context distinguishing it from rybbit_get_overview, rybbit_get_metric, or rybbit_get_journeys. In a crowded 49-tool workspace this is a notable gap — the agent must infer entirely from the tool name that retention is the right choice.

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 carry the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the bar is lower. The description adds the return-content scope and the prerequisite dependency on list_sessions, which is useful context. It does not disclose edge-case behavior like missing/invalid session IDs, but for a read-only fetch tool this is a minor gap.

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. The primary purpose is front-loaded in the first sentence, and the workflow dependency is stated compactly in the second. Every word earns its place.

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

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

With no output schema, the description correctly shoulders the burden of describing the return values, and it does so thoroughly. Combined with full parameter schema coverage, complete safety annotations, and a stated prerequisite workflow, only minor gaps remain (e.g., behavior when a session is not found).

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 both parameters are already described in the input schema, setting the baseline at 3. The description adds a small but real increment by indicating where sessionId comes from (the output of rybbit_list_sessions), though it adds nothing about siteId beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb-resource pair ('Get detailed session information') and enumerates the contents (page views, events, user traits, device info, location, full event timeline), which sets it apart from siblings like rybbit_list_sessions and rybbit_get_session_locations. The phrase 'detailed' plus the content list makes its scope 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?

The second sentence gives an explicit workflow instruction: 'Use rybbit_list_sessions first to find session IDs.' This tells the agent when this tool fits in a multi-step flow. It does not name when-not-to-use alternatives (e.g., get_session_locations for location-only queries), so it stops short of a full 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 establish read-only, idempotent, and non-destructive behavior. The description adds value by disclosing the actual output shape (latitude, longitude, city, country, session count), which is especially useful given no output schema. It doesn't cover defaults like date ranges or pagination behavior, but the safety profile is already handled by annotations.

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

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

A single sentence that front-loads the verb and resource, immediately states the return fields, and ends with the intended use case. Every clause contributes meaning, with no redundant 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 read-only data-fetching tool with a complete parameter schema and supportive annotations, the description provides enough to select and invoke it correctly. It lacks details on default date windows or pagination behavior, which would be helpful given no output schema, but the core purpose, return values, and use case are present.

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 input schema fully documents all 9 parameters. The description does not add parameter-level detail, which is acceptable given the schema's completeness. Baseline 3 applies because no param semantics beyond the schema are needed.

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 opens with a specific verb and resource: 'Get geographic session location data with coordinates.' It also lists the concrete return fields (latitude, longitude, city, country, session count), making it easy to distinguish from sibling session tools like list_sessions and get_session.

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

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

The description clearly frames when the tool is appropriate: 'for map visualization and geographic analysis.' It does not explicitly name alternatives or exclusion conditions, but the use case is specific enough that an agent can infer this is the geo-focused session data tool among many 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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by specifying that this reads the current configuration and listing the exact tracking flags and metadata returned. There is no contradiction with the annotations.

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

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

Two sentences with no filler: the first fronts the purpose and key data fields, the second draws a clear contrast with the update counterpart. The tracking flag list is long but earns its place by signaling what the agent can expect from the response.

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?

This is a simple, one-parameter read operation with strong annotations, so the bar for completeness is lower. The description effectively substitutes for an output schema by listing the major returned fields, though the trailing 'etc.' leaves the exact response shape slightly underspecified. Overall, an agent has enough to select and invoke the tool 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%, and the siteId parameter already includes a helpful description ('numeric ID or domain identifier'). The tool description itself adds no additional parameter semantics, so the baseline of 3 is appropriate: the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Get full site configuration and metadata' for a site. It enumerates concrete content (domain, name, creation date, tracking flags), making the tool's scope immediately clear. It also positions itself against rybbit_update_site_config, helping an agent tell read vs. write apart.

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

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

The description explicitly frames this tool as complementary to rybbit_update_site_config and notes that it 'reads the current config,' giving a clear read-vs-write selection cue. It does not enumerate when to prefer this over other getter siblings like rybbit_get_config, but the context is sufficient for most selection decisions.

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 well covered. The description adds output-structure context (time-bucketed counts by event type) but does not disclose additional behavioral traits like auth requirements, rate limits, or pagination. This is acceptable given the annotation coverage but not exceptional.

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 focused sentences with no filler. The main output is stated first, followed by a concise purpose statement. The enumeration of event types is dense but directly relevant to tool selection and invokes no unnecessary detail.

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

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

For a read-only analytics tool with a rich, fully documented schema, the description provides enough context to call it correctly. There is no output schema, so the description's explanation of time-bucketed counts by event type is essential and adequately covers the return shape. Minor ambiguity about how filters apply to the breakdown is addressed by the filter parameter documentation.

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

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

Schema coverage is 100%, and each parameter has a meaningful description (e.g., bucket granularity, filters example, timeZone default). The tool description itself adds no parameter-level semantics beyond what the schema already provides; it only summarizes the output categories. This matches the baseline for high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action ('get'), a clear resource ('time-bucketed event counts'), and enumerates the breakdown types (pageviews, custom events, performance, etc.). This distinguishes it from generic event timeseries endpoints like rybbit_get_event_timeseries. The site-level scope is implied by the tool name and required siteId parameter.

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

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

The description includes a useful context line ('useful for understanding the volume and mix of tracking events over time'), which helps an agent infer when it might be relevant. However, it does not explicitly state when to prefer this tool over siblings such as rybbit_get_event_timeseries or rybbit_get_org_event_count, nor does it mention any exclusions.

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, and 'Look up' is consistent with those. The description adds the context that the result is a siteId for downstream setup, but it does not disclose details like multiple matches, return shape, or error behavior; partial-match behavior appears only in the schema.

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

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

Two short sentences, with the core lookup operation front-loaded and the use-case motivation in the second sentence. No filler or redundant detail.

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

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

For a simple one-parameter lookup with strong annotations and a fully described schema, the description is nearly complete. It conveys both the input (domain) and the purpose of the output (siteId), though it stops short of specifying the exact output representation because there is no 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?

Schema description coverage is 100%, so the input schema fully documents the single required parameter, including the partial-match example. The tool description adds no parameter meaning beyond what the schema already provides, which matches the baseline for full schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a clear action ('Look up a site ID') on a clear resource ('by domain name'), and the title reinforces this. It does not explicitly distinguish itself from siblings like rybbit_get_site_details or rybbit_list_sites, but the lookup-by-domain purpose is specific enough to avoid serious confusion.

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?

Explains the use case ('needed for tracking setup and analytics queries'), giving an agent a clear reason to select this tool. It does not name alternatives or state when not to use it, so it stops short of a full 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 establish the read-only, idempotent, non-destructive nature. The description adds value by disclosing what the response conceptually contains (traits, session history, activity summary) beyond the schema and annotations. No contradictions with annotations are present.

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

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

A single, focused sentence that front-loads the action and resource, then briefly lists what is returned. Every phrase earns its place, with no redundant elaboration or 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 detail-retrieval tool with no output schema, the description gives a reasonable indication of the response scope. It could be more specific about the shape or time range of session history and activity summary, but the combination of schema and general description is sufficient for an agent to call 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%: siteId and userId are both described with acceptable clarity. The tool description doesn't add any extra parameter meaning, so the baseline of 3 applies. It neither compensates nor needs to.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Get'), a clear resource ('a specific user'), and enumerates the kind of information returned ('traits, session history, and activity summary'). This distinguishes it from broad listing tools like rybbit_list_users and from focused sub-tools like rybbit_get_user_traits or rybbit_get_user_event_breakdown.

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

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

The description clearly implies the context of use: when a caller needs a consolidated detail view of one user. It doesn't explicitly name alternatives or exclusions, but the 'specific user' scoping provides enough direction against siblings. A little more guidance on when to prefer this over rybbit_get_user_traits would push it to 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so safety and non-mutation are already established. The description adds useful behavioral context: it returns a per-event_name breakdown, checks both user ID types, and mentions accepted date forms (startDate/endDate and pastMinutesStart/pastMinutesEnd via schema). It could go further by noting whether an empty breakdown is returned for unknown users, but given the annotation coverage, a 4 is appropriate.

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, each earning its place: what the tool returns, the key input flexibility (userId), and a usage example. The most important information is front-loaded in the first sentence. No filler or repetition of schema details.

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

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

The tool has 8 parameters but only 2 are required, and the optional parameters (filters, timeZone, pastMinutesStart/End) are already fully documented in the schema with 100% coverage. The description focuses on the decision-relevant part: how the userId is resolved and what the breakdown looks like. Since there is no output schema, a brief note on the response shape (e.g., a map of event_name to count) would make it fully complete, but the current level is adequate 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%, so the baseline is 3. The description adds value by clarifying the semantics of the critical userId parameter (accepts either the Rybbit device hash or app-provided identified_user_id, both are checked) and by giving a concrete example of what the output means. The event_name filter dimension is also annotated in the schema but the description reinforces the per-event behavior. This exceeds the bare baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Get'), a resource ('event count breakdown'), and a scope ('for a specific user'). It goes beyond a generic listing by explaining the output semantics ('how many times each event_name was triggered by this user') and even provides example event names. This distinguishes it from siblings like rybbit_get_site_event_count and rybbit_get_org_event_count, which are aggregate counts, and rybbit_get_user, which fetches user details.

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

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

The description clearly explains the key usage context: analyzing per-user behavior (e.g., ad_click, chat_message_sent) and the dual ID flexibility (device hash or app-provided ID). It implies when to use this tool versus site-level or org-level event count tools, though it does not explicitly name alternatives or state when not to use it. That slight gap keeps it from 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 readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is well covered. The description adds useful behavioral context beyond annotations — the 'daily' granularity and 'over time' time-series nature of the result — but doesn't disclose details like date inclusivity or response shape.

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

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

Two sentences with no filler: the first states the action and resource, the second justifies its use case. The description is efficiently front-loaded with the core purpose before the application context.

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

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

For a read-only query tool with 100% schema coverage and strong annotations, the description is largely adequate. 'Daily session counts' hints at the response shape, and the user-scoping is clear. Minor gaps remain — no mention of the exact output fields or date-range behavior — but with no output schema expected, the description carries acceptable weight.

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

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

Schema description coverage is 100%, with well-documented parameters including the helpful hint to use rybbit_list_users for finding user IDs. The description's 'over time' phrasing loosely maps to startDate/endDate but adds no parameter-level detail beyond what the schema already provides, 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 ('Get') and a precise resource ('daily session counts for a specific user over time'), which clearly communicates scope. It differentiates from site-level siblings like rybbit_get_metric and rybbit_get_overview via the 'specific user' qualifier, though it doesn't explicitly name a sibling to contrast against.

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 second sentence ('Useful for analyzing individual user activity patterns and retention') provides an implied use case, which helps an agent know when to select this tool. However, it offers no exclusions or explicit alternatives, such as redirecting to rybbit_get_retention for cross-user cohort analysis or rybbit_live_users for real-time activity.

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 carry the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the description need not restate it. It adds genuine behavioral information beyond annotations: the mode-dependent default selection logic and case-insensitive matching for the 'users' mode. No statement contradicts the annotations.

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

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

Three sentences in about 40 words, with the core purpose front-loaded and each mode explained in its own clause. There is no filler, no repetition of schema text, and every sentence earns its place by clarifying behavior.

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 mode-polymorphic tool with five parameters and no output schema, the description covers all invocation variants and their parameter requirements, which is the main risk an agent faces. It stops short of describing the return shape or limits/offset behavior, but annotations cover the safety profile and the mode semantics are fully specified, leaving no ambiguity about how to call it correctly.

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

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

Schema coverage is 100%, so the schema already documents every parameter including the mode defaults and required conditions for key and value. The description adds modest value beyond the schema — chiefly the case-insensitive matching detail and a readable consolidation of mode-to-parameter interplay — but does not substantially extend what structured fields already convey.

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 opens with a specific verb and resource ('Get user trait keys, values, or find users by trait') and fully disambiguates the tool's polymorphic behavior across three named modes. Because it is framed around user traits, it is clearly distinct from siblings like rybbit_get_user and rybbit_list_users, which target the user record itself rather than trait metadata.

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

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

The description gives explicit conditional usage guidance for mode selection ('mode=values (default when key is provided)', 'mode=keys' default otherwise), so an agent knows which invocation variant applies in which situation. It does not name alternatives or exclusion criteria among the tight siblings, but the mode-level routing is clear and 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 establish that this is a safe, read-only, idempotent operation, and the description adds useful behavioral detail by specifying the returned event fields and the exact semantics of event_name filtering. This goes beyond the structured annotations without contradicting them.

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

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

The description is three focused sentences with no filler: purpose and capabilities, return content, and an important filtering nuance. Every sentence earns its place and the key concept of raw events is front-loaded.

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

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

For a read-only list tool, the description is sufficiently complete: it states the operation, the granularity of results, key returned fields, and the important event_name filtering behavior. The absence of an output schema is partially compensated by the listed return fields, and the schema documents all parameters thoroughly.

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

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

Schema description coverage is 100% and each parameter already has a meaningful description, so the tool description does not need to repeat parameter details. The description only adds general filtering/pagination context and the event_name-vs-sessions distinction, which is also present in the eventName parameter description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description identifies a specific verb ('List'), resource ('raw events'), and scope ('for a site') while also noting filtering and pagination. The emphasis on individual event records rather than sessions helps distinguish it from sibling tools like rybbit_list_sessions and aggregation tools like rybbit_get_event_names.

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

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

The description gives a clear use context: retrieving raw, filtered event records for a site. It also clarifies that event_name filtering yields matching events rather than entire sessions, which implicitly guides the agent away from session-level tools, though no explicit alternative tools are named.

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 the useful behavioral detail that it returns all saved funnels including step definitions, but it does not disclose ordering, pagination, or behavior for invalid or missing sites. With the annotations carrying much of the burden, a 3 is appropriate.

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

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

The description is a single, front-loaded sentence with no filler. Every part earns its place: 'List', 'all saved funnels', 'for a site', and 'with their step definitions' all convey necessary information without 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 simple one-parameter read-only tool with rich annotations and full schema coverage, the description is complete enough. It states what the tool returns (all saved funnels with step definitions) and the scope (a site), which is sufficient for correct invocation. No output schema exists, but the description adequately covers the return content.

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%: siteId is documented as 'Site ID (numeric ID or domain identifier)' in the schema, so the schema already explains the parameter. The description only references 'a site' and adds no additional parameter semantics. 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 uses a specific verb ('List'), a specific resource ('saved funnels'), and a scope ('for a site'), and adds 'with their step definitions' to clarify the payload. This clearly distinguishes it from siblings like rybbit_analyze_funnel, rybbit_get_funnel_step_sessions, and rybbit_create_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?

The phrase 'List all saved funnels for a site' provides clear context for when to call this tool: when you need the full set of saved funnel definitions for a site. It does not explicitly name alternatives or exclusion conditions, but the intent is unambiguous enough for an agent to select it appropriately among the funnel-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, and destructiveHint=false, so the safe read-only nature is covered. The description adds that the response contains conversion metrics and configuration, which is useful, but it does not disclose response shape, default date range behavior, 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?

The description is a single sentence with no filler or repetition. It front-loads the action and resource, then adds the two key output aspects: conversion metrics and configuration.

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

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

For a simple read-only list tool, the description plus a fully documented schema is mostly complete: the required siteId is clear, and the description summarizes the return content. It does not detail output structure or date defaults, but those are minor for this tool given the annotations and 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%, so the schema already documents all seven parameters and their formats. The description adds no parameter-level meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb and resource ('List all goals for a site') and clearly states what is included in the result ('current conversion metrics and configuration'). This distinguishes it from read-only list tools like rybbit_list_funnels and from goal mutation tools like rybbit_create_goal and rybbit_update_goal.

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

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

Usage is implied by the purpose: use this tool when you need all goals for a site. However, it does not explicitly mention alternatives such as rybbit_get_goal_sessions for goal-specific session data or provide exclusions, so the guidance is only implicit.

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 read-only, idempotent, non-destructive behavior, so the description adds useful behavioral detail: returned fields, conditional IP inclusion based on trackIp, and client-side IP filtering. It does not contradict the annotations.

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

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

The description is two sentences with no redundant wording. It front-loads the core purpose, then lists the returned fields and the IP caveat. Every clause adds useful information.

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

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

Given the large input schema and the absence of an output schema, the description compensates well by enumerating the main return fields. It does not describe the exact response envelope or ordering, but the schema carries the parameter details, so the definition is reasonably complete for a list operation.

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 provides detailed descriptions for all 12 parameters. The description adds minimal parameter-level meaning beyond summarizing that filtering and pagination are supported, so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description starts with a specific verb and resource: 'List sessions for a site', and adds concrete scope ('filtering and pagination') plus the exact data set returned. This clearly distinguishes it from singular tools like rybbit_get_session and from session-scoped tools like rybbit_get_funnel_step_sessions or rybbit_get_goal_sessions.

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

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

The description gives clear context: this is the general session-listing tool for a site, with filtering, pagination, and IP filtering. It does not list exclusionary alternatives, but the usage context is unambiguous enough for an agent to select it over the many get_* 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 read-only, non-destructive, idempotent behavior, so the low bar is met. The description adds access-filtering context ('has access to') but does not mention ordering, pagination, or result shape. This is 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?

A single sentence with no filler; the action and scope are front-loaded. 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 zero-parameter read-only listing with rich annotations, the description is nearly complete. There is no output schema, so a bit more detail about whether the response is a flat list or grouped sites/orgs could help, but it is not essential for selecting and invoking the tool.

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

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

There are no parameters and schema coverage is 100%, so the description need not explain inputs. The baseline for zero-parameter tools is 4; the description accurately implies the call requires no arguments.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb-resource pair ('List all sites and organizations') and adds the access scope ('authenticated user has access to'). This clearly separates it from siblings such as rybbit_list_users and rybbit_get_site_details.

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 statement makes the intended use obvious: call when you need the full set of sites/organizations visible to the authenticated user. It does not explicitly name alternatives or exclusion conditions, but for a zero-parameter enumeration this is clear enough.

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 read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral context by specifying the response contents, filtering capability, and the search matching semantics. No contradiction with the annotations 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?

The description is three concise, front-loaded sentences. The first sentence states the core action and output shape, the second adds filtering scope, and the third explains the search parameter. Every sentence earns its place with no filler or redundancy.

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

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

Given there is no output schema, the description's explicit statement of return fields is important. With annotations covering safety behavior and the schema covering all parameters, the definition is largely complete. Sort, pagination, and date-range behavior are left to the schema, which is acceptable given their detailed descriptions there.

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 structured schema already documents all 14 parameters in detail. The description adds little new parameter-level meaning beyond restating the search behavior, which the schema also covers. This is the expected baseline when the schema carries the parameter documentation 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?

The description clearly states the operation ('List users for a site'), identifies the target resource, and enumerates the returned data: user IDs, session counts, first/last seen dates, and user traits. It also specifies the required site scoping. It does not explicitly differentiate from sibling tools like rybbit_get_user or rybbit_live_users, 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 description gives clear usage context: use this to list users for a site and optionally filter by analytics dimensions. It also provides direct guidance for the 'search' param with case-insensitive partial matching. It does not explicitly state when to choose an alternative tool or list exclusions, but the context is strong enough for an agent to select it appropriately.

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 and idempotentHint, so the safety profile is covered. The description adds real-time/live snapshot semantics, which is useful context about data freshness, but it does not disclose details like response format or whether the count can change between calls. The annotations make this a moderate rather than severe gap.

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

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

The description is a single sentence, front-loaded with the core operation and result, with no filler or repeated information. Every word contributes value.

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

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

For a one-parameter read-only tool with full schema coverage and annotations, the description is nearly complete: it names the return value (number of live users) and the resource (a site). It could optionally specify the exact response shape, but the low complexity and explicit 'number' wording reduce the need.

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%; the siteId parameter is already described as 'numeric ID or domain identifier'. The tool description adds no additional parameter-level meaning beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description uses the specific verb 'Get' and the resource 'current number of live/active users on a site', clearly stating the value returned and its real-time nature. This distinguishes it from siblings like rybbit_list_users and rybbit_get_user, which are about user entities rather than a live site-level count.

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

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

'Current' and 'in real-time' imply this is for point-in-time live counts, but there is no explicit guidance on when to choose it over alternatives such as historical metrics or session-based counts. The usage context is implied rather than directly 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 indicate this is a mutating, idempotent, non-destructive operation. The description adds valuable context by explaining the upsert mechanism and how funnelId maps to reportId. It does not mention that the steps array replaces all existing steps, though that is covered in the input schema.

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

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

The description is two sentences with no waste. It front-loads the primary action, then provides the key integration detail about discovering funnel IDs. Every sentence earns its place.

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

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

The description covers the main action, the upsert behavior, and how to resolve the funnelId parameter. There is no output schema, so return values are not described, but this is acceptable for a mutation tool where the primary guidance is about how to invoke it correctly. The steps replacement behavior is left to the schema, which documents it.

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

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

The schema already documents all parameters at 100% coverage, so baseline is 3. The description adds meaningful extra context by explaining that the funnelId is the reportId and how to obtain it via rybbit_list_funnels, which is not derivable from the schema alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the operation ('update an existing funnel'), the specific attributes ('name and/or steps'), and distinguishes it from sibling tools like create_funnel and delete_funnel. It also adds the useful implementation detail that it uses the create endpoint as an upsert, which clarifies the intended behavior.

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

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

The description explicitly directs the agent to use rybbit_list_funnels to find the appropriate funnelId and clarifies that the 'id' field is the reportId. It does not explicitly name create_funnel as the alternative for new funnels, but the phrase 'existing funnel' and the upsert mechanism make the intended use case 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 convey write (readOnlyHint=false), idempotent (idempotentHint=true), and non-destructive (destructiveHint=false). The description adds the crucial behavioral fact beyond annotations: the update replaces the ENTIRE goal, so a partial config would wipe unspecified settings. This is high-value disclosure for an agent deciding what to send. No contradiction with annotations.

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

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

Three sentences, zero filler. The core action is first, the critical replacement warning is second, and the discovery hint is third. Every sentence earns its place and the most decision-relevant information is front-loaded.

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

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

For a mutation tool with nested config and no output schema, the description covers purpose, the full-replacement semantics, and how to find IDs/current config — enough to invoke correctly. The main gap is that it says nothing about the response format (e.g., whether the updated goal is returned for verification), which matters slightly more absent an output schema but is not required 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 80%, so the baseline is 3. The description adds meaningful semantics on top: it frames goalType + config as the 'full goal definition' that gets replaced, explaining why both are required, and it clarifies that goalId should be sourced via rybbit_list_goals. This connects the parameters to the tool's replacement behavior in a way the schema alone does not.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource: 'Update an existing goal.' The full-replacement caveat distinguishes it from partial-update tools, and the phrasing 'existing goal' implicitly separates it from rybbit_create_goal. It stops short of explicitly naming create/delete siblings, but the action and target are 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?

Provides explicit prerequisite guidance: 'Use rybbit_list_goals to find goal IDs and current configuration.' This tells the agent what to do before calling. It does not explicitly state 'use rybbit_create_goal for new goals' as an exclusion, but 'existing goal' in the first sentence implies the boundary.

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