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

The description details the output structure beyond the readOnlyHint annotation, but does not cover other behavioral aspects like error handling or pagination.

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

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

Well-structured with front-loaded purpose, but includes detailed bullet points that may be partially redundant with 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?

Adequate coverage for a simple list tool with one parameter; missing details on error scenarios but sufficient for typical use.

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 has 0% coverage, but the description adds full semantic meaning for app_id, specifying it as a UUID and its purpose.

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 'List all CDP attributes available for audience creation' with a specific verb and resource, distinguishing it from sibling tools that focus on analytics, apps, or audiences.

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

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

It clearly states the tool is essential for creating audience conditions, but does not explicitly mention when not to use or list 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 provide readOnlyHint: true, indicating safe read. Description adds no further behavioral context (e.g., auth needs, error states). Acceptable but minimal contribution beyond annotations.

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

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

Single sentence, no redundancies. Could benefit from a brief note on parameters, but overall conciseness is good. Not overly succinct to the point of harm.

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?

Output schema exists, reducing need to describe return values. However, the tool has two required parameters with no description; the description fails to clarify 'app_id' context. Adequate for a simple getter but incomplete for full agent understanding.

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 0%, requiring description to compensate. However, description only mentions 'by ID', ignoring 'app_id'. It does not explain the role of 'app_id' or the format of 'annotation_id', leaving meaning unclear.

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 clearly states verb 'Get' and resource 'user annotation' with modifier 'by ID', distinguishing it from sibling 'analytics_annotations_list' which lists multiple annotations. No ambiguity.

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

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

No guidance on when to use this tool vs alternatives like 'analytics_annotations_list'. Agent must infer from name alone. Lacks explicit context or exclusion criteria.

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

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

The description lists parameters and notes a return value, which adds some behavioral context beyond the readOnlyHint annotation. However, it omits the 'source' parameter and does not describe pagination behavior or result 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?

The description is concise and structured with Args and Returns sections. It has no fluff, though it could be slightly more front-loaded with the core purpose.

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 6 parameters and a complex schema, the description is incomplete: it does not cover the 'source' parameter, lacks usage guidance, and provides minimal detail on the return value (only 'Annotations list and metadata').

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

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

With 0% schema description coverage, the description partially compensates by providing date format (YYYY-MM-DD) and semantics for limit/offset. However, it fails to mention the 'source' parameter, leaving its purpose unclear.

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 verb 'list' and resource 'user annotations for an app'. It distinguishes from the sibling 'analytics_annotations_get' which retrieves a single annotation, but does not explicitly call out the difference.

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

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

No guidance is provided on when to use this tool versus alternatives, such as when to filter by source or date range. There is no mention of prerequisites or 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?

Discloses RuntimeError for failures and different return types per scope, adding value beyond the readOnlyHint annotation.

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

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

Well-structured with sections for note, args, returns, raises; each sentence is informative and earns its place.

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

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

Covers all necessary details for a 3-param tool with output schema; no gaps remain.

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

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

With 0% schema coverage, the description fully explains each parameter (UUIDs, enum values, routing effects), compensating completely.

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 it gets a custom dimension by ID and explains the scope-based API routing. It is distinct from siblings like list and get_slots.

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 advises using list() first if scope is unknown, providing clear when-to-use guidance and an alternative.

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

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

Annotations already indicate readOnlyHint=true, and the description adds disclosure of return fields (available, used, left) and raises RuntimeError on API failure. This provides behavioral context beyond the annotation.

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

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

The description is well-structured with sections for Args, Returns, and Raises, making it easy to scan. It is concise yet informative, with no redundant content.

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

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

The description fully covers the tool's purpose, input, output, and error conditions. With a simple one-parameter input and existing output schema, 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?

With 0% schema description coverage, the description compensates by explaining the sole parameter website_id as 'Website/App UUID'. This adds meaningful semantic value not present in the input 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 clearly states the tool 'Get slot availability statistics for all dimension types', specifying the resource and action. It distinguishes itself from sibling analytics tools by focusing on slot availability rather than dimensions or metrics.

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

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

No explicit guidance on when to use this tool versus alternatives like analytics_custom_dimensions_list. The description does not mention prerequisites or context for 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 indicate readOnlyHint=true. Description adds behavioral details about pagination limits for standard vs product dimensions and return types per scope, but omits authentication or rate limit info.

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

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

Well-structured with args/returns/raises, front-loaded purpose, but somewhat verbose. Could be slightly more concise.

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 all parameter behavior, return types per scope, edge cases (product pagination), and error handling. Output schema exists, so return value explanation is adequate.

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

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

Input schema has 0% description coverage; description compensates with full explanations for scope enum, limit/offset defaults and special behavior for product dimensions.

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 clearly states it lists custom dimensions with optional scope filter. Distinguishes from sibling tools like analytics_custom_dimensions_get (single dimension) and analytics_dimensions_list (different resource type).

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 guidance on scope parameter usage and defaults, but does not explicitly state when not to use or mention alternatives among siblings.

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

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

