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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds 'synchronous' and 'return JSON results,' which are useful, but it does not explain potential implications like performance, error behavior, or that the query must be read-only. It does not contradict annotations, so this is a moderate score.

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 sentence that directly states the tool's action and output. It is well-structured and front-loaded, with 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?

While an output schema exists (so return values are covered), the description lacks essential context for a powerful SQL execution tool. It does not mention the read-only constraint, any limitations, or how it relates to the higher-level analysis tools. Given the potential impact, this is incomplete for an agent to use safely and effectively.

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 one parameter 'sql' with 0% schema description coverage. The description merely refers to 'SQL query,' which essentially restates the parameter name and provides no additional meaning such as SQL dialect, allowed statements, or syntax examples. It fails to compensate 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 the tool's function: 'Execute one synchronous SQL query and return JSON results.' It identifies a specific verb (execute) and resource (SQL query), and the SQL nature implicitly distinguishes it from the sibling analysis tools. However, it does not explicitly draw that differentiation.

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?

There is no guidance on when to use this tool versus the sibling query_* analysis tools. It does not mention alternatives, prerequisites, or contexts where this tool is appropriate or inappropriate. The description is purely functional without usage direction.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, covering the safety profile. The description adds context about the 'configured ThinkingData project' but does not disclose behavioral traits such as pagination, rate limits, or scope of returned metadata. With annotations present, the description adds some value but stays within expected 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 a single, clearly front-loaded sentence with no redundancy or filler. Every word earns its place, and it efficiently communicates the tool's 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 zero parameters and an output schema is present, the description is complete enough. It states the resource being listed and the project scope, while return-value details are handled by the output schema. No additional context is necessary for this low-complexity 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 tool takes no parameters, and the input schema is an empty object. Per the rubric, 0 params yields a baseline of 4. The description correctly avoids inventing parameters and does not need to explain anything beyond the schema, which is fully covered.

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

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

The description uses a specific verb+resource ('List event metadata') and clearly distinguishes from the sibling tool 'list_property_metadata' by focusing on events rather than properties. The qualifier 'for the configured ThinkingData project' provides project scope, 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 when event metadata is needed but offers no explicit guidance on when to choose this tool over alternatives like 'list_property_metadata' or the various analysis queries. There is no mention of exclusions or prerequisites, so guidance is minimal beyond the obvious function.

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

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

Annotations already indicate this is a safe read-only operation (readOnlyHint=true, destructiveHint=false). The description adds the project context but does not disclose any additional behavioral traits such as pagination, filtering behavior, or specific output characteristics. It does not contradict the annotations, but adds minimal behavioral value beyond them.

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

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

The description is a single concise sentence that is front-loaded with the action and resource, containing no filler or redundant information. Every word 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?

The tool has a moderate complexity with two parameters and an output schema, but the description leaves the event_name parameter unexplained and offers no usage guidance. While the output schema may cover return values, the incomplete parameter semantics and lack of alternatives make it only minimally 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 must compensate by explaining parameters. It only indirectly explains table_type via 'event or user' but completely fails to mention the optional event_name parameter, leaving its purpose and usage ambiguous. This is a significant gap given the schema provides no 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 uses the specific verb 'List' and clearly identifies the resource as 'event or user property metadata' for the configured project. This distinguishes it from siblings like list_event_metadata and the various query analysis tools, making its 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 no guidance on when to use this tool versus alternatives such as list_event_metadata or query tools. There are no explicit use cases, prerequisites, or exclusions, leaving the agent to infer appropriate usage only from the tool name and description.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds no additional behavioral context such as return format, data granularity, or how distribution is computed, offering no value 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 a single sentence, which is concise, but it is under-specified rather than appropriately concise. It states the core purpose but omits necessary details, so the brevity does not fully serve the agent.

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

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

Given the tool's complexity (4 required parameters, nested objects, and an output schema) and its sibling tools, the one-sentence description is inadequate. It does not explain what 'distribution' means, how the property is specified, or what the output contains, leaving significant 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?

Schema description coverage is 0%, and the description does not explain any of the four required parameters. While the schema has meaningful names, the description fails to add any semantic meaning beyond what is in the schema, leaving the agent without guidance on parameter 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?

The description clearly states the tool queries how an event metric is distributed over a property, using a specific verb and resource. It is distinguishable from siblings like query_event_analysis by the focus on 'distribution over a property,' though it does not explicitly name alternatives.

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 such as query_event_analysis or query_user_property_analysis. It only states the action without any contextual scenarios 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 and destructiveHint=false, so safety is covered. The description adds behavioral context by specifying the query can be filtered and grouped over time. It does not contradict annotations and provides some value beyond the structured fields.

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 sentence that is front-loaded with the key action and object. Every word earns its place, and it avoids any 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?

Despite having a complex schema with 6 parameters, nested objects, and multiple enums, the output schema is present, but the description remains overly terse. It does not explain what constitutes 'event metrics', how filters/grouping work, or when this tool is preferable to the many sibling analysis tools. The description is insufficient 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 description coverage is 0%, so the description must compensate for the 6 parameters. It only mentions 'event metrics', 'over time', 'filters', and 'grouping' at a conceptual level, which maps to some parameters but leaves out details on metric types, time_range formats, and granularity. The rich schema with enums and nested objects is not explained, so the description adds little semantic value.

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

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

