Autario Data Analytics Platform

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

Beyond the readOnly/idempotent annotations, it discloses deterministic server-side computation ('nothing re-derived, nothing estimated'), list truncation with marked omitted counts, bounded weekly series, and the requirement of the caller's own account with Audience 360 connected. No contradictions 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 dense but well-structured: starts with core purpose, then usage directive, then section breakdown, then behavioral notes. It is long but every sentence contributes critical context (contents, truncation, filtering, auth). Could be slightly tightened, but not wasteful.

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?

With 8 parameters and no output schema, the description compensates thoroughly: it enumerates all section contents, mentions the output format briefly, notes truncation behavior, gives filtering advice, and points to get_app_context for the data map. This gives an agent enough 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?

Schema description coverage is 100% (baseline 3). The description adds value by explaining what each report section contains and explicitly advising to filter with range/channel/countries to sharpen the question. It maps sections to interpretation use cases, going beyond the schema's parameter-level definitions.

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 this as an audience report over the caller's own connected Google Search Console + GA4 + social connector data, computed server-side. It explicitly lists the eight report sections and distinguishes it from rebuilding KPIs from raw connector tables, making its purpose unambiguous.

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

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

It states 'Use this FIRST for any interpretation question about a user's traffic/audience' with concrete examples, and explicitly recommend it over the alternative of rebuilding KPIs from raw connector tables. It also gives guidance on choosing only needed sections and using filters, plus the prerequisite of an autario account with Audience 360 connected.

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

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

Annotations indicate read-only, idempotent, not destructive. Description adds that results are deterministic, verifiable from SEC filings, includes chart image, shareable URL, and live fetching for unknown tickers. No contradictions.

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

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

Well-structured with purpose first, then explanation, then examples. Some redundancy (multiple examples of similar queries), but overall efficient for the 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?

Given no output schema, description covers output: text verdict, inline chart, shareable URL, and that available_metrics is included. Addresses live fetching and re-calling with different metrics. Comprehensive for 5-param 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 has 100% coverage. Description adds meaning: explains metric options, scale types ('absolute' vs 'indexed' with rebasing), default behavior, and that available_metrics is returned for re-calls. Examples clarify usage.

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

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

Description clearly states the tool checks US stock valuation against fundamentals. It specifies verb (overlays, returns, checks) and resource (stock price vs SEC-reported fundamental). Distinguishes from siblings which are general data analysis 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 says when to use: 'when a user asks is X a bubble, is X overvalued, how does X's P/E compare to its history, etc.' Provides examples. Lacks explicit when-not or alternatives, but context is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe, non-destructive operation. The description adds that it returns per-timepoint results and a summary, and warns about heavy token usage for the 'full' parameter, which is useful but not extensive.

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: the first explains the tool's function and operations, the second gives examples. It is front-loaded with key information and contains no 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 has 6 parameters, no output schema, and moderate sibling complexity, the description covers the core purpose, operations, and output format. It warns about token-heavy usage. Missing details on 'time' and 'entity' parameters are 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?

The description adds meaning beyond the schema by explaining that 'a' and 'b' are indicators, listing ops in text, and clarifying that 'full=true' returns heavy raw data. With only 33% schema description coverage, these additions are valuable. However, 'time' and 'entity' remain sparsely described.

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 specifies the tool's purpose: creating a derived series from two indicators using Excel-style operations. It lists the operations and gives concrete examples (debt-to-GDP ratio, revenue-per-employee), which distinguishes it from sibling tools like 'correlate' or 'pct_change'.

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 explicit use cases ('Use for things like debt-to-GDP ratio...'), helping the agent decide when to invoke this tool. However, it does not mention when not to use it or suggest alternatives, which would improve the 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds value by explaining that the tool returns a schema reference, is cheap, and serves as input for create_chart_from_spec. No contradictions.

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, each providing essential information: what it returns and when/how to use it. 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 (no parameters, no output schema), the description fully covers purpose, usage, and relationship to create_chart_from_spec. It is 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 input schema has zero parameters with 100% coverage, so the description does not need to add parameter details. The baseline for no parameters is 4.

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 the Builder spec schema reference, listing specific contents (chart_type enum, fields, palette, etc.). It distinguishes itself from create_chart_from_spec by noting the output is input for that tool and is cheaper than guessing Plotly JSON.

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

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

The description explicitly advises calling the tool ONCE at session-start and contrasts it with guessing syntax. It provides clear context for when to use, though it does not list alternative tools for obtaining chart specifications.

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

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

Annotations already indicate destructive and idempotent behavior. The description adds value by clarifying that schema/columns are preserved and mentioning the API key requirement, without contradicting 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?

Three short sentences, all essential information, no 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?

For a simple 1-parameter, no-output-schema tool, the description covers purpose, use case, and a requirement, leaving no ambiguity for an agent.

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

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

With 100% schema coverage for the single parameter, the description does not add extra detail beyond what the schema already provides, meeting the baseline but not exceeding it.

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

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

The description clearly states the action ('Delete all rows'), the resource ('dataset'), and the key behavior ('keeping the schema and columns intact'), distinguishing it from siblings like delete_dataset.

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

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

Provides a specific use case ('refreshing data before re-importing'), which helps an agent decide when to use it, though it does not explicitly list when not to use it or name alternatives.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description details the default behavior (returns per-entity summary) and the optional full mode (returns pivot data), noting that full is heavy. This adds significant behavioral context that helps the agent understand output format and token usage.

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 at three sentences, front-loaded with purpose, and uses formatting (e.g., 'BY DEFAULT', 'full=true') for emphasis. Every sentence earns its place 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 no output schema, the description adequately covers what to expect: a per-entity summary with stats and row_count/x_range, and optionally a pivot dataset. It includes use-case examples and covers all key aspects, making it complete for the tool's complexity.

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

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

With 100% schema coverage, the baseline is 3. The description adds value by explaining that 'full=true' returns heavy pivot data and that the default summary is sufficient for answering questions. This enriches the understanding beyond the schema descriptions.

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

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

The description explicitly states it compares one indicator across multiple entities, using a concrete example (GDP of DEU vs USA vs CHN). It clearly identifies the verb 'compare' and the resource 'entities', and distinguishes its use case from siblings by specifying it's for cross-region analyses and chart comparisons of the same metric.

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

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

It directly states when to use the tool: 'Use this for country comparisons, cross-region analyses, or any chart that compares the same metric across entities.' While it does not explicitly list when not to use or name specific alternatives, the guidance is clear and actionable.

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

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

