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

There are no annotations, so the description must disclose behavioral traits. It does state that the tool creates a new metric (mutation) and returns a dictionary with assigned ID, but it does not mention side effects, required permissions, error handling, or rate limits. The important validation note adds some transparency but is not comprehensive.

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

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

The description is well-structured with a concise intro, a highlighted prerequisite, a clear args list, return info, and example queries. It avoids redundant information, though the args list somewhat mirrors the schema. The examples are helpful and 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 no output schema, the description includes return details and covers all parameters. It mentions validation as a prerequisite and provides example queries. However, it lacks information on error cases, default dataview_id behavior, and authentication requirements, leaving some gaps for a creation tool.

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

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

Schema coverage is 0%, so the description must add meaning. It provides context for all 7 parameters: explains name as required, definition structure (func, formula, version), metric_type values, polarity meaning, precision range, and dataview_id optional. This adds significant value beyond the raw schema, though it could include more detail on the formula format.

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

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

The description clearly states the tool creates a new calculated metric in CJA, specifying it's a custom metric with formulas and functions used in reports. It distinguishes itself from sibling tools like cja_list_calculated_metrics and cja_validate_calculated_metric by focusing on creation.

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 prerequisite: validating the definition first using cja_validate_calculated_metric. It also provides example queries that illustrate common use cases, guiding the agent on when to use the tool. However, it does not explicitly state when not to use it or provide 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?

No annotations provided, so description carries full burden. Discloses creation behavior, required and optional parameters, and suggests validation. Adds context about complexity but does not detail error conditions or side effects.

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 summary, best practices, args, returns, examples. Somewhat verbose but all information is useful 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?

For a complex tool with nested objects and no output schema, description provides example definition, return value, and example queries. Missing error handling but sufficient with sibling tools for validation and 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 coverage is 0%, but description explains each parameter thoroughly: name, definition (with example), description, dataview_id. Provides meaning beyond schema types, including example 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?

Clearly states 'Create a new segment in CJA.' with specific verb and resource. Distinguishes from sibling tools like cja_validate_segment and cja_get_segment_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?

Explicitly provides best practices: use cja_get_segment_details to see structure, use cja_validate_segment before creating. Also suggests creating template in UI. Guides when to use this tool vs alternatives.

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

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

With no annotations, the description carries full burden. It mentions returning a dictionary with details and formula, but lacks information on error handling, authentication requirements, or any side effects. Read-only nature is implied but not explicit.

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

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

The description is well-structured with a summary, args, returns, and examples. It is front-loaded with purpose. The example queries are helpful but take some space; 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?

For a simple retrieval tool with two parameters (one required) and no output schema, the description covers essential aspects: what it does, what parameters do, and what is returned. Lack of error details is a minor gap.

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

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

Schema description coverage is 0%, so the description must compensate. It explains metric_id as 'Calculated metric ID to retrieve (required)' and expansion as 'Optional comma-delimited fields: definition, tags, usedIn, compatibility'. This adds significant 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 it retrieves detailed information about a specific calculated metric, including its definition/formula. This distinguishes it from sibling tools like cja_list_calculated_metrics (which lists) and cja_create_calculated_metric (which creates).

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 queries that illustrate appropriate use cases, such as 'Show me the formula for calculated metric a5066209'. However, it does not explicitly state when not to use this tool 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?

No annotations are provided, so the description must convey behavioral traits. It indicates a read-only operation returning configuration metadata, but does not mention error handling, permissions, or response size. The basic behavior is clear but not comprehensive.

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, consisting of a single introductory sentence followed by structured Args and Returns sections. It is front-loaded with the purpose and contains no extraneous information.

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

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

Given the tool's simplicity (two optional params, no output schema), the description covers the essential aspects: purpose, parameters, and example queries. Minor gaps exist, such as the exact return structure and error scenarios, but it is largely sufficient for agent decision-making.

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 well by explaining the two parameters: dataview_id is optional and defaults to a configured value, expansion can include additional fields like 'components'. This adds meaningful context 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 that the tool retrieves detailed information about a CJA data view, using a specific verb and resource. It distinguishes itself from sibling tools, which focus on other entities like metrics, segments, or reports, making the purpose unambiguous.

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

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

The description implies usage for obtaining data view configuration but does not explicitly state when to use this tool versus alternatives or when not to use it. The sibling list provides context, but direct guidelines 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?

