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

With no annotations, the description carries the full burden. It discloses that it reads .env and scans transactions, which goes beyond a generic 'discover' label. It also specifies the return format as a JSON string with apps and count. While it doesn't mention side effects or permissions, the behavior described is transparent for a read-only discovery 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 concise and well-structured: it opens with the primary purpose, explains the method, gives guidance on usage, and then describes the return payload. Every sentence adds value, and there is no fluff or repetition.

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

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

Given the tool has no parameters, an output schema is present, and it is a foundational discovery tool among analytics-focused siblings, the description fully covers the necessary context. It explains what it does, how it works, and why the output is needed, making it complete for an agent to select and invoke it correctly.

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

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

The tool has zero parameters, and schema coverage is 100% (trivially). The description explains what the tool does without needing to describe parameter semantics, which is appropriate. It does not add parameter-specific details, but none are needed.

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: 'Discover all Shopify apps in your partner account.' It explains the method (checks .env config and scans transactions) and distinguishes itself from siblings by noting the returned IDs should be used with all other tools. This is specific and unambiguous.

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

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

The description explicitly instructs to 'use these IDs for all other tools,' which informs when this tool should be used (as a discovery prerequisite). However, it does not explicitly mention sibling alternatives or situations where this tool should not be used, though the purpose is clear enough.

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

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

With no annotations, the description carries the full burden. It discloses the return format (JSON string) and the accepted period values, which is useful. However, it does not mention permissions, rate limits, side effects, or limitations. Since the operation is clearly read-only, the omission is a minor 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 and well-structured: the purpose is stated in the first sentence, followed by the argument and return format. Every sentence provides value with no redundancy or excess length.

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

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

The tool is simple (one optional parameter), and the description covers its purpose and parameter format. An output schema exists, so detailed return fields are predefined. Missing details like timezone handling or default behavior are minor given the straightforward scope.

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 only defines period as a string with a default, but the description enriches it with the exact allowed values ('7d', '30d', '90d', '1y', or a date range) and the return format. This fully compensates for the 0% schema description coverage.

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

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

The description clearly states 'Compare metrics across all your Shopify apps side by side,' using a specific verb (compare) and resource (metrics across all apps). This distinguishes it from siblings like get_app_details (single app) and get_churn_analysis (churn-specific).

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

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

The description implies the use case—comparing metrics across all apps—but does not explicitly mention alternatives or when not to use this tool. There is no comparison to sibling tools or prerequisites, so guidance is implicit rather than explicit.

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 discloses the return format ('JSON string with app name, API key, and GID') and the input format, but does not mention error handling (e.g., invalid ID), authentication requirements, or explicitly confirm read-only semantics, though 'Get' implies it. This is adequate for a simple read operation but leaves some gaps.

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 highly concise and well-structured: a one-line purpose summary followed by explicit Args and Returns sections. Every sentence contributes valuable information without any filler, and the front-loaded purpose ensures quick understanding.

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 low complexity (single required parameter, simple read operation) and the presence of an output schema (per context signals), the description is nearly complete. It specifies the input format, the output fields, and the scope ('specific app'). It could mention error behavior or permissions, but these are less critical for a simple get-by-id tool.

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

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

The input schema only defines app_id as a string with no description, but the Args section in the description fully compensates by explaining it accepts either a GID (with a concrete example) or a numeric ID. This adds meaning far beyond the schema and makes the parameter's format and valid values clear.

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

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

The description clearly states it retrieves details for a specific Shopify app, using the verb 'Get' and a distinct resource ('details for a specific Shopify app'). The listed return fields (app name, API key, GID) differentiate this from sibling aggregate/comparison tools like get_app_comparison or get_app_events, making its purpose unmistakable.

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 usage context is implied by the phrase 'specific Shopify app' (use when you need details for one app), but there is no explicit guidance on when to use this tool versus alternatives, nor any mention of when not to use it. No alternative tools are named, so the guidance is only implied.

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

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

