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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool returns ranked property names by prevalence, which implies a read-only operation, but it doesn't cover critical aspects like rate limits, authentication needs, error handling, or whether the ranking is based on counts or percentages. This leaves significant gaps in understanding the tool's 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 extremely concise and front-loaded, consisting of just two sentences that directly state the tool's function and output. Every word earns its place, with no redundant information or fluff, making 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?

Given the tool's moderate complexity (2 parameters, no output schema, and no annotations), the description is incomplete. It lacks details on output format (e.g., structure of returned properties), error cases, or performance considerations. Without annotations or an output schema, the agent has insufficient information to fully understand how to interpret results or handle edge 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?

The input schema has 100% description coverage, clearly documenting both parameters ('event' and 'limit'). The description adds no additional semantic details beyond what the schema provides, such as examples of event names or default values for 'limit'. Given the high schema coverage, a baseline score of 3 is appropriate as the schema handles the parameter documentation adequately.

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 a specific verb ('Get') and resource ('top properties for a specific event'), and it distinguishes its function from siblings like 'top_events' or 'query_events' by focusing on properties rather than events themselves. However, it doesn't explicitly contrast with all siblings, such as 'list_annotations' or 'segmentation_average', which might involve similar data but different operations.

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. It doesn't mention prerequisites, context, or exclusions, such as how it differs from 'query_properties' or other sibling tools that might handle event properties. This lack of usage context leaves the agent to infer appropriate scenarios.

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

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

With no annotations provided, the description carries full burden and adds valuable behavioral context: it specifies the return format (NDJSON), that it returns 'all properties' per event, and the hard cap ('Capped at 5000 events'). However, it doesn't mention pagination, rate limits, authentication needs, or what happens when the cap is reached.

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

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

Two concise sentences with zero waste: first sentence states purpose and format, second adds critical behavioral constraints (cap). Every word earns its place, and key information 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?

For a data export tool with 5 parameters, 100% schema coverage, and no output schema, the description is reasonably complete: it covers purpose, format, and a key constraint (cap). However, it lacks details on error handling, response structure, or performance implications that would help an agent use it 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?