Annotations already indicate readOnlyHint=true, so the description only adds the return type information and the important note. It does not disclose other behaviors like pagination or authentication requirements, but annotations cover the safety profile.

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 structured with an Args section and a Returns section, making it easy to parse. However, it is slightly verbose and could be trimmed for conciseness.

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 does not need to detail return structure heavily. However, it only vaguely says 'list of all available dimensions with details,' leaving the nature of 'details' unclear. The tool has two simple parameters, so completeness is adequate but not rich.

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

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

The input schema has 0% description coverage. The description mentions `website_id` as a UUID and `dimensions` as a list of dimension names, but this adds minimal meaning beyond the parameter names. It does not provide detailed semantics or formats.

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 'List details of provided dimensions,' specifying the verb (List), resource (dimensions details), and scope (via input). It distinguishes from the sibling `analytics_dimensions_list` which likely lists dimension names only.

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

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

The description includes an important usage note about using enum_values object values instead of keys. While it does not explicitly state when to use this tool versus alternatives, the context of the sibling tools and the purpose implies it is for detailed dimension information.

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

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

Annotations already indicate `readOnlyHint=true`, and the description does not contradict this. It adds the response format and parameter meaning, but does not disclose potential authorization needs or rate limits, which are not critical given the read-only nature.

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

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

The description is concise, well-structured, and front-loaded. It uses backticks for code references and clearly separates Args and Returns. Every sentence adds value.

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

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

For a simple list tool with an output schema, the description adequately covers the purpose, parameter, response format, and sibling relation. It lacks mention of potential errors or permissions, but given the tool's simplicity, it is largely 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?

With 0% schema description coverage, the description compensates by clearly explaining that `website_id` is a UUID of the website/app. This adds meaning beyond the schema's type-only definition.

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 lists available dimensions for analytics queries, uses a specific verb-resource pair, and differentiates from the sibling `analytics_dimensions_details_list` by directing users to that tool for details.

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

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

The description provides clear context that dimensions are for use in `analytics_query_execute` and points to `analytics_dimensions_details_list` for more details. However, it does not explicitly state when not to use this tool or compare to other siblings like `analytics_metrics_list`.

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

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

Annotations include readOnlyHint=true, indicating a safe read operation. The description adds minimal behavioral context beyond that, stating it returns a 'Goal resource'. This is adequate but not exceptional.

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

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

The description is concise with three lines: purpose, arguments, and returns. No extraneous words, effectively 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?

Given the existence of an output schema (indicated by context signals) and the straightforward nature of a get-by-ID operation, the description sufficiently covers the tool's functionality. Minor edge cases (e.g., missing IDs) are not addressed but are standard for such 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?

With 0% schema description coverage, the description compensates by labeling parameters as 'Goal UUID' and 'Website/App UUID', adding meaningful context beyond type 'string'.

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 explicitly states 'Get a specific goal by ID', using a clear verb and resource. It naturally distinguishes itself from the sibling 'analytics_goals_list' which retrieves multiple goals.

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

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

No guidance is provided on when to use this tool versus alternatives, when not to use it, or any prerequisites. The agent must infer usage solely from the verb 'Get'.

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, so the safety profile is covered. The description adds valuable workflow context: exact name matching in data[].attributes.name, using the returned id as goal_uuid, and the warning not to include goal_uuid in query columns. Minor ambiguity remains because 'List all goals' could suggest unbounded results while the default limit is 10.

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, then provides a focused workflow, parameter notes, and return shape. Every sentence serves a purpose, and the Args section is compact despite covering all three parameters.

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

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

Given the output schema exists, the description still provides enough context on parameters, return shape, and downstream usage to let an agent select and invoke the tool correctly. It covers the full workflow from listing goals to querying them, which is sufficient for this tool's complexity.

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

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

Schema description coverage is 0%, but the Args section fully compensates by documenting all three parameters: website_id as Website/App UUID, limit with default/min/max, and offset with default/min. This adds real semantic meaning beyond the bare 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 'List all goals for a website,' which clearly states the verb, resource, and scope. It also distinguishes this tool from siblings like analytics_goals_get by framing it as the list operation used to resolve a named goal to an ID.

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

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

The description explicitly says 'Use this before goal conversion queries when the user names a specific goal' and explains the exact workflow: match by name, then use the ID in analytics_query_execute. It does not explicitly describe when not to use it or compare it to analytics_goals_get, so it falls just short of the full alternatives/exclusions bar.

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

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

Annotations already indicate readOnlyHint=true, so the description's job is light. It adds context that the returned metrics are 'all available metrics with details' and usable as columns, which is valuable beyond the annotation. No contradictions.

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 structured with an Args section and is clear, though slightly verbose with the 'Returns:' line. It is front-loaded with the main purpose and uses minimal 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 output schema exists and parameters are explained, the description covers what the tool does, its inputs, and output. It could mention differentiation from analytics_metrics_list, but overall sufficient.

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

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

Schema coverage is 0%, so description must explain parameters. It does so by defining website_id as 'UUID of the website/app' and metrics as 'list of metric names', adding meaning beyond the schema's titles.

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 verb 'List details' and the resource 'provided metrics', and distinguishes from sibling tools like analytics_metrics_list by specifying it returns all metrics usable as columns in analytics_query_execute.

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 explains the tool returns metrics that can be used as columns for query execution, implying when to use it. However, it does not explicitly mention when not to use or provide alternative tools, such as analytics_metrics_list for just 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?