The description implies a read-only operation ('Get', 'retrieves'), but no annotations are present. It does not explicitly state side effects or safety, though for a get operation the behavior is transparent enough. Additional details on auth or rate limits would improve it.

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 fairly concise and well-structured with sections for Args, Returns, and Example queries. It could be slightly shorter by removing redundant phrases like 'which shows the exact logic and rules', but overall it is efficient.

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

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

Given the tool's simplicity (2 parameters, no output schema), the description covers the core functionality, parameters, and provides examples. It lacks error handling or permission notes, but is sufficient for a straightforward get operation.

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

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

Schema description coverage is 0%, but the description adds meaningful information for both parameters: segment_id is the ID to retrieve, and expansion lists possible additional fields. It does not provide format or constraints, but compensates for the lack of schema descriptions.

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

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

The description clearly states it retrieves detailed information about a specific segment, including definition and logic. The tool name and example queries reinforce this, and it is distinct from sibling tools like list_segments or create_segment.

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?

Example queries are provided, but the description does not explicitly state when to use this tool versus alternatives (e.g., list_segments for listing, validate_segment for validation). No when-not 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?

With no annotations, the description carries full burden. It discloses that the tool returns a dictionary with metric values and mentions a max limit of 500, which is useful. However, it does not explicitly state that the tool is read-only, non-destructive, or any other behavioral traits beyond the return format.

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: a concise purpose statement at the top, followed by a bullet-style Args section and a Returns clause, plus example queries. It is appropriately sized without unnecessary fluff, though the Args section repeats some schema metadata.

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

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

Given no output schema, the description provides a brief return description and example queries, which is adequate. All 6 parameters are documented, and the tool's purpose is clear. However, it could benefit from explaining pagination or the structure of the returned dictionary in more 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 description coverage is 0%, so the description must compensate. It provides clear parameter explanations for all 6 parameters, including examples for dimension and metric (e.g., 'variables/page'), date format, limit with default and max, and dataview_id optionality. This adds significant meaning beyond the schema names and types.

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 gets 'top N items for a dimension ranked by a metric', with concrete examples like 'top pages by visits' and 'top products by revenue'. This verb+resource combination is specific and distinguishes it from sibling report tools (e.g., cja_run_report, cja_run_breakdown_report) by emphasizing ranking and top-N filtering.

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 is 'optimized for finding the top performing dimension items' and provides example queries, giving strong context for when to use it. However, it does not explicitly state when not to use it or compare to alternative siblings like cja_run_breakdown_report for cross-tabulations or cja_search_dimension_items for searching.

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

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

With no annotations, the description details filtering, pagination, and expansion options. It discloses read-only behavior and no destructive actions, though it omits rate limits or authentication 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 is well-structured with a summary, parameter details, return info, and examples. It is slightly lengthy but each sentence is meaningful 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?

For a list tool with 7 parameters and no output schema, the description covers arguments comprehensively and provides usage examples. It lacks detail on the return structure beyond a dictionary with list and count, which 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?

Schema descriptions are absent (0% coverage), but the description explains each parameter's purpose, options, and defaults clearly, adding significant value beyond the schema itself.

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 calculated metrics in CJA, explaining they are custom formulas for reports. This distinguishes it from siblings like cja_get_calculated_metric_details (single metric) and cja_create_calculated_metric (creation).

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 filter parameters and example queries guiding usage. It does not explicitly exclude when to use alternatives, but the context and examples imply proper use, e.g., listing vs. getting details.

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

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

No annotations are provided, so the description must convey behavioral traits. It mentions optional parameters and a return dictionary with list and count. It does not discuss permissions, rate limits, or error handling. The read-only nature is implied but not explicit.

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, using a docstring format with Args and Returns sections. It includes example queries without being verbose. It is well-structured and easy to read.

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 absence of an output schema, the description fairly covers the purpose and parameters. However, it lacks any mention of errors, performance, or limitations, which would be helpful for completeness.

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% description coverage, but the description explains the parameters 'dataview_id' (optional, uses default) and 'expansion' (additional fields) with an example. This adds useful 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 that the tool lists all available dimensions in the CJA data view, with examples of what dimensions are. It distinguishes from siblings like list_metrics and list_segments by focusing on attributes that break down 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 explains when to use this tool (e.g., 'What dimensions are available?') and provides example queries. However, it does not explicitly mention when not to use it or contrast with alternatives like cja_search_dimension_items.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the tool lists all metrics and returns a dictionary with a list and total count. However, it does not mention any behavioral traits such as data view restrictions, authorization needs, or performance implications. The description provides basic but incomplete behavioral 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 well-structured with a clear opening sentence, separate Args and Returns sections, and example queries. It is informative without being overly verbose. Minor redundancy exists in repeating 'metrics' in examples, but overall it is concise 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?

