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

Annotations already convey this is a non-read-only, non-destructive, non-idempotent operation. The description adds meaningful behavioral context: it performs a direct membership add, requires elevated permission, and bypasses the normal access-code requirement. 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 well-organized with Args/Returns/Examples sections, front-loads the purpose, and avoids unnecessary filler. Slight redundancy with the schema's parameter descriptions, but the example 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?

No output schema exists, but the description explicitly defines the return shape. Permission requirements, parameter sourcing, role defaults, and an example are all present. An agent has everything needed to 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 coverage is 100%, so the baseline is 3. The description adds value by telling the agent to get user_id from umami_list_users and provides a concrete example mapping natural language to role values, plus the default role is restated.

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 ('Add'), resource ('an existing Umami login to a team'), and the key differentiator ('directly, without needing the access code'), which clearly distinguishes it from the sibling umami_join_team. The permission requirement is also stated.

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 'without needing the access code' signals when this tool is appropriate versus the access-code flow, and the permission requirement ('team-manager or owner permission') gives an explicit gate. It does not name the alternative tool directly, but the context is clear.

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

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

Beyond the annotations, the description discloses important behavior: it returns raw JSON pretty-printed, only permits GET, rejects query strings in the path, requires epoch-millisecond timestamps and UUID website IDs, and returns the Umami status code on failure. This substantially enriches the safety and expectations information carried by 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 long but densely informative, with clear sections for purpose, usage, args, returns, examples, and error handling. The purpose and fallback guidance are front-loaded, and each sentence adds operational value rather than repeating structured metadata.

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

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

For a generic raw-API tool with no output schema, the description provides everything an agent needs to invoke it correctly: endpoint format, parameter constraints, return behavior, example calls, and error handling. It is complete enough to handle arbitrary new or undocumented endpoints using the same API surface.

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?

Even though schema description coverage is 100%, the description adds meaningful semantics: it clarifies path is relative to API root, forbids '/api' prefix and embedded query strings, requires params values as strings, and gives several realistic examples with exact parameter shapes. This goes well beyond the schema's minimal descriptions.

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

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

The description states a precise verb and resource: 'Make a read-only GET request against any Umami API endpoint that does not have a dedicated tool here.' It clearly positions this tool as a general fallback, which differentiates it from the many dedicated sibling tools that wrap specific endpoints.

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 says to use this 'only as a fallback' and explains that dedicated tools handle date parsing, website resolution, and formatting while this one does not. It lists concrete example endpoints and mentions newer Umami endpoints, giving an agent clear selection 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 indicate mutation (readOnlyHint=false, idempotentHint=false), and the description adds that the cohort is 'persisted' and 'appears under Audience > Cohorts in the Umami UI', plus the return shape. It does not contradict annotations. It could disclose more about duplicates or permissions, but the added persistence/UI context justifies a 4.

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 organized into Args, Returns, and Examples sections, with the core purpose front-loaded. Some parameter details are redundant with the schema, but the examples and return type add useful context and the structure is easy to scan.

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 7-parameter create tool with no output schema, the description covers the return object, defaults, parameter semantics, optional website behavior, and examples. An agent has everything it needs 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%, so the schema already documents all seven parameters. The description's Args section largely restates this information, though the two natural-language examples help map intent to parameter values. It adds modest value 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 ('Create') and resource ('persisted audience Cohort'), locates the result in the Umami UI ('Audience > Cohorts'), and clearly distinguishes this from sibling tools like umami_create_segment or umami_create_funnel by defining exactly what a cohort is.

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 about what a cohort is and provides natural-language examples, but it never explicitly says when to choose this tool over related creation tools or when not to use it. Usage is implied by the cohort definition rather than stated as direct guidance.

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

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

Annotations already indicate this is not read-only, not idempotent, and not destructive. The description adds useful behavioral context beyond those hints: the funnel is persisted, appears for anyone browsing the dashboard, and is not merely a transient computed result. It also discloses the return shape, which helps set expectations for a create 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 well structured and front-loaded, starting with the core persistence/UI distinction, then providing Args, Returns, and a concrete Example. Every section adds value, especially the return shape and example steps, without unnecessary filler.

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

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

With no output schema, the description provides a return shape, which is essential for an agent to interpret results. It covers all four parameters, gives a realistic example, and explains the key difference from umami_get_funnel. The tool is complex enough that this level of detail makes it safely callable without external 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 description coverage is 100%, so the schema already documents all four parameters. The description restates parameter meaning without adding significant new semantics, though it does helpfully summarize constraints like '2-8 ordered steps' and 'default 60' in a single place. This is acceptable but not additive 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 states the tool creates a 'persisted Funnel' that appears under 'Behavior > Funnels in the Umami web UI', clearly distinguishing it from a computed result. It explicitly contrasts with umami_get_funnel, so an agent can differentiate this tool from its closest sibling without guessing.

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 says 'Unlike umami_get_funnel (which computes step conversion on demand and shows nothing in the UI)', directly guiding the agent to choose this tool when persistence and dashboard visibility are needed. It also references when get_funnel would not suffice, giving clear selection 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?

The annotation readOnlyHint=false indicates a write operation, and the description enriches this by explaining the goal is persisted, appears in the dashboard UI, and remains until changed. It also discloses return shape and an important edge case: match_type='event' accepts event names that have never fired and will show 0 conversions until they do. This goes well beyond what annotations alone provide.

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

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

The description is front-loaded with the core purpose and sibling distinction, then uses clearly labeled Args, Returns, and Error handling sections. Every element earns its place, and the prose is tight without unnecessary 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?

Given four parameters, no output schema, and minimal annotations, the description covers creation semantics, UI visibility, parameter behavior, return format, and an error edge case. An agent has enough information to invoke the tool correctly and to interpret its response without needing additional schema context.

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?

Input schema coverage is 100%, so the schema already documents all four parameters. The description largely repeats these definitions but adds one meaningful semantic insight: match_type='event' accepts any event name, even one that has never fired yet, which clarifies the value and match_type interaction 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 states a specific verb and resource: 'Create a persisted Goal that appears under Behavior > Goals in the Umami web UI.' It clearly contrasts with umami_get_goal, which 'computes a conversion rate on demand and shows nothing in the UI', so an agent can immediately distinguish this tool from related siblings.

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

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

The description explicitly names the alternative umami_get_goal and explains the key difference: create_goal persists a UI-visible goal, while get_goal only computes on-demand. This tells an agent when to select this tool over the closest sibling, which satisfies the explicit when/when-not guidance criterion.

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

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

With annotations already covering readOnlyHint=false, idempotentHint=false, and destructiveHint=false, the description adds meaningful context by stating the segment is 'persisted' and visible in the UI, and by documenting the return shape. 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 well-organized into Args, Returns, and Examples, and the most important purpose is front-loaded. The examples are useful and the overall length is appropriate, though some parameter details are repeated from the schema.

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

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

The description provides enough information for an agent to call the tool correctly: required parameters, optional website handling, valid dimensions, match semantics, examples, and the return shape. Since no output schema is present, documenting the return object is especially valuable.

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 carries full parameter documentation. The description adds value by compactly listing the filter dimensions, clarifying the match default, and giving concrete filter examples that make it easy to construct valid calls.

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 ('create') and resource ('persisted audience Segment'), and further clarifies exactly where it appears in the UI ('Audience > Segments'). This cleanly distinguishes it from sibling tools like umami_create_goal or umami_create_cohort.

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

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