Annotations already provide readOnlyHint, and the description adds the response format and return type, providing additional behavioral context beyond the annotations.

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

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

The description is concise and front-loaded with purpose, though includes a code block and Args/Returns sections that could be slightly 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?

Given an output schema exists, the description provides a sufficient overview of return format and type, making it complete for a simple list endpoint.

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

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

With 0% schema coverage, the description adds minimal meaning by stating website_id is a UUID, but does not elaborate on its purpose or formatting 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 clearly states the tool lists available metrics for analytics queries and specifies they can be used as columns in analytics_query_execute, distinguishing it from sibling tools like analytics_dimensions_list.

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

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

The description implies use before executing queries by stating it returns metrics for analytics_query_execute, but no explicit when-not or alternatives are given.

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

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

Beyond the readOnlyHint annotation, the description reveals crucial behavioral constraints: metrics cannot be transformed, timestamp needs transformation_id='to_date', order_by indexes are zero-based, goal_uuid must be a filter not a column, multi-period queries should be run once per period, and rank positions are per period. No contradiction with annotations.

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

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

The description is long but well-organized with clear headings, bullet lists, and an explicit numbered workflow. It earns most of its length, though there is some redundancy between the 'Before calling' paragraph and the numbered steps, so it is not maximally concise.

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 complex 10-parameter analytics execution tool, the description covers query planning, prerequisites, date handling, filtering, transformations, ordering, goal conversion flows, multi-period comparisons, and limits. Since an output schema exists, omission of return-value details is acceptable; the description is highly complete.

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

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

Schema description coverage is 0%, but the Args section compensates fully by explaining all 10 parameters, including columns dict fields, filters structure with operators, relative_date options, order_by structure, and offset/limit defaults. It adds meaning far beyond the raw JSON 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 precise verb+resource statement: 'Execute an analytics query against Piwik PRO.' It clearly distinguishes itself from the sibling list/get analytics tools by focusing on query execution, and it states its role in the workflow ('Call this tool with validated column_ids and transformation_ids').

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

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

The description provides explicit when-to-use rules, including a required workflow calling analytics_dimensions_list/metrics_list/details before executing, and says 'DO NOT RUN THIS TOOL BEFORE CHECKING DIMENSIONS AND METRICS DETAILS!'. It also gives re-run policy and uses 'columns vs filters' heuristics to guide query construction, making tool selection and invocation unambiguous.

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

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

Annotations declare readOnlyHint: true, so the read-only nature is already known. The description adds value beyond that by detailing the return fields (e.g., id, name, urls, etc.), which provides transparency about what the tool returns. It does not mention any side effects or permissions, but none are expected for a read operation.

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

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

The description is well-structured with intro, args, returns, and a usage tip. It is front-loaded with the purpose and each sentence earns its place. No redundant or unnecessary information.

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

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

Given one parameter and an implied output schema (detailed in returns), the description is fully complete. It covers what the tool does, what to pass, what you get back, and provides a pointer to a related tool for deeper 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?

The single parameter 'app_id' is described as 'UUID of the app to retrieve' in the Args section, which adds specificity beyond the schema's generic type 'string' and title 'App Id'. Since schema description coverage is 0%, the description fully compensates.

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

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

The description starts with 'Get detailed information about a specific app,' which clearly states the verb and resource. It distinguishes itself from sibling tools like apps_list by specifying retrieval of a single app by ID, and even suggests an alternative tool (tracker_settings_app_get) for more tracking details.

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

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

The description includes an explicit alternative: 'For more tracking details use tracker_settings_app_get.' This clearly guides when to use this tool versus another. The context of 'specific app' versus listing all apps is implied, aiding correct invocation.

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

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

Annotations already provide readOnlyHint=true, indicating a safe read operation. The description adds valuable context about pagination (limit, offset) and return structure, which goes beyond the annotation. It does not mention any side effects, which is consistent with read-only behavior.

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

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

The description is well-structured with Args and Returns sections. It is clear but slightly verbose with redundant first line. Overall efficient and easy to parse.

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 simplicity and the presence of an output schema, the description covers all necessary aspects: purpose, parameters, and return values. It includes pagination details and metadata fields, making it complete for an agent to use 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 0%, so no parameter descriptions exist in the schema. The description fully compensates by explaining limit (max 1000), offset (skipping), and search (filter by name), adding meaning beyond types and defaults.

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 it lists apps from Piwik PRO analytics and explains it retrieves tracked applications. It uses a specific verb and resource. However, it does not explicitly differentiate from sibling tools like apps_get, though the verb 'list' implies it's for multiple apps.

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 implied usage context for listing apps but lacks explicit guidance on when to use this tool versus alternatives (e.g., apps_get for single app). No when-not or alternative references are given.

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, so the description's 'get' aligns and adds no contradiction. It transparently lists return fields, providing behavioral context beyond annotations.

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

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

The description is structured with Args and Returns, front-loading the purpose. It is moderately concise, though the full field list may be redundant given the output schema exists. Still efficient.

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

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

Given the presence of an output schema, the description covers purpose, parameters, and returns adequately. It lacks error handling notes but is sufficient for a standard retrieval 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?