No annotations are provided, so the description carries the full burden. It discloses the return format ('JSON string with keys: events (list with type, shop, date), count, app_id'), enumerates all valid event type values, and mentions the default limit. This is solid transparency, though it does not discuss error handling, authentication, or pagination 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 well-structured with 'Args' and 'Returns' sections, lists the event types compactly, and contains no filler. It is appropriately detailed without being bloated, making it easy to scan and parse.

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

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

The description covers all parameters and return shape, which is sufficient for a read-only event listing operation. It does not mention pagination or how this tool relates to other app-level analytics tools, but given that it has no annotations and a simple schema, this is a minor gap.

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

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

The input schema has no descriptions, but the description compensates fully by explaining every parameter: app_id, event_types with the complete list of allowed values, date_from and date_to with format, and limit with default. This gives the agent everything needed to construct correct arguments.

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 begins with 'Get app events (installs, uninstalls, charges, etc.) for a specific app,' which uses a specific verb and resource and clearly distinguishes this tool from sibling analytics tools like get_transactions or get_revenue_summary. The scope is unambiguous: events for a single app.

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 clearly implies when to use the tool: to retrieve events for a specific app, with optional filters by event type and date range. It does not explicitly mention alternatives or when-not-to-use, but the context is clear enough for an agent to select it appropriately among siblings.

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

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

With no annotations, the description carries the full burden. It discloses the return value: 'JSON string with period summary, comparison to previous period, highlights, new installs, and recent churns.' This is helpful, but it omits details like error handling, custom range formatting, or any rate limits. It gives enough to understand the output but not deeper behavioral traits.

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

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

The description is well-structured: a one-sentence purpose, followed by Args and Returns sections. Every sentence adds value, with no fluff. The format is front-loaded and easily parseable.

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

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

The tool is moderately simple (2 params, output schema present). The description covers purpose, all parameters, and return format. It lacks error scenarios or prerequisites, but for a read-only digest tool this is sufficient. Given the sibling tools, it could mention when to use this digest vs more focused tools, but overall it is complete enough.

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

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

The schema has no parameter descriptions (0% coverage), so the description compensates fully. It explains app_id as 'App GID or numeric ID (required)' and period as '7d' (weekly), '30d' (monthly), or custom range.' This adds concrete meaning beyond the schema's minimal title and default fields.

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

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

The description clearly states the tool's purpose: 'Get a business digest with key metrics and highlights.' This is a specific verb+resource combination. However, it does not explicitly distinguish this from sibling tools like get_revenue_summary or get_churn_analysis, though the 'digest' framing implies a combined overview.

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 gives parameter usage (app_id and period) but no context on scenarios where this digest is preferred over get_revenue_summary or get_churn_analysis. There are no explicit exclusions or alternative tool references.

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 burden. It does state that the return is a JSON string and lists the returned metrics, which is useful, but it does not mention error behavior, authentication, rate limits, or whether the operation is read-only (implied by 'Get'). Since the output schema already covers the return format, this adds minimal 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 concise and well-structured: a one-line summary followed by explicit Args and Returns sections. No wasted words, and the most important 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 simple two-parameter read tool, the description covers the purpose, parameter formats, and return type. It is sufficiently complete for an agent to invoke the tool correctly, though it lacks contextual guidance on when to use it relative to siblings. The presence of an output schema reduces the need to detail return values.

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

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

Schema description coverage is 0%, so the description's Args section is essential. It explains that app_id accepts 'App GID or numeric ID' and is required, and it enumerates valid period values ('7d', '30d', '90d', '1y', or a date range). This adds substantial meaning beyond the bare schema titles.

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

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

The description opens with 'Get churn metrics: revenue churn %, logo churn %, uninstall reasons,' which clearly states the exact purpose and specific output fields. This distinguishes it from sibling tools like get_churn_risk and get_churned_merchants by naming distinct metrics.

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

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