The description implies usage by defining what a segment is and providing practical examples such as 'Mobile visitors' and 'Paid social, not from the US'. However, it never explicitly states when to prefer this tool over related alternatives like umami_create_cohort or umami_create_goal.

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 provide mutation/idempotency/destruction hints; the description adds meaningful context: teams are separate from personal accounts and the returned access_code enables self-joining. This goes beyond the structured hints 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?

Well-organized with Args, Returns, and Example sections; every sentence adds useful information and the access_code behavior is explained without padding.

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

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

For a single-required-parameter tool with no output schema, the description fully covers what to pass, what comes back, and how the result is used. Nothing necessary for correct invocation is missing.

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

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

Schema coverage is 100% and the schema fully documents name as a required string. The description repeats the parameter and adds an example, but no significant semantic detail 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?

Uses a specific verb (create) and resource (team) and explains what a team is: a shared-access grouping of websites/members separate from personal accounts. This clearly distinguishes it from team update/join/delete operations.

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

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

Gives an explicit use case: keeping a client's or product line's websites together with a dedicated access code. It also names the join path (umami_join_team) as the alternative for sharing access, though it doesn't enumerate exclusions like update/delete scenarios.

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

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

Annotations only cover read-only/idempotent/destructive hints, so the description carries the behavioral burden and succeeds. It discloses error conditions (400 for duplicate username, 403 for non-admin), permission requirements, platform availability, and a post-creation behavior (user can change password after logging in). It also explains role privileges ('admin' can manage all users and websites, etc.) in detail. 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 long but every section earns its place: purpose, audience, constraints, args, returns, example, and error handling. It is front-loaded with the core purpose. Minor redundancy exists where arg descriptions echo the schema verbatim (username, id), but the role explanation, return shape, and error handling justify the length.

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 privileged mutation tool with no output schema, the description is unusually complete: it covers return shape (compensating for the missing output schema), permission prerequisites, error handling, all parameter semantics, and a usage example. There is nothing an agent needs to know to invoke this correctly that is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description nonetheless adds value beyond the schema: it expands role semantics from a bare 'Instance-wide role' into concrete permissions for each role, notes that the password is changeable after login, and provides an example mapping natural language to parameter values. This is meaningful additive semantic content.

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

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

States a specific verb and resource: 'Create a new login account on this self-hosted Umami instance.' It distinguishes itself from sibling tools by clarifying 'not for issuing client-facing accounts,' which separates it from umami_onboard_client and umami_create_team. An agent can tell exactly what this tool does and what it is not for.

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

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

Explicitly states the target audience ('internal team members who need their own login') and gives a clear exclusion ('not for issuing client-facing accounts'). It also provides preconditions ('Admin access required') and a platform limitation ('Not available on Umami Cloud'). It does not name the alternative tool explicitly (e.g., 'use umami_onboard_client instead'), which keeps it a 4 rather than 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 (readOnlyHint=false, idempotentHint=false), the description discloses meaningful behavior: it returns a tracking snippet and website ID, fails on duplicate forced IDs, and is unavailable in read-only API-key mode on Umami Cloud. This gives the agent a realistic model of side effects and failure conditions.

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 well-structured with clear sections for Args, Returns, Examples, and Error handling. The opening sentence front-loads the core purpose and the rest is tightly scoped with no filler. Every section earns its place.

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

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

Given the tool has no output schema, the description supplies the full return JSON shape, highlights the tracking ID's role, and covers the main error cases. It gives enough context for an agent to call the tool correctly and interpret the result.

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

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

Even though the schema covers all parameters, the description adds practical semantics: team_id is tied to umami_list_teams, id is explained with a use case ('match an ID reserved elsewhere'), and domain's 'No protocol' constraint is reinforced. The examples map natural language requests to actual parameter values, which is genuinely helpful.

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 — 'Register a new website for tracking in Umami' — and immediately clarifies the tool's role as the first step in onboarding a client or project. It explains the returned website ID feeds into the tracking script, which distinguishes it from sibling tools like umami_update_website or umami_list_websites.

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 when to use it: it is the first step in onboarding and must precede use of stats tools. It also cross-references umami_list_teams to find a team_id. However, it does not explicitly name alternatives or state when not to use it, such as 'use umami_update_website for existing sites.'

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds valuable context beyond that: 'This cannot be undone', the confirm requirement, and the exact return shape. It does not contradict the annotations, even with idempotentHint=true.

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

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

The description is concise, front-loaded, and well-structured with clear Args and Returns sections. Every sentence adds value, including the cross-reference to the sibling tool and the irreversible-warning.

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

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

This is a simple two-parameter destructive tool with no output schema. The description covers how to obtain the ID, the confirm requirement, the alternative for segments/cohorts, and the return value. Nothing essential is missing for an agent to invoke 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 description coverage is 100%, so the schema already fully documents both parameters. The description's Args section mostly repeats the schema text, though it does reinforce that confirm must be true and cannot be undone. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'Permanently delete a saved report (goal, funnel, journey, or retention)' and clarifies the effect ('no longer appears in the Umami UI'). It also distinguishes itself from the sibling umami_delete_segment_cohort by explicitly naming the alternative for segments/cohorts.

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 tells the agent how to get the report ID ('Get the report ID from umami_list_saved_reports'), when not to use this tool ('For a segment or cohort, use umami_delete_segment_cohort instead'), and the required confirmation flag ('Requires confirm=true'). This is clear, actionable 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?

Beyond destructiveHint=true, the description discloses 'Permanently delete', 'This cannot be undone', and 'There is no undo', clearly communicating irreversibility and the need for confirmation. It also supplies the return shape. It does not discuss repeated-call behavior, but that is covered by idempotentHint=true, and the description 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 front-loaded with the core purpose, followed by a one-line warning and compact Args/Returns sections. It is slightly redundant with the input schema's parameter descriptions, but it remains short and well organized.

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 Returns block fills an important gap by stating the exact success shape. The description also covers the ID discovery prerequisite, the required confirm flag, and the irreversible destructive nature. Nothing essential is missing for a low-complexity 3-parameter delete 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 schema already documents all three parameters, including the report_id source and the confirm=true requirement. The description's Args section largely repeats that information without adding new semantics, so it stays at the baseline for fully-covered schemas.

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: 'Permanently delete a saved Segment or Cohort', with a concrete outcome ('no longer appears in the Umami UI'). The target is unambiguous and clearly separated from sibling delete tools such as umami_delete_website, umami_delete_user, and umami_delete_saved_report.

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

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

The first sentence establishes the intended use, and 'Get the ID from umami_list_segments_cohorts' gives an explicit prerequisite. 'Requires confirm=true' is a clear precondition. It does not explicitly mention when not to use this tool or contrast it with related deletion siblings, so it falls just 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?

Goes well beyond the destructiveHint and readOnlyHint annotations. It explicitly states the side effect on owned websites (not deleted but inaccessible), warns that the action cannot be undone, and requires confirm=true. This is exactly the behavioral context an agent needs before calling a destructive tool.

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

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