With 0% schema description coverage, the description compensates by explaining each parameter as 'UUID of the app' and 'UUID of the audience to retrieve,' adding meaningful semantics beyond the bare 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 description clearly states 'Get detailed information about a specific audience,' using a specific verb and resource. It distinguishes itself from sibling tools like 'audiences_list' by targeting a single audience.

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

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

The description implies usage for retrieving one audience by IDs but does not explicitly state when to use this over the list tool or provide exclusions. Basic guidance is present but lacks explicit context.

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

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

Annotations already declare readOnlyHint=true, making the read-only nature clear. The description adds return structure (audiences list and total), providing useful behavioral context beyond annotations.

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

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

The description is brief and front-loaded with the main purpose. The Args/Returns structure is clear and adds no superfluous 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?

Given the simplicity of the tool (one parameter, list output) and the presence of an output schema (not shown), the description adequately covers purpose, parameter, and return format. Minor omission: no mention of pagination or limits.

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 0%, so the description must explain the parameter. It describes app_id as 'UUID of the app to list audiences for', adding meaning that the schema lacks.

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 'List audiences from Piwik PRO CDP' and specifies it retrieves a list for a given app. This distinguishes it from sibling tools like audiences_get, which likely retrieves a single audience.

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 indicates usage with a required app_id but does not explicitly state when to use list vs. get tools. Context from sibling names implies differentiation, but no direct guidance is given.

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

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

Annotations already provide readOnlyHint=true, indicating a safe read operation. The description adds the return shape but no additional behavioral traits like permissions, rate limits, or side effects. It meets the baseline but does not go beyond.

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 Args, Returns, and Examples sections. The key purpose sentence is front-loaded. It could be more concise, but the format is clear and not overly long.

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

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

For a simple, single-parameter read-only tool, the description covers input, output, and an example. With the likely output schema available, this is fully adequate for an agent to use the tool correctly.

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

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

The schema has 0% coverage, but the description adds 'UUID of the app' and an example with a UUID string, clarifying the expected format beyond the plain 'string' type. This adds significant meaning.

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

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

The description clearly states the tool's purpose with 'Get installation code for an app.' The purpose is specific and the resource is identified. However, it does not differentiate from sibling tools like container_settings_list, missing explicit distinction.

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?

An example and parameter/return description imply usage, but no guidance on when to use this tool versus alternatives or when not to use it. The context is straightforward, but explicit exclusions or contexts are missing.

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

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

Annotations already indicate read-only. Description adds return format (JSON:API with pagination) and example. No contradiction, but limited additional 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?

Concise and well-structured: one-line summary, Args, Returns, Examples. Every sentence adds value with no redundancy.

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

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

For a simple read-only list tool, the description covers purpose, parameter, and return format. Lacks mention of authentication or error handling, but output schema exists to cover 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 has no description for 'app_id' (0% coverage). Description adds 'UUID of the app' and an example, which adds meaning but could include more constraints or format details.

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 action ('Get') and resource ('container settings for an app'). It is specific and distinct from siblings like 'container_settings_get_installation_code'.

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

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

No guidance on when to use this tool versus alternatives. No when-to-use or when-not-to-use instructions are provided.

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

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

Annotations provide readOnlyHint, and the description adds comprehensive behavioral details: lifecycle states, field shapes, and conditions for when fields are present. No contradictions with annotations.

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

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

The description is well-structured with Args and Returns sections, front-loaded with purpose, and concise. Every sentence adds value without redundancy.

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

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

Given the tool's simplicity (2 parameters, output schema present), the description is complete. It details return fields comprehensively, including optional nested data and example shapes.

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 0%, but the description explains parameters as 'UUID of the app' and 'UUID of the operation', adding meaning beyond type and title. Sufficient for two simple 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 it retrieves a Tag Manager async operation by ID, specifying the verb 'Get' and resource 'async operation'. It distinguishes from sibling tools by focusing on background operation status checking.

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

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

The description explicitly lists when to use this tool (checking status of operations started by publish, restore, etc.), providing clear context. It doesn't explicitly state when not to use, but the specific use case is well-defined.

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, so the description's addition of 'Get detailed information' is consistent but doesn't add new behavioral details. No contradictions.

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

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

The description is concise with two sentences and a list. The list includes function signatures which add useful context but also some verbosity; still, the structure is clear and 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?

The tool has an output schema (not shown) but lacks parameter descriptions. For a simple get operation, the information is adequate but not thorough. Could benefit from describing what 'detailed information' includes.

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 0%, and the description does not explain the parameters (app_id, tag_id) beyond their names. The related tools section includes parameter lists for other tools but not for this one, providing no added meaning.

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

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

The description clearly states 'Get detailed information about a specific tag', which is a specific verb-resource combination. It distinguishes itself from sibling tools like tags_list (which lists tags) and tags_list_triggers (which gets triggers for a tag).

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

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

The description provides a 'Related Tools' section listing tags_list_triggers and variables_list with their parameters, hinting at alternatives. However, it doesn't explicitly state when to use this tool versus others, leaving some inference to the agent.

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

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

Annotations already mark this as read-only (readOnlyHint=true). The description adds value by listing filterable fields, but does not disclose additional behavioral traits like rate limits, response structure, or behavior when no tags exist. The annotation reduces the burden, but more detail would improve transparency.

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

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