For a simple list tool with no output schema, the description covers the essential aspects: purpose, parameters, return format, and usage examples. It lacks details on expansion values, but given the tool's simplicity, the description is largely complete and useful.

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 adds value by explaining that dataview_id is optional and uses a configured default, and that expansion allows additional fields. However, it does not specify what values expansion can take or provide examples, leaving some ambiguity. This is adequate but not excellent.

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 all available metrics in the CJA data view', which is a specific verb-resource combination. It distinguishes from sibling tools like cja_list_dimensions and cja_list_segments by focusing on metrics, and provides examples of metrics (visits, page views, revenue) that clarify the tool's 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 includes example queries like 'What metrics can I measure?' which imply when to use, but it does not explicitly state when not to use this tool or provide direct alternatives. While the sibling list clarifies alternatives, the description itself lacks explicit usage guidance or conditions.

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

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

With no annotations, the description discloses key behavioral aspects: it retrieves segments the user has access to, supports pagination and expansion, and returns a dictionary. It does not explicitly declare read-only intent, but the listing nature implies no side effects.

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

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

The description is well-structured with a brief opening, parameter list, return note, and example queries. It is slightly verbose due to the parenthetical clarification about segments/filters, but all content 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 7 parameters and no output schema or annotations, the description covers the tool's functionality well, including parameter details and use examples. It lacks precise output structure (e.g., exact keys), but the dictionary description is adequate for a list tool.

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

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

Schema description coverage is 0%, but the description fully compensates by explaining each parameter: dataview_id (optional filter, default), name (partial match), tag_names (comma-delimited), include_type (with examples 'shared', 'all', 'templates'), limit (default 10, max 1000), page (0-indexed), expansion (list of fields).

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 all available segments/filters in CJA', using a specific verb and resource. It distinguishes segments from related siblings like cja_get_segment_details and cja_create_segment by focusing on listing all accessible segments.

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?

Example queries demonstrate typical use cases (e.g., 'List all available segments', 'Show me segments with 'mobile' in the name'). However, the description does not explicitly state when to avoid this tool or compare it to siblings like cja_get_segment_details for more detail.

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

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

No annotations provided; description covers what the tool does (breakdown analysis, returns nested results) but lacks explicit mention of read-only nature, side effects, or rate limits.

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

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

Well-structured with summary, args, returns, and examples. Contains some redundancy but overall concise and informative.

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 parameters, usage context, and return format. Given no output schema, the description is sufficiently complete for 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?

Input schema has 0% description coverage, but description compensates by explaining each parameter's purpose, including examples and default values.

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 runs a breakdown report with primary and secondary dimensions. Examples differentiate from sibling tools like cja_run_report and cja_run_trended_report.

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

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

Provides clear usage context with example queries and parameter explanations. Does not explicitly state when not to use, but sibling tool names imply 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?

No annotations exist, so description bears full burden. It explains the function and return type but omits details like caching, pagination, or rate limits. The note about limit max and default is helpful.

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: overview, important note, args, returns, patterns, examples. Front-loaded with purpose. Could be slightly more concise but remains clear and organized.

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

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

Given 6 params, no output schema, and no annotations, the description covers inputs well and explains return type. Common patterns and example queries add context. Missing details on output structure, but adequate for 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?

Schema coverage is 0%, but the description documents all 6 parameters with names, types, defaults, and examples. It adds meaning beyond the schema, especially for dimension and metrics with common ID references.

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 runs a CJA report with dimension and metrics over a date range, explicitly calling it 'the primary tool for analyzing data.' It distinguishes from siblings like breakdown and trended reports through its general nature.

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 advises checking the quick-reference resource for IDs and provides common patterns and example queries. However, it does not explicitly contrast with sibling tools or specify when not to use it.

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

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

