Tracklution

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

Annotations cover the safety profile (destructiveHint=true, idempotentHint=false), and the description goes well beyond them: the URL is a single-use credential, `login_link_consume_disabled`/HTTP 503 means the feature is disabled, and required permissions differ per target_page ('dns' needs admin, others need view). These are authorization and side-effect facts the agent cannot infer from the schema.

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

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

Front-loaded with the core action and scope, then error/permission caveats, then a sibling disclaimer. Dense but every sentence carries operational information; only the error-code granularity could be trimmed.

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

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

An output schema exists, so return values need not be described. The description covers the scope restriction, error semantics and permission requirements, which is the important context for a credential-minting mutation. The residual gap is the undocumented non-`target_page` parameters.

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

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

Schema description coverage is only 17% across 6 parameters, so the description must carry weight. It usefully explains the `target_page` enum's permission implications, but says nothing about `idempotency_key`, `expires_in_minutes`, `container_id`, or `container_hash`, leaving most parameters to an undocumented 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 first sentence states a specific verb (creates), resource (one-time dashboard login URL) and the effect on `target_page`. It also explicitly disclaims a sibling role, saying it is 'Not a data tool: analytics questions are answered by get_summary / get_report', so an agent can separate it from the query_* and get_* 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?

It states the applicability precondition ('after setup'), a hard scope restriction ('MAIN SERVER CONTAINERS ONLY'), the failure mode on other servers (`container_pinned_to_other_server`) and the alternate path (`data.manual_handoff`). It stops just short of naming a sibling tool to call in the non-main-server case, but the routing context is unusually explicit.

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

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

Annotations already cover readOnly/non-destructive, and the description adds value beyond them: it clarifies the output is diagnostic metadata, not analytics, and discloses that results span every connected server (a non-obvious multi-server behavior). It doesn't mention failure modes (e.g., what happens with an invalid/expired key), so it sits just under full marks.

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 negation-and-scope line is front-loaded, the returned fields come next, and the routing/exclusions come last. Every clause carries decision-relevant information; there is no filler.

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

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

With an output schema present, the description needn't document return structure, yet it still names the four key fields. For a zero-param read tool with annotations, nothing an agent needs in order to select and call it 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?

Zero parameters, so the baseline is 4. The description implicitly confirms a no-argument call ('for every connected server') and doesn't introduce any confusing parameter-like language.

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 ('API key inspection') and immediately negates the most likely misread ('does NOT return any analytics data'). Explicitly enumerates returned fields (key name, prefix, container count, expiry) and the 'every connected server' scope, which separates it cleanly from get_summary/get_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?

A dedicated USE WHEN block gives two concrete triggers (identity/expiry questions, authorization errors) and an explicit exclusion with a named alternative: 'For any data question, skip this and go straight to get_summary or get_report.' This is the strongest form of routing guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds value beyond that with the negative scope ("no time-series or event data") and the ordering prerequisite, though it says nothing about auth requirements or response shape.

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

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

Front-loaded with the core purpose, then organized into scannable USE WHEN bullets with a closing scope note. Every sentence carries information; there is no filler.

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

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

With an output schema present, return values need no prose explanation, and the description still supplies the two things an agent actually needs — the list_containers prerequisite and how this tool pairs with get_summary/get_report. Nothing material 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 both parameters (server_name, container_id) are already fully documented with the trc_ prefix hint and the list_containers pointer. The description reinforces the container_id lookup but adds no syntax or format detail beyond the schema — baseline 3 is correct.

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

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

"Detail view of one container" names a specific verb and resource, then specifies exactly what it reveals (tracked event names, active connectors) — information an agent can use to distinguish it from list_containers and get_report without opening a schema.

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

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