Annotations already indicate safe, idempotent behavior. The description adds that it returns r, p-value, n, interpretation, and includes a causation disclaimer, and notes the full parameter for heavy data. No contradiction.

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, concise and front-loaded with the core action. Every sentence adds value.

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

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

Given 5 parameters and no output schema, the description covers the return values, the automatic disclaimer, and the optional full parameter. It is fairly complete for a statistical tool.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add parameter details beyond the schema; it only mentions the behavior of the 'full' parameter, which is already described 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 verb 'Compute' and the resource 'Pearson + Spearman correlation between two indicators for one entity.' It distinguishes itself from sibling tools like 'regression' by focusing on correlation.

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

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

The description explicitly says 'Use for "does X move with Y?" questions.' This provides clear guidance on when to use the tool, though it does not explicitly mention when not to use or list alternatives.

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

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

The description discloses key behavioral traits beyond annotations: automatic brand attribution that cannot be overridden, and validation of insight numbers leading to a 422 error if hallucinated. These details about irreversible attribution and error handling add significant value beyond the structured 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 concise (4 sentences), front-loading the primary purpose ('PREFERRED chart-creation path'), then efficiently covering constraints and fallback. Every sentence contributes essential 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 description covers key aspects: purpose, preferred status, attribution, input validation, and fallback. However, it lacks details about the return value or output format (e.g., does it return a chart ID?), which would be helpful given the absence of an output schema. Overall, it is mostly complete but has 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?

Although the input schema has 100% coverage and detailed parameter descriptions, the description adds extra context: it explains that the top-level title overrides builder_spec.title, and references chart_instructions() for full builder_spec details. This provides additional semantic value beyond the schema alone.

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 is the 'PREFERRED chart-creation path' that builds charts from a structured Builder spec, distinguishing itself from the sibling tool publish_chart. It specifies the verb 'create' and resource 'chart' with a specific method (Builder spec), and explicitly contrasts with the fallback path for advanced use cases.

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 explicit guidance: it is the preferred path, with a fallback to publish_chart for advanced cases, and recommends calling chart_instructions() first if unsure. This covers when to use the tool, when not to, and what alternative to use.

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

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

The description adds value beyond annotations by disclosing that the tool returns a dataset_id for subsequent population with write_rows, and that it requires AUTARIO_API_KEY. Annotations only indicate non-readOnly and non-destructive, which is consistent.

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

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

The description is concise with three sentences, each serving a distinct purpose: defining the action, explaining the return value and next steps, and providing a usage condition and authentication requirement. No unnecessary 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 has 4 parameters, no output schema, and minimal annotations, the description is quite complete. It covers the creation flow, follow-up action, condition, and auth. It lacks details on error handling or response format, but these are minor.

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

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

Input schema covers all 4 parameters with descriptions. The description does not add any parameter-specific semantics beyond what the schema provides, so baseline score of 3 is appropriate.

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 "Create a new empty dataset on Autario" with a specific verb and resource. It uniquely identifies the tool's purpose among siblings, as no other sibling tool creates datasets.

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 a clear condition for use: "Only create new datasets if the data does not already exist on Autario." It does not explicitly name alternatives or say when not to use, but the context is sufficient.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds critical behavioral details: the statistical method (multiple regression), multicollinearity handling (flagging not_separable pairs), and output fields. No contradictions.

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: bold title, method explanation, collinearity handling, output, usage instruction, and entity note. Every sentence adds value, and key information is front-loaded.

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

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

No output schema exists, but the description clearly explains the return per candidate. It covers constraints, when to use vs siblings, and entity behavior. Annotations cover safety, making this 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 80% (4 of 5 parameters have descriptions). The description adds context for entity omission and candidate count range, and implies max_lag scanning for lead/lag. It does not add details for time, but overall adds value 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 it performs a multiple regression to decompose a target into driver contributions, accounting for confounders. It explicitly distinguishes itself from find_drivers by focusing on overlapping candidates and providing honest effect sizes.

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

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

The description explicitly says 'Use this instead of find_drivers when candidates may overlap or when you need honest independent effect sizes.' It also provides constraints: 2-15 candidates, omit entity for entity-less series, and max_lag default.

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?

Goes beyond annotations by detailing consequences (permanent, irreversible), authorization (owner only), and authentication (requires API key). 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?

Three concise sentences, front-loaded with main action, then consequences, then prerequisites. No unnecessary 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?

Adequately covers action, irreversibility, ownership, and auth. Could mention post-deletion behavior, but acceptable given destructive nature and no output schema.

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 covers parameter fully (100% coverage). Description mentions dataset_id implicitly but adds no new semantics beyond schema 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?

Clearly states the verb 'delete' and resource 'dataset' with emphasis on permanence. Differentiates from sibling tools like create_dataset and get_dataset_info.

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 warns that deletion is irreversible and restricted to dataset owners, providing clear when-not conditions. Lacks explicit alternatives but context suffices.

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

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

Annotations already convey read-only, idempotent, and non-destructive behavior. The description adds no additional behavioral traits beyond stating it computes summary statistics. It does not discuss performance, rate limits, or any side effects. Since annotations carry the full burden and description adds minimal extra transparency, a score of 2 is appropriate.

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 that efficiently convey the purpose, output, and usage guidance. It is well-structured with the core function stated first, followed by a clear user directive. No unnecessary 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 description covers the main output and usage intent but omits details about the optional 'time' parameter and does not explain how time filtering affects the statistics. With no output schema, the description could be more explicit about the return format. Overall, it is adequate for a simple descriptive tool but has 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 coverage is 0%, meaning the input schema has no descriptions. The description only mentions 'indicator' and 'entity' by name but provides no explanation of their meaning, valid values, or format. The 'time' parameter is not mentioned at all. The description fails to compensate for the lack of schema descriptions, resulting in very poor parameter semantics.

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 provides summary statistics for a single indicator+entity and lists the specific statistics returned (n, mean, median, std, min/max, quartiles, skew, histogram). It also positions the tool as a preliminary step, distinguishing it from sibling tools by advising to use it 'FIRST' before any test.

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 tells when to use the tool: 'Use FIRST before running any test' and explains the purpose (know sample size, completeness, distribution shape). It does not provide explicit when-not-to-use or list alternatives, but the guidance is clear and actionable, justifying 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?

Description adds value beyond readOnlyHint/idempotentHint by detailing ranking tiers (tier_1, tier_2, tier_3), quality gates (is_public, completeness, scope, length), and that results are SEO-ready. It doesn't mention auth or side effects, but annotations already cover 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 concise with four sentences, front-loading the purpose and use case. Every sentence provides unique value without repetition, making it efficient and easy to 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?