Compact and well-structured: warning first, then arguments, then return shape. Every section adds practical value, and the irreversible nature is emphasized without unnecessary prose.

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?

Complete for a destructive two-parameter tool. It explains the consequences, the confirmation requirement, the return value, and gives actionable advice (reassign websites first). No critical invocation detail is missing.

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

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

Schema description coverage is 100%, so the schema already documents both team_id and confirm fully. The description largely restates their meanings rather than adding new semantic details, which justifies the baseline score.

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

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

States the exact operation: 'Permanently delete a team' — specific verb and resource, distinct from team update/list/get siblings. The permanent nature and team scoping remove 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?

Provides a clear prerequisite: reassign websites before deletion if they still need a home. However, it does not explicitly discuss when to prefer this tool over alternatives like umami_update_team or umami_delete_website, 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?

Beyond the destructiveHint annotation, the description explains that the deletion is permanent, irreversible, and requires explicit confirmation. It also discloses the important side effect that owned websites are not deleted but become inaccessible, plus environment constraints.

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 front-loaded with the core action and its most important consequence. It is compact, organized, and each section serves a purpose, with the return format included since no output schema exists.

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

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

For a two-parameter destructive tool, the description covers prerequisites, environment limitations, effects on associated resources, irreversibility, required confirmation, and the expected return value. Nothing an agent needs to invoke this tool correctly is missing.

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

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

Schema coverage is 100%, and the parameter descriptions in the schema already convey everything needed: user_id is a UUID and confirm must be true with no undo. The description's Args section mostly duplicates the schema, so it adds little new semantic value.

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 ('delete') and resource ('login account') and clearly states the scope: a self-hosted Umami instance. It distinguishes itself from related deletion tools like delete_website and delete_team by focusing on user account deletion.

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 clear conditions for use: admin access required, not available on Umami Cloud, and confirm=true must be passed. It does not explicitly name alternative tools for related actions like updating a user, but the context is sufficient for an agent to know when this tool 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 mark destructiveHint=true and readOnlyHint=false; the description builds on this by confirming the deletion is permanent, cannot be undone, and that confirm must be true. It also discloses that all collected data is removed alongside the registration, which is important side-effect information. The idempotentHint annotation is not contradicted by the description.

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 well-structured with clear sections (purpose, caveats, args, returns, example) and contains no filler. It packs a warning, an alternative tool, parameter semantics, and return format into a compact block.

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 only two parameters and no output schema, the description covers all needed invocation details: parameter formats, confirm constraint, return shape, and a usage example. No critical information for calling the tool correctly is missing.

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

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

The schema already provides descriptions for both parameters (100% coverage), and the description adds guidance on how to discover valid website values (umami_list_websites) and that website is optional when UMAMI_DEFAULT_WEBSITE is set. The 'required' tag on website is slightly inconsistent with the schema, but the subsequent clarification mitigates it. Overall it enriches 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 opens with a specific verb ('Permanently delete') and resource ('website registration and all of its collected data'), which clearly states what the tool does. It also differentiates itself from the sibling 'umami_reset_website' by explicitly naming the alternative. This leaves no ambiguity about the tool's function.

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 tells the agent to use umami_reset_website instead when the goal is to keep the registration and tracking ID but clear historical data. It also states the hard requirement that confirm=true must be passed, and provides a concrete usage example. This gives clear selection and invocation guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: the 5-minute window, the realtime-only scope, and the exact return JSON shape, which is especially valuable given there is no output schema.

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

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

The description is compact and front-loaded. It opens with the core purpose, immediately gives the exclusion for umami_get_stats, then provides structured args, returns, and an example. No sentence is wasted.

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

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

Given one optional parameter, a fully descriptive schema, and no output schema, the description supplies the missing return shape and a concrete example. It also routes the agent to the correct sibling for period-based traffic, making the tool easy to invoke correctly without further research.

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

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

Schema description coverage is 100% and the description mirrors the schema's 'Website ID, name, or domain' guidance. It adds a useful example mapping 'example.com' to the website parameter, but most semantic weight is already carried by the schema, 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 the number of unique visitors active on a website in the last 5 minutes.' It clearly differentiates itself from umami_get_stats by explicitly labeling itself 'the realtime counter only.'

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 says when to use this tool versus the alternative: 'This is the realtime counter only. For traffic over a period use umami_get_stats.' The example query further reinforces the intended use case.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive, so the bar is to add context beyond that. The description delivers: it reveals the underlying mechanism (filtering replays, downloading with a cap, extracting clicks, normalizing against viewport size, bucketing into a grid), explains why replay volume may be lower, and discloses error scenarios. This is strong behavioral transparency for a read-only analysis tool.

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

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

The description is detailed but every sentence earns its place: the one-line purpose, the implementation rationale, the parameter breakdown, the return shape, and error handling. It is front-loaded with the most decision-relevant information and uses structured sections for scannability. This is appropriately sized for a tool with no output schema and 8 parameters.

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 output schema, the description compensates by specifying the exact JSON return shape including cell structure. It also covers defaults, caps, overrides, and error interpretation. For a tool with this complexity, nothing material is missing that an agent would need to invoke it correctly and interpret its results.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds substantial meaning beyond the schema. It explains the purpose of max_replays as a cap, why range defaults to 30d due to lower replay volume, how grid_size maps to a NxN grid, and exactly what response_format changes. The Args section mirrors and enriches the schema without merely repeating it.

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 a click-density heatmap for one page path.' It immediately distinguishes this from sibling analytics tools by clarifying it is built from session replays rather than a dedicated Umami endpoint. The title and opening sentence align, and the tool's unique role among the siblings is clear.

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

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

The description explicitly explains when this tool is appropriate: use it when you need a click heatmap, knowing that Umami has no native heatmap endpoint and that the data must be derived from session replays. It also provides a concrete alternative in the error-handling section: 'check umami_list_replays for that path first' when zero clicks are returned, giving the agent a branching decision.

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 meaningful behavioral detail beyond that: results are grouped by event name, time-bucketed, unit selection is automatic when omitted, and the response is a specific JSON shape with totals and series.

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 well-structured with short labeled sections (overview, use case, args, returns, examples) and front-loads the key purpose. The Args section somewhat duplicates the schema, but the compact summaries and concrete examples justify the length.

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 provides a full return shape, documents the default response format, covers all parameters via Args, and includes realistic examples. For a complex analytics read tool with nested filters and nine parameters, this is complete enough for an agent to invoke 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 baseline is 3. The description adds value beyond the schema by summarizing override behavior for start_date/end_date, explaining that unit is auto-selected, and providing natural-language examples mapping queries to parameter values like range='last_week' and event='contact-form-submit'.

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 opening sentence names a specific verb ('Get'), resource ('custom tracked events'), and core behavior ('bucketed over time, grouped by event name'). This clearly distinguishes it from pageviews-focused siblings and states exactly what the tool computes.

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 says to use this for conversion and interaction tracking, listing form submits, button clicks, signups, and umami.track() events. It gives clear context, though it does not explicitly name sibling tools to avoid, so it stops short of a full when-not/alternatives statement.

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

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