There is no guidance on when to use this tool versus alternatives. Sibling tools such as get_churn_risk and get_retention_cohorts are related, but the description does not mention when to choose this over those or any 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 must be self-reliant. It discloses the return format (JSON string with specific fields) and that results are sorted most recent first, which is valuable. However, it does not explicitly state that this is a safe, read-only operation, nor does it mention any permissions or limitations. Since 'get' implies read-only, this is adequate but not fully transparent.

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 compact and well-structured, breaking naturally into action, args, and returns. Every sentence adds necessary information without redundancy. It is appropriately sized for the tool's simplicity and is front-loaded with the core purpose.

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

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

Given the tool's low complexity (2 parameters) and the presence of an output schema, the description covers the essential aspects: purpose, arguments, and return format with sorting. It lacks explicit mention of pagination, limit sizes, or error conditions, but for a straightforward 'get' operation this is sufficient. The description is nearly complete, missing only optional edge-case behavior.

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

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

The input schema has zero descriptions, so the description fully compensates by explaining both parameters: app_id is a required App GID or numeric ID, and days is an optional look-back period with a default of 30. This adds clear meaning beyond the raw schema types and is especially valuable given the 0% schema description coverage.

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

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

The description begins with 'Get recently churned merchants with uninstall reasons,' which clearly states the action (get), the resource (recently churned merchants), and a distinctive detail (uninstall reasons). This differentiates it from sibling tools like get_churn_analysis or get_churn_risk, making the purpose unmistakable.

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

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

The description gives a clear context for what the tool does and what arguments are needed, so an agent can infer when to use it (when a list of churned merchants with reasons is required). However, it does not explicitly mention alternatives or state when not to use this tool, which keeps it at an 'implied usage' level rather than providing explicit 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?

With no annotations, the description carries the full burden and does well by disclosing heuristic signals (deactivation events, subscription cancellations, etc.) and the exact return structure (JSON string with risk summary and grouped merchant lists). It does not mention side effects or permissions, but the read-only nature is implied.

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

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

The description is well-structured with clear sections for purpose, args, heuristic signals, and returns. Every sentence adds value, and it is appropriately concise without extraneous detail.

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

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

Given the tool's simplicity (one parameter), the description covers the main aspects: purpose, input, behavior, and output. It does not explicitly differentiate from get_churn_analysis or get_churned_merchants, which slightly reduces completeness, but overall it is sufficiently self-contained.

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

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

Schema description coverage is 0%, and the description compensates by explaining that app_id can be 'App GID or numeric ID', adding meaning beyond the bare schema property. It clearly labels the parameter as required and gives a brief but useful type clarification.

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

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

The description starts with a clear verb and resource: 'Score active merchants by churn risk' and specifies the output levels (low/medium/high). It is specific but does not explicitly differentiate from sibling tools like get_churn_analysis or get_churned_merchants.

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

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

No guidance is given on when to use this tool versus alternatives. There is no mention of suitable conditions, exclusions, or references to sibling tools. The description simply states what it does without contextual usage advice.

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

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

No annotations are provided, so the description carries the full burden. It discloses the return format (JSON string with totals, giveback percentage, transaction details) and parameters, but does not mention potential side effects, limitations, or behaviors like timezone handling, pagination, or custom range format. For a read-only 'get' tool, the lack of mutation disclosure is acceptable, but deeper behavioral context is missing.

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

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

The description is concise and well-structured with a clear purpose line, an Args section, and a Returns section. Every sentence adds value and there is no fluff or repetition of schema content.

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

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

The tool has a simple signature (2 optional params, output schema) and the description covers purpose, parameters, and returns. It is sufficiently complete for a basic read tool, but lacks details on custom range formatting and any behavioral caveats, which would be needed for a more complex operation.

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

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

Schema description coverage is 0%, but the description compensates well by explaining both parameters: app_id as optional filter and period with allowed values ('7d', '30d', '90d', '1y', or custom range). It adds meaning beyond the bare schema; however, it does not clarify the exact format for a custom range or other edge cases.

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 tracks credits, adjustments, and refunds, which is specific and distinguishes it from sibling tools like get_transactions (general transactions) and get_revenue_summary (broader revenue). The verb 'Track' and resource scope are clear.

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 purpose implies usage when credit/adjustment/refund tracking is needed, but there is no explicit when-to-use or alternative comparisons. Given the many sibling tools, more explicit guidance on choosing this over get_transactions or get_revenue_summary would improve clarity.

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

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