The description is concise (two sentences plus an Args list) and front-loaded with the main purpose. Every sentence adds value, and the structure is clear. No unnecessary words or repetition.

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

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

Given the presence of an output schema (so return values need not be described) and the tool's moderate complexity (4 parameters), the description covers the core functionality and parameter details well. It lacks mention of optional parameters or default behavior, but overall it is sufficiently complete for an AI agent to select and invoke the tool.

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

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

With 0% schema description coverage, the description fully compensates by explaining each parameter: 'app_id' as UUID, 'limit' and 'offset' with defaults, and 'filters' with specific filterable fields. This provides meaning beyond the bare schema. However, the 'filters' parameter could be more explicit about its structure (e.g., key-value pairs).

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 action ('List tags'), the resource ('tags'), and the context ('for an app in Piwik PRO Tag Manager'). It distinguishes itself from sibling tools like 'tags_get' (single tag) and 'templates_list_tags' (templates) by specifying the resource and 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?

The description implies usage for listing tags with optional filters, but does not explicitly state when to use this tool versus alternatives like 'tags_get' for individual tags or 'triggers_list_tags' for cross-referencing. No exclusion criteria or context is provided.

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

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

The description states 'Get list', which is consistent with the annotation 'readOnlyHint: true'. No additional behavioral traits are disclosed beyond the annotation. Since annotations already indicate read-only, the description adds no new transparency, but also does not contradict annotations.

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

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

The description is concise and well-structured with a clear purpose statement and a bullet-like list of parameters. The 'Args:' block is slightly verbose but remains easy to scan. Each sentence serves a purpose, though the parameter list could be more compact.

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 7 parameters and no output schema, the description adequately explains the input parameters but does not describe the return value or pagination behavior beyond limit/offset. The tool is fairly complex with filtering options, but the description lacks context on response format or usage scenarios.

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?

Despite 0% schema description coverage, the description lists all parameters with brief explanations (e.g., 'UUID of the app', 'Sort order - name, -name, created_at, etc.'). This provides meaningful guidance beyond the bare schema, especially for parameters like 'sort' with examples. However, some explanations are minimal.

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 'Get list of triggers attached to a specific tag', which is a specific verb ('Get list') and resource ('triggers attached to a specific tag'). This distinguishes from sibling tools like 'triggers_list' (all triggers) and 'triggers_list_tags' (tags for a trigger).

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 no guidance on when to use this tool versus alternatives. There is no mention of prerequisites, filtering behavior, or comparison to sibling tools. Usage context is entirely 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 declare readOnlyHint=true, which the description aligns with by stating it 'gets' details. The description adds context about requiring exact names and a workflow, but does not detail the exact return structure (no output schema). Since annotations cover safety, the description adds value with workflow context.

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

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

The description is well-structured with sections, but slightly verbose (e.g., the workflow repeats the same steps). However, every sentence is purposeful and front-loaded with the core purpose. Minor redundancy prevents 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?

The tool has one parameter and no output schema. The description explains the input requirement and usage flow, but does not detail the output format (e.g., example response). For a simple retrieval tool, the context is solid but missing explicit return 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?

The only parameter 'template_name' has 0% schema description coverage. The description compensates fully by specifying it must be an exact name from 'templates_list_tags()', including a workflow example. This adds critical meaning beyond the raw 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 clearly states 'Get requirements and usage details for a specific tag template.' It uses a specific verb ('Get') and resource ('tag template'), distinguishing it from sibling tools like 'templates_list_tags' (for listing) and 'tags_get' (for existing tags).

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

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

The description explicitly says 'You MUST call templates_list_tags() first to get exact template names' and provides a numbered workflow. It warns against guessing and specifies the correct usage order, leaving no ambiguity.

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, so the description adds value by specifying the returned data (requirements/usage details) and the prerequisite. It does not disclose additional behavioral traits but complements annotations well.

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

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

The description is concise yet structured with a clear purpose line, warning section, Args, and Workflow. Every sentence is necessary and well-organized, with no fluff.

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

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

Despite having no output schema and simple parameters, the description fully covers the prerequisite workflow and proper parameter sourcing. It references sibling tools and provides complete context for correct invocation.

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

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

With 0% schema description coverage, the description fully compensates by stating that template_name must be 'the exact trigger type name as returned by templates_list_triggers()'. This adds critical semantic meaning beyond the schema's type/required declaration.

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 'Get requirements and usage details for a specific trigger template,' using a specific verb and resource. This distinguishes it from sibling tools like templates_list_triggers (list) and triggers_get (get instance).

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

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

The description explicitly instructs to call templates_list_triggers() first to get exact trigger type names, warns against guessing, and provides a numbered workflow. This gives excellent when-to-use and prerequisite 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. Description adds context that the tool returns requirements, mutability, and usage details. No contradictions or missing behavioral info beyond annotations.

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

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

Well-structured with a main sentence, bold warning, Args section, and numbered workflow. Every sentence adds value without redundancy.

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

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

For a simple lookup tool with one parameter and read-only annotation, the description fully covers what it does, prerequisites, and workflow integration. No missing elements.

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?