Schema description coverage is 100%, so parameters are fully documented in the schema. The description doesn't add any parameter-specific semantics beyond what's in the schema (e.g., it doesn't explain filtering logic or date format nuances). Baseline 3 is appropriate since the schema does the heavy lifting.

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 specific action ('Export raw event data as NDJSON'), the resource ('event data'), and distinguishes from siblings by specifying it returns 'individual events with all properties' (unlike aggregated reports or filtered queries). It explicitly mentions the format (NDJSON) and output 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 retrieving raw event data with date ranges and filtering, but doesn't explicitly state when to use this vs. alternatives like 'query_events' or 'top_events'. No guidance on prerequisites, exclusions, or comparative contexts with sibling tools 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool 'shows how often users perform an event' but doesn't describe output format, pagination, rate limits, authentication needs, or whether it's read-only or destructive. For a tool with 7 parameters and no annotations, this leaves critical behavioral traits undocumented.

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 appropriately concise with two sentences that efficiently convey the core purpose. It's front-loaded with the main action ('Get a frequency report') and avoids unnecessary details. However, the parenthetical '(addiction report)' adds minor ambiguity without clear explanation.

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 (7 parameters, no output schema, no annotations), the description is incomplete. It doesn't address output format, error conditions, or behavioral constraints. While the schema covers parameters well, the description fails to provide sufficient context for safe and effective use, especially compared to sibling tools.

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

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

Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds minimal value beyond the schema by implying the report analyzes 'users' and 'events', but it doesn't explain parameter interactions or provide additional context. The baseline score of 3 is appropriate when the schema does the heavy lifting.

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 a frequency report (addiction report). Shows how often users perform an event within a time window.' It specifies the verb ('Get'), resource ('frequency report'), and scope ('users perform an event within a time window'). However, it doesn't explicitly differentiate from sibling tools like 'query_events' or 'top_events' that might also involve event 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 versus alternatives. It mentions the general context ('frequency report') but doesn't specify use cases, prerequisites, or exclusions. With many sibling tools available for event analysis (e.g., 'query_events', 'top_events'), the lack of comparative guidance is a significant gap.

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 of behavioral disclosure. It states the tool lists annotations but doesn't cover critical aspects like pagination, rate limits, permissions required, or what happens if no annotations exist in the date range. For a read operation with zero annotation coverage, this is a significant 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 concise with two sentences that directly state the purpose and define annotations. It's front-loaded and wastes no words, though it could be slightly more structured by explicitly mentioning the date 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 lack of annotations and output schema, the description is incomplete. It doesn't explain return values, error conditions, or behavioral traits like whether dates are inclusive. For a tool with two required parameters and no structured output, more context is needed to guide the agent 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 description coverage is 100%, with clear descriptions for 'from_date' and 'to_date' as start and end dates in YYYY-MM-DD format. The description doesn't add any parameter details beyond what the schema provides, so it meets the baseline of 3 for high schema 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 the verb ('List') and resource ('all annotations in the project'), and defines what annotations are ('notes attached to specific dates'). However, it doesn't differentiate from sibling tools like 'list_cohorts' or 'list_funnels' beyond the resource type, which is why it's not a 5.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools or contexts where other tools might be more appropriate, such as using 'query_events' for more complex filtering. This leaves the agent with minimal usage 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool returns 'cohort IDs, names, and metadata', which adds useful context about the output format. However, it doesn't disclose important behavioral traits like whether results are paginated, sorted, or filtered, or if there are rate limits or authentication requirements for this 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 perfectly concise with two sentences that each earn their place. The first sentence states the core action and resource, while the second provides essential output details. There's zero wasted text, and information is front-loaded with the primary purpose stated immediately.

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 operation with 0 parameters and no annotations, the description is adequate but has clear gaps. It explains what the tool does and what it returns, but without an output schema, it should ideally provide more detail about the return structure (e.g., format of metadata). The lack of behavioral context and usage guidelines reduces completeness for this read 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?

The input schema has 0 parameters with 100% coverage, so the baseline is 4. The description appropriately doesn't discuss parameters since none exist, and it adds value by explaining what the tool returns rather than focusing on inputs. No parameter information is needed or missing given the empty 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 verb 'List' and resource 'all cohorts in the project', making the purpose unambiguous. It distinguishes from siblings like 'list_annotations' by specifying the cohort resource, though it doesn't explicitly contrast with other list operations. The description avoids tautology by providing meaningful details beyond just the tool name.

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. It doesn't mention prerequisites, context for use, or compare it to sibling tools like 'query_events' or 'list_funnels' that might serve similar listing purposes. The agent must infer usage from the tool name and description alone without explicit 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?

No annotations are provided, so the description carries the full burden. It mentions the return format ('funnel IDs and names'), which adds some behavioral context, but fails to disclose critical traits like whether this is a read-only operation, pagination behavior, rate limits, or authentication needs. For a tool with zero annotation coverage, this is inadequate.

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

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

The description is two sentences, front-loaded with the core action, and every word earns its place without redundancy. It's efficiently structured and appropriately sized for the tool's simplicity.

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 low complexity (0 parameters, no output schema, no annotations), the description is minimally complete by stating what it does and the return format. However, it lacks behavioral details that would be helpful for an agent, such as pagination or error handling, keeping it at an adequate but basic level.

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 parameters with 100% coverage, so no parameter documentation is needed. The description doesn't add parameter details, which is appropriate, earning a baseline score of 4 for this context.

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 ('all saved funnels in the project'), making the purpose specific and understandable. However, it doesn't explicitly differentiate from sibling tools like 'query_funnels' or 'list_cohorts', which prevents a perfect 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 provides no guidance on when to use this tool versus alternatives like 'query_funnels' or other list tools. It lacks context about prerequisites, timing, or exclusions, leaving the agent with minimal 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?

With no annotations provided, the description carries full burden for behavioral disclosure. It mentions returns time-series event counts with optional segmentation, but doesn't describe pagination behavior, rate limits, authentication requirements, error conditions, or what happens with large date ranges. For a query tool with 7 parameters, this is insufficient.

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 perfectly concise - a single sentence that efficiently communicates the core functionality. It's front-loaded with the main purpose and includes the key optional feature (segmentation) without any 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 query tool with 7 parameters, no annotations, and no output schema, the description is inadequate. It doesn't explain the return format, error handling, performance characteristics, or how it differs from similar query tools in the sibling set. The agent would struggle to use this effectively without trial and error.

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

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

Schema description coverage is 100%, so the schema already documents all 7 parameters thoroughly. The description adds minimal value beyond the schema - it mentions segmentation which relates to the 'on' parameter, but doesn't provide additional context about parameter interactions or usage patterns.

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: query event data with segmentation and return time-series event counts. It specifies the verb 'query' and resource 'event data', but doesn't explicitly differentiate from siblings like 'query_insights' or 'top_events' which might have overlapping functionality.

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. With multiple query-related siblings (query_funnels, query_insights, query_profiles, query_retention), there's no indication of what makes this tool distinct or when it's the appropriate choice.

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 of behavioral disclosure. It states the tool queries and returns data, implying a read-only operation, but doesn't address permissions, rate limits, error handling, or data freshness. For a query tool with zero annotation coverage, this is a significant gap in 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 extremely concise and front-loaded: two sentences that directly state the action and output with zero waste. Every word earns its place, making 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?

Given the complexity (7 parameters, no output schema, no annotations), the description is minimally adequate. It covers the basic purpose and output but lacks behavioral context, usage guidelines, and details on return format. With no output schema, the agent must infer the structure from 'conversion rates and drop-off at each step', which is somewhat vague.

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

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

Schema description coverage is 100%, so the schema already documents all 7 parameters thoroughly. The description adds no parameter-specific information beyond what's in the schema (e.g., it doesn't explain how 'where' filters interact with funnel steps). With high schema coverage, the baseline is 3 even without param details in the description.

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

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