With no annotations, the description discloses the return format ('JSON string with LTV, ARPU, average lifespan, and top/bottom 5 merchants') and the optional app_id filter. However, it does not mention any behavioral constraints such as data requirements, error handling, or whether the metrics are computed in real-time. This is minimal 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 compact and well-structured with an Args/Returns format. Each line serves a purpose with no 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?

The tool is simple: one optional parameter and a well-defined return set. The description covers the purpose, parameter, and return structure. With an output schema present, this is sufficient, though it could add a brief usage note.

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 only provides the parameter name 'app_id' with a default value; the description adds that it is an optional filter by app. This gives enough meaning for a single parameter, compensating for the 0% 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 identifies the tool's function: computing customer lifetime value, ARPU, and merchant rankings. However, it does not explicitly differentiate from sibling analytics tools like get_revenue_anomalies or get_merchant_health, so it earns a 4 rather than 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 alternative metrics tools. It only explains the optional app_id parameter, which is parameter semantics, not usage context. This is a clear 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 full burden. It discloses that the tool returns a JSON string with weekly data and acceleration signals, but it does not explicitly state read-only behavior, authentication requirements, rate limits, or other side effects. The 'Get' prefix implies safety, but it is not definitive.

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 compact and well-structured: a one-line purpose, an Args section, and a Returns section. Every sentence earns its place, and the front-loaded purpose ensures quick understanding.

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

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

The description covers the core functionality and return value, and the existence of an output schema likely fills in the detailed return structure. For a simple analytics tool with two parameters, this is sufficiently complete.

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

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

With 0% schema description coverage, the description compensates by explaining app_id as 'App GID or numeric ID' and weeks as 'Number of weeks to analyze' with a default of 12. This adds meaning beyond the raw schema and covers both parameters 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 uses the verb 'Get' and clearly identifies the resource: 'week-over-week growth trends with acceleration signals.' It distinguishes from siblings by highlighting acceleration signals and listing specific metrics (installs/uninstalls/revenue), making it distinct from related analytics 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 implies usage for analyzing growth velocity but does not explicitly state when to use this tool versus alternatives. No exclusions or preferred sibling tools are mentioned, so the context is only implied.

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 responsibility for behavioral disclosure. It explicitly describes the return format (JSON string with specific fields), which goes beyond the basic 'analyze' verb. While it doesn't discuss rate limits or authentication, the read-only analytical nature is implied. This level of detail is commendable for a non-mutating analytics tool.

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

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

The description is compact: a one-sentence summary followed by concise args and returns sections. It avoids verbosity and front-loads the core purpose. Every sentence contributes essential 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?

For a simple one-parameter tool, the description covers the input semantics and explicitly lists the output fields included in the JSON string. The presence of an output schema reduces the need to explain return structures in detail, but the description still provides a useful overview. No major gaps exist for a read-only analytics tool.

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

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

The schema only provides the parameter name and type, with 0% coverage. The description compensates by specifying the accepted format ('App GID or numeric ID') and marks it as required. This adds meaningful semantic value beyond the structural 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 analyzes install patterns and specifies the dimensions (day of week, time of month). It uses a specific verb and resource, and the scope of analysis is apparent. This distinguishes it from sibling analytics tools like get_app_events or get_revenue_summary.

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 context is clear: use this tool to fetch install pattern analytics for a specific app. It does not explicitly name alternatives or exclusions, but the detailed focus on install patterns makes the intended use apparent. No misleading guidance is present.

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. It fully discloses the composite scoring methodology, dimensions, grade thresholds, and return format, which is substantial behavioral context beyond a simple one-liner. It doesn't mention potential side effects or data freshness, but for a read-only analytics tool, this is adequate.

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

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