Single parameter template_name has no schema description. Description fills the gap by explaining it must be an exact variable type name from templates_list_variables, which is critical for correct usage.

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 clearly states it retrieves requirements, field mutability, and usage details for a specific variable template. Verb 'Get' is specific, and the resource is clearly identified. It distinguishes from siblings like templates_list_variables and other get templates.

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 warns to call templates_list_variables first and not to guess variable type names. Provides a step-by-step workflow showing how this tool fits with list and create/update tools.

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

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

Annotations already declare readOnlyHint=true, so the description does not need to restate that. It adds that the tool lists 'available' templates and must be called first, but does not disclose any further behavioral details (e.g., pagination, sorting, or output format). This is adequate but minimal 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 concise: two sentences plus a formatted workflow. Every sentence adds value, the warning is appropriately emphasized, and the structure is front-loaded with the core purpose.

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

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

Given the tool has no parameters, a read-only annotation, and no output schema, the description covers the necessary context: purpose, prerequisite, and workflow. However, it omits any hint about the return format (e.g., list of names or objects), which could be useful. Still, it is largely complete for this simple 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?

The input schema has zero parameters with 100% schema description coverage. Per guidelines, a baseline of 4 is appropriate. The description does not need to add parameter semantics since none exist.

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 lists all available tag templates for use with tags_create. It distinguishes from sibling tools like templates_get_tag and templates_list_triggers by explicitly mentioning the workflow and the prerequisite role.

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

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

The description explicitly instructs the agent to call this tool before templates_get_tag or tags_create, warns against guessing names, and provides a clear three-step workflow. This leaves no ambiguity about when and why to use it.

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

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

Annotations already declare readOnlyHint=true, so no contradiction. Description adds valuable context about the necessity of discovery and workflow steps, but does not reveal additional behavioral traits beyond what annotations provide.

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

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

Description is concise, with front-loaded purpose and a clear warning followed by a numbered workflow. Every sentence adds value, no wasted words.

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

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

For a parameterless list tool with no output schema, the description fully explains its purpose, why it's needed, and how to use it in sequence with sibling tools. No gaps.

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

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

Input schema has zero parameters, so baseline is 4. Description does not need to add parameter details, and it appropriately describes the tool as listing all available templates.

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 clearly states it lists all trigger templates for use with triggers_create, specifying a specific verb and resource. It distinguishes from sibling tools like templates_get_trigger and templates_list_tags by stating its role in the workflow.

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 instructs to call this tool before templates_get_trigger or triggers_create, provides a numbered workflow, and warns against guessing trigger type names. Clearly communicates when and why to use this tool.

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

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

The description adds workflow context beyond the annotations (readOnlyHint=true). It explains that the tool discovers exact variable type names, which is useful behavioral context. No contradictions with annotations.

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

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

The description is slightly lengthy but well-structured with headings, emojis, and bullet points. Every sentence adds value, though some redundancy exists between the IMPORTANT note and the workflow steps.

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 tool's purpose and integration into a workflow. It doesn't specify the return format, but the tool is simple with no parameters and no output schema, so the description is sufficiently complete for an agent to understand when and how to use 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?

With 0 parameters, schema coverage is 100%. The description adds value by explaining that the tool returns exact variable type names needed for subsequent steps. Baseline 4 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 clearly states the verb 'list' and the resource 'variable templates', and explains its use with 'variables_create' and 'variables_update'. It distinguishes from sibling tools like 'templates_list_tags' and 'templates_list_triggers'.

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 instructs that this tool MUST be called before 'templates_get_variable' or 'variables_create', provides a step-by-step workflow, and warns against guessing variable type names. This sets clear usage context and 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, and description adds that it raises ValueError for unrecognized tool names, which is behavioral context beyond the annotation. No contradictions.

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

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

The description is well-structured with sections for Args, Returns, Example, Raises, but slightly verbose. The purpose is front-loaded, and each section adds value.

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

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

Given no output schema, the description explains return structure in detail and includes exception info. For a simple tool with one parameter, it is fairly 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 input schema has 0% description coverage for the only parameter, but the description provides a clear explanation: 'tool_name: Name of the MCP tool to get parameters for (e.g., "apps_update")', adding essential meaning.

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

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

The description clearly states 'Get JSON schema for tool parameters' and explains it returns complete JSON schema for MCP tools. It distinguishes from sibling tools which perform different operations like listing or getting data.

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

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

The description provides example usage and mentions it's for tools using JSON attributes interface. However, it doesn't explicitly state when not to use or compare 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?

Beyond the readOnlyHint annotation, the description adds detailed behavioral context including resolution rules for scalar, boolean, and array values, and explains the effect of the 'detailed' parameter. This provides rich transparency without contradicting annotations.

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

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

The description is well-structured with clear sections for Args, Returns, and Resolution rules, and front-loads the purpose. While comprehensive, it could be slightly more concise without losing clarity.

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

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

Given the tool's moderate complexity (2 params, 1 required), no output schema, and the presence of sibling tools, the description thoroughly covers the purpose, behavior, parameters, and resolution logic, making it complete for effective usage.

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

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