The description goes well beyond the readOnly/idempotent annotations by explaining that Umami has no funnel endpoint, that sessions are walked individually, that scanning is capped by max_sessions, and that truncated results may need a higher cap. It also discloses the cost of higher caps (extra API calls per session) and defines truncation behavior clearly.

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 well-structured with sections for args, returns, examples, and error handling, and it front-loads the core purpose. It is longer than necessary partly because it repeats some schema descriptions, but the additional behavioral context earns the length.

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, yet the description provides the full JSON return shape, explains truncation semantics, includes an example, and documents error handling. Given the tool's complexity and the absence of structured output metadata, the description is sufficiently complete for an agent to invoke and interpret results 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 schema already documents parameters well. The description adds meaningful semantics beyond the schema, especially the matching rule for steps, the session-advancement logic, and the practical trade-off of max_sessions.

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

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

The description clearly states the tool's purpose: get session counts and drop-off across an ordered sequence of pages and/or custom events. It is specific about the verb and resource, but it does not explicitly distinguish itself from siblings like umami_get_journeys or umami_get_retention.

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 clear context about when this tool is appropriate — when a funnel-style ordered conversion analysis is needed — and includes an example mapping a user request to steps. It does not, however, name alternative tools or give explicit when-not-to-use guidance.

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

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

Beyond the readOnly and idempotent annotations, the description discloses that Umami has no dedicated goals feature, that the metric is computed by comparing two filtered calls to the stats endpoint, and that a zero-occurrence event usually means the tracker never fired rather than an error. This is valuable behavioral context that annotations do not provide.

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

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

The description is long but well-structured with Args, Returns, Examples, and Error handling sections. Each part earns its place: parameter relationships are clarified, return shape is given, and realistic usage examples are included. The slight repetition of 'exactly one of path/event required' is acceptable for emphasis.

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 appropriately provides the JSON return shape. It also covers error interpretation, parameter dependencies, defaults, and example mappings from user intent to arguments. An agent has enough information to select and invoke the tool correctly without additional inference.

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

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

Schema coverage is already 100%, but the description adds important semantic detail: exactly one of path/event is required, start_date/end_date override range, filters apply to both the goal and the baseline, and response_format controls output style. This goes beyond the schema's per-field descriptions and helps an agent construct correct calls.

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 the conversion rate for a single-step goal: visitors who reached a page, versus all visitors in the same range.' It clearly defines the goal types (path or event) and distinguishes this from raw stats or multi-step funnels, making the tool's purpose unambiguous.

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

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

The description gives clear context for when to use the tool: for single-step goal conversion rates, with exactly one of path/event required. It does not explicitly name alternatives such as umami_get_funnel for multi-step goals or umami_get_stats for raw analytics, so it falls short of full when-not guidance, but the usage context is strong.

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 this as read-only, idempotent, and non-destructive, and the description adds substantial behavioral detail beyond that: it walks every session's activity trail, collapses consecutive repeats, truncates to depth steps, caps scanning via max_sessions, and returns a truncated flag. It also explains the performance tradeoff through the max_sessions cap. 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 well-organized and front-loaded: a one-sentence purpose, a concise algorithm paragraph, a compact args list, return shape, and an example. Despite the detail, every section earns its place and the structure makes scanning easy for an agent.

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 10-parameter tool with no output schema, the description is unusually complete. It explains the computation, the cap behavior, all parameter semantics, the exact JSON return shape, and a usage example. Nothing essential for correctly invoking the tool is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds practical meaning with the algorithm explanation and the example mapping 'What do people do after landing on the homepage?' to start_path='/' and depth=3. The Args list compacts defaults and constraints, though some entries repeat schema descriptions.

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

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

The description opens with a specific verb and resource: 'Get the most common sequences of pages visitors take through the site.' It makes clear this is a journey/path-analysis tool, distinct from pageview series, metrics, funnels, and retention tools, and it further clarifies that no native Umami endpoint exists for journeys.

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 strong contextual usage guidance, including the concrete example 'What do people do after landing on the homepage?' and how to express it with start_path and depth. It does not explicitly contrast against sibling tools like umami_get_funnel or umami_get_retention, so exclusions and when-not-to-use guidance are absent.

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. The description adds meaningful context beyond those: output shape differences for expanded=true, pagination via offset, filter behavior, and the 'No data' error case. The only slight weakness is that the Returns section describes JSON shapes while the default response_format is 'markdown', leaving the default output representation somewhat underspecified.

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 long but extremely well structured: purpose, usage guidance, args, returns, examples, and error handling each have a clear section. The most important information is front-loaded, and every section serves a real agent decision, so its length is justified without 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?

Given 10 parameters, nested filter objects, and no output schema, the description is remarkably complete. It documents every parameter with defaults, provides return shapes for both expanded and plain modes, gives multiple examples, and explains the 'No data' case. An agent has enough context to select, parameterize, and interpret 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 adds value above the schema with concrete examples (e.g., top pages for mobile visitors in Florida), clarification that website can be ID/name/domain, range categories, and practical filter usage. It mostly restates schema fields but the examples and contextual hints push it above 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 opens with a specific verb and resource: 'Get a ranked breakdown of traffic by one dimension,' and enumerates the dimension families (pages, referrers, countries, browsers, etc.). The phrase 'workhorse for top N questions' further clarifies the tool's niche and distinguishes it from aggregate stats or time-series siblings, even though it does not name them explicitly.

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

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

The description explicitly says when to use this tool: for 'top N' questions, and when to set expanded=true to get engagement-quality metrics per row. It does not name sibling alternatives or state when not to use this tool in favor of, say, a time-series or aggregate-stats tool, so it stops short of full exclusion guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: bucket-size caps, automatic unit selection, start_date/end_date overriding range, timezone handling, and the exact JSON return 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?

The description is well-structured and front-loaded: the core purpose and when-to-use guidance come first, followed by concise Args, Returns, and Examples sections. Every section earns its place, and the examples are compact and directly illustrative.

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 8 parameters, no output schema, and nested filter objects, the description is remarkably complete. It documents the return shape, provides example mappings, covers optionality and defaults, and clarifies important edge behavior like bucket caps and date overrides. An agent has enough information to 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 coverage is 100%, so the baseline is 3. The description adds useful semantic value on top: it maps examples to parameter choices, explains that unit is chosen automatically when omitted, and documents the Umami caps for each unit. This goes beyond what the schema alone provides.

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

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

The description states a specific verb and resource ('Get pageviews and sessions bucketed over time') and explicitly frames the purpose around trend and seasonality questions. It also distinguishes itself from single-total queries, which separates it from sibling tools like umami_get_stats.

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 when-to-use guidance: 'Use this when the question is about shape over time rather than a single total' and lists concrete question types. It does not explicitly name an alternative tool like umami_get_stats, but the contrast with 'a single total' makes the intended usage 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 indicate readOnly, idempotent, and non-destructive behavior. The description adds meaningful context beyond that: it reads the same public endpoint as the tracker, making it ground truth, and clarifies that it resolves unit ambiguity on max duration. 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 well-structured and every section earns its place: a precise summary, a rationale for using it, an Args block, a Returns block with the JSON shape, and a concrete example. It is front-loaded with the core purpose and contains no filler.

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

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