The description is well-structured with a clear opening statement, an Args section, a concise breakdown of grading dimensions, and a Returns section. Every sentence adds value, and the length is appropriate for the tool's complexity.

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

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

The description explains the purpose, parameters, grading logic, thresholds, and output structure. Despite the tool's complexity, the description provides enough context for an agent to correctly invoke and interpret results. The presence of an output schema reduces the need to explain return types further, but the description already covers the key details.

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

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

The schema only shows app_id as a string without description. The description compensates fully by explaining app_id as 'App GID or numeric ID (required)', adding critical format and requirement context beyond the schema.

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

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

The description clearly states 'Score merchants with a composite health grade (A-F)' using a specific verb (score) and resource (merchants with health grade). It distinguishes from siblings by specifying the composite health grade focus, which differs from churn, retention, or revenue 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 clearly indicates it is for scoring merchant health, and the required app_id is specified. While it doesn't explicitly state when not to use it or name alternatives, the context is clear enough that an agent would understand when to invoke it.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It clearly states the return format (JSON string) and the contents (merchant status, revenue total, full chronological timeline), and it clarifies that both app_id and shop_domain are required. It doesn't explicitly note side effects (none expected for a lookup), but the provided details suffice for a read-only 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 efficiently organized with 'Args' and 'Returns' sections. It uses only two short paragraphs and includes an example, with no redundant or filler content. Every sentence adds useful 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 that this is a simple two-parameter lookup with no annotations, the description covers the essential aspects: what it does, required inputs, and the output structure. It lacks explicit usage timing or error/rate-limit caveats, but for a read-only single-merchant lookup, it is largely complete.

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

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

The schema provides only parameter names and types. The description enriches both parameters: app_id is explained as 'App GID or numeric ID' and shop_domain is given a concrete example ('my-store.myshopify.com'). This goes beyond the bare string types and clarifies expected input formats.

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

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

The description opens with 'Get full timeline for a specific merchant', which clearly identifies the action (get) and resource (full timeline for a merchant). It distinguishes from sibling tools by emphasizing a single merchant's chronological events, unlike tools like get_merchants or get_churn_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 explicit guidance on when to use this tool versus alternatives. It doesn't mention when to prefer this over get_merchant_health or get_transactions, nor does it state any exclusions. The only implied context is 'specific merchant', but there is no comparative 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, the description carries the full transparency burden. It discloses the data source ('Derived from app events'), the default status behavior, and the return structure (JSON string with keys). It does not explicitly state read-only or permissions, but it is a list operation and the description is informative enough for a safe read.

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 with Args and Returns sections, no filler, and each sentence adds value. It packs necessary details into a clear, scannable format.

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 two-parameter list tool with an output schema, the description covers purpose, parameter semantics, data origin, and return shape. It is complete for selection and invocation without redundancy.

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

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

Schema description coverage is 0%, but the description fully compensates by explaining app_id as 'App GID or numeric ID (required)' and status with exact allowed values and default. This is exactly the needed guidance beyond the bare schema.

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

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

The description clearly states a specific verb and resource: 'List merchants (stores) using a specific app.' This distinguishes the tool from siblings like get_merchant_lookup or get_churned_merchants by emphasizing the app-scoped, list-oriented nature.

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

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

Parameter usage is well explained with status options and default, but there is no explicit when-to-use versus alternatives. The 'Derived from app events' note gives some context, but the description does not reference sibling tools like get_churned_merchants or edge cases.

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

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

No annotations are provided, so the description carries the burden of disclosing behavior. It does mention the return format (JSON string) and that it compares current vs previous period, which is useful. However, it does not explicitly state that this is a read-only operation, nor does it disclose any edge cases or calculation caveats, leaving some gaps.

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

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

The description is concise and well-structured: a one-line purpose, a short Args section, a clarifying sentence, and a Returns section. It is front-loaded with the core purpose, and every sentence contributes necessary information without redundancy.

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

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

Given the tool's simplicity (2 optional parameters, no nested objects), the description is complete. It covers the purpose, parameter semantics, and return format, leaving the agent with enough information to invoke it correctly. The presence of an output schema is complemented by the description's explicit listing of return fields.

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

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