The description clearly states the tool's purpose: 'Query a saved funnel by ID' specifies the verb (query) and resource (saved funnel), and 'Returns conversion rates and drop-off at each step' explains the output. However, it doesn't explicitly differentiate from sibling tools like 'list_funnels' or 'query_insights', which would require a 5.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'list_funnels' (for listing funnels) or 'query_insights' (for other analytics), nor does it specify prerequisites or exclusions. This leaves the agent without contextual usage 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?

With no annotations provided, the description carries full burden for behavioral disclosure. It mentions 'Run an Insights report' which implies execution/processing but doesn't clarify whether this is a read-only operation, whether it requires specific permissions, what the output format might be, or any performance considerations. The 'Flexible analytics query' phrasing suggests some capability but lacks concrete behavioral details needed for proper tool selection.

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 brief sentences that don't waste words. It's front-loaded with the core purpose ('Run an Insights report') followed by additional capability context. While it could be more informative, every sentence serves a purpose without unnecessary verbiage.

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 tool with no annotations, no output schema, and multiple similar sibling tools, the description is insufficiently complete. It doesn't explain what an 'Insights report' returns, how it differs from other query tools, what 'flexible analytics' means in practice, or any behavioral characteristics. The agent would struggle to understand when and how to use this tool 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 description provides no parameter information beyond what's already in the schema. With 100% schema description coverage (the single parameter 'bookmark_id' is well-described as 'Saved Insights report ID'), the baseline score of 3 is appropriate. The description doesn't add any additional context about parameter usage, constraints, or relationships.

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 'Run an Insights report' which provides a basic verb+resource combination, but it's vague about what an 'Insights report' entails. It adds 'Flexible analytics query supporting multiple event types' which gives some context but doesn't clearly distinguish this tool from sibling analytics tools like query_events, query_funnels, or query_profiles. The purpose is understandable but lacks specificity.

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. With multiple query-related sibling tools (query_events, query_funnels, query_profiles, query_retention), there's no indication of what makes 'Insights report' different or when it's the appropriate choice. The mention of 'multiple event types' is too vague to serve as meaningful usage guidance.

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

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

No annotations are provided, so the description carries full burden. It states the tool queries and retrieves data, implying a read-only operation, but doesn't disclose behavioral traits like authentication requirements, rate limits, pagination behavior beyond the schema, or potential side effects. This leaves significant gaps for an agent to understand operational constraints.

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 short sentences that directly state the tool's function. It's front-loaded with the core purpose and avoids unnecessary details, though it could be slightly more structured by explicitly mentioning the API context upfront.

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 of a query tool with 5 parameters, no annotations, and no output schema, the description is incomplete. It lacks information on return values, error handling, or usage context, which is crucial for an agent to invoke the tool correctly without structured output guidance.

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

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