With 0% schema description coverage, the description fully compensates by explaining both parameters: 'app_id' as UUID of the app and 'detailed' controlling the inclusion of raw inputs. It also details the return structure, adding meaning beyond the schema.

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

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

The description clearly states 'Get effective tracker settings for a specific app', using a specific verb and resource. It distinguishes itself from the sibling tool 'tracker_settings_global_get' which gets global settings, ensuring no ambiguity.

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

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

The description provides clear context on when to use the tool and explains resolution rules, but it does not explicitly state when not to use it or list alternative tools. It mentions an alternative 'tracker_settings_global_update' for changing global defaults, but lacks explicit exclusion for other siblings.

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

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

Annotations already declare readOnlyHint=true. The description adds value by listing the returned dictionary keys, providing specific behavioral context beyond annotations.

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

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

The description is a single concise paragraph with bullet-pointed return fields, no wasted words, and the purpose 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?

Given zero parameters and an existing output schema, the description provides comprehensive details about the return structure, making the tool's behavior fully understood.

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

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

Input schema has 0 parameters, so baseline is 4. The description explains the output in detail, which covers the only semantic need.

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 'Get global tracker settings' and lists the returned fields, specifying the resource and scope. It distinguishes from sibling 'tracker_settings_app_get' by indicating global vs app-specific.

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

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

No explicit guidance on when to use this tool versus alternatives like 'tracker_settings_app_get'. However, the context implies it is for global settings, and the tool is straightforward with no parameters, so usage is self-explanatory.

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 provide readOnlyHint=true, aligning with the description's 'Get' action. However, beyond safety, the description adds no behavioral context (e.g., error handling, authentication requirements). The description does not contradict annotations.

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

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

The description is short (two sentences) and front-loaded with the main action. The related tools note adds utility without redundancy. It is appropriately concise.

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 get-by-ID operation with an output schema, the description is minimally adequate but lacks parameter context and error scenarios. It covers the core purpose but leaves gaps for an AI agent.

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 0%, and the description does not explain the two required parameters (app_id, trigger_id). The description adds no meaning beyond the schema, which already provides minimal info.

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 the specific verb 'Get' and resource 'detailed information about a specific trigger', clearly distinguishing it from sibling tools like triggers_list (which lists triggers) and triggers_list_tags (which lists tags).

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 mentions a related tool (triggers_list_tags) but does not provide explicit guidance on when to use this tool versus alternatives like triggers_list or triggers_get with other contexts. Usage is implied but not clearly scoped.

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, which the description is consistent with — no contradiction. The description adds modest behavioral context: available filter keys and the pageview gotcha, which hints at how the underlying API behaves. However, it doesn't go deeper into pagination limits, sorting, or rate-limit considerations. Acceptable given annotations cover the safety profile.

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?

Tight one-sentence summary followed by clean, scannable Args documentation. No fluff, no repetition of the schema, and every sentence earns its place. The format makes it easy for an agent to parse quickly.

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

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

An output schema exists, so the description doesn't need to explain return values — and it doesn't. For a straightforward list operation with read-only annotations, the description plus schema cover requirements, parameters, and a key gotcha. Minor gaps: no mention of maximum limit values or default sort order, but nothing substantial is missing for a tool of this complexity.

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

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

Schema coverage is 0%, so the description carries the entire documentation burden — and it delivers. It documents the semantic meaning of all 4 parameters and, critically, lists the valid filter keys for the opaque 'filters' object (which the schema leaves as additionalProperties: true). The page_view tip adds value. Would be a 5 with filter value types (e.g., is has_any_tags a boolean or tag ID?).

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

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

Clear verb+resource+scope: 'List triggers for an app in Piwik PRO Tag Manager.' This clearly signals a read/list operation and implies the scope. It's distinguishable from siblings like triggers_get (singular) and tags_list_triggers by name and context, though it doesn't explicitly name them or their differentiators.

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

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

No explicit when-to-use or when-not-to-use guidance, and no named alternatives despite siblings like triggers_get and tags_list_triggers existing. However, the filter documentation and the tip about using 'page_view' (not 'pageview') provide useful value-format guidance that helps an agent use this tool correctly. As such, it earns above a 2 for basic usage context that implies when this list tool is 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?

Annotations already declare readOnlyHint=true, which is consistent with 'Get list'. The description adds no additional behavioral context such as pagination details, authorization requirements, or side effects. Given annotations, a 3 is appropriate.

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

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

The description is a single sentence plus a clear docstring-style parameter list. It's efficient and front-loaded, though the parameter list could be more compact.

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

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

Given 10 parameters and no output schema, the description covers most parameter semantics. However, it lacks details on return format, pagination behavior, and default sort order, which would be beneficial.

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

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

The input schema has 0% description coverage, so the description compensates by explaining each parameter's purpose (e.g., 'Filter by tag name (partial match)'). This adds meaningful context beyond the schema titles.

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 'Get list of tags assigned to a specific trigger' with a specific verb and resource. It distinguishes from sibling tools like tags_list (all tags) and tags_list_triggers (triggers for a tag).

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

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

No explicit guidance on when to use this tool versus alternatives. The agent must infer usage from the parameter list and tool name, but no 'when not to use' or 'prefer X for Y' is provided.

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

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