The input schema has 0% description coverage, but the description fully documents both parameters: app_id is described as an optional filter, and period has its allowed values ('7d', '30d', '90d', '1y', or a date range) explicitly listed. This adds significant meaning beyond the schema's plain type and default fields.

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

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

The description opens with 'Get MRR movement breakdown' and enumerates specific components (new, expansion, contraction, churn, reactivation), making the tool's purpose concrete and distinct from broader revenue metrics. It further clarifies scope by stating it shows how MRR changed between current and previous period, which distinguishes it from sibling tools that focus on summaries or churn only.

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

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

The description clearly implies when to use this tool (whenever an MRR movement breakdown is needed) and provides context for the period parameter with valid values. However, it does not explicitly mention alternatives or state when not to use this tool, so it falls short of full 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 the full burden. It discloses the return format (JSON string with specific fields) and adds a caveat that amounts are for analytics, not accounting. This goes beyond a simple 'get' and provides useful behavioral context. However, it doesn't mention side effects (though it's a read operation) or authentication requirements.

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

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

The description is well-structured: a one-sentence summary, followed by Args and Returns sections. The caveat is included. No wasted words.

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

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

Given the tool's simplicity, an output schema exists, and the description covers the return values and note. It also explains parameters sufficiently. The description is complete for an AI agent to invoke it correctly.

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

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

The input schema has 0% coverage, but the description compensates with an explicit Args section explaining app_id as an optional filter and period with valid values like '7d', '30d', and date ranges. This fully adds meaning beyond the schema.

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

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

The description clearly states the tool gets a payout summary with specific components (gross revenue, Shopify fees, net payout). This distinguishes it from sibling tools like get_revenue_summary, which cover different metrics.

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

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

The description doesn't explicitly mention alternatives or when-not-to-use, but the context is clear: it's for payout reports. The parameter details (app_id, period) indicate it's for filtering payout data. No exclusions or sibling comparisons are provided, so a 4.

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

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

With no annotations, the description carries the full burden. It discloses the return format (JSON string) and the specific metric fields (subscribers, total revenue, avg revenue per merchant). However, it does not note that this is a read-only operation, potential data inference caveats, or any error/timezone behaviors. The 'inferred pricing tier' hint adds some transparency but is not elaborated.

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

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

The description is a well-structured docstring with Args and Returns sections, front-loading the main purpose. Every sentence is necessary, with no fluff or repetition.

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

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

The tool is simple with two optional parameters, and the description covers the parameters, accepted values, return format, and key metrics. It lacks context on when to use it or what 'inferred pricing tier' means, but the presence of an output schema (per signal) and the low complexity make this moderately complete.

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

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

Schema coverage is 0%, but the description fully explains both parameters: app_id is 'Filter by app (optional)' and period lists all accepted formats including '7d', '30d', '90d', '1y', and an explicit date range. This adds essential meaning beyond the bare schema.

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

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

The description opens with a clear verb and resource: 'Get metrics per pricing plan tier.' This specifies exactly what the tool does and distinguishes it from sibling analytics tools by focusing on plan-tier-level metrics rather than overall revenue or churn.

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 through its purpose but does not explicitly state when to use this tool over alternatives like get_revenue_summary or get_mrr_movement. No exclusions or alternative references are provided, leaving the agent to infer applicability.

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

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

With no annotations, the description carries the burden. It discloses that the output is a JSON string with specific fields (total revenue, count, comparison, details) and period options, which adds useful behavioral context. However, it does not explicitly mention read-only status, data freshness, or custom range format.

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

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

The description is concise and well-structured with purpose, args, and returns sections. Every sentence provides value with no redundancy.

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

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

For a simple one-parameter tool with an output schema, the description is nearly complete: it states purpose, parameter options, and return composition. Minor gaps like custom range syntax or timezone handling prevent a perfect score.

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

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

