Tracklution

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

With no annotations provided, the description carries the full burden and does it well. It discloses the single-use token nature, tells the agent not to write to disk or echo the URL, describes the container_pinned_to_other_server refusal, the login_link_consume_disabled 503 when the flag is off, and the admin-permission requirement for target_page: 'dns'. This is rich, actionable behavioral context.

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

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

The description is long but information-dense, with critical warnings front-loaded and no filler. The second paragraph clearly separates exclusions/alternatives. It could be lightly restructured for scannability, but every sentence earns its place given the tool's complexity.

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 no annotations, 6 parameters, and a complex usage context, the description covers the main flow, error/refusal cases, feature-flag behavior, permission requirements, and security handling. The presence of an output schema reduces the need to describe return structure, and the description even mentions _request_id in structuredContent. This is complete for an agent to call correctly.

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

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

Schema description coverage is only 17% (container_hash is the only parameter documented in the schema). The description adds meaningful semantics for target_page (admin vs. view permission) but does not explain the purpose, constraints, or interplay of idempotency_key, container_id, auth_token, or expires_in_minutes. Since the schema leaves most parameters undocumented, the description should have compensated more.

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

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

Description states a specific verb and resource: 'Create a one-time dashboard handoff URL after AI setup.' It clearly distinguishes this from analytics siblings by explicitly saying it is for 'post-install navigation only' and not for data questions. An agent can immediately tell this is a discrete authentication/handoff tool rather than a query tool.

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 and when-not-to-use guidance: 'MAIN SERVER CONTAINERS ONLY' versus manual handoff on other servers, and 'DO NOT use this tool to answer analytics or stats questions' with named alternatives (get_summary, get_report, list_containers). It also covers the feature-flag-off fallback and permission requirements, leaving no ambiguity about 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?

With no annotations, the description carries the behavioral disclosure burden and does so well: it declares the operation is inspection-only, states it does not return analytics, and lists exactly what it shows. It does not cover error behavior or auth prerequisites, but the negative scope and output contents are clearly 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?

The description is front-loaded with the most important scoping statement, then organized into clear USE WHEN bullets and an explicit alternative. Every sentence 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?

For a simple zero-parameter read-only tool, the description gives complete operational guidance: what it returns, when to use it, and which sibling to choose for data questions. The presence of an output schema means the description need not restate return structure in detail.

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

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

The tool has zero parameters and an empty input schema, so there is no parameter semantics to add; the description correctly avoids inventing parameter details. This matches the baseline for a parameter-less tool.

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 precisely identifies the tool as API key inspection, enumerates the exact output fields (key name, prefix, container access count, expiry), and explicitly negates any analytics role, which distinguishes it from data-focused 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?

The 'USE WHEN' section gives concrete triggers, including the user asking about connected account/key or key expiration, and an authorization-error scenario. It also explicitly states when not to use it, directing data questions to get_summary or get_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?

With no annotations, the description carries the behavioral burden. It clearly discloses what the tool returns, what it deliberately does not return ('no time-series or event data'), and the prerequisite call to list_containers. It could add explicit read-only confirmation or error conditions, but the behavioral contract is clear.

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 uses bullets for conditions. Every sentence earns its place: purpose, usage triggers, prerequisite, and boundary of what the tool does not return. 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?

Despite having no annotations, the description gives a complete operational picture: what the tool reveals, when to use it, what to call first, and what to pair it with for missing data. An output schema exists, so return-value detail is not the description's responsibility.

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 parameters. The description reinforces that container_id starts with 'trc_' and that list_containers can supply it, but it does not add meaningful semantics 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 opens with a specific verb and resource: 'Detail view of one container.' It then states exactly what the tool reveals (tracked event names and active connectors), which distinguishes it from data-returning siblings like get_report and get_summary.

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' section names concrete trigger scenarios, tells the agent to call list_containers first to get the trc_ ID, and pairs get_container with get_report / get_summary for time-series data. It also tells the agent not to guess event names.

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

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

With no annotations provided, the description carries the full disclosure burden and delivers substantially: it reveals that the response includes a _sensitive_webhook block where only structuredContent carries the live URL, that every response embeds _request_id, and that the tracking engine deduplicates repeat Purchases, accepts late ContactInfo, and absorbs React Strict Mode double-fires — reframing common_mistakes as optimization hints rather than breakage warnings. This is exactly the kind of behavioral context an 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?