Despite no output schema, the description explains that results include tagline and sample facts, enabling the agent to pick top datasets without extra calls. It covers parameter behavior, ranking logic, and quality gates, fully addressing complexity.

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

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

All parameters have schema descriptions (100% coverage). The description adds context on how parameters affect ranking (topic-relevance weight, recency_window filtering) and explains the output includes tagline+sample facts, which aids selection.

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 discovers relevant verified datasets by topic, using a specific verb and resource. It distinguishes from siblings like query_dataset and search_datasets by emphasizing quality-ranked results and tagline+sample facts to avoid round-trips.

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

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

The description explicitly says to use when starting an article, dashboard, or analysis, and that results include sample facts to avoid further query_dataset calls. It implies not to use for deep queries but lacks explicit when-not-to-use language.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral details: maximum 30 candidates, returns ranked list with correlation metrics. No contradiction.

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

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

Two concise sentences, front-loaded with 'KILLER ANALYSIS', no redundant words. Every sentence adds value.

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

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

Given the tool's moderate complexity and no output schema, the description covers input constraints, purpose, and output format (ranked list with stats). Sufficient for an agent to understand and invoke 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?

Schema coverage is 75%, with most parameters described. The description adds the 'max 30' constraint for candidates, which is not in the schema, and clarifies that target_indicator is 'the KPI you want to explain'. This adds value 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?

Description clearly states the tool ranks candidate indicators by correlation strength against a target KPI, using action-oriented language ('KILLER ANALYSIS') and specific output details (r, p-value, R²). It distinguishes itself from sibling tools like 'correlate' or 'regression' by focusing on driver 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?

Explicitly says 'Perfect for 'what moves my KPI?' questions' and caps candidates at 30. Does not specify when not to use or list alternatives, but the use case is clear.

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?

Description adds behavioral details beyond annotations: truncation for large artifacts ('marked with truncation notes; row/item counts stay correct'), read-only and cost-free nature, and gating behavior. No contradiction with readOnlyHint=true and destructiveHint=false.

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?

Description is clear and front-loaded with purpose, but is slightly lengthy. Each sentence adds value, though some phrasing could be tighter without losing meaning.

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 (gating, truncation, format options, no output schema), the description covers all necessary aspects: what it returns, when to call it, parameter specifics, and limitations. References sibling tools for 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?

With 100% schema coverage, description still adds value: explains slug source, provides app_id examples, details format options (toon, compact, json) and their use cases, including REST API behavior.

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 loads 'ONE saved artifact' and specifies the content: 'report configuration, chart spec, OKR board, screener view' plus inline data. It distinguishes from siblings by referencing get_app_context/get_my_workspace for listing slugs.

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?