The schema has no parameter descriptions (0% coverage), but the description compensates by enumerating valid period values ('7d', '30d', '90d', '1y', or custom range) and implying the default. This adds meaning beyond the bare schema.

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

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

The description clearly states the tool 'Track referral revenue from merchant referrals to Shopify' with a specific verb and resource, distinguishing it from sibling analytics tools focused on churn, LTV, or revenue forecasts.

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

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

No explicit guidance on when to use this tool versus alternatives. It does not reference sibling tools or provide contextual decision criteria, only describing what the tool does.

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

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

Without annotations, the description carries the full burden. It discloses the return format (JSON string with monthly cohort table) and the meaning of values above 100% (expansion), which adds useful behavioral context. However, it does not explicitly state that this is a read-only operation or describe any side effects or permissions needed, though 'Get' implies safety.

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 compact and well-structured with separate sections for purpose, args, and returns. Every sentence adds value, with no redundant 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?

The description covers purpose, parameters, and return value, making it adequate for a simple read-only tool with only two optional parameters. It also provides a useful interpretation of the output (>100% indicates expansion). However, it could be more explicit about the default behavior when app_id is empty, but the overall completeness is high.

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 provides no descriptions (0% coverage), so the description is essential. It explains 'app_id' as 'Filter by app (optional)' and 'months' as 'How many months to track per cohort (default 12),' which adds meaning beyond the raw schema. Both parameters are adequately explained.

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

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

The description clearly states 'Get monthly revenue retention cohort table' – a specific verb and resource. This distinguishes it from sibling tools like get_churn_analysis or get_customer_ltv by focusing on retention cohorts.

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 explicit guidance on when to use this tool versus alternatives. 'Get monthly revenue retention cohort table' implies a use case but does not mention exclusions or alternative tools. There is no context such as 'for churn analysis, use X instead.'

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

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

No annotations are provided, so the description carries the full burden. It discloses the return format (JSON string with date, amount, expected, deviation, type) and the empty-list behavior, but it does not mention permissions, data freshness, or what 'unusual' means algorithmically. There is no contradiction with annotations.

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

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

The description is well-structured with a one-sentence purpose, an Args block, and a Returns block. It is concise and front-loaded, with no wasted words.

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

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

The tool is simple with two optional parameters and an output schema. The description covers purpose, parameters, and returns, making it self-contained. It could add more context about anomaly types, but it is not necessary for a basic understanding.

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

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

Schema description coverage is 0%, so the description must compensate. It explains app_id as 'Filter by app (optional)' and lookback_days as 'Analysis window in days (default 90)', adding meaning beyond the schema's type/default. Both parameters are addressed.

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

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

The description opens with 'Detect unusual patterns in revenue', which is a specific verb and resource. It clearly distinguishes itself from siblings like get_revenue_summary and get_revenue_forecast by focusing on anomaly detection.

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 when to use this tool (when revenue anomalies are of interest) but provides no explicit exclusion or comparison with alternatives. It does not mention, for example, 'use this to identify outliers rather than forecast trends'.

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 burden of behavioral disclosure. It explains the return format ('JSON string with current MRR, growth rate, historical data, monthly projections, and projected ARR') and parameter defaults. It does not explicitly state that the operation is read-only, but the 'get' prefix and return-focused description imply safe behavior. Adding an explicit 'does not modify data' statement would make it a 5.

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

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

The description is concise and well-structured: a one-sentence purpose followed by labeled Args and Returns sections. Every sentence provides useful information with no redundancy or fluff.

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

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

The tool has only two optional parameters and an output schema (not shown but indicated as present). The description explains the return contents and parameter options, making it sufficiently complete for an agent to select and invoke the tool correctly. No additional context is necessary.

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 no descriptions (0% coverage), but the description fully compensates by explaining each parameter: 'app_id: Filter by app (optional)' and 'forecast_months: How many months to project (default 6).' This adds meaningful semantics beyond the schema's bare type/default information.

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: 'Project future MRR for the next 3-6 months.' This uses a specific verb ('project') and resource ('future MRR'), and the time horizon distinguishes it from siblings like get_revenue_summary or get_mrr_movement.

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 the tool (when future MRR projections are needed) but does not explicitly mention alternatives or when-not scenarios. It implies usage without exclusions, earning a 4 rather than 5.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It discloses the return format (JSON string with metrics), parameter filters, and accepted period values. It does not explicitly declare read-only behavior, but the verb 'Get' and analytics nature imply no side effects, and the description adds context beyond schema fields.

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

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