The description is long but uniformly dense and front-loaded: purpose first, then sensitive-handling warnings, then per-snippet conditions, then the common_mistakes interpretation. Every section carries unique, actionable information an agent needs before invoking, so the length is justified 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?

Given high complexity (10 parameters, conditional snippet generation, sensitive output handling) and zero annotations, the description covers purpose, sensitive-block behavior, snippet selection conditions, and downstream verification consequences; an output schema exists so return-value detail is not required. The single gap is flow positioning — it never states where this call belongs in the sequence relative to register_and_provision, select_installation_method, or verify_and_score.

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%, and the description compensates for the decision-critical parameters by mapping has_checkout=true to the purchase snippet, has_login=true to contact_info, and lead-gen to the lead snippet, giving behavioral meaning to the boolean/enum fields. Remaining parameters like container_id, framework, app_dir_path, and nextjs_version get no description-side explanation, though several are largely self-descriptive by 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 opening sentence names a specific verb ('Return') and a precise resource set (paste-safe snippets, webhook templates, recommended events, common mistakes, verification instructions) scoped by framework, which inherently separates it from query-style siblings like list_containers or query_events. However, it never explicitly contrasts itself with the installation-flow siblings it neighbors (select_installation_method, verify_and_score, get_next_steps), so differentiation is conveyed by content rather than 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 description provides exceptionally explicit post-call application rules: init and page_view are always required, purchase applies only when has_checkout=true, lead for lead-gen funnels, and contact_info when has_login=true, with a concrete consequence warning that skipping contact_info leaves verify_and_score.scoring_complete false. But there is zero when-to-call guidance versus alternatives — no mention of when to prefer select_installation_method, get_next_steps, or register_and_provision instead — so tool selection itself is left to inference.

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

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

With no annotations, the description carries the burden and covers key behavior: non-mutating, recalculate is expensive, every response contains _request_id in structuredContent, and non-main-server containers yield tool_to_call: null plus manual_handoff. This goes well beyond 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 purpose, compact behavioral notes, and a clearly separated server rule. Every sentence carries operational value and there is no redundant restating of schema fields.

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

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

The description covers the unusual multi-server behavior, recalculate cost, and response ID, and an output schema exists for return shape. It is complete for invocation, though the auth_token/container_hash mutual-exclusion detail is left to the schema description rather than the tool 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?

The description adds real meaning for recalculate (expensive fresh pass) and references the server_name condition, but schema coverage is only 33%. It does not add semantics for framework, auth_token, or container_id beyond what their names and types imply, so the compensation for low coverage is partial.

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 action—return scoring-driven ordered guidance for the agent—with a distinct resource and adds the non-mutating qualifier. The server rule about create_login_link/manual handoff also differentiates this from plain read-only getters, so an agent can tell what this tool contributes.

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 conditional guidance: recalculate=true only when a fresh scoring pass is wanted, and a clear server rule saying when to hand off manually instead of calling create_login_link. It does not explicitly contrast against other get_* siblings, but the context is strong enough to avoid misuse.

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 no annotations provided, the description must carry the burden of behavioral disclosure. It mentions the pre-auth token is sensitive and that every response includes `_request_id` in structuredContent, adding useful context. However, it doesn't explain what happens to the session data, whether the token is consumed or persists, or any rate limits or side effects, leaving gaps for an operation that retrieves sensitive data.

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

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

The description is three sentences, each earning its place: it states the core purpose, gives explicit auth-routing guidance, and notes a key response field. It is front-loaded with the primary action and does not waste words.

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

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

Given the tool's moderate complexity (3 parameters, output schema present), the description covers the essential decision point (which token to use) and alerts to a sensitive field. It lacks detail on error conditions, whether the session requires ownership, or how the transcript is returned (though output schema covers return shape). Given the presence of an output schema and the focus on auth, it's adequately complete, missing only non-critical edge-case info.

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 coverage is 67%: both auth_token and onboarding_session_token have descriptions, but onboarding_session_id only has a pattern without a description. The description adds crucial value by clarifying when each auth parameter is used (JWT for user sessions, pre-auth token for pre-auth sessions), which the schema doesn't convey. This compensates for the missing description on the session ID parameter.

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

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

The description clearly states the tool retrieves a replayable onboarding transcript and mentions two distinct authentication paths making it identifiable. It doesn't explicitly contrast with sibling tools sharing a 'get_' prefix, but the focus on onboarding sessions is distinct enough.

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

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