No annotations are provided, so the description must cover behavioral aspects. It indicates the tool runs a report (assumed read-only) and returns a dictionary, but it does not mention side effects, auth requirements, or rate limits. For a reporting tool, this is adequate but not thorough.

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: a short intro, followed by an Args list, returns note, and example queries. It is front-loaded with the core purpose. While a bit lengthy, it earns its space by providing clear guidance without unnecessary 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?

Given 8 parameters (3 required) and no output schema, the description provides sufficient context: it explains what the tool does, what each parameter does, what it returns, and example use cases. It could detail error handling or output format further, but this is adequate for a reporting 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 0% description coverage, so the description's 'Args' section adds significant meaning beyond the schema. It explains each parameter in plain language, including examples like 'dimension: Optional dimension to break down the trend (e.g., "variables/mobiledevicetype")', which is highly valuable.

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 'Run a time-series trend report' and explains that it analyzes how metrics change over time with specified granularity. This distinguishes it from siblings like cja_run_breakdown_report or cja_run_report, as it focuses on time-based trends.

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 queries that illustrate when to use the tool, such as 'Show me daily visits trend for last 30 days'. It also explains optional dimension breakdown, giving context for usage, though it does not explicitly state when not to use it.

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

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

No annotations exist, so the description carries full burden. It explains the search operation and returns, but does not explicitly state it is read-only or describe error handling, rate limits, or access requirements. Minimal but adequate for a search tool.

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

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

The description is well-structured with a summary, usage paragraph, Args list, Returns, and examples. It is appropriately sized for the parameter count and does not contain fluff, though it could be slightly more concise if schema parameters were documented.

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, no annotations, and 6 parameters, the description covers the core functionality well with examples. It lacks details on edge cases, case sensitivity, or pagination behavior, but is sufficient for typical 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 thoroughly documents all 6 parameters, including format hints (e.g., YYYY-MM-DD for dates), defaults (limit 100), and optionality (dataview_id uses configured default). The Args section adds significant value.

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

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

The description clearly states the tool searches for dimension items matching a search term, specifying the verb 'Search' and resource 'dimension items'. Examples with specific use cases like 'Find all pages containing checkout' make the purpose unambiguous.

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

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

The description provides usage examples and states it's useful for finding specific items, but does not explicitly contrast with sibling tools like cja_get_top_items or mention when not to use it. Guidance on alternatives is 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?

With no annotations, the description carries full burden. It discloses the tool is a validation step (non-destructive), and specifies return values including validation result, metrics used, and functions detected. No side effects are mentioned, but the nature implies read-only.

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: purpose sentence, usage sentence, bulleted Args, Returns, and example queries. It is concise, front-loaded, and each part 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 5 parameters and no output schema or annotations, the description fully explains all inputs and output structure. It provides sufficient context for an agent to use the tool correctly, including example queries.

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 fully compensates by detailing each parameter: name required, definition required, metric_type with default 'decimal', description optional, dataview_id optional with default behavior. This adds clear 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 the tool validates a calculated metric definition before creation or update, using specific verbs ('validate', 'check') and distinguishing from siblings like create or segment validation.

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 advises 'Always use this before creating a new metric', giving clear when-to-use guidance. Although no explicit when-not-to or alternatives are mentioned, the context is strong enough.

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

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

The description discloses the tool checks syntax and compatibility, and returns a dictionary. However, with no annotations, it does not explicitly confirm it is read-only or describe error handling, which is a gap.

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

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

The description is well-structured with Args, Returns, and Example queries. It is front-loaded with purpose. Minor redundancy like extra period after 'updating.' but overall 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?

The description includes example queries and basic return info. But lacks output schema and detailed validation result format. For a validation tool, more specifics on success/failure indicators would improve completeness.

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?

Description adds meaning to both parameters: explains 'definition' is required segment definition and 'dataview_id' is optional with default. However, schema coverage is 0% and the nested 'definition' object is not described, limiting usefulness.

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 'validate' and the resource 'segment definition'. It distinguishes this tool from siblings like 'cja_validate_calculated_metric' and 'cja_create_segment' by specifying it validates before creating or updating.

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 'Always use this before creating a new segment' and mentions validation for updates. It provides clear context but lacks explicit when-not-to-use or alternatives.

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