A dedicated USE WHEN block gives explicit triggers (need event names, need connector alias, user asks what's set up) and names the sibling tools each feeds into. It also flags the prerequisite (call list_containers first) and explicitly states what it does NOT return.

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, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds a useful return-shape hint ('with the search_events fields'), but says nothing about error behavior for invalid ids or whether the TE… dashboard id resolves to the same object.

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

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

One front-loaded sentence with no filler; the id-format detail is placed immediately after the verb. The trailing clause 'with the search_events fields' is terse to the point of being slightly ambiguous, but it is not 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?

An output schema exists, so return values need not be spelled out, and parameters are fully documented in the schema. The only remaining gap is the absence of any guidance on failure modes or on how this differs from search_events, which keeps it short of a 5.

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

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

Schema description coverage is 100%, with all three parameters documented including the evt_…/TE… formats and the multi-server requirement for server_name. The description restates the id formats but adds no meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Returns one event by its id') and scopes it to a single item, which implicitly separates it from list_events, query_events, and search_events. It does not explicitly name those siblings, so differentiation still requires the agent to infer it from the word 'one'.

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?

Single-item retrieval by id implies the use case (you already have an event id), but there is no explicit when-to-use or when-not, and no named alternative such as search_events for id-less lookup. Usage is inferable rather than stated.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the description only needs incremental context. It adds real behavioral value by disclosing data freshness ('nightly') and the fixed 7-day window, which an annotation cannot express. It does not mention rate limits or result size, so it stops short of a 5.

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

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

Front-loaded with the USE WHEN trigger and only three sentences total, so every sentence earns its place. The trigger list trails off with an ellipsis ('identity signal…'), which is slightly loose, and the 'nightly / last 7 days' detail sits after the trigger rather than up front.

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

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

An output schema exists, so return-value detail is not required, and the required 'container_id' is fully documented in the schema. The description supplies the trigger context, the data window, and the routing alternative. It could be marginally stronger by noting the Insights are scoped to a single container.

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

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

Schema description coverage is 100%, including the enum semantics for 'view' (report vs metrics) and the meaning of 'detail', so the schema carries this dimension. The description adds no parameter-level detail beyond that, which is the expected baseline when the schema is complete.

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

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

States a specific verb and resource ('Returns Tracklution's nightly Insights') with an explicit scope window ('last 7 days'), which distinguishes it from the sibling get_summary. An agent can identify the tool without opening the schema.

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

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

Opens with an explicit 'USE WHEN' trigger list (tracking health, data quality, consent, ad blockers, bots, identity signal) and names the alternative for a different case: 'For raw totals over a custom date range use get_summary.' Both the when and the when-not are stated.

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

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

Annotations already establish read-only, non-destructive, non-open-world behavior. The description adds real value beyond that: the `_sensitive_webhook` block carries a live URL and only appears in `structuredContent`, and it clarifies that `common_mistakes[]` are optimal-vs-acceptable notes rather than breakage warnings, preventing an agent from over-reacting to 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?

Front-loaded with the core purpose, then organized by output key with backtick notation. Dense but every clause carries meaning; the jargon-heavy style is efficient rather than padded.

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

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

An output schema exists, so return values need not be re-explained, yet the description adds useful structural hints about keys and where sensitive data lives. For a 10-parameter tool it leaves some parameter-level gaps, but covers the behavioral and output-shape essentials an agent needs.

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 only 30%, so the description must compensate. It does explain the conditional flags (`has_checkout`, `has_login`) and indirectly maps `event_goal` values to `framework_snippets` keys, but several parameters (`app_dir_path`, `nextjs_version`, `container_id`, `event_goal` semantics) remain undocumented in the description.

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

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

States a specific verb and resource — returns paste-safe tracking snippets, webhook templates, recommended events, mistakes, and verification instructions for a framework. An agent can distinguish this from siblings like select_installation_method or verify_and_score without opening the schema.

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

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

Usage is implied rather than stated: the conditional notes (`has_checkout=true` for purchase, `has_login=true` for contact_info) and the link to `verify_and_score` scoring hint at the workflow, but there is no explicit 'call this after X' or 'use this instead of Y' guidance against the many sibling installation tools.

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

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

Annotations already declare readOnlyHint/destructiveHint/openWorldHint, so safety is covered. The description adds genuine value beyond them: `recalculate=true` triggers a slower fresh scoring pass, and the multi-server path returns `tool_to_call: null` with `data.manual_handoff`. That hand-off behavior is non-obvious and well 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?

Two tight paragraphs, front-loaded with the core behavior before the edge case. Field-name jargon (`tool_to_call`, `data.manual_handoff`) is dense but informative; little wasted text.

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

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

An output schema exists, so return-shape detail is largely redundant but harmless. The description covers the tricky multi-server auth/hand-off path that the schema does not, leaving only minor gaps around the non-required parameters. Adequate for a read-only scoring tool.

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

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

Schema coverage is only 33%, so the description should carry more weight. It explains `recalculate` semantics well, but says nothing about `framework`, `auth_token`, `container_id`, or `server_name` beyond what the schema already states. Partial compensation for the coverage gap.

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

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

States a specific verb and resource ('Returns scoring-driven ordered setup steps for a container') and names the concrete return fields (`overall_progress`, `next_steps[]`). It does not explicitly differentiate from setup-related siblings like get_status or verify_and_score, but the purpose is unambiguous.

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

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

Usage is implied (fetch ordered setup steps) and the multi-server hand-off scenario is described, but there is no explicit 'use this when X, not Y' routing against siblings such as get_status, get_onboarding_session, or verify_and_score. Guidance exists for one edge case only.

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, destructiveHint=false and closed-world scope, so safety is covered. The description adds genuinely useful behavioral context beyond that: the tool requires authentication and the required credential changes depending on whether the session is pre-auth or user-linked. It doesn't cover failure modes (e.g. missing/invalid session) but adds real value.

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

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

Two sentences, zero filler, with the primary purpose front-loaded and the auth conditionality following. Every clause carries information the agent needs.

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

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

An output schema exists, so return values need not be described, and annotations cover the safety profile; the description fills the remaining gap (which credential to supply). It omits error/not-found behavior, which is a minor gap for a read tool.

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

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

Schema coverage is only 67%, so the description must help — and it does by tying the two auth parameters together into a mutually exclusive choice keyed on session state, adding the 'before sign-up' nuance the schema's terse per-field notes lack. `onboarding_session_id` format is left entirely to the schema's pattern, hence not 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?

States a specific verb and resource ('Returns the replayable onboarding transcript for `onboarding_session_id`'), which no sibling covers — none of the other get_*/list_* tools deal with onboarding sessions. An agent can identify the target object and the key input from the first clause alone.

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

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

The description gives conditional context for the two auth modes ('once the session has a user' vs 'before sign-up'), which tells the agent which credential path applies. It does not name alternative tools or state when not to use this one, so it falls short of full when/when-not 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, non-destructive and closed-world, so safety is covered; the description adds the meaningful operational constraint of 'at most 30 days per request'. It doesn't discuss rate limits or error behavior, but the output schema handles 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?

Front-loads the core purpose and constraint, then the sibling-routing sentence; no filler. The colon-list phrasing is dense but every clause carries scope information, though it reads telegraphically.

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

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

With a full output schema and safety annotations present, the description need only cover scope, limits and routing, which it does. Minor gaps like multi-server behavior are left to the schema's server_name description.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning beyond the schema: connector is characterized as 'events delivered to one destination' and attribution is tied to the 'v1 first-click attribution model', clarifying semantics the schema's short blurbs leave implicit.

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 ('pre-aggregated event counts from the v1 API'), enumerates available breakdown dimensions, and explicitly names what differentiates it from run_report (connector filter, v1 first-click attribution). An agent can distinguish it from siblings without opening the schema.

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

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

Gives explicit when-to-use and when-not-to-use: connector filtering and first-click attribution select this tool, while 'Sessions, channels, landing pages, goals, period comparison and longer ranges' route to run_report. The 30-day cap further scopes appropriate use.

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 read-only and non-destructive, but the description adds substantial behavioral context beyond them: the key is created by the user in the dashboard, the tool never returns a key, and the response also carries the API docs link, base URL and safe-use rules (server only, caching, expiry). That is exactly the kind of side-effect and workflow disclosure an agent needs here.

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?

Four sentences, purpose-first, then usage, then the crucial negative scope, then response contents. Each sentence earns its place, though the final sentence about return contents partially overlaps the output schema and could be trimmed.

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

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

With an output schema present, return values need not be spelled out, and the description still covers usage, side effects and limitations well. The only gap is the dangling reference to an expiry date that isn't a parameter, which slightly muddies the picture for a three-parameter 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 purpose, server_name and container_id thoroughly, and the description adds little beyond noting that a name and expiry date are pre-filled. The mention of an 'expiry date' has no corresponding parameter, which adds a small amount of confusion rather than clarity. Baseline 3 applies.

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

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

The description opens with a concrete verb+resource pair ('Builds a link to the Tracklution dashboard that opens the "Create Reporting API key" form') and scopes it to one container's company, immediately distinguishing it from creation tools like get_api_key_info. An agent can tell what artifact this produces without opening the schema.

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

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

It gives a clear triggering condition ('Use it when the user wants to build a website, backend or script that reads Tracklution data outside this chat') and rules out a common misconception by stating the tool 'does not create a key and does not return one.' What's missing is explicit routing to a sibling (e.g., get_api_key_info for inspecting existing keys), so it stops short of full when/when-not/alternatives 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 safety, but the description adds valuable behavioral detail: the first sources are limited to 3 to 90 days, pages are returned in order with their times, and event values are grouped per currency. These are useful traits beyond the annotations, though auth and response-size behavior are not covered.

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 remains a single dense sentence. It is appropriately sized, though cramming several return-value details into one sentence makes it slightly less scannable.

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

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

Given that an output schema exists and annotations cover safety, the description is largely complete: it identifies the id format and summarizes the returned session details. The main remaining gap is guidance on when to choose this tool over its sibling search/list tools.

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

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

Schema description coverage is 100%, so the baseline is 3. The description repeats that session_id can be a ses_… or VS… id, but this is already documented in the schema, and it adds no meaning for container_id or server_name.

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: 'Returns one session by its id'. It also distinguishes the tool from siblings like list_sessions and search_sessions by emphasizing a single session and naming the fields sourced from search_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?

Usage is implied: fetch a session by id and use its event ids with get_event. However, the description does not explicitly state when to use this tool versus list_sessions, search_sessions, or query_sessions, and gives no exclusions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuine behavioral context beyond that: it discloses the scope of the operation (every connected server) and the shape of the outcome (reachable / unreachable), which tells the agent what kind of signal to expect. It stops short of describing failure modes or timing, but with annotations and an output schema present 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?

Front-loaded with the key constraint in the first clause, then a compact USE WHEN block. Every sentence carries distinct information — scope, exclusions, and the routing rule — with no filler.

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

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

An output schema exists, so return values need not be explained, and annotations cover the safety profile. For a zero-parameter connectivity probe the description supplies everything an agent needs: what it checks, what it returns, and when to prefer a data tool instead.

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?

Zero parameters, so per the rubric the baseline is 4. There is nothing for the description to disambiguate, and it correctly implies the tool takes no input by describing an unconditional ping of all servers.

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 ('Pings every connected Tracklution server and reports reachable / unreachable') and immediately negates the common misread: 'Connectivity check only — does NOT return any analytics data.' This cleanly separates it from data-returning siblings like get_summary and get_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?

Provides explicit USE WHEN scenarios (integration 'isn't working', verifying a newly-added server) and an explicit when-not-to-use routing rule: 'For any data question (counts, events, sessions), skip this and go straight to get_summary or get_report.' Both the positive and negative conditions are named with 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 declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: the 30-day maximum range, single-container scope, and 'in one call' aggregation promise. It stops short of describing result shape, but an output schema exists to carry that.

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

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

Two sentences, front-loaded with what you get before the routing alternatives. The first sentence is a dense enumerated list but each item carries information; nothing is padding. Slightly run-on, which keeps it from a 5.

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?

Covers return contents, scope limits, the routing decision against both relevant siblings, and safety behavior is carried by annotations plus an output schema. An agent has everything needed to call this correctly and to pick it over alternatives.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes slightly beyond the schema by imposing the ≤30-day cap on date_from/date_to, which the schema itself does not state. It does not explain currency, attribution, or server_name, but those are documented in the schema.

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

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

States exactly what is returned (event totals, consent stats, recovery stats, per-source breakdown) with a concrete scope (one container, one date range of at most 30 days). It explicitly distinguishes itself from run_report and get_report by naming the report types each covers, so an agent can select without opening any schema.

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

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

Gives explicit routing: sessions/channels/landing pages/goals/period comparison/longer ranges go to run_report, and event-name/day/hour/device/browser breakdowns go to get_report. It also states the selection constraint (single container, ≤30-day range) that governs 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 declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so safety is covered. The description adds real context beyond that: it discloses the cross-server aggregation scope, that `domain` can be null on freshly created containers, and that `container_hash` is the secret half of onboarding auth and is null on older backends with a documented fallback (register_and_provision with auth_token + website_url). That fallback path is genuinely useful behavioral disclosure.

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

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

Front-loaded with the entry-point role, then a scannable USE WHEN list. Dense and mostly earned, but the final sentence about return values is heavy with nested parentheticals (the container_hash fallback aside is a long aside inside a list of fields) and partly duplicates the 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?

Handles the tricky cases an agent would otherwise stumble on: what to do for multi-server setups, how to resolve a container from a host name when `domain` is null, and the legacy-backend path when `container_hash` is missing. With an output schema present, the field enumeration is a bonus rather than a requirement, so 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% for the single `server_name` parameter, so the baseline is 3. The description improves on it by tying the parameter to a concrete motive ('You need the server_name for multi-server setups'), which tells an agent why it would ever set it rather than always omitting 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?

States a specific verb and resource ('Lists every tracking container the user can access across all connected servers') and immediately defines the resource unit ('Each container is one tracked website or app'). The 'Entry-point tool' framing plus the cross-server scope distinguishes it cleanly from the sibling get_container, which fetches a single one.

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

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

The USE WHEN block explicitly covers the triggering conditions: session start because get_report/get_summary/list_events/list_sessions need a container_id, brand-name-without-ID lookups, multi-server setups needing server_name, and onboarding pair resolution. It also names the downstream tools that depend on its output and states what to do when `domain` is null.

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 safety is covered; the description adds genuinely new behavior context: this is a legacy v1-API path and its return payload is a subset of get_event's (missing page URL and destinations). It does not discuss error behavior for invalid ids, but an output schema exists to carry 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?

Two short sentences, both earning their place: the first fixes the name/purpose mismatch, the second routes to the preferred sibling. Legacy status is front-loaded.

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

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

With full schema coverage, an output schema, and clear annotations, the remaining burden is orientation — and the description meets it by flagging legacy status and the get_event alternative. A slightly firmer deprecation/selection rule is the only thing 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 all three parameters (including the evt_/TE id formats and the multi-server container constraint) are already documented in the schema. The description only references the id formats the schema already explains, adding no syntax or semantics beyond it — baseline 3 applies.

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

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

The description states a specific verb and resource — returns ONE event by its id — and explicitly corrects the misleading 'list' name by emphasizing single-item retrieval. It also names the sibling get_event and distinguishes scope, so an agent can tell them apart without opening either schema.

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

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

Labeling it a 'Legacy tool' plus noting that get_event returns the same event with its page URL and destinations strongly steers the agent toward the non-legacy alternative. It stops short of an explicit 'prefer get_event unless X' rule, so it's clear context rather than a hard when/when-not directive.

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

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

Annotations already declare readOnly and non-destructive, and the description adds real behavioral context beyond them: request limits, realtime fields, timezone, data_from, and ingest_lag_seconds. It stops short of describing pagination or failure behavior, so 4 rather than 5.

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

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

Front-loaded with the core purpose, then a compact enumeration of what is returned. The second sentence's return-value list is slightly long given an output schema exists, but nothing is wasted.

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

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

For a two-parameter read-only listing tool with full schema coverage and an output schema, this covers scoping and content well. The only minor gap is that multi-server behavior is left entirely to the schema rather than acknowledged.

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 documents both container_id and the multi-server server_name requirement. The description only reinforces container scoping ('for one container') and adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource (lists dimensions and metrics) and ties the scope to run_report's accepted fields for one container. The relation to run_report cleanly distinguishes it from the sibling that actually executes reports.

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 'that run_report accepts' makes the natural usage (discovering valid fields before calling run_report) evident, and the scope ('for one container') clarifies context. No explicit when-not or named alternatives, keeping it 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 establish readOnlyHint=true, destructiveHint=false, and openWorldHint=false. The description adds useful context beyond annotations: it is a legacy v1 API tool, returns exactly one session, and discloses the returned field groups. It does not discuss auth or rate limits, but that is minor given the annotation coverage.

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

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

The description is two tight sentences, front-loaded with 'Legacy tool' and 'returns ONE session'. Every clause carries selection-relevant information, including the sibling contrast.

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 legacy single-record read with an output schema and rich annotations, the description is complete enough. It covers what the tool returns, why it exists, and how it differs from get_session, while the schema handles parameters and annotations cover safety.

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

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

Schema description coverage is 100%, and the schema already documents session_id prefixes, container_id, and server_name. The description only reinforces that the id fetches one session and adds no syntax or constraints beyond the schema. 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: it returns ONE session by id from the v1 API, with named field groups. It also distinguishes the tool from sibling get_session by explaining what get_session returns but does not include. The mismatch with the name list_sessions is explicitly corrected by 'returns ONE session'.

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

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

The description gives a clear contrast with sibling get_session, implying this tool should be selected when funnel-stage counts, contact flags, or the full event timeline are needed. It does not explicitly address the other session list/search/query siblings, so the guidance is strong but not exhaustive.

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

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

Annotations already establish that this is a read-only, non-destructive, closed-world operation. The description adds useful behavioral context: the listed reports compare the last 28 full days with the previous 28 days, and their requests can be passed directly to run_report.

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

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

The description is three tight sentences with no waste. It front-loads the core action and then adds the run_report compatibility and time-comparison details that an agent needs for correct use.

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 annotations, complete input schema coverage, and presence of an output schema, the description is complete enough for correct invocation. It also adds the important temporal context that the standard report requests compare the last 28 full days with the prior 28 days.

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 both server_name and container_id are already documented in the schema. The description only implies the container scope through 'one container' and adds no parameter-specific syntax or constraints 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 gives a clear verb and resource: 'Lists the standard reports of one container' and enumerates the categories Audience, Acquisition, Behavior, and Conversions. It also ties the tool to the sibling run_report by explaining that each variant contains a request run_report accepts as-is, making its distinct role easy to identify.

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 makes the downstream usage explicit: list standard report variants, then pass their request to run_report. It does not explicitly state when to prefer this over other report-related siblings such as get_report, but the intended workflow is clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: the 7-14 day retention window and the pagination contract (meta.cursor.next_cursor), which are the two things an agent would otherwise get wrong. It does not discuss cost/rate limits, but for a read tool with an output schema that is minor.

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

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

Three short sentences, zero filler, with the legacy status and retention limit front-loaded before the sibling comparison. Every sentence carries information the agent needs.

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

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

For a 20-parameter legacy tool this is complete on the dimensions that matter — scope, retention, deprecation status, and pagination — and an output schema exists so return values need not be explained. Only the absence of explicit cost/performance guidance keeps it from a 5.

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

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

Schema description coverage is 100% across all 20 parameters, so filtering semantics (status default, per_page guidance, clid flags) are already fully documented. The description only restates the cursor mechanism, adding nothing beyond the schema — baseline 3 is appropriate.

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

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

States a specific verb+resource ("lists events from the v2 store") and immediately contrasts it with the sibling search_events, including what each covers. An agent can tell it apart from list_events/search_events without opening a schema.

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

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

Names the alternative (search_events) and its advantages — 6-month window and more filters — which implicitly routes the agent away from this tool for anything beyond ~2 weeks. It stops short of an explicit "use this only when..." rule, but the decision 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is clear. The description adds valuable context beyond annotations: the v2 store retention window of roughly 7-14 days and the pagination mechanism via meta.cursor.next_cursor.

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

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

Three short sentences with no wasted text. It is front-loaded with the legacy status and immediately gives the sibling comparison and pagination 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?

Despite 18 parameters, the schema fully documents them and an output schema exists. The description supplies the critical missing context: legacy retention limits, the search_sessions alternative, and cursor pagination.

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

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

Schema description coverage is 100%, so all 18 parameters are already documented in the input schema. The description adds only high-level pagination context and the legacy date-range limitation; it does not need to explain individual filter 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 verb and resource: lists sessions from the legacy v2 store. It explicitly distinguishes this from the sibling search_sessions, which covers a longer period and supports report-dimension filters.

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 names the alternative search_sessions and explains the key selection condition: search_sessions covers roughly six months with filters, while this legacy tool is limited to about 7-14 days. An agent can route correctly without opening either schema.

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 annotations: discloses the required idempotency_key, the welcome/set-password email and its pending_user_activation/welcome_email_sent_to signals, the 60-minute JWT lifetime, admin-vs-view permission requirements per container state, per-domain rate-limit semantics, and multi-server next_action.server_name behavior. This is rich operational context the annotations (readOnly/destructive/idempotent hints only) cannot convey.

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?

Long but well-structured: the core behavior and mode branching are front-loaded, followed by a scannable error list. Nearly every sentence carries operational value (recovery URLs, permission names, retry semantics), though the enumeration of returned token fields is somewhat verbose given an 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 15-parameter mutating entry-point tool with an output schema present, the description covers the critical paths, error taxonomy, and permission model well, so return values need not be re-explained. The remaining gap is the large set of undocumented optional parameters (dry_run, framework, agent_client, event_source_system, company), whose semantics an agent must infer.

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

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

Schema description coverage is only 20% across 15 parameters, so the description must compensate. It does add meaning for idempotency_key (UUID v7), auth_token (existing-user path), website_url, and the email/name branch, but leaves goal, phone, company, dry_run, framework, agent_client, heard_from, event_source_system, and the onboarding_session_* pair unexplained in both schema and description.

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

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

States a specific verb and resource ('Creates or reuses a Tracklution account and the first tracking container for website_url') and immediately distinguishes the two operating modes (new email vs. existing auth_token). An agent can tell what the tool produces without opening the schema.

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

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

Explicitly says which path applies when ('New email: ...' vs. 'With auth_token instead of email/name: ...') and gives recovery actions for each error condition, including re-running the tool after the user creates a container. It does not, however, position itself against any named sibling (e.g., create_login_link, get_onboarding_session), so routing among siblings is left implicit.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), and the description adds real value beyond them: bots are excluded from counts, and an empty result may signal a late realtime feed rather than zero traffic. That empty-result caveat is exactly the kind of non-obvious behavior an agent needs.

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

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

Three tight sentences: scope first, then the enumerated dimensions and metrics, then the bots and late-feed caveats. No filler and nothing buried.

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

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

With an output schema present, return values need no explanation, and the description covers the enumerated vocabulary the schema delegates to it plus the empty-result semantics. Minor gap: nothing about multi-server usage or the minuteRanges default beyond what the schema states.

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%, but the metrics and dimensions schemas explicitly defer to the description for valid names, and the description supplies them. It says nothing about limit, orderBys, minuteRanges, or server_name beyond what the schema already states, so it adds meaning where it matters most and stays silent elsewhere.

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 (runs a report) plus a precise scope: hits from the last 30 minutes. The 30-minute window implicitly separates it from the sibling run_report, though it never names that sibling explicitly.

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

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

The realtime window implies when to reach for this tool over run_report, but the description never states the alternative or an exclusion. An agent must infer the routing decision from the 'last 30 minutes' phrasing alone.

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

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

Annotations already establish that this is a read-only, non-destructive operation. The description adds meaningful behavioral context beyond annotations: date-range caps, zero-filled days before data_from, no error for pre-data dates, session attribution on start day, exclusion of blocked/deleted events, and possible discrepancy with get_summary.

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 operation and then efficiently adds constraints and data caveats in one dense but purposeful sentence. There is no filler, and every clause contributes operational meaning.

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 complexity, the presence of an output schema, complete schema descriptions, and read-only annotations, the description covers the important semantic pitfalls: valid names must come from list_metrics_dimensions, date limits, pre-data zero behavior, and session-counting differences from get_summary. Nothing critical for correct invocation is missing.

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

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

Schema description coverage is 100%, so the input schema already documents the parameters in detail. The description reinforces key constraints such as the 0-7 dimensions and 1-10 metrics limits and the page-dimension/page-metric date-range restriction, but most of this repeats schema content rather than adding new parameter-level semantics.

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

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

The description clearly states a specific verb and resource: it runs an analytics report over Tracklution sessions using a GA4 runReport-shaped API. It distinguishes the tool from get_summary by noting differing session totals and depends on list_metrics_dimensions for valid names, but it does not explicitly differentiate itself from related siblings such as get_report or run_realtime_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 implies that this is the tool for custom reports with date ranges, dimensions, and metrics, and it usefully points to list_metrics_dimensions for valid names. However, it gives no explicit 'use this when...' guidance or side-by-side comparison against related reporting siblings like get_report or run_realtime_report.

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

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

Annotations declare destructiveHint=true and openWorldHint=true, and the description adds genuinely non-obvious behavior: no auth required, a single-use sensitive token, and creation of a persistent onboarding session. It does not address why the call is destructive, whether repeated scouting creates duplicate sessions (idempotentHint=false), or any rate limits.

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

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

Three tight sentences, front-loaded with the auth/visibility constraint before purpose and outputs. No filler, though the final sentence is dense with backticked identifiers and chaining instructions packed into one line.

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 non-idempotent, state-creating tool with an output schema, the description covers the essentials an agent needs: no auth, the session it creates, both returned values, and which sibling consumes each. Return-value explanation is a bonus since an output schema already exists.

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

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

Schema description coverage is 100% with enums documented for agent_client and framework_hint, so the schema carries parameter meaning. The description only alludes to website_url via 'fetches it' and adds no format or constraint detail beyond the schema, matching the baseline 3.

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

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

States a concrete verb set and resource: it fetches a public website, detects CMS/platform hints, and creates an onboarding session. It also names two siblings (register_and_provision, get_onboarding_session) and their roles in the flow, so an agent can place it in the workflow. It stops short of an explicit 'use this instead of X' contrast, which keeps it at 4.

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?

'Public discovery; works without auth' plus the explicit chaining rules (register_and_provision consumes both outputs; get_onboarding_session takes the token before sign-up) tell an agent exactly when this tool fits in the sequence. No exclusions or 'when not to use' guidance are given, so it does not reach 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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations: default date range, newest-first ordering, inclusion of every status, returned fields, and cursor-based pagination. It does not mention auth or rate limits, but those are less critical given the annotations.

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

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

The description is two dense but well-structured sentences, front-loaded with the core purpose and default behavior. Every clause adds useful information about scope, return fields, filters, or pagination, with no wasted wording.

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 complexity, full schema coverage, annotations, and an output schema, the description provides enough context to call it correctly: default date range, ordering, returned fields, filter categories, and pagination. It is slightly incomplete because it does not route the agent away from sibling event-query tools when another is more appropriate.

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 17 parameters thoroughly. The description names several filters and mentions paging, but it largely restates schema content and does not cover all parameters, such as limit, cursor, container_id, server_name, or pageLocation. Baseline 3 is appropriate when the schema carries the parameter documentation.

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

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

The description uses a specific verb and resource: 'Lists the events,' and states the date-range scope, default last 7 days, newest-first ordering, every status, and returned fields. It is clear what the tool does, but it does not explicitly differentiate itself from sibling tools such as list_events, query_events, or get_event.

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 through its filter list and pagination notes, making it clear this is for searching events with criteria. However, it does not explicitly say when to use this tool versus list_events, query_events, or get_event, nor does it state when not to use it. The reference to search_sessions filters is useful but not a full usage guideline.

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

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

Annotations already declare read-only, non-destructive, closed-world, so the description is free to add operational context — and it does: newest-first ordering, a 7-day default window, a data-freshness caveat ('a new session appears a few minutes after its events'), and cursor pagination. It stops short of describing result shape or edge cases like empty windows, but the behaviorally important traits are covered.

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

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

Front-loaded with the core action and the default scope, then the returned fields, then filter provenance and freshness. The field enumeration ('channel, source / medium, campaign, landing page, country, device and more') is a bit list-heavy but earns its place by telling the agent what comes back.

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

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

With an output schema present the description needn't explain return values, and it covers defaults, date limits, pagination, and ingestion latency. The remaining gap is sibling disambiguation — search_sessions vs list_sessions vs query_sessions is left ambiguous in a crowded family of session tools.

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

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

Schema coverage is 100%, so the schema already carries the per-parameter documentation and the baseline would be 3. The description adds genuine meaning the schema does not: filters accept the values of a run_report row, and 'paged with next_cursor' ties the cursor param to the pagination cycle. It doesn't elaborate on limit/date interplay, so not 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?

States a specific verb and resource ('Lists the sessions that started in a date range') plus the returned payload (report values, pageviews, events, landing URL, referrer) and sort order. It does not, however, distinguish itself from the closely related siblings list_sessions and query_sessions, which an agent would need to choose between.

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

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

Usage is implied rather than stated: 'The filters take the values of a run_report row' hints at how to pick filter values, and the 7-day default plus 400-day cap scope the call. There is no explicit when-to-use/when-not or routing to list_sessions/query_sessions for alternative access patterns.

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 annotations by disclosing that a required admin permission is needed, the exact failure mode for view-only users (HTTP 403 insufficient_permissions with details.required_permission='admin'), that errors[0].message is user-facing, and that a retry returns the same error. This is rich, actionable behavioral context on top of the existing readOnly/idempotent/destructive hints.

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

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

Three sentences, front-loaded with the core action before the mutation and permission details. Efficient with little waste, though the error-handling sentence is dense.

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

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

An output schema exists, so return values need not be described, and annotations cover the safety profile. The description adds mutation, permission, and error behavior, making it fairly complete for this mutating tool, with the main gap being the under-documented parameters.

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

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

Schema description coverage is low (29%), so the description must carry more of the parameter burden. It only notes that idempotency_key is required and implies the method enum; the other parameters (server_name, container_hash, auth_token, dry_run, container_id) receive no explanation, leaving much of the schema's meaning unexplained.

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: 'Persists the chosen installation method on the container.' This is clearly a write operation, distinguishing it from the many read-oriented get/list siblings. It does not explicitly name a sibling it is contrasted with, so it stops short of a 5.

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

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

Usage is implied: persisting a 'chosen' method signals this is a post-selection step in the installation flow. However, no alternatives are named and no explicit when-to-use / when-not guidance is given relative to siblings like get_installation_scripts or register_and_provision.

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

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

With annotations already declaring destructiveHint=true and idempotentHint=false, the description still adds substantial context the structured fields cannot: it states the tool is mutating, that `idempotency_key` is required, that the same key within 30s returns a cached response while a fresh key runs a new pass, and that `create_login_link` is refused on a non-main server. This is exactly the kind of side-effect, caching, and refusal behavior an agent needs before invoking.

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

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

The core action and the mutating/idempotency warning are front-loaded, then status interpretation is organized into terse bulleted groups, which suits the high branching complexity. It is long, and lines like the `data.set_events_seen` nuance sit near the edge of what earns its place, but the structure keeps it navigable.

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 high-complexity, many-state tool with an output schema present, the description supplies the missing behavioral and routing context (state meanings, follow-up tools, multi-server handling). Because a return schema exists, its detailed restatement of `status`/`scoring_complete`/`retry` fields is partly redundant, but nothing essential is absent.

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

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

Schema description coverage is only 25%, so the description must compensate, and it does for the most important parameter: it explains that `idempotency_key` is required and defines its 30-second caching semantics. However it says nothing about `expected_domain`, `expected_events`, `onboarding_session_id`, `auth_token`, or `container_hash`, leaving most parameters documented only by pattern/type.

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 states a specific, multi-part action: force-process recent events, recalculate scoring, and return a verification diagnosis. That clearly separates it from list/get siblings like get_status or get_summary, though it never explicitly names what it is NOT, so an agent must infer the boundary from behavior rather than an explicit contrast.

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 conditional routing: it tells the agent what each `not_ready_reason` means and what to do after the retry budget is exhausted (`get_next_steps` + `create_login_link`). It stops short of an explicit 'call this when...' statement or an exclusion against similar verification/status siblings, so context is clear but not exhaustive.

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