The description provides clear guidance on when to use the JWT vs the pre-auth token, which is critical for the agent to choose the right authentication. It doesn't explicitly say when not to use this tool versus alternatives like get_status or list_sessions, but the authentication differentiation offers sufficient context.

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

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

There are no annotations, so the description carries the full burden of behavioral disclosure. It reveals performance characteristics ('Fast — hits the pre-aggregated reporting endpoint'), a hard constraint ('Date range required, max 30 days'), response nuance ('read daily_series in response'), and a prerequisite for valid event names. These details go well beyond the schema and give the agent a clear model of how the tool behaves.

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 a one-sentence summary, followed by a scannable USE WHEN bullet list and explicit alternative routing. Although it is longer than average, every section earns its place by resolving a distinct selection or invocation decision for an 11-parameter tool.

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

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

Given the tool's complexity, full schema coverage, and presence of an output schema, the description is complete for an agent's needs. It covers purpose, when to use it, when not to use it, parameter semantics through examples, constraints, and prerequisites. No consequential gap remains for correct tool selection and 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 coverage is 100%, so the baseline is 3, but the description adds substantial value by translating user intent into parameter settings, e.g., dimensions=['source'] for traffic sources and connector='facebook' for delivery integration filters. It also documents the max-30-days date-range constraint, which the schema does not state. This exceeds the baseline and meaningfully helps the agent construct correct invocations.

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: 'Aggregated analytics broken down by dimension and/or time.' It also explicitly contrasts itself with siblings by stating it hits the pre-aggregated reporting endpoint rather than the raw events table, and it names get_summary, list_events, and list_sessions as distinct tools. An agent can immediately tell what this tool does and what it is not.

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 an explicit USE WHEN section with concrete natural-language examples mapped to parameter values, such as 'how many Purchases vs Leads?' → dimensions=['event_name'] and 'first-click vs last-click attribution' → attribution='first_click'. It also gives clear when-not-to-use guidance: use get_summary for a single-period snapshot, and prefer this over list_events/list_sessions for numeric/chart/ranking questions. It even states required prerequisites like calling get_container first for valid event names.

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

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

No annotations are provided, so the description carries the full burden, and it delivers: it states the tool is connectivity-only, does not return analytics data, pings all connected servers, and reports reachable/unreachable status. This fully discloses the behavior an agent needs to anticipate.

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: the core behavior and negative scope appear in the first sentence. The USE WHEN bullets and the explicit alternative guidance earn their place without any fluff 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?

For a zero-parameter connectivity-check tool with an output schema present, the description covers everything an agent needs: what it does, what it does not do, when to use it, and when to choose a sibling instead. There is no meaningful gap.

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

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

The tool has zero parameters, so the baseline is 4. The description does not need to document parameters and instead focuses on the tool's purpose and output behavior, which is appropriate for a no-argument status check.

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: 'Connectivity check only' and 'Pings every connected Tracklution server and reports reachable / unreachable.' It explicitly distinguishes itself from analytics tools by stating 'does NOT return any analytics data' and names the siblings it is not, so an agent can reliably tell it apart.

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

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

The 'USE WHEN' section gives two concrete scenarios: isolating network vs. data issues and confirming a newly-added server is online. It also explicitly says to skip this tool for any data question and use get_summary or get_report, providing a clear exclusion and 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?

With no annotations provided, the description carries the behavioral burden. It discloses that the tool is fast because it hits a pre-aggregated endpoint rather than raw events, returns several categories of stats in one call, and enforces a max 30-day date range. It does not mention auth, rate limits, or failure behavior, but the core operational behavior is clearly conveyed.

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 key definition and performance characteristic, then uses compact bullets for usage guidance. Every sentence earns its place: the examples help match user intents, the return-content summary sets expectations, and the escalation rule routes to get_report. It is thorough 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 6-parameter tool with complete schema coverage and an output schema, the description covers the essential selection and invocation context: scope, date range constraint, return categories, and relationship to get_report. It could be more complete by noting whether the operation is strictly read-only or what happens if the date range exceeds 30 days, but those are minor gaps given the schema and output schema.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by clarifying the date-range scope ('Date range required, max 30 days') and emphasizing that this is for a single container over a range. This helps the agent understand parameter intent without re-reading 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 definition: 'Aggregated performance snapshot for one container over a date range.' It clearly names the resource, the verb, and the scope. It also distinguishes itself from get_report by saying it is the default first call and that get_report is for dimension breakdowns/time series.

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

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