Schema description coverage is 100%, so the schema fully documents all 5 parameters. The description adds no additional meaning beyond the schema, such as examples of filter expressions or guidance on property selection. This meets the baseline of 3, as the schema handles parameter semantics adequately.

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 ('Query') and resource ('user profiles') with the specific API ('Engage API'), making the purpose evident. However, it doesn't explicitly differentiate this tool from sibling tools like 'query_events' or 'user_activity', which might also involve user data, leaving some ambiguity in sibling context.

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. It mentions filtering and retrieving user profile data but doesn't specify scenarios, prerequisites, or exclusions compared to other tools in the list, such as 'query_events' for event data or 'list_cohorts' for grouped users.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. While it indicates this is a query/analysis tool (implied read-only), it doesn't address important behavioral aspects: whether it requires specific permissions, how results are formatted, whether it's paginated, performance characteristics, or rate limits. For a complex analytical tool with 10 parameters, this leaves significant gaps in understanding how the tool behaves.

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

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

The description is extremely concise with just two sentences that directly state the tool's purpose. There's zero wasted language, and the most important information (what the tool does) comes first. The structure is front-loaded and efficient, with every word earning 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 complex analytical tool with 10 parameters, no annotations, and no output schema, the description is insufficient. It doesn't explain what the output looks like (tabular data? aggregated metrics?), doesn't address performance considerations for large date ranges, and doesn't provide context about retention analysis methodology. The combination of complexity and lack of structured metadata requires a more comprehensive description.

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

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

The schema description coverage is 100%, meaning all parameters are documented in the input schema. The description doesn't add any parameter-specific information beyond what's already in the schema. It mentions 'retention data' and 'initial event' which loosely map to some parameters, but provides no additional syntax, format, or usage details for the 10 parameters. This meets the baseline for high schema 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 the tool's purpose: 'Query retention data' with the specific function of 'Shows how many users come back after an initial event.' This provides a verb+resource combination that explains what the tool does. However, it doesn't explicitly differentiate this retention analysis tool from its sibling tools like query_events or query_insights, which prevents a perfect 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 provides no guidance on when to use this tool versus alternatives. With multiple query-related sibling tools (query_events, query_funnels, query_insights, query_profiles), there's no indication of when retention analysis is appropriate versus other analytical approaches. The description doesn't mention prerequisites, limitations, or comparison to other tools.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool runs scripts but doesn't cover critical aspects like authentication needs, rate limits, execution time, error handling, or data modification risks (e.g., whether it's read-only or can mutate data). This leaves significant gaps for safe and effective use.

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

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

The description is two sentences with zero waste: it directly states the tool's function and key capability. It's front-loaded and appropriately sized, making it easy to parse without unnecessary details.

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

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

Given the complexity of running custom scripts against data, lack of annotations, and no output schema, the description is incomplete. It doesn't address behavioral risks, return values, or integration with sibling tools, leaving the agent under-informed for a potentially powerful 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 100%, so the schema already documents both parameters (script and params). The description adds minimal value by implying 'complex custom queries' but doesn't elaborate on parameter usage, syntax, or examples beyond what the schema provides, meeting the baseline for high 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 the action ('Run a JQL script') and target ('against Mixpanel data'), with specificity about the query language. It distinguishes from siblings by mentioning 'complex custom queries,' which suggests capabilities beyond simpler query tools like query_events or query_funnels, though not explicitly named.

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_events or export_events. It mentions 'complex custom queries' but doesn't specify scenarios or prerequisites, leaving the agent to infer usage without explicit 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the tool is 'useful for tracking averages,' which implies a read-only, analytical function, but doesn't specify if it requires authentication, has rate limits, returns data in a specific format (e.g., time-series), or handles errors. This leaves gaps in understanding its operational 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 front-loaded with the core purpose in the first sentence and includes a concise second sentence for context. Both sentences earn their place by clarifying functionality and use cases without redundancy, making it efficient and well-structured.

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 (6 parameters, no annotations, no output schema), the description is adequate but incomplete. It covers the basic purpose and hints at usage, but lacks details on output format, error handling, or behavioral constraints, which are crucial for an agent to invoke it correctly without structured support.

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 100% description coverage, clearly documenting all 6 parameters. The description adds minimal value beyond the schema by implying the 'on' parameter is numeric and mentioning an example ('order value'), but doesn't provide additional syntax or usage details. This meets the baseline score since the schema does the heavy lifting.

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 the average of a numeric event property over time.' It specifies the verb ('Get the average') and resource ('numeric event property over time'), making it easy to understand. However, it doesn't explicitly differentiate from sibling tools like 'segmentation_sum' or 'query_insights' that might also involve event 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 implied usage guidance with 'Useful for tracking averages like order value,' suggesting contexts for application. However, it lacks explicit instructions on when to use this tool versus alternatives such as 'segmentation_sum' for sums or 'query_insights' for other metrics, and doesn't mention prerequisites 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?