With no output schema present, the description compensates by documenting the exact JSON return shape. The tool is simple, has one optional parameter, and its typical use case is explained clearly. Nothing an agent needs to select and invoke this tool correctly is missing.

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

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

The schema already fully documents the optional website parameter (ID, name, or domain) and notes the default website fallback. The description repeats this and gives an example, but adds no new semantic detail such as accepted formats, units, or edge cases. Because schema coverage is 100%, baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'Get the recorder configuration Umami is actually serving to the tracker for a website.' It enumerates the exact config fields returned, which makes the tool's scope unmistakable and clearly distinguishes it from analytics and heatmap data siblings like umami_get_click_heatmap.

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 when to use it: as the ground truth after umami_update_website changes, to confirm values took effect and resolve unit ambiguity. It does not explicitly list when not to use it or name alternative tools, so it falls just short of fully explicit routing.

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 indicate a read-only, idempotent operation. The description adds meaningful behavioral context: output is summarized rather than raw, raw event streams can be tens of thousands of events, and click coordinates are capped at 200. Minor inconsistency: the first sentence promises a 'duration/event breakdown,' but the listed JSON shape does not include duration.

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 well-structured and front-loaded: purpose, caveats, args, and return shape are clearly separated. The Args section is somewhat redundant with the schema, but the overall length is reasonable given the lack of an output schema and the need to explain return shape and 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?

Because there is no output schema, the description appropriately provides a JSON return shape and upstream ID-sourcing instructions. It falls short by not explaining how the default markdown output presents the duration/event breakdown and by omitting any error or edge-case behavior.

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 fully documents replay_id, website, include_clicks, and response_format. The Args list mostly restates schema content; the only extra parameter-related guidance is the upstream hint to use response_format='json' with umami_list_replays.

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 ('Summarize') and resource ('one recorded session replay'), then enumerates the summary contents: pages visited, click count, and a duration/event breakdown. It also explicitly distinguishes the tool from raw event-stream access, making its role clear relative to related replay/session tools.

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

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

It clearly states how to obtain replay IDs (from umami_list_replays) and sets a boundary: this tool returns a summary, not the raw rrweb event stream. It does not explicitly name alternative tools for raw events or heatmaps, so some when-not-to-use guidance is implied rather than fully spelled out.

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?

Adds substantial behavioral context beyond the readOnlyHint/idempotentHint annotations: the tool groups distinctId overlap, requires persistent user IDs, reports zero when instrumentation is missing, and clearly separates instrumentation gaps from data gaps. This is exactly the kind of nuance an agent needs to interpret results correctly.

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 detailed but well-structured with clear sections: purpose, implementation, prereq, Args, Returns, and Error handling. Every sentence adds value, especially the return shape, which compensates for the missing output schema.

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

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

Despite having no output schema, the description fully specifies the JSON return shape, parameter behaviors, prerequisites, and error interpretation. For a read-only analytics tool with an unusual dependency on identify() instrumentation, nothing essential is missing.

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

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

Schema coverage is 100%, so the schema already documents all four parameters and their defaults. The description mostly restates those same details, though it adds useful output-related context such as cohort_size of 0 meaning no identify()'d visitors in the earliest period.

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 a cohort retention curve' with a precise definition of what it computes. It also distinguishes itself from other analytics siblings by explaining that it is built from identify()'d visitors and that no native retention endpoint exists.

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

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

Explicitly states when the tool is valid: only if the site calls umami.identify(persistentId) with a stable ID. It also tells agents when not to rely on it — without identify(), it reports zero visitors — and points to pageview/session tools as the fallback for traffic data.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds meaningful behavioral context: it explains the computation method (summing value x occurrence count across recorded values), the lack of built-in revenue tracking, and the meaning of a zero result. The conflicting default range ('30d' in the description vs '7d' in the schema) is a minor transparency blemish.

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 well-organized with clear sections for purpose, arguments, return shape, and error handling. It is slightly longer than necessary because the Args list repeats schema information, but the added examples and behavioral notes justify most of the length.

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 8 parameters, nested filter objects, and no output schema, the description does well: it documents the return JSON shape, explains output formats, covers error semantics, and mentions how to discover website IDs. However, the default-range contradiction leaves the agent with conflicting information, so it is not fully complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does add useful examples and clarifies the relationship between event, property, and tracking, but the Args section largely duplicates the schema. It also contains a factual inconsistency: the description says range defaults to '30d' while the schema says '7d', which reduces trust in the parameter guidance.

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

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

The first sentence states the exact operation: get total and average revenue from a numeric custom-event property, with a concrete 'purchase'/'amount' example. It also distinguishes itself from siblings by explaining that self-hosted Umami has no built-in revenue tracking and by pointing to umami_get_metrics in the error-handling section.

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 when to use the tool: when revenue must be derived from a numeric custom-event property because Umami has no native revenue tracking. It also provides a conditional alternative: if total_revenue is 0, check umami_get_metrics with type='event' to confirm the event fires. It does not enumerate exclusions, but the guidance is 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 cover readOnly, idempotent, and non-destructive behavior. The description adds meaningful behavioral detail beyond those hints: the optional activity trail, the boundary that activity outside the selected range is not returned, and a concrete JSON shape showing what fields to expect. This gives the agent an accurate mental model of the tool's 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?

The description is front-loaded with the core purpose, followed by a short use-case statement, compact argument bullets, a return shape, and one illustrative example. Every section contributes useful information and there is no filler or redundant repetition.

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 correctly supplies a detailed JSON return shape for both session and activity entries. It also covers defaults, source of the required session_id, and the range-sensitive behavior. This is sufficient for an agent to call the tool correctly and interpret the result.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds practical semantics beyond the schema: it explains where session_id comes from, gives an example mapping a natural-language request to session_id and include_activity, and clarifies that range determines whether activity is returned. These additions help the agent choose and populate parameters correctly.

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

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

The description states a specific verb+resource: 'Get details for one visitor session', and immediately clarifies the individual-level scope with an optional page-by-page activity trail. It differentiates this tool from list/aggregate siblings by saying it traces an individual journey and by pointing to umami_list_sessions as the source for session IDs.

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 on when to use it: 'Use this to trace an individual journey through the site: entry page, path taken, events fired, exit point.' It also tells the agent where to get the required session_id. It does not explicitly state when not to use it or compare it to nearby alternatives like umami_get_journeys, 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds useful behavior beyond annotations: it discloses that bounce rate and avg duration are derived from raw counts, that compare defaults to true, that all-zero results usually mean the range predates tracking, and that a 404 is returned for a bad website ID. It could go further on pagination/timezone details, but this is solid.

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 organized into clear sections (summary, args, returns, examples, error handling) and is front-loaded with the key differentiator. It is somewhat long relative to the schema's completeness, but every section earns its place by adding behavioral or selection guidance rather than repeating schema text verbatim.

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 100% schema coverage and no output schema, the description goes well beyond the minimum: it documents the return JSON shape, gives realistic examples, explains defaults, and covers error behavior. A fully complete definition might also enumerate sibling alternatives or disclose timezone defaults, but the gaps are minor given the rich 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 coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema: it explains the meaning of 'range' values ('Relative... named... or use start_date/end_date'), clarifies the relationship between start_date/end_date and range (overriding), gives the default for compare and response_format, and provides a concrete filters example not fully enumerated in the schema's prose. The Args list is a useful summary even though it mirrors the schema closely.

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

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