Explicit instruction to 'Call after get_app_context / get_my_workspace listed the artifact slugs.' Covers gating ('Owner-gated... foreign private artifacts are invisible') and alternative action for full data ('query the app's datasets via query_dataset').

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

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

Annotations already declare readOnlyHint and idempotentHint; description adds that secrets are never included and differentiates behavior for authenticated vs unauthenticated callers, adding value beyond 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?

Front-loaded with key purpose, each sentence adds value, though slightly wordy. Could be tightened but effective.

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?

No output schema but description comprehensively details return data (manifest, tables, artifacts, examples) and accounts for authentication state, making it complete for its purpose.

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 100%, so baseline is 3. Description references app_id source and format but doesn't add significant new meaning beyond schema descriptions.

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

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

The description clearly states the tool returns the data map behind a single app, including manifest, tables, artifacts, and query examples. It distinguishes itself from sibling tools by being app-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?

Provides explicit example queries like 'what does my <app> run on' and mentions where app_ids come from. Lacks explicit when-not-to-use guidance but context is clear.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds transparency by detailing the bounded nature of the response (no raw spec or full arrays), token-efficiency, and the per-series summary specifics beyond what annotations provide.

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

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

The description is front-loaded with purpose and return summary, then details what is returned. It is slightly verbose but every sentence adds value. Minor trimming (e.g., repeated mention of 'compact') could improve conciseness.

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

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

Given 2 parameters and no output schema, the description adequately explains the return structure, including what is not returned (raw spec, data arrays). It covers key aspects needed for an agent to understand the tool's capabilities and limitations.

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 100% with clear descriptions. The description mentions 'toon' format but adds no semantic value beyond schema. It reinforces the format options but does not provide new constraints or examples.

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 a specific chart by ID or slug, distinguishing it from list_charts (which lists all) and create_chart_from_spec (which requires spec input). It specifies the compact summary returned and what is excluded.

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 this tool should be used when a compact summary is sufficient, directing users to view_url for full interactive data. It does not explicitly exclude alternatives but provides clear context for appropriate use.

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

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

Annotations indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the tool is safe. The description adds value by stating that it returns 'latest verified data from autario.com' and instructs to cite the citation_url, which informs the agent about data freshness and attribution 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 concise, includes essential information, and is well-structured with a clear purpose, usage guidance, metric list, and examples. Every sentence adds value 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?

For a simple tool with 2 parameters and no output schema, the description is complete: it explains purpose, when to use, what metrics are available, provides examples, and notes data freshness. No gaps are present.

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 100%, so the schema documents parameters. The description adds meaning by listing all available metrics and providing examples with typical usage patterns, which helps the agent select appropriate metrics.

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 current stock metrics for a public company.' It uses a specific verb (Get) and resource (stock metrics), and while no sibling tool directly competes, the description effectively differentiates by focusing on stock 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 explicitly states when to use the tool: 'whenever a user asks about stock price, market cap, performance, or company financials.' It provides clear usage context but does not explicitly exclude scenarios or mention alternatives, leaving a slight 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds behavioral context by specifying which fields are returned and how they should be used (e.g., unit for chart titles). This goes beyond the annotations, providing useful operational semantics without contradiction.

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

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

The description is front-loaded with the main purpose and then details specific fields. It is two sentences, but the first sentence is long due to the field enumeration. It could be slightly more concise by omitting less critical fields, but overall it is well-structured and each part adds value.

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

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

With no output schema, the description compensates by thoroughly listing returned fields and providing usage guidance for unit and frequency. This makes the tool's behavior clear despite the lack of a structured output definition. The description is complete for an informational retrieval 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 both parameters. The description does not add additional meaning to the parameters themselves (dataset_id and format). It focuses on output fields, not input parameters. According to guidelines, when coverage is high, baseline is 3.

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

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

The description clearly states that the tool retrieves full metadata for a specific dataset, listing many fields including ontology fields. It distinguishes itself from siblings like search_datasets (which searches) and get_dataset_schema (which only returns schema). The verb 'get' and resource 'full metadata for a specific dataset' 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 provides explicit guidance on how to use the output: the 'unit' field should be used verbatim in chart titles via create_chart_from_spec.title, and 'frequency' plus data span should derive year-range suffix. It implies this tool is for retrieving metadata before chart creation. However, it does not explicitly state when not to use it or name alternatives, though context from siblings helps.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description goes beyond by detailing the datasheet structure (shape, roles, cadence, etc.) and explaining the single_series shape, adding significant behavioral context about the return value and its interpretation.

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

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

The description is a single paragraph that front-loads the main purpose and then details the datasheet. It is fairly concise given the complexity, though it could be improved with bullet points for readability. Every sentence adds value.

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

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

Given the complexity of the datasheet and the lack of an output schema, the description thoroughly explains what the tool returns and how to interpret it. It also covers usage instructions and edge cases (e.g., single_series shape, ignoring columns), making it complete for an agent.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add new meaning to the parameters beyond what the schema provides, but it provides valuable context about how the output datasheet relates to parameter choices indirectly. No additional parameter semantics 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 retrieves column names, data types, row count, and a datasheet for a dataset. It distinguishes from siblings like query_dataset and charting tools by explicitly saying 'Always call this before query_dataset' and 'before charting', giving it a specific and unique purpose.

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 explicit guidance on when to use the tool: before querying a dataset and before charting. It does not mention alternative tools for similar purposes, but the context is clear enough to differentiate from 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?

Even though annotations already declare readOnlyHint=true and destructiveHint=false, the description adds substantial context: it is read-only, never auto-fixes, includes a permission error for unauthorized callers, and explains that the trends parameter adds history for before/after comparison. This is exactly the kind of behavioral disclosure that helps the agent reason about invocation safety and expectations.

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 information-dense and every clause adds value, but the opening sentence is a long run-on that packs many report sections together. It is front-loaded with the critical 'ADMIN/CURATOR ONLY' caveat, and the content is well-organized overall, but it could be broken into bullet-like sentences for easier parsing.

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 report tool with no output schema, the description thoroughly covers what the report contains (funnel, backlog, asset list, health, failure patterns, queue state, alerts), the permission prerequisite, read-only behavior, and optional trends expansion. This gives the agent enough context to invoke it appropriately and understand what to expect in the result.

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 100%, so parameters are already well-documented. The description goes beyond the schema by specifically explaining the purpose of the 'trends' flag in the context of 'did my change help?', and clarifies the default output is 'toon' as the token-efficient format. It does not add as much depth for 'format' and 'trend_days', but it appropriately complements 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 this tool provides a machine-readable health report of the autario data engine, listing its exact scope (ingestion funnel, dirty backlog, asset coverage, etc.). It distinguishes itself from sibling tools by focusing specifically on the engine health as rendered by /admin/health and /admin/storage, and is unambiguous about its resource and purpose.

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 states this is ADMIN/CURATOR ONLY and requires OAuth authorization as the curator account, warning that any other caller gets a permission error. It also gives concrete usage triggers ('Use when asked...' followed by five specific questions), which is excellent guidance for when to choose this tool over alternatives.

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

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

Annotations already declare safe read-only behavior. Description adds context about automatic joining, the stats block contents, and token implications of full=true, enhancing transparency beyond 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?

Front-loaded with key purpose and capability. Uses bullet-like structure but could be slightly more concise. Still efficient and well-organized.

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

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

Covers all critical aspects: purpose, inputs, output structure, default vs. full mode, and references to sibling tools. No output schema, but description compensates fully.

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 100%, but description enriches parameters by detailing the stats block fields, explaining ISO-3166 entity codes, and illustrating the structure of the full data rows.

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 fetches data for one entity across multiple indicators with automatic time-based joining, and distinguishes itself from get_entity_profile and compare_entities by highlighting its cross-dataset join capability.

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

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

Provides explicit guidance on when to use the default summary vs. the full raw data, and how to obtain entity codes and indicator IDs from sibling tools. Does not explicitly state when not to use, but context is clear.

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

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

Annotations indicate readOnlyHint, idempotentHint, destructiveHint. The description adds pagination details (default 100, offset, has_more), topic filtering, and token-light format, which are not captured by annotations. No contradictions.

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

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

The description is a single paragraph that front-loads the core action and includes essential details (pagination, filtering, examples). It is concise but covers necessary context without verbosity.

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?

Though no output schema is provided, the description thoroughly explains the return structure (indicator IDs, metadata, time coverage, total_indicators, has_more, offset). Combined with parameter details and usage examples, it is contextually complete for this tool.

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

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

Schema coverage is 100% with descriptions for all 5 parameters. The description supplements by explaining pagination mechanics, default limit, and entity code formats (ISO 3166, World Bank aggregates), adding value beyond 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 retrieves indicators for an entity (country, aggregate) with metadata and time coverage. It distinguishes from siblings like get_entity_data by focusing on discovery of what indicators are available.

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

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

The description explicitly advises 'Use this to discover what you can query about Germany, USA, G7, or any known entity.' It provides entity code examples and mentions filtering by topic. While it doesn't explicitly say when not to use, the context is clear.

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

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

Annotations already indicate readOnlyHint=true. The description adds context: requires authentication, no cost, guarantees consistency with user's view, and that it's read-only. No contradictions.

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 dense and packed with information, but it is a single long paragraph without bullet points or clear segmentation. Some redundancy (e.g., 'read-only, no cost' repeated). Could be 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?

For a tool with no output schema, the description thoroughly lists what is returned (apps, providers, tables with dataset_id/slug + row count + last refresh, artifacts, query example). Also covers authentication and cost. Very 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?

Only one parameter (format) with enum values. The description explains the meaning of each format (toon for fewest tokens, compact vs json) beyond the schema, helping agents choose appropriately.

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 returns the user's workspace (data-apps, providers, tables, artifacts, query example) in one call. It distinguishes from sibling tools like get_app_context by explicitly mentioning it replaces multiple round-trips.

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 says 'THE first call when a user references "my <app>"' and provides concrete use cases. It also guides to drill-down tools (get_app_artifact, query_dataset) for further details, though it does not explicitly state when not to use this tool.

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?

Adds behavioral context beyond annotations: requires OAuth authorization as curator, returns cached fast JSON, excludes bots, and lists specific sections. Annotations already provide readOnlyHint and destructiveHint, and description extends with access restrictions and output 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?

Description is detailed but front-loaded with key info (access restriction). Lists many specifics in a structured way. Could be slightly more concise, but all sentences earn their place.

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

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

Given no parameters and no output schema, description fully covers what the tool returns (sections like human-only numbers, MCP calls, signups, etc.) and preconditions (admin only). Complete for agent understanding.

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

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

No parameters, so schema coverage is 100%. Description adds meaning by explaining what the parameterless call returns, satisfying the baseline of 4.

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

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

Description uses specific verb 'Fetch' with resource 'autario traction overview' and details its contents (three signal sources, etc.). It distinguishes itself from sibling tools by being a specific report uniting multiple data sources, clearly answering what the tool does.

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 'ADMIN/CURATOR ONLY' and gives usage triggers like 'how is autario doing', 'show traction', etc. While it doesn't explicitly contrast with alternatives, the context is clear enough for when to invoke.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive). The description adds value by explaining output interpretation (peak |r| meaning) and lag range. This supplements the annotations well.

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 plus an example, all front-loaded. Every word serves a purpose, 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 description explains purpose, interpretation, and a use case. Though there is no output schema, the description clarifies what to look for (peak |r| at lags). It is complete for the tool's complexity.

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

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

Schema coverage is 80% with good param descriptions. The tool description does not add significant extra meaning beyond the schema, such as parameter formats or constraints, so baseline 3 is appropriate.

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 performs cross-correlation at multiple lags, answers lead/lag questions, and interprets peak |r|. The example 'is consumer confidence a leading indicator of retail sales?' adds concrete context. This distinguishes it from siblings like correlate or regression.

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 lead/lag analysis with a common use case, but does not explicitly state when to use it versus alternatives like correlate (no lag) or regression. It provides clear context but lacks explicit 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?

Adds context beyond annotations: explains behavior for authenticated vs unauthenticated callers, defines format options, and confirms read-only nature. No contradictions.

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

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

Well-structured with front-loaded core function followed by usage guidance and parameter explanation. No wasted sentences.

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

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

Despite no output schema, the description fully explains what the output contains. Addresses authentication, cost, and usage flow. Complete for this simple tool.

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

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

Schema coverage is 100% and its description of the 'format' parameter is sufficient. The tool description adds no extra parameter meaning, so baseline of 3 is appropriate.

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 lists autario data apps (the app catalog) and details the fields returned. It distinguishes from sibling get_app_context by specifying it as the starting point.

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 tells when to use ('when a user mentions an app by name or asks what apps exist') and when to follow up with get_app_context. Also notes it's read-only and no cost.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds that returned datasets are pre-filtered to be chartable, lists return fields, and explains that a listed dataset won't bounce back with errors.

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?

Description is front-loaded with key info and is clear. Slightly long but all sentences add value. Could be trimmed slightly without loss.

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?

No output schema, but description enumerates return fields. Explains pre-filtering and provides workflow context. For a simple 1-param admin tool, this is 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?

Only one parameter (limit) with full schema description (default 25, max 200). Description does not add substantial 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?

Description clearly states it lists datasets with no published chart, ranked by relevance, pre-filtered to be chartable. It specifies admin-only and internal use, distinguishing from sibling tools by indicating it's the queue for autario-generated charts.

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 says AUTARIO-INTERNAL (admin only) and that non-admin keys receive 403. Recommends workflow: request_chart (preferred) or alternative steps. Contrasts with third-party needs.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the agent knows this is a safe read operation. The description adds no behavioral caveats beyond what annotations provide, nor does it contradict them. Returns field details are helpful but not behavioral.

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 succinct sentences that front-load the core purpose and immediately follow with what is returned. Every word earns its place, no 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?

For a simple list operation with comprehensive annotations and full schema coverage, the description is complete. It explains the return fields and usage intent. The lack of output schema is mitigated by the description of returned data. No missing critical information.

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 each parameter is already documented. The description does not add extra meaning or usage context for parameters; it just summarizes return fields. Baseline 3 is appropriate.

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

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

The description clearly states the action 'list' and the resource 'published chart visualizations', and lists the returned fields. It distinguishes this from siblings like get_chart (single chart) and discover_by_topic (topic-based search).

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

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

The description explicitly says 'Use to discover existing analyses', indicating when to use. It does not mention when not to use or alternatives, but the context of siblings provides implicit differentiation. Clear enough for an agent.

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

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

Annotations already declare readOnlyHint and destructiveHint, but the description adds valuable information: 'never handles credentials', requires AUTARIO_API_KEY, and explains the fields returned (dataset_id, datasets, refresh interval, last refresh time). This goes beyond 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 mostly concise front-loaded with the main action. Some verbosity exists in the explanation of datasets (parentheses and pipe), but overall it efficiently conveys purpose and output.

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 simple tool (0 params, rich annotations, no output schema), the description covers all essential aspects: returned fields, auth requirement, relationship to sibling tools, and limitations. It is fully adequate for an agent to use 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?

There are zero parameters, so schema coverage is trivially 100%. The description adds no parameter information, but the baseline for 0 params is 4. The description compensates by detailing output 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 lists REST API connectors on the account, specifying the verb 'list' and resource 'connectors'. It distinguishes from sibling tools like refresh_connector and query_dataset.

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

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

The description explicitly says 'Use this to find a connector before refreshing it or reading its hosted table', providing clear context. It implies when not to use (e.g., for credential handling), but does not explicitly name alternatives beyond refresh_connector.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds context about the semantic layer and filter facets, but no behavioral contradictions. It slightly exceeds 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?

Two sentences: first defines the tool and its facets, second gives usage guidance and comparison. Every sentence adds value, 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?

For a read-only filter tool with 7 optional parameters and no output schema, the description sufficiently conveys what the tool does, how to use it, and why it's useful. No missing critical details.

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

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

Schema has 100% coverage with detailed descriptions for each parameter. The description lists available facets but does not add significant per-parameter detail beyond the schema. Baseline 3 is appropriate.

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

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

The description states it's for browsing 'the Autario indicator registry — semantic layer over all 2600+ datasets' with specific facets (topic, unit, frequency, entity_type). It clearly distinguishes from sibling 'search_datasets' by claiming precision advantage.

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 says 'Use this to discover what data is available before querying it' and provides a direct comparison: 'Much more precise than search_datasets when you know what topic or unit you need.'

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

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

Annotations already indicate readOnlyHint=true and idempotentHint=true, establishing safety. The description adds no new behavioral traits beyond the calculation nature. It does not contradict annotations, but also does not elaborate on side effects or prerequisites.

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 contains no filler. Every sentence serves a clear informative 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 (5 parameters, no output schema), the description is adequate but incomplete. It does not explain the return format, the role of the 'time' parameter, or what happens when data is missing. However, the 'full' parameter description in the schema compensates partially.

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 40%, and the tool description does not mention any parameters. Required parameters 'entity' and 'indicator' have no descriptions in either the schema or the description, leaving the agent to infer their meaning. The 'full' and 'period' parameters are documented in the schema, but the description adds no additional clarity.

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 computes 'period-over-period percentage change' for an indicator, and specifies its use for growth rates (YoY, QoQ, MoM). This verb-resource pairing is specific and distinguishes it from sibling tools like 'calculate' or 'lag_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 explicit usage context ('Use for growth rates (YoY, QoQ, MoM)'), but does not mention when not to use it or compare with alternatives such as 'lag_analysis' or 'rolling_stats'.

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

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

Annotations indicate writing and non-destructive behavior. Description adds context about authentication (AUTARIO_API_KEY) and verification gates. While not detailing side effects or output, the annotations lower the burden, and the description provides additional useful 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?

Three sentences, each serving a distinct purpose: stating the tool's function, providing an alternative, and listing prerequisites. Front-loaded with the most important information. 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 complexity (5 parameters, nested plotly_spec) and no output schema, the description covers purpose and comparison but lacks return value information and usage tips for the complex plotly_spec parameter. It is adequate but incomplete.

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 100%, so baseline is 3. The description does not add meaning beyond the schema; it repeats the concept of 'freeform Plotly spec' but does not elaborate on parameter usage or constraints. No extra value is provided.

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

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

Description clearly states it publishes a chart using a freeform Plotly spec and distinguishes from create_chart_from_spec by noting that the latter should be used unless specific Plotly features are needed. The verb 'publish' and resource 'chart' are explicit, and sibling differentiation is provided.

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 instructs to use create_chart_from_spec instead unless Plotly features are required. Also mentions requirements: AUTARIO_API_KEY, brand attribution, and insight verification gate, providing clear context for when to use this tool.

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?

Discloses that aggregations are numerically correct even though values are stored as text, mentions server-side aggregations and GROUP BY, and states the return format (rows plus per-category statistics). No contradiction with annotations (readOnlyHint, idempotentHint, destructiveHint false).

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 slightly long but well-structured: starts with core purpose, then efficiency tips, then return format. Every sentence adds value, but could be more concise without losing 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 11 parameters and no output schema, the description covers pagination, filtering, aggregations, formatting, and provides usage examples. It mentions return type and citation requirement. Completes the picture for a complex query tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant explanatory value beyond the schema, especially for aggregate (explains functions, aliases, numerical correctness) and summary_only (token efficiency). Adds meaning beyond parameter names.

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 data from a dataset with optional filtering, sorting, and field selection.' It also mentions aggregations and GROUP BY, which distinguishes it from other dataset tools like get_dataset_info or get_dataset_schema.

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?

Excellent usage guidance: provides explicit examples (e.g., 'average GDP of Germany 2010-2020' => aggregate=avg(value) + filters), recommends using aggregations or summary_only over raw rows for token efficiency, and explains when to use non_null_only to avoid wasted tokens.

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

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

The description adds valuable behavioral context beyond annotations: it states the tool is 'Deterministic fetch, no LLM cost' and 'Requires AUTARIO_API_KEY.' This complements the annotations (idempotentHint=true, readOnlyHint=false) without contradiction. The agent learns about side-effect freedom and authentication needs.

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 (4 sentences) with no redundant information. It front-loads the action and purpose, then adds usage conditions, return value, and authentication. Every sentence earns its place.

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

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

Despite no output schema, the description explicitly states return values: 'Returns the new row count and the dataset_id you can then read with query_dataset / get_dataset_schema.' Combined with clear purpose, prerequisites, and behavioral notes, the description is fully complete for a single-parameter tool.

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

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

Schema coverage is 100% with one parameter (connector_id) described as 'The id of the connector instance to refresh (from list_connectors).' The description adds no additional meaning beyond the schema; it only repeats 'connector' in a broader context. Baseline of 3 is appropriate.

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: 'Pull the latest data from a connector's source REST API now and refresh its hosted Postgres table on Autario.' It specifies the verb (refresh), resource (connector), and outcome (new rows, dataset_id). This distinguishes it from sibling tools like list_connectors (list only) and query_dataset (read 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 explicitly says 'Use when the user wants fresh data before analysis' and provides a prerequisite: 'The connector must already exist (the owner sets it up in the UI).' It does not explicitly state when not to use it or mention alternative tools, but the context is clear enough for an agent.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering safety. The description adds useful behavioral context: it operates on one entity only, returns specific outputs and interpretation, but does not detail time parameter effects or data 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 extremely concise: two sentences. First sentence states method and outputs, second provides usage. No wasted words, 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?

Covers core purpose, outputs, and usage, but omits details on time parameter handling, data sufficiency, and interpretation format. Given no output schema, a fuller description of return values would improve completeness.

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

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

Schema covers 3 of 5 parameters (x, y, full) with descriptions. The description adds context that entity means 'one entity', but time parameter remains undocumented. With 60% schema coverage, description partially compensates but not fully.

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 statistical method (linear regression), variables (y ~ x), scope (one entity), and outputs (slope, intercept, R², interpretation). The usage example 'how does X predict Y?' differentiates it from siblings like 'correlate'.

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

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

The description explicitly says 'Use for "how does X predict Y?" questions', providing a clear usage guideline. It implicitly differentiates from alternatives but does not specify when not to use or list alternatives explicitly.

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?

Beyond annotations (idempotentHint, not readOnly), the description adds that authentication is required, that duplicate reports are no-ops, and explains routing behavior (auto re-ingest vs. human review). It fully discloses the tool's effects without contradicting 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 moderately long but every sentence earns its place. It starts with a clear one-line purpose, lists use cases, gives a critical instruction about evidence, and ends with routing and dedup details. No fluff.

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

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

Given the complexity (5 params, nested objects, no output schema), the description covers purpose, usage, parameter guidance, authentication, and routing. It lacks detail on the return value (e.g., status or issue ID), but this is minor for a reporting tool.

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

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

With 100% schema coverage, the description adds little beyond what the schema already provides. It reinforces the importance of 'evidence' and gives usage examples, but most parameter details are already in the schema. Baseline 3 is appropriate.

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 'Report a data-quality problem you found in a dataset or chart' with a specific verb and resource. It lists concrete scenarios and distinguishes itself from sibling tools like 'create_dataset' or 'update_chart' which do not involve reporting issues.

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 states 'Use this during a QA pass when you spot:' and enumerates specific conditions. It also instructs to always attach evidence and notes that reporting the same issue twice is harmless, providing clear when-to-use and when-not-to-worry 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?

Goes well beyond annotations (readOnlyHint false, openWorldHint true) by detailing administrative restriction, deterministic server-side charting, no LLM involvement, prepare/publish flow, entity verification, and 422 error response with actionable info.

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?

Every sentence provides necessary detail, but the description is long. It front-loads key information and is well-organized, though could be slightly more concise without losing 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 no output schema and the tool's complexity (two-step flow, entity family handling, verification), the description fully covers what the agent needs: return values, error handling, and usage steps. No 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 coverage is 100% and description adds valuable context: soft preferences for time, region, chart_type; the dual use of insight (omit on prepare, send on publish); and the precedence of dataset_id over query.

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's for high-level chart requests with a two-step flow. It distinguishes itself from sibling tool create_chart_from_spec by specifying when to use this tool over the alternative.

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 explains when to use (avoiding full spec) and when not (admin-only; third parties use other tools). Provides clear two-step procedure: prepare then publish, with details on each call's requirements.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint as safe. The description adds interpretive context (smoothing, trends) but no additional behavioral traits like authentication needs or rate limits. The description does not contradict annotations.

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

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

The description is a single 12-word sentence with no redundant words. It efficiently conveys the core functionality and purpose without unnecessary 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?

With no output schema and 6 parameters, the description lacks critical context about the return format or how to interpret results. The param 'full' in schema mentions returning summary vs. full series, but the description omits this guidance. The agent would need to rely heavily on the schema and parameter descriptions for proper usage.

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

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

Schema description coverage is 50%, with three parameters (op, full, window) described in the schema. The main description does not add any param-specific information beyond listing the operations in the op field, which is already covered. The description fails to compensate for the uncovered parameters (entity, indicator, time).

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 computes rolling window statistics (mean, std, min, max, sum) for an indicator, with the purpose of smoothing noise and revealing trends. It distinguishes from sibling statistical tools like lag_analysis or pct_change by specifying the rolling window and smoothing aspect.

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 use cases (smoothing noise, revealing trends) but does not explicitly state when to use this tool versus alternatives like lag_analysis or pct_change. No direct comparison or exclusion criteria are provided, making guidelines 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?

Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds behavioral context: returns ontology fields conditionally, authenticated users see own private datasets, never others' private data. No contradictions.

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

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

Well-structured paragraph with key info first. Slightly verbose in listing fields but necessary for completeness. No wasted sentences.

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?

No output schema, but description enumerates returned fields. All 6 parameters are documented with context. Privacy and ontology behavior fully disclosed. Sufficient for an AI agent to use 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?

Schema coverage is 100% but description adds value: explains visibility default logic (public vs private based on auth) and format option usage (toon vs json). Does not simply repeat schema, but enhances 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?

Clear verb 'search' with specific resource 'Autario data catalog'. Distinct from siblings like list_indicators and discover_by_topic, explicitly differentiating scope and use case.

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?

Explicit directive: 'Use this first to discover available datasets before querying.' Provides specific alternatives: 'For precise topic/unit/frequency filtering...prefer list_indicators. For TOPIC-DRIVEN article research, prefer discover_by_topic.' Also explains authentication-dependent visibility behavior.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint false, so the description need not restate those. It adds value by specifying the decomposition model (additive) and that it returns per-timepoint components and summary amplitude. No contradictions with annotations. It does not discuss edge cases or data requirements, but for a read-only analysis 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?

Two sentences efficiently convey the model, use case, and output. No redundant or filler content. The description is front-loaded with the key equation and then the application, 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 complexity of a time series decomposition tool with no output schema, the description covers purpose and return type but omits details about the summary amplitude structure and the role of the undocumented 'time', 'entity', 'indicator' parameters. An AI might need to infer their usage from naming conventions. For a routine analysis tool, this is minimally adequate but not comprehensive.

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 40% with only 'full' and 'period' having descriptions; three parameters ('time', 'entity', 'indicator') lack any description in either schema or tool description. The description mentions 'monthly or quarterly' which indirectly relates to 'period' but adds no specific syntax for 'time', 'entity', or 'indicator'. The 'full' parameter is well-described in schema, but the description does not compensate for the undocumented required parameters, reducing its additive value.

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

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

The description clearly states the tool performs additive decomposition (trend, seasonal, residual). It specifies the verb 'decompose' implicitly and the resource is a time series. The phrase 'strip seasonal cycle... reveal underlying trend' clarifies the purpose, and it is distinct from siblings like 'correlate' or 'decompose_drivers' which serve different analytical functions.

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 guidance on when to use: 'for monthly or quarterly data' with examples (retail sales, unemployment). It implies use for seasonal data but does not explicitly state when not to use or mention alternative tools among siblings. However, the context is sufficiently clear for an AI to select this tool for seasonal decomposition.

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?

Beyond the readOnly/idempotent annotations, the description discloses that results are computed server-side from connected GSC data, are deterministic, and match the exact numbers in the app. It also notes transparency about incomplete previous windows and bounded crawl scope, plus authentication requirements and a pointer to get_app_context('seo-360'). This adds significant 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 lengthy but well-structured, starting with a core summary and then enumerating sections with parenthetical explanations. Each sentence provides useful detail for a complex tool; however, the length is at the upper limit and could be trimmed without losing much. Therefore a 4.

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?

There is no output schema, so the description must explain what the tool returns. It does this thoroughly by detailing each of the 10 sections and their content, along with data sources and requirements. It covers edge cases (incomplete windows) and authentication, making it complete for an AI agent.

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

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

The schema covers all three parameters with descriptions, so the baseline is 3. The description further explains what each report section contains (e.g., page2_gaps as 'position 8-20 pairs ranked by potential click gain'), which helps in selecting 'sections' values. This adds meaning beyond the bare schema, so a 4 is appropriate.

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 produces a deterministic Search Console action report from the caller's own GSC data, with a specific unit (query, page) and concrete actions. It also distinguishes itself from sibling audience_360, stating 'Deeper than audience_360' and listing specific use-case questions. This makes the purpose unambiguous and differentiates it from siblings.

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 lists when to use this tool: 'this is the tool to call when a user asks...' for several SEO action questions. It also contrasts with audience_360, indicating which tool answers traffic-source questions. It adds a prerequisite for using the tool (autario account with Search Console connection), which is useful 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?

Annotations already declare readOnlyHint and idempotentHint, but the description goes far beyond: it explains that the report is computed server-side using 'the exact numbers the user sees in the app', that missing platform metrics are 'DROPPED and the weights renormalized, never counted as zero', and that spike candidates are 'hedged by design, never a claimed cause'. It also discloses auth requirements ('Requires the caller's own autario account') and connector freshness behavior. No contradictions 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 densely packed and front-loaded with the core purpose, but it is quite long. Almost every sentence adds value, especially the section breakdowns and caveats. However, some parentheses could be condensed without loss, and the overall length may challenge quick consumption. Still, it is appropriately sized 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?

Without an output schema, the description compensates by detailing each report section (score, explorer, posts, geo, spikes, peers, health), their content, and limitations. It also covers prerequisites, data provenance, and edge cases (e.g., unconnected platforms carry an honest not-connected state). The tool's complexity is fully addressed, enabling 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?

While the schema already describes all parameters (100% coverage), the description adds significant context: 'days' is explained as being anchored per-platform to the newest connector table date; 'sections' gets token-efficiency and re-call guidance; 'format' clarifies wire format tradeoffs and that the REST API always returns JSON; 'sort' is placed within the posts section context. The main description also details what each report section contains, enriching the 'sections' parameter meaning.

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 specific verb+resource: 'the caller's OWN deterministic social performance report over their connected Facebook Page, Instagram, TikTok and YouTube data'. It also lists concrete user intents ('how are my social accounts doing', 'which post worked best', etc.) and explicitly distinguishes itself from sibling audience_360 ('Deeper than audience_360... this one judges social performance and names the post behind it').

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

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

Provides explicit trigger phrases like 'Call it when a user asks' and 'which format should I post more of'. It also contrasts with the sibling audience_360, stating that this tool judges social performance while audience_360 answers 'who comes from where'. Additionally, it states the prerequisite of having an autario account with at least one social connector, which is essential for correct invocation.

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

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

Annotations indicate mutation (readOnlyHint=false) and non-destructive (destructiveHint=false). Description adds ownership and API key constraint, which is valuable beyond annotations. No contradictions.

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, front-loaded with the core purpose, no unnecessary words. Efficient and clear.

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 update tool with no output schema, the description is complete: it covers purpose, constraints, and what can be modified. No missing critical information.

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

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

Input schema has 100% coverage with descriptions for all parameters. Description reiterates that Plotly spec, title, or insight can be modified, but adds minimal new 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?

Clearly states it updates an existing chart, specifies ownership constraint, and lists modifiable aspects (Plotly spec, title, insight). Distinguishes from siblings like publish_chart and get_chart.

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 says to use for updating a chart you own, with the constraint that only the creating API key can update. Does not explicitly list when not to use, but context with sibling tools implies differentiation.

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

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

Annotations already mark the tool as readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that the tool returns 'whether autario's live value matches, with relative difference and provenance,' which provides behavioral context beyond annotations. 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 two sentences with zero waste. The first sentence states the purpose and usage context; the second explains what to pass and what is returned. Every sentence earns its place.

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

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

Given no output schema, the description adequately covers what is returned. It mentions the verification result, relative difference, and provenance. It does not detail error cases or format, but for a read-only, idempotent verification tool with 4 well-documented 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?

Schema coverage is 100%, so the schema already documents all parameters. The description adds value by clarifying the expected parameter as optional for existence-only checks and grouping the core parameters (indicator, entity, time). This goes beyond what the schema alone provides.

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: 'Verify that a claimed value is correct.' It specifies the action (verify), the resource (claimed value), and the scope (double-check cited numbers). This clearly distinguishes it from sibling tools like get_entity_data which retrieve raw data, not verify assertions.

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 explicit when-to-use guidance: 'when a user asks did you hallucinate that? or when you want to double-check your cited numbers before presenting.' It does not explicitly list when not to use or alternatives, but the context is clear enough for an agent to infer appropriate usage.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable behavioral details: auto-selection from ontology, confidence labels, sharpen-suggestions, frequency alignment, and no inflated n-counts. 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 two sentences, front-loading the core purpose, then detailing key behaviors. Every clause adds information without redundancy or irrelevant detail. Punctuation and structure support readability.

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

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

Given no output schema, the description explains return format (ranking with confidence labels, reason strings, sharpen-suggestions) and important nuances (frequency alignment, no inflated n-counts). It covers all key aspects for an agent to use the tool effectively.

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

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

Schema coverage is 75% (three of four parameters have descriptions in schema). The description adds meaning for 'candidates' (auto-selection behavior) but does not elaborate on 'time' or further clarify 'entity'/'outcome' beyond schema. This adds value but is not exhaustive.

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

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

The description states the tool ranks which other metrics best explain a given outcome metric and entity, using specific verbs ('rank') and resources ('metrics'). It explicitly distinguishes from the sibling tool 'find_drivers' by noting this tool is for 'narrative-grade' answers.

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 guidance: 'Use this instead of find_drivers when you want a narrative-grade answer.' It also explains auto-selection behavior when 'candidates' is omitted, helping the agent decide when to rely on default behavior versus manual candidates.

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?

Adds beyond annotations: all values stored as text, max rows per call, and auth requirement. No contradiction with annotations (readOnlyHint=false, destructiveHint=false).

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?

Four concise sentences, front-loaded with purpose, no wasted words. Each sentence adds critical 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?

Covers purpose, schema inference, value type, row limit, and auth. Despite no output schema, key behavioral aspects are addressed. Lacks details on error handling or what happens if dataset missing, but sufficient for typical 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?

Schema coverage is 100%, but description adds 'all values stored as text' and that schema is inferred from first batch, which adds value beyond the schema's parameter descriptions.

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

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

Clear verb 'append' and resource 'rows to an existing dataset'. Distinguishes from siblings like 'clear_rows' and 'create_dataset'.

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 max rows (10,000) and suggests multiple calls for larger data. Mentions API key requirement and automatic schema inference, guiding usage. Does not explicitly mention alternatives but implies them.

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