Provides explicit 'USE WHEN' examples covering common user phrasings, then states it is the DEFAULT first call for single-period performance questions. It also gives a concrete exclusion: 'Only escalate to get_report when the user wants a breakdown by a specific dimension... or a time series.' This leaves no ambiguity about when to choose this tool over its siblings.

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

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

With no annotations provided, the description carries the full burden. It discloses that container_hash is a secret half of the dual-key auth-token cache lookup, may be null on legacy deploys, and describes the fallback to register_and_provision. It also notes that `domain` may be null on freshly-created containers. These are behavioral nuances an agent needs to handle 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 longer than typical, but it's well-organized with a clear opening statement, a bulleted 'USE WHEN' section, and a returns clause. Each part carries essential information for an entry-point tool, though it could be slightly tightened by moving some contract details to a linked doc. Still, it earns a 4 for efficient structure.

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 this is a complex, entry-point tool with an output schema, the description covers all necessary aspects: purpose, usage triggers, return fields, special-case handling (null domain, legacy hash), and the OAuth contract. It leaves no critical gap for an agent to safely invoke it.

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

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

The schema already describes `server_name` ('Filter to a specific server. Omit to list containers from all servers.') at 100% coverage, so the baseline is 3. The description adds value by mentioning 'you need the server_name for multi-server setups,' which clarifies when to actually use the parameter, pushing it to 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?

States a specific verb ('Lists') and resource ('every tracking container the user can access across all connected servers'), and immediately frames it as the entry-point tool. It distinguishes itself from siblings by naming the tools that require a container_id (get_report, get_summary, list_events, list_sessions) and by explaining the OAuth fallback path, making its role unambiguous.

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

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

Has an explicit 'USE WHEN' section listing concrete scenarios: starting any session, when the user names a brand without a trc_ ID, for multi-server setups, and the OAuth fallback contract. It also tells the agent to match against the `domain` field and skip null domains, giving precise routing guidance vs. other 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?

With no annotations provided, the description carries the full burden. It discloses the key behavioral limitation (listing/filtering not supported), the requirement of a known ID, and the return format (a one-element events array). While it doesn't detail error behavior or auth, it covers the core operational traits that an agent needs to know.

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 USE WHEN and DON'T USE sections, and the core purpose is front-loaded. It is slightly longer than strictly necessary, but every sentence earns its place by disambiguating from siblings and explaining the return contract.

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

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

The tool is simple, and the output schema exists, so return values don't need explanation. The description covers when to use, when not to use, and the return shape. Missing edge-case handling (e.g., not-found behavior) is a minor gap, but the description is sufficient for an agent to invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds marginal value by reiterating the ID format (evt_ vs TE) and the server_name requirement, but these are already in the schema. It does not explain container_id beyond what's there, so it adds no new meaning 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 clearly states 'Fetch ONE event by its ID' with the specific constraint that it only works with a known event_id, and explicitly differentiates itself from listing/filtering tools. It names the resource (event) and the exact action (fetch by ID), making it distinguishable from siblings like query_events.

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

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

The description provides explicit 'USE WHEN' and 'DON'T USE' sections, naming get_report and get_summary as alternatives for counts, trends, and snapshots, and even instructs agents to ask users for a dashboard ID when raw events are needed. This is the clearest possible 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?

With no annotations, the description carries the behavioral burden. It states the tool only accepts a known session ID, explicitly denies listing/filtering, and discloses the return format ('one-element sessions array'). It doesn't mention error cases (e.g., invalid ID) or auth/rate limits, but the disclosed restrictions and return shape are substantive. Minor gap: 'same shape as before' is vague without prior 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?

Organized with USE WHEN / DON'T USE sections, bullet-like clarity, and front-loaded purpose. Slightly verbose with some redundancy (e.g., 'The only way to use this tool' repeats the restriction stated earlier), but the structure earns high marks overall.

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 an output schema, so return values are covered automatically. The description provides all necessary calling context: required ID, unsupported operations, alternative tools, and parameter nuances. Nothing critical 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 coverage is 100%, so baseline is 3. The description adds value by clarifying the two ID formats (ses_ vs VS and their meaning), the server_name condition ('required when connected to multiple servers'), and container_id prefix (trc_). These enrich the schema's basic descriptions enough to warrant 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 opens with 'Fetch ONE visitor session by its ID' — a precise verb+resource statement. It also explicitly excludes listing/filtering, clearly distinguishing from siblings like query_sessions and list_events. The inclusion of ID prefix examples (ses_, VS) reinforces the specific scope.

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?

