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 tool returns data over time periods and has a default limit, but doesn't disclose critical behavioral traits: whether it's a read-only operation, potential rate limits, authentication needs, error conditions, or what the output format looks like (since no output schema exists). The description adds some context but leaves significant gaps for a tool with 10 parameters.

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 sized with two sentences. The first sentence front-loads the core functionality, and the second provides usage context. There's minimal waste, though the second sentence could be more specific about differentiation from siblings.

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 (10 parameters, no annotations, no output schema), the description is incomplete. It doesn't explain what the tool returns, error handling, or how it differs from similar sibling tools. For an analytics tool with significant parameter complexity, more behavioral and contextual information would be needed for an agent to 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 the schema already documents all 10 parameters thoroughly. The description adds marginal value by mentioning 'days, weeks, or months' (mapping to the 'unit' parameter) and 'unique, general, or average' (mapping to 'type'), but doesn't provide additional semantics beyond what's in the schema. 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 unique, general, or average data for a single event and property over days, weeks, or months.' It specifies the verb ('Get'), resource ('data for a single event and property'), and temporal scope. However, it doesn't explicitly differentiate from sibling tools like 'top_event_property_values' or 'query_segmentation_report', which appear related.

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

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

The description provides implied usage context: 'Useful for analyzing how specific properties affect event performance, segmenting users, and identifying valuable user attributes.' This suggests when to use it, but it doesn't explicitly state when NOT to use it or name alternatives among the many sibling tools. No prerequisites or exclusions are mentioned.

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 is for 'trend analysis' and 'time-series visualizations,' which hints at read-only, analytical use, but does not explicitly state whether it's read-only, its permissions, rate limits, or what the output format looks like (e.g., pagination, error handling). For a tool with 7 parameters and no 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 efficiently structured in two sentences: the first states the purpose, and the second provides usage context. It is front-loaded with key information and avoids unnecessary details, though it could be slightly more concise by integrating the two sentences more tightly.

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 lacks details on behavioral traits (e.g., read-only status, error conditions), output format, and explicit differentiation from sibling tools. While the schema covers parameters well, the description does not compensate for the absence of annotations and output schema, making it inadequate for full contextual 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?

The schema description coverage is 100%, meaning all parameters are well-documented in the input schema itself (e.g., 'event' as a JSON array, 'type' with enum values). The description adds minimal value beyond the schema by mentioning 'unique, general, or average data' (which aligns with the 'type' enum) and 'over N days, weeks, or months' (hinting at 'interval' and 'unit'), but does not provide additional syntax or format details. 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 unique, general, or average data for a set of events over N days, weeks, or months.' It specifies the verb ('Get'), resource ('data for a set of events'), and scope ('over N days, weeks, or months'), but does not explicitly differentiate it from sibling tools like 'query_segmentation_report' or 'query_insights_report', which may also involve event data 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 by stating it's 'Useful for trend analysis, comparing event performance over time, and creating time-series visualizations.' However, it does not explicitly mention when to use this tool versus alternatives among the many sibling tools (e.g., 'query_frequency_report' or 'get_top_events'), nor does it specify any 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions the tool runs scripts for 'complex custom analyses' and 'advanced data transformations,' which hints at potential computational intensity or data mutation, but doesn't specify execution limits, permissions required, error handling, or output format. For a tool that executes custom code against data with no annotation coverage, this leaves significant gaps in understanding its behavior and risks.

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 long, front-loaded with the core purpose and followed by usage context. Every word earns its place: the first sentence defines the tool, and the second explains its utility without redundancy. It's efficiently structured and avoids unnecessary elaboration, 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 the tool's complexity (executing custom code against data), lack of annotations, and no output schema, the description is incomplete. It doesn't address critical aspects like what the output looks like (e.g., JSON structure, error responses), execution limits (e.g., timeouts, data size), or security implications (e.g., script validation). For a powerful, open-ended tool with no structured behavioral data, the description should provide more guidance to ensure safe and effective use.

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

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