The description is compact, front-loads the purpose in the first sentence, and uses clear sections for Args and Returns. Every sentence provides necessary information without redundancy.

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

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

The tool has only two optional parameters, both fully explained with defaults and allowed values. The return payload is described in detail. Given the output schema exists, the description is sufficiently complete for an agent to select and invoke the tool correctly.

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

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

The input schema has no descriptions (0% coverage), so the description fully compensates. It explains app_id's optionality and default behavior and enumerates all valid period values including the date range format. This is essential for correct invocation.

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

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

The description clearly states the tool retrieves revenue analytics with specific metrics (MRR, ARR, total revenue, growth rate, ARPU). This verb+resource+scope distinguishes it from sibling analytics tools like get_churn_analysis and get_revenue_anomalies.

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 parameter usage but does not explicitly state when to use this tool versus alternatives. No exclusions or alternative tool recommendations are given; usage context is implied by the tool's name and the fact it returns a revenue summary.

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. It discloses the return format and transaction types, which is helpful. But it doesn't mention behavior like whether filters are required, whether pagination is supported beyond a limit, or any error conditions. Still, for a read-only tool, the core behavior is clear.

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

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

The description is structured with Args and Returns sections, front-loaded with the purpose. It includes necessary detail without fluff. The transaction type list is long but required for correct usage.

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

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

The description covers the main purpose, all parameters, and the return structure. It also includes a count in the response. Given the moderate complexity and the presence of an output schema, this is adequate, though it doesn't address potential edge cases or pagination beyond the limit parameter.

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

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

Schema description coverage is 0%, so the description must compensate. It does so thoroughly: each parameter (app_id, date_from, date_to, transaction_types, limit) gets an explanation, including the accepted values for transaction_types and the default for limit. This exceeds the schema's minimal info.

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

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

The description clearly states 'Get revenue transactions from your Shopify Partner account,' naming a specific verb and resource. However, it does not explicitly differentiate this tool from sibling tools like get_revenue_summary or get_payout_report, so it stops short of 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 instead of alternatives. It lists arguments but does not state the scenario this tool is best suited for, or any exclusions. There is no 'use X instead' type of instruction.

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

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

With no annotations, the description carries the full transparency burden. It discloses the return type (JSON string) and the specific contents ('conversion funnel metrics, timing analysis, and lists of converted/unconverted merchants'), which goes beyond the schema. It does not mention pagination or rate limits, but for a read-only analytics tool this is reasonably complete.

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, uses a clear Args/Returns structure, and every sentence provides necessary information. There is no redundancy or filler.

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

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

Given the tool's simple read-only nature, two parameters, and no annotations, the description is complete: it covers the required parameter, optional parameter with format, and outlines the return content. It gives an agent enough information to select and invoke the tool correctly without needing 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?

The schema only defines 'app_id' and 'period' as strings with no descriptions or enums (schema coverage 0%). The description compensates fully by specifying app_id as 'App GID or numeric ID (required)' and providing exact allowed values for period ('7d', '30d', '90d', '1y', or 'YYYY-MM-DD:YYYY-MM-DD'), adding essential meaning beyond the raw schema.

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

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

The description starts with 'Get trial-to-paid conversion funnel' which is a specific verb and resource, clearly distinguishing it from sibling analytics tools. It explicitly states what the tool does: retrieves trial-to-paid conversion 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 implies the use case (trial conversion analysis) but does not provide explicit guidance on when to use this tool versus alternatives like get_churn_analysis or get_retention_cohorts. It gives clear context but no exclusions or alternatives.

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