Dedicated USE WHEN and DON'T USE sections give explicit conditions: use when a session ID is referenced, avoid for counts/rates/top-sources, and route to get_report or get_summary instead. It even advises asking the user for a dashboard ID when no ID is known. This is exemplary alternative 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?

With no annotations provided, the description carries the full burden and does so thoroughly. It discloses the 7-14 day retention window, the fact that older date_from values pass validation but return empty rows, the warnings array behavior, the default status filter, and cursor-based pagination semantics (pass next_cursor, stop when has_more is false, 30-day backend cap). This is rich behavioral context beyond what the schema could 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?

The description is well-structured with clear sections (retention note, USE WHEN, DON'T USE, STATUS FILTER, pagination) and front-loads the most critical caveat (limited timeframe). It is longer than average, but every section earns its place given the tool's complexity and the absence of annotations. Minor redundancy exists between the opening retention note and the DATA RETENTION section.

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 tool with no annotations, the description covers all the non-obvious context an agent needs: retention limits, status semantics, pagination mechanics, and sibling routing. The output schema exists, so return-value details don't need to be in the description. The only minor gap is that it doesn't explicitly state the default per_page value, but the schema already documents that.

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 value beyond the schema by explaining the status default and its debugging-only use case, the retention-window interaction with date_from, and the per_page performance guidance. It doesn't enumerate every has_* flag, but the schema already documents those clearly, so the description doesn't need to.

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

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

The description states a specific verb and resource ('Paginated list of raw events for a date range') and immediately distinguishes it from siblings by naming get_report and list_events as alternatives. It also clarifies the scope (raw events, not aggregates), which prevents confusion with query_sessions and get_summary.

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 explicit USE WHEN and DON'T USE sections, naming get_report for aggregates and list_events for single-event-by-ID lookups. It also gives detailed guidance on the status filter, warning that non-processed statuses should only be used for debugging. This is exemplary 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?

With no annotations provided, the description carries the full burden and does so thoroughly: it discloses retention limits, empty-result behavior for old dates, a warnings array, cursor-based pagination with has_more, a 30-day range cap, and the absence of raw PII. This is exemplary for a tool of this complexity.

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 Note, USE WHEN, DON'T USE, and pagination sections, and the most important constraint (retention) is front-loaded. However, the retention warning appears twice in nearly identical form, which is a small redundancy.

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

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

Given the high parameter count, the presence of an output schema, and no annotations, the description covers everything needed for correct invocation: retention caveats, pagination mechanics, filter semantics, excluded use cases, and data content. Nothing critical is missing.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds cross-parameter meaning beyond individual schema entries: it explains cursor chaining via meta.cursor.next_cursor, the 30-day backend limit on date_from/date_to, and the role of the has_* filters as click-ID presence flags. This is a meaningful supplement to 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: a paginated list of visitor sessions for a date range with filters and per-session record details. It also differentiates itself from siblings by naming list_sessions for single-session lookup and get_report/get_summary for aggregated questions.

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?

Explicit USE WHEN and DON'T USE sections give the agent clear decision rules, including concrete alternatives like get_report, get_summary, and list_sessions. This leaves no ambiguity about when the tool is or isn't appropriate.

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 no annotations, the description takes the full burden and delivers: it discloses side effects (welcome email, account creation), security-sensitive JWT handling, 409/429 error behavior, idempotency-key requirements, and multi-server session behavior. It also warns that the server does not generate idempotency keys and that every response includes _request_id.

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

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

The description is long, but it is organized into labeled sections (PROACTIVE auth_token, RECOVERY, PERMISSIONS, MULTI-SERVER, rate limits) that make it scannable. Every section conveys load-bearing operational guidance; the length is justified by the tool's complexity, though a few points could be tightened.

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

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

For a 15-parameter, 4-required, no-annotation tool with output schema, the description is remarkably complete. It covers success paths, all major error classes with concrete recovery actions, permission requirements, rate-limit backoff, multi-server routing, and security constraints on token handling. An agent has enough context to call this correctly and recover from failures.

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%, so the description must compensate, and it does for the most decision-critical parameters: auth_token, email, idempotency_key, website_url, and name. Some remaining parameters like dry_run, goal, phone, and company are left to their names/schema, but the description covers the non-obvious inter-parameter constraints well.

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 precise verb-resource pair: 'Create/reuse an account and the first tracking container in one agent-safe call.' It clearly distinguishes fresh-email registration from authenticated reuse, and its naming of auth_token behavior separates it from sibling tools like get_container and list_containers.

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 and when-not-to-use guidance: pass auth_token instead of email for signed-in users, never pass name/email alongside auth_token, and stop without calling other MCP tools on multi_client_ambiguous. It also names alternatives like account recovery URLs and outlines permissions prerequisites for container creation.

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 no annotations, the description carries the full behavioral burden and does so thoroughly: safe without auth, creates an onboarding session, returns a single-use sensitive token, and guarantees `_request_id` in every response for log correlation.

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 most operationally important fact: 'Public discovery; safe to call without auth.' Every sentence earns its place, though it is slightly dense with token-lifecycle and support-correlation details.

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

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

Given that an output schema exists, the description does not need to restate all return values. It covers auth posture, side effects, the follow-up tool, custom return fields, and support correlation, giving an agent enough context to call it correctly.

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

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

The input schema already documents all three parameters with 100% coverage, so the baseline is 3. The description adds no parameter-specific semantics beyond what the schema provides.

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

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

The description states a specific verb and resource: 'Public discovery... Detects CMS/platform hints and creates an onboarding session.' It clearly distinguishes this from sibling provisioning, verification, and session-query 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 establishes this as the unauthenticated discovery entry point and explicitly links its output to `register_and_provision`, implying the intended call order. It does not enumerate when not to use it or name alternatives, so it stops short of full 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?

No annotations are present, so the description carries full burden. It discloses mutating behavior, idempotency requirement, request_id presence in structuredContent, admin permission requirement, exact error shape, and the instruction to surface the message and stop without retrying.

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 dense but well organized: purpose first, then mutating behavior, response contract, permissions, and error handling. Every clause adds operational value and no filler is present.

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 output schema present, return values need not be explained; the description covers permissions, errors, idempotency, and retry behavior. It is not fully complete because it omits guidance for several parameters with low schema coverage, but it covers the most consequential invocation details.

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 29%, and the description does not compensate. It only mentions idempotency_key, which is already required in the schema, and provides no guidance for method enum values, container_id, auth_token, dry_run, or the auth_token/container_hash interplay.

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: 'Persist the chosen installation method on the container.' It also labels the operation as mutating, which clearly distinguishes it from the read-oriented sibling tools such as get_container and list_containers.

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 by stating the operation is mutating, requires an agent-supplied idempotency_key, and requires admin permission on the container's company. It does not name explicit alternatives or exclusions, but the prerequisites and failure mode are enough to guide when it should be used.

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 no annotations, the description carries the full behavioral burden and does it thoroughly: it discloses mutation, the force-process behavior, the 30-second idempotency dedupe window, the success-signal trap (`status` vs `scoring_complete`), the server-pinning refusal rule, and the full stable enum of `not_ready_reason`. This goes far beyond a typical tool 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 long, but the length is justified by a ten-value state machine and explicit action contract; it is front-loaded with a one-line purpose, then organized into labeled classes and bullets. It is not truly concise, but every section earns its place for this tool's complexity.

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

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

The description covers the operational context an agent needs: which output fields to read, how to interpret `status` + `not_ready_reason`, when to retry vs exit, and which sibling tools to call for hand-off. It omits guidance on several input parameters and relies on an external `agent-install.md` reference, but for this complex verification flow it is substantially 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?

The description adds real semantic value for `idempotency_key` (same key dedupes within 30s, fresh key triggers a new pass) and implies the role of `expected_events` via the `event_not_received_yet` case. With only 25% schema coverage and six parameters left unexplained by both schema and description, however, it does not fully compensate for the low coverage.

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

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

The opening sentence names a specific verb/resource outcome: 'Force-process recent events, recalculate scoring, and return a strict verification diagnosis.' It also flags the mutating nature, which separates it from read-only sibling status/summary tools, so an agent can distinguish it without opening the schema.

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

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

The description provides an exhaustive decision tree for every `not_ready_reason`, including retry budgets, 'do NOT retry' rules, and explicit follow-up sibling calls (`get_next_steps`, `create_login_link`). It does not, however, explicitly contrast this tool with alternative status/verification tools such as `get_status`, leaving a small inference gap.

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