The input schema has 100% description coverage, with clear documentation for all four parameters (e.g., 'script' as 'JavaScript code that uses Mixpanel's JQL functions'). The description adds no additional parameter details beyond what the schema provides, such as examples or constraints. Given the high schema coverage, a baseline score of 3 is appropriate, as the schema adequately handles parameter semantics without extra help from 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: 'Run a custom JQL (JSON Query Language) script against your Mixpanel data.' It specifies the verb ('run'), resource ('JQL script'), and target ('Mixpanel data'), making the function unambiguous. However, it doesn't explicitly differentiate this from sibling tools like 'query_funnel_report' or 'query_retention_report', which also query Mixpanel data but through standard reports rather than custom scripts.

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

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

The description provides clear context for when to use this tool: 'Useful for complex custom analyses, advanced data transformations, and queries that can't be handled by standard report types.' This implies it should be used instead of sibling tools like 'query_funnel_report' when standard reports are insufficient. However, it doesn't explicitly name alternatives or state when not to use it, such as for simple queries better suited to standard 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 full burden for behavioral disclosure. It mentions the tool is for 'real-time user activity' monitoring, which implies freshness of data, but doesn't disclose critical behavioral traits like rate limits, authentication requirements, error conditions, or what format the results return. The description adds some context about use cases but lacks operational transparency needed for a tool with no annotation coverage.

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 sized with two sentences. The first sentence states the core purpose, and the second provides usage context. Both sentences earn their place by adding value. It's front-loaded with the main function. Could be slightly more structured but efficiently conveys key information without waste.

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 3 parameters with full schema coverage but no annotations and no output schema, the description provides adequate purpose and usage context but lacks completeness about behavioral aspects. For a data retrieval tool with multiple parameters and no output schema, the description should ideally mention something about return format or data structure. It's minimally viable but has clear gaps in operational transparency.

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 three parameters (limit, project_id, type) with descriptions and enum values. The description adds no parameter-specific information beyond what's in the schema. 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: 'Get today's top events from Mixpanel' with specific verb ('Get') and resource ('today's top events'). It distinguishes from siblings like 'get_top_events' by specifying 'today's' scope. However, it doesn't fully differentiate from other event-related tools like 'aggregate_event_counts' or 'top_event_properties' beyond the temporal focus.

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

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

The description provides implied usage context: 'Useful for quickly identifying the most active events happening today, spotting trends, and monitoring real-time user activity.' This suggests when to use it (for real-time monitoring and trend spotting), but doesn't explicitly state when NOT to use it or name alternatives among the many sibling tools. No explicit exclusions or comparisons 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. While it mentions the 31-day time window and general purpose, it fails to describe key behavioral traits: whether this is a read-only operation, what the output format looks like (e.g., list structure, pagination), or any rate limits or authentication requirements. For a tool with no annotation coverage, this leaves significant gaps in understanding how it 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 efficiently structured in two sentences: the first states the core functionality, and the second provides usage context. Every sentence earns its place by adding value—no redundancy or fluff. It's appropriately sized and front-loaded with the main 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's moderate complexity (3 parameters, no output schema, no annotations), the description is partially complete. It covers the purpose and usage context well but lacks details on behavioral traits (e.g., output format, safety profile) and doesn't leverage the absence of an output schema to explain return values. For a tool with no annotations, it should do more to compensate, but it meets a minimum viable threshold.

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, with clear documentation for all three parameters (limit, project_id, type). The description adds no additional parameter semantics beyond what's in the schema—it doesn't explain parameter interactions, default values, or usage examples. Since the schema does the heavy lifting, the baseline score of 3 is appropriate, but the description doesn't enhance parameter understanding.

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 list of the most common events over the last 31 days.' It specifies the verb ('Get'), resource ('most common events'), and time scope ('last 31 days'), making it easy to understand what the tool does. However, it doesn't explicitly differentiate from sibling tools like 'get_today_top_events' or 'aggregate_event_counts', 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 implied usage guidance by stating the tool is 'useful for identifying key user actions, prioritizing feature development, and understanding overall platform usage patterns.' This suggests appropriate contexts for use. However, it lacks explicit guidance on when to choose this tool over alternatives like 'get_today_top_events' (for today's data) or 'aggregate_event_counts' (for custom date ranges), which would be needed for a higher score.

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' certain tasks, but doesn't describe key behaviors like whether it returns all cohorts at once (pagination?), what format the output is in, or any authentication/rate limit considerations. The description adds minimal behavioral context beyond the basic purpose.

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, starting with the core purpose in the first sentence. The second sentence adds value by explaining use cases without redundancy. It could be slightly more structured (e.g., bullet points for use cases), but overall it's efficient with minimal waste.

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 (list operation with 2 optional parameters), no annotations, and no output schema, the description is partially complete. It covers the purpose and use cases adequately, but lacks details on output format, pagination, error handling, or behavioral constraints. For a read-only list tool, this is a minimal viable description with clear 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 already documents both parameters ('project_id' and 'workspace_id') with descriptions. The tool description adds no parameter-specific information beyond what's in the schema, such as explaining how these IDs are obtained or their relationships. Baseline 3 is appropriate when the schema handles parameter documentation.

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 all cohorts in a given project.' It specifies the verb ('Get') and resource ('cohorts'), and distinguishes it from siblings by focusing on cohorts rather than events, funnels, or reports. However, it doesn't explicitly differentiate from similar list tools like 'list_saved_funnels' beyond the resource type.

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

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

The description provides implied usage through phrases like 'Useful for discovering user segments, planning targeted analyses, and retrieving cohort IDs for filtering in other reports.' This gives context for when to use it, but lacks explicit guidance on when to choose this tool over alternatives (e.g., vs. querying profiles directly) or any exclusions. No sibling-specific comparisons are made.

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 describes the tool's purpose and usage context well, but doesn't disclose behavioral traits like whether it requires authentication, rate limits, pagination behavior, or what happens if no funnels exist. For a read operation with no annotation coverage, it provides basic context but lacks operational details.

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 sentences, zero waste. First sentence states purpose, second provides usage guidance. Every sentence earns its place by adding distinct value. Appropriately sized and front-loaded with the core functionality.

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 2 optional parameters and no output schema, the description provides good purpose and usage context. However, without annotations or output schema, it could better explain what the return format looks like (e.g., list of objects with name/id fields) and any authentication requirements. It's mostly complete but has minor 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 already fully documents both parameters. The description doesn't add any parameter-specific information beyond what's in the schema. With high schema coverage, baseline 3 is appropriate as the description doesn't compensate but doesn't need to.

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

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

The description clearly states the verb ('Get') and resource ('names and IDs of your saved funnels'), and distinguishes from siblings by specifying it's for discovering funnels and retrieving IDs needed for query_funnel_report. It's specific and differentiates from other list/query tools.

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

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

Explicitly states when to use: 'Useful for discovering available funnels for analysis and retrieving funnel IDs needed for the query_funnel_report tool.' This provides clear context and names a specific alternative tool (query_funnel_report) for different purposes.

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 the tool is 'useful for' certain analyses but doesn't disclose critical behavioral traits: whether this is a read-only operation, what permissions are needed, whether it has rate limits, what format the returned data takes, or if there are pagination considerations. The description adds some context about use cases but lacks operational details.

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. The first sentence states the core purpose, and the second provides use case context. Both sentences earn their place by adding value. However, it could be slightly more front-loaded with the most critical operational 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 has 5 parameters, no annotations, and no output schema, the description is incomplete. It doesn't address what the tool returns, how results are structured, or important behavioral constraints. For a data retrieval tool with multiple parameters and no structured output documentation, the description should provide more complete operational context.

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 fully documents all 5 parameters. The description doesn't add any parameter-specific information beyond what's in the schema. It mentions 'profile' which relates to 'distinct_ids' but doesn't provide additional semantic context about parameter relationships 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: 'Get data for a profile's event activity.' It specifies the resource (profile's event activity) and verb (get data). However, it doesn't explicitly differentiate from sibling tools like 'query_profiles' or 'aggregate_event_counts' that might also involve profile or event data.

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

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

The description provides implied usage context: 'Useful for understanding individual user journeys, troubleshooting user-specific issues, and analyzing behavior patterns of specific users.' This suggests when to use it (for individual user analysis), but doesn't explicitly state when not to use it or name alternatives among the many sibling 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 full burden for behavioral disclosure. It states the tool 'gets data' which implies a read-only operation, but doesn't specify authentication requirements, rate limits, pagination behavior, or what the return format looks like (especially critical since there's no output schema). For a 10-parameter query tool with complex filtering, this is a significant gap in behavioral context.

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

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

The description is appropriately concise with two sentences that efficiently state the purpose and use cases. It's front-loaded with the core function ('Get data for frequency of actions over time') followed by specific applications. No wasted words, though it could be slightly more structured with bullet points for the use cases.

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

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

For a complex 10-parameter query tool with no annotations and no output schema, the description is insufficient. It doesn't explain what the return data looks like (tabular? aggregated counts?), how results are structured, or provide examples of typical queries. The description should compensate for the lack of output schema by describing the return format, but doesn't.

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 10 parameters thoroughly. The description adds no specific parameter information beyond what's in the schema - it doesn't explain relationships between parameters like 'unit' and 'addiction_unit', or provide examples for the complex 'where' expression. 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 as 'Get data for frequency of actions over time' with specific use cases like analyzing user action frequency, identifying behavior patterns, and tracking engagement. It provides a verb ('Get') and resource ('data for frequency of actions'), but doesn't explicitly distinguish it from sibling tools like 'aggregate_event_counts' or 'query_segmentation_report' that might also involve frequency or time-based 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 includes 'Useful for analyzing how often users perform specific actions...' which implies usage context, but provides no explicit guidance on when to use this tool versus alternatives like 'aggregate_event_counts' or 'query_segmentation_report'. There are no when-not-to-use statements, prerequisites, or named alternatives mentioned.

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's purpose and prerequisite but lacks details on behavioral traits such as rate limits, authentication needs, response format, or error handling. The description adds some context about use cases but does not fully compensate for the absence of annotations, leaving gaps 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 appropriately sized and front-loaded, with the core purpose stated first: 'Get data for a funnel based on a funnel_id.' The subsequent sentences add useful context without redundancy. Every sentence earns its place by clarifying use cases and prerequisites, 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 (9 parameters, no annotations, no output schema), the description is adequate but incomplete. It covers the purpose, use cases, and a prerequisite, but lacks details on behavioral aspects, response format, or error handling. Without annotations or output schema, more context would be needed for full completeness, but it meets a minimum viable 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 schema description coverage is 100%, meaning all parameters are documented in the input schema. The description does not add any parameter-specific information beyond what the schema provides (e.g., it doesn't explain parameter interactions or provide examples). Thus, it meets the baseline score of 3, as the schema handles the heavy lifting without extra value from 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: 'Get data for a funnel based on a funnel_id.' It specifies the verb ('Get data') and resource ('a funnel'), and distinguishes it from siblings by mentioning the prerequisite tool 'list_saved_funnels' for obtaining funnel IDs, which sets it apart from other query/report tools like query_frequency_report or query_insights_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 clear context for when to use this tool: 'Useful for analyzing user conversion paths, identifying drop-off points in user journeys, and optimizing multi-step processes.' It also explicitly states a prerequisite: 'Funnel IDs should be retrieved using the list_saved_funnels tool.' However, it does not specify when not to use it or name alternatives among siblings, which prevents a perfect score.

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 tool retrieves data from saved reports but doesn't disclose behavioral traits like whether it's read-only, requires authentication, has rate limits, returns paginated results, or what format the data comes in. For a data retrieval tool 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 appropriately sized (two sentences) and front-loaded with the core purpose. The second sentence adds useful context about use cases without being verbose. Every sentence earns its place, though it could be slightly more 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 (data retrieval with 3 parameters), lack of annotations, and no output schema, the description is incomplete. It doesn't explain what the returned data looks like, error conditions, or important behavioral constraints. For a query tool in a crowded namespace, more context is needed.

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 three parameters. The description doesn't add any parameter-specific information beyond what's in the schema (e.g., it doesn't explain what an 'Insights report' is or how to find bookmark_id). 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 data from your Insights reports' (verb+resource). It distinguishes from siblings by specifying 'Insights reports' rather than events, funnels, or profiles, though it doesn't explicitly contrast with similar tools like query_frequency_report or query_funnel_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 implied usage context: 'Useful for accessing saved analyses, sharing standardized metrics across teams, and retrieving complex pre-configured visualizations.' This suggests when to use it (for saved/pre-configured reports) but doesn't explicitly state when not to use it or name alternatives among the many sibling query 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 mentions the tool is for 'querying' and 'retrieving,' which implies read-only behavior, but doesn't explicitly state whether it's safe, requires authentication, has rate limits, or what format the results return. For a tool with 13 parameters and no output schema, this leaves significant behavioral gaps unaddressed.

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, stating the core purpose in the first sentence. The second sentence elaborates on use cases without redundancy. Both sentences earn their place by clarifying intent and utility, 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 complexity (13 parameters, no annotations, no output schema), the description is incomplete. It doesn't explain what the tool returns, how results are structured, or any behavioral constraints like pagination or error handling. For a query tool with many options and no structured output documentation, this leaves the agent with insufficient context to 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?

The schema description coverage is 100%, meaning all 13 parameters are documented in the input schema itself. The description adds no specific parameter information beyond the generic mention of 'filtering options.' Since the schema does the heavy lifting, the baseline score of 3 is appropriate—the description doesn't add value here but doesn't need to compensate for gaps.

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 Mixpanel user profiles with filtering options.' It specifies the resource (user profiles) and action (query with filtering). However, it doesn't explicitly differentiate this from sibling tools like 'profile_event_activity' or 'list_saved_cohorts', which likely work with similar Mixpanel data but serve different purposes.

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 some implied usage context by mentioning it's 'useful for retrieving detailed user profiles, filtering by specific properties, and analyzing user behavior across different dimensions.' This suggests when to use it, but it doesn't explicitly state when NOT to use it or name alternatives among the sibling tools. For example, it doesn't clarify when to use this versus 'profile_event_activity' for user behavior analysis.

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. While it mentions the parameter constraint (interval/unit exclusivity), it doesn't describe important behavioral aspects: whether this is a read-only operation, potential data volume/performance implications, authentication requirements, rate limits, or what the output format looks like. For a complex 14-parameter reporting tool, 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 efficiently structured in two sentences: one stating the purpose and use cases, another providing a critical parameter constraint. Every sentence earns its place, though it could be slightly more front-loaded by leading with the parameter constraint for immediate usability.

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 14-parameter reporting tool with no annotations and no output schema, the description is insufficient. It doesn't explain what data format to expect, how results are structured, whether there are pagination considerations, or what authentication context is required. The description should provide more context about the tool's behavior and output expectations.

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 14 parameters thoroughly. The description adds minimal value beyond the schema - only the interval/unit exclusivity rule. It doesn't explain parameter relationships, provide examples, or clarify how parameters like 'born_event' and 'retention_type' interact in practice. 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 data from your Retention reports' with specific use cases like analyzing user engagement and measuring product stickiness. It distinguishes from siblings by focusing on retention reports, but doesn't explicitly differentiate from similar reporting tools like query_frequency_report or query_funnel_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 some usage guidance with 'Only use params interval or unit, not both' which helps avoid parameter conflicts. However, it doesn't explain when to choose this tool over sibling reporting tools like query_funnel_report or query_insights_report, nor does it provide context about when retention analysis is appropriate versus other report types.

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's function but lacks critical details: it doesn't specify whether this is a read-only operation, what permissions are required, how results are returned (e.g., format, pagination), or any rate limits. For a complex 8-parameter tool with no 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 efficiently structured in two sentences: the first states the core purpose, and the second provides usage examples. There's no wasted verbiage, and it's front-loaded with the key functionality. However, it could be slightly more concise by integrating the examples more tightly.

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 (8 parameters, no annotations, no output schema), the description is incomplete. It adequately explains the purpose but fails to address behavioral aspects like safety, permissions, or result format. For a tool performing data aggregation with multiple inputs, more context is needed to ensure proper agent 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?

The schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds marginal value by clarifying that the expression should be numeric and mentioning 'per unit time' (hinting at the 'unit' parameter), but it doesn't provide additional syntax, format, or constraint details beyond what the schema provides. 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: 'Averages an expression for events per unit time' with specific examples like purchase amounts and session durations. It distinguishes from siblings by focusing on averaging rather than counting, summing, or other aggregation types, though it doesn't 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 implies usage context with 'Useful for calculating average values... and tracking how these averages change over time,' suggesting temporal analysis applications. However, it doesn't provide explicit guidance on when to choose this tool over similar siblings like query_segmentation_sum or query_segmentation_bucket, nor does it 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It describes the tool's function but lacks critical behavioral details: it doesn't mention whether this is a read-only operation, what permissions might be required, how results are returned (e.g., pagination, format), rate limits, or error conditions. For a complex query tool with 9 parameters, 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 appropriately concise with two sentences: the first states the core functionality, and the second provides usage context. It's front-loaded with the main purpose. However, the second sentence could be slightly more specific to avoid generic phrasing like 'useful for analyzing distributions.'

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 (9 parameters, no annotations, no output schema), the description is minimally adequate. It covers the purpose and hints at usage but lacks behavioral transparency and output details. Without annotations or an output schema, the description should do more to explain what the tool returns and any operational constraints, but it falls short of being complete for such a multifaceted 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 100%, so the schema already documents all parameters thoroughly. The description adds some context by mentioning 'segmented and filtered by properties' and 'numeric buckets,' which aligns with parameters like 'on' (numeric property for segmentation) and 'where' (filtering), but doesn't provide additional syntax or format details beyond what the schema provides. 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 data for an event, segmented and filtered by properties, with values placed into numeric buckets.' It specifies the verb ('Get'), resource ('data for an event'), and key operations (segmentation, filtering, bucketing). However, it doesn't explicitly differentiate from sibling tools like 'query_segmentation_average' or 'query_segmentation_sum', which appear related but have different analysis types.

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 by stating it's 'Useful for analyzing distributions of numeric values, creating histograms, and understanding the range of quantitative metrics.' This suggests when to use it (for distribution analysis), but doesn't explicitly state when not to use it or name alternatives among the sibling tools. No prerequisites or exclusions are mentioned.

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. While it mentions the tool's utility for segmentation and filtering, it doesn't describe important behavioral aspects such as: whether this is a read-only operation, what format the data returns in (beyond the optional 'csv' parameter), whether there are rate limits, authentication requirements, or what happens with large datasets. The description adds some context about use cases but lacks critical operational details.

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 efficiently structured in two sentences. The first sentence clearly states the core functionality, and the second sentence provides useful context about applications. There's no wasted verbiage or redundancy, though it could be slightly more front-loaded with explicit differentiation from sibling tools.

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 (12 parameters, 4 required), lack of annotations, and no output schema, the description is moderately complete. It explains what the tool does and suggests use cases, but it doesn't address behavioral aspects like data format, performance characteristics, or error handling. For a tool with this many parameters and no structured safety hints, the description should provide more operational guidance to be fully complete.

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

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

The description doesn't mention any specific parameters, but the input schema has 100% description coverage with detailed parameter documentation. The baseline score of 3 is appropriate since the schema does the heavy lifting of explaining parameters like 'event', 'on', 'where', 'type', etc. The description's mention of 'segmented and filtered by properties' loosely maps to parameters like 'on' and 'where' but adds minimal semantic value beyond what's already in the schema.

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

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

The description clearly states the tool's purpose: 'Get data for an event, segmented and filtered by properties.' It specifies the verb ('Get'), resource ('data for an event'), and key operations ('segmented and filtered by properties'). However, it doesn't explicitly differentiate from sibling tools like query_segmentation_average or query_segmentation_sum, which appear to be related segmentation tools.

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

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

The description provides implied usage context with phrases like 'Useful for breaking down event data by user attributes, comparing performance across segments, and identifying which user groups perform specific actions.' This suggests when the tool might be valuable, but it doesn't explicitly state when to use this tool versus alternatives like query_segmentation_average or query_frequency_report, nor does it mention any 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. While it mentions the tool sums numeric expressions over time, it doesn't describe critical behaviors: whether this is a read-only operation, what permissions are required, how results are formatted (e.g., time-series data), if there are rate limits, or error conditions. The description adds minimal 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 sized with two sentences. The first sentence states the core purpose, and the second provides usage examples. There's no wasted text, and it's front-loaded with the essential function. However, it could be slightly more structured by explicitly separating purpose from 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?

Given the tool's complexity (8 parameters, no output schema, no annotations), the description is moderately complete. It covers the basic purpose and usage examples but lacks behavioral details (e.g., output format, error handling) and explicit differentiation from siblings. For a tool with rich parameter documentation but no other structured context, this leaves gaps in guiding 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?

Schema description coverage is 100%, so the schema already documents all 8 parameters thoroughly. The description doesn't add any parameter-specific information beyond what's in the schema (e.g., it doesn't explain the 'on' parameter's syntax or provide examples for the 'where' expression). 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: 'Sum a numeric expression for events over time.' It specifies the verb ('sum'), resource ('numeric expression for events'), and scope ('over time'). However, it doesn't explicitly differentiate from sibling tools like query_segmentation_average or query_segmentation_bucket, which likely perform different aggregation functions on similar data.

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

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

The description provides implied usage guidance through examples: 'Useful for calculating revenue metrics, aggregating quantitative values, and tracking cumulative totals across different time periods.' This suggests appropriate contexts but doesn't explicitly state when to use this tool versus alternatives like query_segmentation_average (for averages) or query_segmentation_bucket (for bucketing). No exclusions or prerequisites are mentioned.

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 describes the tool's purpose and usefulness but lacks details on behavioral traits like authentication requirements, rate limits, error handling, or what the output looks like (e.g., format, ordering). For a tool with no annotations, this leaves significant gaps in understanding how it 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 concise and front-loaded, starting with the core purpose ('Get the top property names for an event.') followed by usefulness context. Both sentences earn their place by clarifying intent and application, with no wasted words, though it could be slightly more structured for clarity.

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

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

Given the complexity of a data analysis tool with 4 parameters, no annotations, and no output schema, the description is incomplete. It lacks details on output format, behavioral constraints, and explicit differentiation from siblings. While it covers purpose and usage context, it doesn't provide enough information for an agent to fully understand how to use the tool effectively in practice.

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%, so the input schema already documents all parameters well. The description doesn't add any parameter-specific semantics beyond what's in the schema, such as explaining 'event' beyond being a single name or 'limit' beyond its default. With high schema coverage, the baseline score of 3 is appropriate, as the description doesn't compensate but doesn't need to heavily.

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 top property names for an event.' It specifies the verb ('Get') and resource ('top property names for an event'), making it easy to understand. However, it doesn't explicitly differentiate from its sibling 'top_event_property_values' (which returns values rather than names), leaving some ambiguity.

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

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

The description provides implied usage guidelines by stating it's 'Useful for discovering which properties are most commonly associated with an event, prioritizing which dimensions to analyze, and understanding event structure.' This gives context on when to use it, but it doesn't explicitly mention when not to use it or name alternatives among the sibling tools, such as 'top_event_property_values' for property values instead of names.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions the tool is 'useful for understanding distribution' and 'planning further analyses,' which implies it's a read-only operation, but doesn't explicitly state this, nor does it cover permissions, rate limits, or response format. The description adds some context about use cases but lacks critical behavioral details for a tool with 5 parameters.

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 sized with two sentences: the first states the purpose, and the second explains use cases. It's front-loaded with the core function and avoids unnecessary details, though it could be slightly more concise by integrating the use cases more tightly.

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 (5 parameters, no annotations, no output schema), the description is minimally adequate. It covers the purpose and use cases but lacks details on behavioral traits, output format, and explicit sibling differentiation. It's complete enough for basic understanding but leaves gaps for effective agent invocation without additional context.

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 5 parameters (event, limit, name, project_id, workspace_id) with descriptions. The description adds no specific parameter semantics beyond what's in the schema, such as explaining property name constraints or event selection criteria. 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 top values for a property.' It specifies the verb ('Get') and resource ('top values for a property'), and distinguishes it from siblings like 'top_event_properties' by focusing on values rather than properties themselves. However, it doesn't explicitly differentiate from tools like 'query_segmentation_report' that might also analyze property distributions.

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

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

The description provides implied usage context: 'Useful for understanding the distribution of values for a specific property, identifying the most common categories or segments, and planning further targeted analyses.' This suggests when to use it (for exploratory data analysis), but it doesn't explicitly state when not to use it or name alternatives among the many sibling tools, such as 'aggregated_event_property_values' or 'query_segmentation_report'.

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