With no annotations provided, the description carries full burden for behavioral disclosure. It states the tool returns a sum over time, which is helpful, but doesn't describe important behavioral aspects: whether results are aggregated, paginated, cached, or have rate limits; what format the output takes; or any authentication requirements. The description adds minimal behavioral context beyond the basic 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 appropriately concise with two sentences that get straight to the point. The first sentence states the core functionality, and the second provides a use case example. There's no wasted verbiage, though it could be slightly more structured with clearer separation of purpose and guidelines.

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

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

For a 6-parameter analytical tool with no annotations and no output schema, the description is insufficiently complete. It doesn't explain the return format, aggregation behavior, timezone handling, or how the 'unit' parameter affects bucketing. The example 'revenue' helps but doesn't compensate for missing behavioral and output context that an agent needs to use this tool 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?

Schema description coverage is 100%, so the schema already documents all 6 parameters thoroughly. The description adds no specific parameter information beyond what's in the schema - it doesn't explain parameter relationships, provide examples beyond 'revenue', or clarify how 'where' filters interact with the sum calculation. Baseline 3 is appropriate when schema does the heavy lifting.

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 the sum of a numeric event property over time' - a specific verb (get sum) and resource (numeric event property). It distinguishes from some siblings like 'segmentation_average' (average vs sum) but doesn't explicitly differentiate from all analytical tools like 'query_insights' or 'frequency_report'.

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

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

The description provides minimal usage guidance: 'Useful for tracking totals like revenue' gives a generic use case but offers no explicit when-to-use vs when-not-to-use instructions. No alternatives are mentioned, and there's no guidance on when to choose this tool over similar siblings like 'segmentation_average' or 'query_insights'.

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 full burden for behavioral disclosure. It mentions the time scope ('last day') and ranking behavior ('ranked by volume'), but lacks critical details like whether this is a read-only operation, potential rate limits, authentication requirements, or what happens if no events exist. For a tool with no annotation coverage, this is insufficient.

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 extremely concise—two sentences with zero waste. It front-loads the core purpose and efficiently adds output details. Every word earns its place, making it easy 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?

Given no annotations, no output schema, and 2 parameters with full schema coverage, the description is minimally adequate. It covers the basic purpose and output format but lacks behavioral context (e.g., safety, limits) and detailed usage guidelines. For a simple read tool, it meets the bare minimum but leaves 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 100%, so the schema fully documents both parameters ('type' with enum/default and 'limit'). The description adds no parameter-specific information beyond implying ranking by volume, which doesn't clarify parameter usage. Baseline 3 is appropriate when the schema does the heavy lifting.

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 the most common events over the last day. Returns event names ranked by volume.' It specifies the verb ('Get'), resource ('most common events'), time scope ('last day'), and output format ('ranked by volume'). However, it doesn't explicitly differentiate from sibling tools like 'query_events' or 'frequency_report', which prevents a perfect 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 provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'query_events' or 'frequency_report', nor does it specify prerequisites, exclusions, or appropriate contexts. The user must infer usage from the purpose alone.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions the tool 'Returns recent events for a specific user,' which implies a read-only operation, but doesn't cover critical aspects like authentication requirements, rate limits, pagination, error handling, or the format of the returned events. This leaves significant gaps for a tool with no annotation support.

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, consisting of two clear sentences that directly state the tool's purpose and output. There's no wasted verbiage, making it efficient for quick understanding, though it could be slightly more structured with bullet points or explicit sections for better readability.

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 (retrieving user activity data with three required parameters), lack of annotations, and no output schema, the description is incomplete. It fails to address behavioral aspects like authentication, rate limits, or return format, and doesn't provide usage guidelines relative to siblings. This leaves the agent under-informed for effective tool 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?

The input schema has 100% description coverage, clearly documenting all three required parameters (distinct_id, from_date, to_date). The description adds no additional parameter semantics beyond what's in the schema, such as explaining the meaning of 'distinct_id' or date format nuances. With high schema coverage, the baseline score of 3 is appropriate as the description doesn't compensate but also doesn't detract.

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 a specific verb ('Get') and resource ('user's activity stream'), and specifies what it returns ('recent events for a specific user'). However, it doesn't explicitly differentiate from sibling tools like 'query_events' or 'export_events', which might also retrieve event data, so it doesn't reach the highest 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 provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'query_events' or 'export_events', nor does it specify any prerequisites, exclusions, or contextual cues for usage, leaving the agent without clear direction.

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