States a specific verb+resource ('Get summary traffic statistics for a website over a date range') and immediately distinguishes itself as the 'headline-numbers tool' with pageviews, visitors, visits, bounce rate, and average visit duration. It is clearly differentiated from sibling analytics tools like umami_get_pageviews_series, umami_get_metrics, and umami_get_active_visitors.

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 clear context on when to use the tool via the 'headline-numbers' framing, examples, and error-handling notes that point to umami_get_website for data-range concerns. It does not explicitly state when NOT to use this tool or list alternatives by name, so it loses a point, but the examples and scope are strong enough for an agent to select it correctly.

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 readOnly/idempotent/non-destructive, so the bar is lower. The description adds useful behavioral detail: it returns the full member list with roles, supports markdown/json output, and gives the exact JSON shape. This goes meaningfully beyond 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 compact, front-loaded, and structured with Args and Returns sections. Every sentence adds useful information 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?

There is no output schema, so the description compensates by including the JSON return shape. Combined with clear parameter guidance and comprehensive annotations, the description is sufficiently complete for a simple read-only tool, though it could explicitly mention sibling distinctions.

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 the valuable guidance that team_id should come from umami_list_teams, which helps the agent construct a valid call. response_format semantics are already covered by the schema, but the added source guidance justifies a 4.

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') and resource ('team'), and specifies the key content: details, full member list, and roles. This clearly distinguishes it from siblings like umami_list_teams (listing teams) and umami_get_team_websites (team websites).

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

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

The description implies usage for fetching team details/members and tells the agent to obtain team_id from umami_list_teams, but it does not explicitly state when to choose this tool over alternatives or mention exclusions such as 'for team websites use umami_get_team_websites'.

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 read-only, idempotent, and non-destructive. The description adds useful behavioral detail beyond that: the exact return shape, case-insensitive search behavior, and the difference between markdown and JSON response formats. There is 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 well-organized and compact, with a clear one-line summary followed by concise Args and Returns sections. It is front-loaded and easy to parse, though the Args block somewhat duplicates the input schema's parameter descriptions.

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 listing tool with no output schema, the description provides sufficient context: required team_id, optional search behavior, response_format options, and the exact JSON return shape. An agent has everything needed to invoke the tool correctly and interpret its output.

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 all three parameters and their constraints. The description restates the parameter meanings but does not meaningfully enrich them beyond what the schema provides, 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 opens with a specific verb and resource: 'List every website belonging to a team.' This clearly communicates both the action and the scope, and distinguishes it from broader tools like umami_list_websites or single-website tools like umami_get_website.

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 intended use case: fetch team-scoped websites, optionally filtered by a case-insensitive search term. It does not explicitly name sibling alternatives or state when not to use the tool, but the context is strong enough for an agent to select it correctly.

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 readOnly, idempotent, and non-destructive behavior, but the description adds meaningful context: access control requirements, platform restrictions, and the exact return shape. Since there is no output schema, including the JSON structure provides valuable transparency beyond 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 well-organized with a one-sentence summary, prerequisite note, Args section, and Returns section. Every element earns its place; there is no filler or redundant restating of the title.

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

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

For a simple read-only lookup with two parameters and no output schema, the description is complete: it covers what the tool returns, who can use it, where it is available, and how to obtain the required argument. An agent has everything needed to invoke it correctly.

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

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

The schema covers 100% of parameters, so the baseline is 3. The description adds useful guidance beyond the schema by telling the agent to source user_id from umami_list_users and by reiterating the response_format default. This extra context justifies a slightly higher score.

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') and clearly identifies the resource: a login account's details plus the websites and teams it can access. This distinguishes it from sibling tools like umami_list_users (list) or umami_get_team (team details), even without explicitly naming them.

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

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

It states prerequisites: admin access for other users, self-lookup for authenticated users, and unavailability on Umami Cloud. It also points to umami_list_users for obtaining the user_id. It does not explicitly contrast with alternative getters like umami_get_website or umami_get_team, so the guidance is clear but lacks direct 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?

Beyond the existing readOnly/idempotent annotations, the description exposes an important behavioral caveat: data_start/data_end determine whether queries return real traffic or zeros, which can be misread as a collapse. It also discloses the return shape, including nullable fields and active_visitors, adding substantive context.

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

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

The description is well-structured and front-loaded, with a purpose statement, a valuable caveat, concise args, return shape, and examples. Every section earns its place and there is no filler or repetition that hurts usability.

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 explicit return shape is necessary and provided. The description covers the non-obvious data coverage behavior, defaults, parameter notes, and examples, making it complete enough for an agent to call the tool correctly without external 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 description coverage is 100%, and the description mostly restates what the schema already says for 'website' and 'response_format'. The examples add illustrative value but do not introduce new parameter semantics beyond the schema, so the high-coverage 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 configuration details for one website' plus the date range of actually collected data. The scope 'one website' distinguishes it from list-style siblings like umami_list_websites, and the focus on configuration/data coverage separates it from stats, sessions, and heatmap tools.

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 on when the tool is useful: 'Check this first when numbers look surprisingly empty' because pre-tracking periods return zeros. It also provides natural-language examples that map to invocations. It does not explicitly name alternative tools or state when-not-to-use, so it does not reach 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 indicate mutating, idempotent, non-destructive behavior. The description adds context beyond annotations by stating the current authenticated user is the subject, that the access code comes from umami_create_team or umami_get_team, and by providing the return shape. It does not fully describe side effects, but the annotation coverage lowers the burden.

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 well-structured: a clear purpose sentence, a differentiating sentence, an args section, and a returns section. No filler or redundancy; every sentence carries necessary 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 single-parameter tool with no output schema, the description is complete: it explains the required input, where to get it, the operation semantics, and the return value format. Low complexity plus existing annotations make this fully 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 specifying the access code's provenance ('from umami_create_team or umami_get_team'), which is not present in the schema's simple 'The team's access code.' This extra guidance helps the agent know where to obtain a valid code.

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: 'Join a team as the currently authenticated user, using its access code.' It clearly differentiates itself from umami_add_team_user by framing the action as the self-serve counterpart, so an agent can distinguish between joining for oneself versus adding another user.

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 states when to use this tool vs. the alternative: 'This is the self-serve counterpart to umami_add_team_user, which an existing team manager uses to add someone else directly.' This gives a clear direct/indirect distinction with no inference required.

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 description adds value beyond them by disclosing ordering ('newest first'), the dependency on recording config, and the meaning of empty results. It also provides a detailed return shape and error-handling guidance, which is especially useful since no output schema is 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?