The description is consistent with 'readOnlyHint' annotation. It adds no extra behavioral context beyond the annotation, but the annotation itself covers the safety profile.

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

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

The description is concise, only one sentence. It is front-loaded and contains no unnecessary 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 existence of an output schema and readOnlyHint annotation, the description is minimally sufficient. However, it lacks guidance on usage compared to siblings and does not explain what 'detailed information' entails.

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

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

With 0% schema description coverage, the description does not explain the parameters. Although parameter names 'app_id' and 'variable_id' are intuitive, the description adds no meaning beyond the schema.

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

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

The description clearly states the tool retrieves detailed information about a specific variable. The verb 'get' and resource 'variable' are explicit, and it distinguishes from 'variables_list' which would list multiple variables.

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

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

No guidance on when to use this tool over siblings like 'variables_list'. No mention of prerequisites or context for using the tool.

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

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

The annotations provide readOnlyHint=true, so the read-only nature is already established. The description adds meaningful behavioral context by clarifying that the tool handles only custom variables and that built-in UUIDs are fixed platform-wide, which helps the agent understand platform behavior beyond the annotation. It does not disclose response details, but the output schema covers 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?

The description is concise yet complete: the verbiage is purposeful, and the 'Do not use' caveat earns its place because it prevents misuse. The Args block is well-organized and makes each parameter easy to find. No obvious fluff or tautology.

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 is a straightforward read-only list operation, the description covers its core limitations in scope, parameter use, and alternative sources for built-in identifiers. Sibling tools like variables_get would naturally be for individual retrieval, but the list semantics are clear. All necessary context is present.

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

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

Input schema has no descriptions on properties, so the description must compensate. The Args section documents all four parameters, including the crucial note that filters can use keys 'name', 'variable_type', and 'builtin'. This adds useful meaning beyond the bare schema, though values for each available item are not detailed.

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

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

The description states a clear verb and resource: 'List variables for an app in Piwik PRO Tag Manager.' It further specifies that it lists custom (user-created) variables and explicitly distinguishes this tool from resolving built-in variable UUIDs. This clearly separates it from sibling tools like variables_get and templates_list_variables.

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 an explicit exclusion and an alternative: 'Do not use this tool to resolve built-in variable UUIDs for trigger conditions' and points to trigger_base.json → conditions_reference.conditions.<key>.builtin_variable_id. This is strong usage guidance beyond just stating what the tool does.

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 indicate readOnlyHint=true, so the description adds no behavioral context beyond that. It does not contradict annotations, but also does not disclose permissions, uniqueness, or return format details beyond what's in the schema.

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

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

The description is concise, well-structured with Args and Returns sections, and front-loaded with the core purpose in the first sentence.

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 getter with one parameter and an output schema (not shown but referenced), the description covers the return structure and is sufficiently complete for the tool's complexity.

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

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

Schema has 0% description coverage, but the description adds semantic value by stating 'UUID of the app' for the parameter app_id, which is more informative than the schema's 'App Id' title.

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 action ('Get') and the resource ('draft version for an app'), and distinguishes itself from siblings like versions_get_published and versions_list.

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

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

The description provides no guidance on when to use this tool versus alternatives (e.g., when to get draft vs published), nor any preconditions or 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, indicating a safe read operation. The description adds behavioral context by detailing the return format (dictionary with data, tags, triggers, variables), going beyond the minimal annotation information.

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

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

The description is concise and well-structured: a one-sentence purpose, followed by structured Args and Returns sections. Every part adds value with no redundancy.

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

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

For a simple read-only tool with one parameter, the description covers purpose, parameter semantics, and return shape comprehensively. The presence of an output schema further alleviates the need to describe return values 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?

Schema coverage is 0%, but the description fully compensates by clearly documenting the single parameter 'app_id' as 'UUID of the app,' adding meaning beyond the schema's type-only definition.

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

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

The description clearly states the tool's purpose: 'Get published version for an app.' It uses a specific verb and resource, and distinguishes from siblings like versions_get_draft and versions_list, as it specifically targets the published version.

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 no guidance on when to use this tool versus its siblings (e.g., versions_get_draft). It lacks explicit context, such as 'use this when you need the active/live version' or 'for draft use versions_get_draft.'

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 mark this as readOnlyHint=true, and the description adds that it returns a dictionary with pagination metadata. It does not contradict annotations and provides useful return format details, though it omits potential rate limits or auth requirements.

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 uses a clear docstring format with Args and Returns sections. It is slightly verbose but well-organized and easy to parse. No unnecessary filler.

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

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

With annotations providing readOnlyHint and the description covering parameters and return structure, the description is largely complete for a list tool. Minor gap: no mention of error conditions or behavior when app_id is invalid.

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 meanings for all three parameters (app_id, limit, offset) beyond the schema titles, including default values and roles. This compensates for the 0% schema description coverage.

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

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

The description clearly states it lists versions for a specific app in Piwik PRO Tag Manager, using the verb 'list' and the resource 'versions'. It distinguishes from siblings like versions_get_draft and versions_get_published by focusing on the full version list.

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

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

No explicit guidance on when to use this tool versus alternatives (e.g., versions_get_draft, versions_get_published). The description implies it is for listing all versions, but does not mention exclusions or context.

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