The description clearly states the tool queries event metrics over time with optional filters and grouping. It uses a specific verb ('query') and identifies the resource ('event metrics'), but it does not explicitly distinguish itself from sibling analytics tools like query_retention_analysis or query_funnel_analysis, so it misses the top score.

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 querying event metrics over time, but it does not provide explicit guidance on when to use this tool over siblings, nor does it mention any exclusions or prerequisites. There is no reference to alternative 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 and destructiveHint=false, so the safe read nature is known. The description adds no additional behavioral context beyond the core concept; it does not contradict annotations, but also does not disclose pagination, ordering requirements, or return characteristics, though output schema covers some of this.

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, front-loaded sentence with no wasted words. It communicates the essential purpose efficiently and is appropriately sized for the tool.

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

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

Given the tool has four parameters with nested objects and the description provides no parameter semantics, usage guidance, or behavioral disclosure, the description is too thin to be fully useful. While the output schema exists and annotations cover safety, the lack of explanation for key concepts like conversion_window and steps limits 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?

Schema description coverage is 0%, and the description provides no explanation of the four parameters (steps, filters, time_range, conversion_window) or their semantics. The nested structure and units (e.g., conversion_window) are left entirely to the schema, which does not explain their meaning in the context of funnel analysis.

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

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

The description states the tool queries conversion across an ordered sequence of event steps, which is a clear and specific definition of funnel analysis. It distinguishes from sibling tools like retention or path analysis by focusing on sequential conversion, though the verb 'query' is generic.

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?

There is no explicit guidance on when to use this tool versus alternatives like query_path_analysis or query_retention_analysis. The use case is implied by the description (conversion across steps), but no exclusions or alternative recommendations 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 indicate a read-only, non-destructive operation, which is consistent with the description. However, the description adds no behavioral context beyond that—it does not explain what an 'elapsed interval' includes, how events are matched, or any limitations.

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 with no redundant words, making it very concise and easy to read. It is appropriately 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 nested parameters and several sibling tools, this description is far too minimal. It lacks details about how the time range options work, the meaning of interval results, and any usage context, leaving significant gaps for the 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 any of the three parameters (start_event, end_event, time_range). The schema provides type information but no semantic guidance on how these parameters interact or should be used.

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 queries elapsed intervals between a start and end event, using a specific verb and resource. This distinguishes it from sibling tools like query_event_analysis or query_retention_analysis.

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 alternative analysis tools. The description does not mention exclusions, prerequisites, or recommended use cases.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's 'Query' is consistent but adds no additional behavioral context. It does not disclose output format, limits, or any other side effects beyond what the annotations imply, failing to add value beyond the structured data.

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

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

The description is a single sentence with no wasted words and front-loads the core action. It is concise, but the brevity borders on under-specification given the tool's complexity, so it loses a point for being too terse.

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?

Although an output schema exists, the tool is complex with nested objects and an enum. The description does not explain the meaning of direction, how events should be listed, or the time_range structure, making it insufficient for an agent to invoke the tool correctly in non-trivial cases.

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 must compensate for the four required parameters. It only vaguely references 'selected starting event' (start_event), while events, direction (with enum initial_event/termination_event), and time_range remain unexplained. This leaves the agent without enough information to correctly construct the input.

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 'Query' and the resource 'paths around a selected starting event', indicating a read-only path analysis tool. It adds the notion of a starting event, which gives some context beyond the tool name. However, it does not explicitly distinguish it from sibling query_* tools or clarify what 'paths' means, so it lacks sibling differentiation.

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 like query_event_analysis or query_funnel_analysis. There is no mention of context, prerequisites, or exclusions, leaving the agent without direction on tool selection.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only safety is covered. The description adds the temporal relationship between initial and returning events, which is useful behavioral context. However, it doesn't disclose output format, time range semantics, or any other behaviors, so it doesn't go beyond the annotations meaningfully.

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?

A single, front-loaded sentence with no redundant words. It communicates the core action and key entities efficiently. The brevity is not padding but under-specification, yet for this dimension it deserves full marks 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?

Given the complexity (nested objects, output schema, sibling analytical tools), the description is minimal. It lacks context on what retention metrics are returned, how cohorts are defined, or how time_range options behave. The presence of an output schema reduces the need to explain return values, but the core semantic of retention analysis is not fleshed out, making the tool hard to use correctly for an 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%, so the description must compensate. It clarifies the role of initial_event and returning_event (as start and end events) but provides no explanation of time_range (start_time/end_time vs recent_day). The nested object structure is also unexplained, leaving a significant portion of the parameters semantically ambiguous.

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

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

The description uses a specific verb ('Query') and resource ('retention') with the initial/returning event relationship. It clearly states what the tool does and distinguishes from siblings by focusing on retention, though it doesn't explicitly contrast with funnel or path analysis.

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 over siblings like query_funnel_analysis or query_event_analysis, nor any exclusions. It only implies usage through the term 'retention', which is insufficient for an agent to select among the many analytical 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 and destructiveHint=false, so the safety profile is known. However, the description adds no behavioral context such as return format, pagination, limits, or required permissions, offering no value 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 a single, front-loaded sentence with no redundant words, making it concise. However, it is under-specified, which limits its usefulness despite being brief. It is not as extreme as a tautology but still lacks substance.

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 nested schema, many sibling tools, and presence of an output schema, the description is far too minimal. It does not provide adequate context for tool selection or understanding of the aggregation types, leaving the agent to infer too much from the schema alone.

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, and the description only mentions 'aggregation' and 'user or event property,' which vaguely map to the aggregation and property parameters. It does not explain time_range formats or the meaning of aggregation enum values like USER_NUM, leaving most parameters semantically 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 core function with a specific verb ('Query') and resource ('an aggregation over a user or event property'). It distinguishes the tool from non-aggregation siblings like funnel or retention analysis, but it could be confused with query_event_analysis or query_distribution_analysis since it doesn't explicitly differentiate.

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 the many sibling analysis tools. There are no alternative names, exclusions, or contextual hints, leaving tool selection ambiguous for an AI agent.

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