The description is well-organized with clear sections for behavior, arguments, return shape, and error handling. It front-loads the core purpose and usage guidance, and every section contributes practical information without padding or repetition.

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 compensates by including a concrete JSON return shape. It also covers prerequisites, empty-result interpretation, and related tools, making the tool fully usable by an agent without needing additional inference. The description is complete for a read-only listing 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 schema already documents all seven parameters thoroughly. The description's Args section largely restates the schema rather than adding new semantic detail, but it does reinforce key defaults and the relationship between range and start_date/end_date. This aligns with the baseline of 3 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 states a specific verb and resource ('List recorded session replays for a website over a date range, newest first'), making the tool's function immediately clear. It also differentiates from siblings by pointing to umami_get_replay for detailed inspection and implicitly distinguishing replays from general 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 explicitly states preconditions ('Replays only exist where recording is enabled...'), names the alternative tool for deeper inspection ('Use umami_get_replay to inspect one in detail'), and explains how to interpret empty results. This gives an agent clear decision criteria for when to call this tool versus alternatives.

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 read-only, idempotent, non-destructive behavior, so the description does not need to repeat safety traits. It adds useful context by specifying the returned JSON shape and by clarifying the UI-sidebar semantics. It does not mention pagination or list limits, but this is minor for a simple read-only listing tool.

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

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

The description is compact and front-loaded with the core purpose, then gives the one important alternative, followed by concise arg and return summaries. Every section earns its place without unnecessary 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?

Given the tool's low complexity, no output schema, and rich annotations, the description provides everything an agent needs: what it lists, how to scope it, which sibling to use instead, the argument semantics, and the exact return shape. No significant information is missing.

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

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

Schema description coverage is 100%, so the schema already documents every parameter well. The description's Args section largely restates what the schema says, adding only marginal convenience; it introduces no substantial new meaning 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 states a clear action ('List the saved reports of one type for a website') and identifies the resource precisely as saved reports corresponding to the Umami UI sidebar sections. It also distinguishes itself from umami_list_segments_cohorts, making the tool's scope immediately clear relative to siblings.

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

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

The description explicitly says to use umami_list_segments_cohorts instead for Segments or Cohorts, and explains they live on a different endpoint. It also scopes the tool to one report type per call, which helps an agent decide how to invoke it correctly.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior, so the description does not need to restate those. It adds value with the concrete return shape and the response_format option, clarifying what the agent will receive. It does not detail pagination or markdown formatting behavior, but for a simple list tool with strong annotations this is sufficient.

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 front-loaded with the main purpose, followed by clean Args and Returns sections. Every sentence earns its place, and the inclusion of the JSON return shape is compact and directly useful.

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 straightforward list tool, the description covers the purpose, the required filter, the optional website, the output format, and the return shape. It is slightly incomplete in that it does not explicitly distinguish this from umami_list_saved_reports or mention pagination/limits, but those are minor for this use case.

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 67%, and the description repeats the schema's parameter meanings without adding substantial detail. The required 'type' param is explained as 'which kind to list', which is helpful, but the description does not go beyond what the schema already provides for 'website' and 'response_format'.

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') and a specific resource ('saved Segments or Cohorts for a website'), and situates the data in the Umami UI ('as they appear under Audience'). This makes the tool's purpose immediately distinguishable from reporting, user, and team tools in the sibling list.

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

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

The description implies usage: call this when you need saved segments or cohorts for a website, optionally after using umami_list_websites to find the website ID. However, it does not explicitly contrast with nearby sibling tools like umami_list_saved_reports or the create/delete segment-cohort tools, so the when/why routing is left mostly 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?

The annotations already establish read-only, idempotent, non-destructive behavior, and the description adds meaningful context beyond that: sessions are anonymous, results are newest-first, an empty result set is returned when no sessions exist, and the exact JSON response shape is documented. This is especially valuable because there is no output schema.

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

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

The description is well-organized into purpose, args, returns, examples, and error handling, with the core purpose front-loaded. It is longer than minimal because it documents the return shape and examples, which are justified by the lack of an output schema, though the Args list partially duplicates 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 9-parameter tool with no output schema, the description is complete: it states the operation, scope, ordering, parameter behavior, return shape, example usage, and error handling. Nothing an agent needs to invoke it correctly appears to be missing.

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

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

Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds short examples and clarifies that start_date/end_date override range, but it mostly repeats information already present in the input schema, which is adequate but not additive.

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: 'List individual visitor sessions for a website over a date range, newest first.' It clearly differentiates the tool from aggregate analytics tools by emphasizing that it exposes individual sessions rather than aggregates, which is enough to distinguish it from siblings like umami_get_stats and umami_traffic_report.

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

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

The description explicitly states when to use this tool: 'Use this to inspect real visit behaviour rather than aggregates,' and gives concrete example phrasings. It does not name specific alternative tools for non-list session needs, but the exclusion of aggregates and the examples provide clear practical guidance.

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

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

Annotations already cover read-only, idempotent, non-destructive behavior. The description adds meaningful behavioral detail beyond that: it states the response shape, documents pagination via limit/offset, mentions that offset is converted to a page number, and explains the response_format choices. This gives the agent a solid model of what will happen.

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 well-structured with a concise summary, explicit argument documentation, return shape, and an example. It is slightly repetitive with the input schema, but the structured format makes key details easy to parse without being bloated.

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, parameterless-required tool, the description is complete: it explains what is returned, the JSON shape, default values, format options, and a sample invocation. Since there is no output schema, including the return shape in the description is especially valuable.

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 three parameters. The description still adds value by clarifying the offset behavior ('converted to a page number') and showing a concrete example with no arguments. This is a modest but real contribution 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 and resource: 'List every team on this Umami account, with member and website counts.' It clearly communicates the scope and the included aggregate data, and it is easy to distinguish from sibling tools like umami_list_websites and umami_list_users.

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

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

The description establishes clear context: it is for enumerating teams in the account and even provides a natural-language example ('What teams do we have set up?'). It does not explicitly name alternative tools or state when not to use it, but the purpose is specific enough that an agent can infer appropriate usage.

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

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

Annotations already mark the operation as read-only, idempotent, and non-destructive. The description adds valuable behavioral detail beyond that: admin privileges are required, Umami Cloud is excluded, and the exact JSON return shape is specified. This is especially important because there is no output schema.

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

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

The description is compact and well-structured, leading with the core purpose and then using short Args, Returns, and Examples sections. Every sentence contributes useful information, and the example clarifies that the tool can be called with no arguments.

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

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

For a simple list operation with one optional parameter, the description covers everything an agent needs: scope, access requirements, environment limitation, return shape, and a usage example. The lack of an output schema is compensated by the explicit JSON return contract.

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

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

Schema coverage is 100%, and the schema already documents response_format with its enum, default, and meaning. The description's Args section largely restates this and the example only confirms the default behavior, adding no meaningful new parameter semantics.

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

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

The description opens with a specific verb and resource: 'List every login account on this self-hosted Umami instance.' It clearly distinguishes the tool from singular user operations like umami_get_user and from other list_* siblings by naming the exact resource being listed.

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 concrete usage context: admin access is required, and the tool is explicitly not available on Umami Cloud. It does not explicitly name alternative tools for related lookups, such as umami_get_user for a single account, 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: team-owned websites are included, output shape is specified, and error behavior (auth failure vs 'No websites found') is disclosed.

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?

Well-structured with clear Args, Returns, Examples, and Error handling sections. The key 'start here' advice is front-loaded, and each section earns its place without redundancy 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?

Despite having no output schema, the description provides the full JSON return shape, parameter details, use-case examples, and error handling. An agent has everything needed to invoke the tool correctly and interpret the result.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mostly restates the schema's parameter info, though the examples ('search="example.com"') add a small amount of practical guidance 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?

States a specific verb and resource ('List every website tracked in this Umami account') and immediately clarifies scope ('including websites owned by teams'). It also distinguishes itself from sibling tools by framing this as the discovery entry point when a website ID is unknown.

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

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

Explicitly tells the agent to 'Start here when you do not already know a website ID' and explains that every other tool takes an ID, name, or domain. It could name a specific alternative like umami_get_website for the already-known-ID case, but the guidance is still 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?

The description goes well beyond the annotations by disclosing partial-failure behavior: 'If website creation succeeds but team creation fails, the website still exists; the response reports the partial result rather than leaving it unclear.' It also explains recovery steps after replay/heatmap update failure. This is meaningful behavioral context that the annotations alone do not provide, and it does not contradict readOnlyHint=false or 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?

The description is long but well-structured into Args, Returns, Examples, and Error handling, with the core purpose and routing statement front-loaded. Every section earns its place given the tool's complexity: nine parameters, conditional behavior, return shape, and failure semantics all need explanation. Nothing feels redundant or decorative.

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 provides a complete return JSON shape, which is essential for an agent interpreting results. It also covers examples, parameter dependencies, and several partial-failure scenarios. For a tool that creates multiple related resources and has follow-up recovery paths, this is more than sufficient for correct invocation and interpretation.

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

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

Although the schema covers 100% of parameters, the description adds substantial meaning beyond the schema: 'Omit to create the website under your personal account instead,' 'Ignored if grant_user_id or team_name is omitted,' and 'Only applied if replay_enabled or heatmap_enabled is set.' It also tells the agent where to source grant_user_id ('from umami_list_users') and includes real-world examples mapping intent to 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 states a specific action: 'Set up everything Umami needs for a new client or project in a single call: register the website, optionally create a dedicated team for it, and optionally grant an existing internal user access to that team.' This clearly identifies the resource, the verb, and the scope. It also distinguishes itself from sibling tools by explicitly positioning itself as the 'fast path' versus separate creation tools.

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 says when to use this tool: 'This is the fast path for "get this new site tracked and set up properly."' It also gives a concrete when-not-to-use rule: 'For anything more custom, for example multiple websites under one team, use umami_create_website, umami_create_team, and umami_add_team_user individually.' This is clear routing guidance with named alternatives.

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 this as destructive and non-read-only, but the description adds valuable behavior beyond those flags: it requires confirm=true and explicitly scopes the destruction by noting that login and personally owned websites remain intact. This is genuinely useful context for an agent invoking a destructive 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 key behavioral information is front-loaded in the first two sentences, followed by a compact Args/Returns block. There is no filler, though the Args section does duplicate what the schema already provides.

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

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

Given the tool's low complexity, rich input schema, and annotations, the description covers all critical call-time concerns: the confirmation requirement, the precise side effects, and the expected return shape. This is enough for an agent to invoke the tool correctly without external 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 description coverage is 100%, so the input schema already documents team_id, user_id, and the confirm constraint. The description's Args block mostly restates the schema without adding new semantic meaning, earning the baseline score of 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 opens with a specific verb and resource, 'Remove a member from a team', and clarifies the exact scope by stating that the user's login and personally owned websites are unaffected while access to shared team websites is lost. This clearly distinguishes it from sibling tools like delete_user or delete_team.

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 the goal is to revoke a user's access to a team's shared websites—and clarifies what it does not do, such as deleting the user's login or personal websites. However, it does not explicitly name alternatives like update_team_user for role changes or delete_team for removing the entire team.

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 (destructiveHint=true, readOnlyHint=false), the description discloses what is destroyed, what is preserved, that the action is irreversible, that confirm=true is required, and that data collection restarts fresh. This is precisely the behavioral context an agent needs before invoking a destructive tool.

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

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

The summary is front-loaded and the Args/Returns/Examples structure is clear and easy to scan. The irreversibility warning is repeated a few times across the description and schema, but for a destructive action this emphasis is acceptable rather than wasteful.

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

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

For a two-parameter destructive tool with no output schema, the description provides the return shape, an example, and clear statements of effect and guardrail. The main gap is the inconsistent required status of the website parameter and no explicit mention of the default-website fallback behavior.

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 both parameters, but the description adds a helpful explicit example. However, it labels website as required while the schema says it is optional if UMAMI_DEFAULT_WEBSITE is set, which directly contradicts the input schema and could cause an agent to demand a value unnecessarily.

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 destructive action: 'Permanently delete all collected data for a website' and enumerates exactly which data types are affected (pageviews, sessions, events). It explicitly notes that the website registration and tracking ID are kept, which distinguishes it from umami_delete_website and prevents confusion with sibling tools.

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 concrete use case ('Wipe the test data we collected before going live') and clearly states the confirm=true requirement. It does not explicitly name alternatives or say when not to use it, but preserving the registration implicitly differentiates it from full deletion, which is enough for an agent to route correctly.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description stays consistent with that safety profile. It adds genuinely useful behavior beyond annotations: partial-failure handling (failing breakdowns are omitted with a note), default behaviors (compare=true, default breakdown set), and the markdown/json output distinction. However, it states the range default as '30d' while the input schema says '7d' — an internal inconsistency that could mislead an agent.

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

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

The description is long but well-structured with labeled sections (Args, Returns, Examples, Error handling) and a strong front-loaded first sentence. The Args block largely duplicates the 100%-covered schema descriptions, which is the main redundancy; the Returns JSON shape and examples earn their space given that no output schema exists.

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 tool with no output schema, this is nearly complete: it provides a full return shape, error-handling semantics, default behaviors, and three worked examples spanning range, compare, and filters usage. Minor gaps: the skipped-breakdowns note in error handling isn't reflected in the documented JSON shape, and the range default conflict creates 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic value: website accepts 'ID, name, or domain', filters are clarified as applying 'to every part of the report', and the examples map natural-language requests to concrete parameter values (range='last_month', filters={ country: 'US', device: 'mobile' }). The added value is partly undermined by the conflicting range default ('30d' in description vs '7d' in schema), which keeps this below a 5.

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?

Opens with a specific verb and resource — 'Build a complete traffic report for a website in one call' — and enumerates exactly what the report contains (headline stats, period-over-period change, ranked breakdowns across eight dimensions). It also names its closest siblings (umami_get_stats, umami_get_metrics), so an agent can distinguish it from the other analytics tools without opening schemas.

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

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

Gives an explicit preference rule: prefer this over 'chaining umami_get_stats and several umami_get_metrics calls' for broad questions, and lists concrete route-to-alternative conditions ('one specific dimension, deeper pagination, or expanded engagement metrics'). Named alternatives plus selection criteria make the decision unambiguous.

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

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

Annotations already mark this as a non-read-only, non-destructive, idempotent write, so the description adds value by noting that rotating the access code invalidates the old one. It also documents the return object shape, which is useful because no output schema is provided. 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 compact and front-loaded with a clear purpose sentence, followed by a short Args block and a Returns line. The Args block somewhat duplicates the schema, but the overall structure is scannable and free of unnecessary prose.

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 tool, the description covers the core operation, side effects, and return shape. However, it does not state whether at least one of name or access_code must be provided, or whether both can be updated together, which leaves a real ambiguity for correct invocation.

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