Autario

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds substantial behavioral context: deterministic reads, no re-derived numbers, no LLM run, honest null/empty states, branded-question exclusions, and account ownership guarantees. This goes well beyond what annotations alone convey.

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 call triggers, and nearly every sentence carries distinct information. However, it is a long, dense block with repeated emphasis on 'own brand' and 'nothing re-derived', which could be tightened or structured with bullets for easier scanning.

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 carries the full burden of explaining return content, and it does: it enumerates sections, empty-state behavior, metric exclusion rules, auth prerequisites, and account ownership constraints. An agent has enough context to call the tool correctly without external references.

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 the description adds decision-critical meaning: brand optionality and multi-brand behavior ('nothing is picked for you'), detailed semantics for every section enum, and format nuances such as the REST API always returning JSON. This materially improves correct parameter 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 opens with a specific verb and resource: reads the caller's own AI-assistant brand-visibility report from stored runs. It clearly distinguishes itself from sibling analytics tools (audience_360, seo_360, social_360) by focusing on AI-assistant visibility and explicitly stating no LLM run is started.

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 provides explicit call triggers with example user queries ('how visible is my brand in ChatGPT', 'do assistants recommend us or a competitor'), and explains when not to use it: runs, prompt edits, and settings are deliberately not exposed. It also routes custom deliverables to create_dataset, write_rows, and create_chart_from_spec.

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 states numbers are 'computed deterministically server-side' and 'nothing re-derived, nothing estimated', emphasizing accuracy. It also discloses that lists are 'capped' with truncations marked, and notes the prerequisite of an autario account with the app connected, pointing to get_app_context for the data map.

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 every sentence adds value, from listing the eight sections to filtering guidance and prerequisites. It could be broken into paragraphs for readability, but it is appropriately sized for a tool with 10 parameters and 8 sections, and it front-loads the purpose with the 'use this FIRST' directive.

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 tool with no output schema, the description covers all essentials: section options, filtering, truncation behavior with omitted counts, prerequisites, and where to find the data map. It also warns about instance validation errors, so an agent can call it correctly without 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 coverage is 100%, so the schema already documents parameters. The description adds valuable context: the brand/brand_term backward compatibility, the range= custom pairing with from/to, the default sections and selection advice, and the instance validation behavior. This enriches schema definitions but a few parameters (like countries) remain self-explanatory 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 identifies the tool as an 'Audience 360' report on the caller's own audience data from Google Search Console, GA4, and social connectors. It explicitly states 'computed deterministically server-side' and differentiates from rebuilding KPIs from raw connector tables, making its purpose distinct among sibling tools like seo_360 and social_360.

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 FIRST for any interpretation question about a user's traffic/audience' and provides example questions like 'why is my AI traffic falling' and 'which queries are rising'. It contrasts with rebuilding from raw tables, advises picking only needed sections, and suggests filtering with range/channel/countries, giving concrete and actionable usage guidance.

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

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

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 and idempotentHint, so the tool is safe. The description goes further by explaining the refusal behavior (error_code incompatible_semantics), the override mechanism with audit reason, and that every result includes a computation block with columns, kinds, rows, and window. It also clarifies the 'full' parameter's heavy token cost and default summary-only behavior, which is critical for cost-aware selection.

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

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

The description is dense but tightly written, with each sentence covering an essential aspect: operations, use cases, refusal behavior, override path, result structure, and supported data sources. Front-loading the verb and operations helps. Minor deduction for being long (3-4 sentences) and listing many sources at the end, but all is relevant.

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

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

Given the tool's complexity (8 params, 50% schema coverage, no output schema), the description covers all critical aspects: operation semantics, use cases, failure modes (incompatible semantics), override with audit trail, result computation block, full vs summary output, and data source compatibility. An agent has enough to call it correctly and handle errors. The only missing piece is a note that no output schema exists, but that's 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?

While schema coverage is only 50%, the description compensates by explaining the semantics of the op parameter ('Excel-style op: ratio, ratio_pct, diff, sum, product'), the role of a and b as two indicators, and the meaning of full (returns full series vs summary) and reason/override (justification for overrides, returned for audit). It adds depth beyond the schema's terse 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 opens with a precise verb ('Create a derived series') and names the exact resource (two indicators) plus the operations supported (ratio, ratio_pct, diff, sum, product). It clearly distinguishes from siblings like 'pct_change' and 'correlate' by focusing on pairwise arithmetic combinations, and the examples (debt-to-GDP) make the use case concrete.

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 explicitly states when to use it (debt-to-GDP, revenue-per-employee, yield spreads) and when to avoid it: it mentions that autario refuses to combine columns of different semantic kinds, and instructs the agent to read the schema's semantics field before combining. It also describes what to do on refusal (override with reason), covering both standard and edge cases.

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

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

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 include destructiveHint=true and idempotentHint=true, and the description adds rich context beyond the annotations: it clarifies exactly what is destroyed (rows only, not schema/columns), what surface area is affected (own datasets only), and the API key requirement. No contradiction exists between description and 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, each earning its place: the first states the core action, the second gives the primary use case, and the third sets scope boundaries and authentication. Information is front-loaded and there is 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 single-parameter tool with rich annotations and no output schema, the description covers purpose, scope, destructive effect, what remains intact, and authentication. Nothing an agent needs to decide whether to call this tool is missing.

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 the schema describes dataset_id as 'The UUID of the dataset to clear all rows from,' which is already complete. The description reinforces that this must be an owned dataset but adds no new syntax details 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 first sentence names a specific verb ('Delete all rows'), a specific resource ('a dataset you own'), and a key qualifier ('keeping the schema and columns intact'). This clearly distinguishes the tool from destructive siblings like delete_dataset and from data-writing tools like write_rows.

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

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

The description provides clear context: use it to refresh your own uploaded table before re-importing. It also gives a strong exclusion rule—only own datasets are reachable, never public catalog or other users' data. It doesn't explicitly mention alternatives by name, but the usage scenario is sufficiently 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?

The description adds substantial behavioral context beyond the annotations: the default per-entity summary behavior, the optional full pivot output, the heaviness of full=true, and token-cost implications. Since annotations already mark this as read-only and idempotent, the description's extra detail about output shape and cost is valuable and non-redundant.

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 front-loaded with the core purpose, then covers the output default, the full-mode variant, use cases, and token precision. It is longer than minimal but every sentence carries useful information, and the examples make it more scannable.

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

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

Given the tool has no output schema, the description does a good job of explaining the return shape (summary stats vs. wide pivot rows) and the tradeoff of using full=true. It covers core behavioral expectations; it could be slightly more complete by noting edge cases like missing data or unsupported indicators, but nothing essential is missing for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by explaining what the default output looks like, when full should be set to true, and how the summary statistics (first/latest/min/max/avg/count) support comparative answers. This goes beyond the schema's property descriptions.

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

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

The description clearly states the tool's specific function: comparing ONE indicator across MULTIPLE entities, with concrete examples (GDP of DEU vs USA vs CHN). This distinguishes it from sibling tools like get_entity_data or correlate, which serve different analytical purposes.

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

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

The description explicitly states when to use this tool: 'Use this for country comparisons, cross-region analyses, or any chart that compares the same metric across entities.' It also explains when to use the full parameter. However, it does not explicitly name alternative tools or provide when-not-to-use guidance, so it stops short of a 5.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds meaningful context by listing return fields (r, p-value, n, interpretation) and disclosing that a causation disclaimer is automatically included. 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 dense, information-rich sentences with no filler. The core operation and output are front-loaded, and every sentence contributes: what it computes, when to use it, and what data it runs on.

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 statistical tool with fully documented parameters, the description covers the operation, output fields, intended question type, and supported data sources. There is no output schema, but the description summarizes return values sufficiently. Edge cases like short series or missing overlap are not mentioned but are not critical for correct invocation.

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

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

Schema coverage is 100%, so every parameter is already documented in the input schema. The description adds only light mapping context ('two indicators', 'one entity') and does not need to compensate further because the schema fully covers 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 uses a specific verb ('Compute') and clearly names the resource: Pearson + Spearman correlation between two indicators for one entity. It also states what is returned. It does not explicitly name a sibling alternative like regression or lag_analysis, so it stops short of full differentiation.

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

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

It gives a clear usage context: 'does X move with Y?' questions, and scopes valid inputs to verified indicators from named sources. However, it does not explicitly state when not to use this tool or mention alternatives such as regression or lag_analysis.

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

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

Beyond the annotations, the description discloses critical behaviors: the app is created as PRIVATE, is not in any catalog or public URL until publish_app, runs in a locked sandbox, has a 512 KB limit, and requires authentication. This is far more behavioral context than the annotations alone 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 longer than average, but it is well-structured and front-loaded with the core purpose. The data-source list is extensive and adds specific guidance, though it could be slightly trimmed without losing essential 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?

For a creation tool with no output schema and sparse annotations, the description covers the full lifecycle: creation, ownership, privacy, sandbox constraints, required authentication, and the recommended follow-up calls. An agent has enough context to invoke this tool correctly and set expectations about 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 the baseline is 3, but the description adds meaningful semantics: the app id is derived from the name, the content can be a URL or self-contained HTML, and uploaded content runs in a sandbox with no outbound network. These details go beyond the schema's descriptions, though not every parameter gets extra commentary.

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 and resource: 'Create a data app on autario in ONE call, owned by you.' It clearly distinguishes this from siblings by framing it as the FIRST step and naming follow-up tools like write_app_artifact, get_app_preview_url, and publish_app.

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

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

It explicitly states when to use the tool: whenever a user asks to build an app, dashboard, report page, or tool over autario data. It also gives a concrete workflow sequence with named alternatives for subsequent steps, which makes the intended usage unambiguous.

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 provide readOnlyHint=false and destructiveHint=false, so the tool is known to be a mutating create. The description adds valuable behavioral constraints: brand attribution is applied automatically and cannot be overridden; insight must cite verifiable numbers and hallucinated numbers return 422 with an anchor list. It also mentions the fallback path. While it doesn't cover rate limits or auth, the disclosures go well beyond the annotations and materially help the agent.

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 dense with purpose. It front-loads the core purpose and preferred status, then adds constraints (brand attribution, insight validation) and ends with fallback and guidance. Every sentence adds value; however, the length and nested parameter description could be slightly streamlined without loss. It remains well-structured and readable for an agent.

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

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

For a tool with nested objects and five parameters, the description covers required and optional fields, validation rules, fallback, and error behavior (422). It appropriately points to chart_instructions() for full spec reference rather than duplicating it. The absence of an output schema means return values don't need explanation. Minor gaps: it doesn't explicitly state whether the chart is immediately visible or if additional steps are needed, but the fallback reference and instruction pointer cover most needs.

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 goes far beyond: it specifies the exact title format with required year range and unit (with conditional rules based on get_dataset_info), requires insight to use only numbers from query results, and details the required and optional fields within the nested builder_spec object. This is a substantial addition that compensates for the complexity of nested parameters and clarifies usage 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 states a specific verb (create), resource (chart), and input (Builder spec) and clearly distinguishes itself from the sibling publish_chart by positioning itself as the preferred path with a defined fallback. It also names the tool it is not (publish_chart) and the condition that selects it, making the purpose unambiguous without opening the 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?

Explicitly states when to use this tool ('PREFERRED chart-creation path') and when not to (advanced use cases fall back to publish_chart). It also directs the agent to call chart_instructions() if unsure of the spec shape, giving clear context and exclusions. This is model guidance for selecting among siblings.

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

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

The description opens with

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

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

The description is compact and front-loaded with the core create statement, then moves through return value, workflow, precondition, and auth requirement. The list of public catalog names is slightly extraneous but reinforces the 'alongside the public catalog' point without bloating the text.

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

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

The tool is a mutation with no output schema, and the description covers the essentials: it states the return value (dataset_id), the auth requirement (AUTARIO_API_KEY), the privacy default, and the surrounding workflow (search first, then write_rows, query_dataset, create_chart_from_spec). This makes the description complete enough for an agent to 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 coverage is 100%, so the baseline is 3. The description adds only modest parameter context: it clarifies that is_public controls privacy ('private to you unless you set is_public'). The other parameters (title, category, description) are already fully documented in the schema, and the description doesn't enrich them beyond the 'empty dataset' concept.

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

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 opens with

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 how collinearity is handled (VIF > 5 or pairwise |r| > 0.8) and that entangled candidates are flagged not_separable rather than ranked with a confident wrong number. It also details the per-candidate outputs. These behaviors go well beyond the readOnly/idempotent annotations and are internally 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 dense but each sentence adds a distinct useful fact: method, collinearity handling, returned metrics, alternative tool, supported data, and constraints. The key 'confounder-aware' concept is front-loaded, and no sentence is 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 regression-style analysis tool with no output schema, it covers algorithm, failure mode, return fields, data sources, and candidate constraints. However, the optional `time` parameter is left undocumented in both the schema and description, which is a minor completeness gap for constructing a fully valid call.

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%, so the baseline is 3; the description adds meaningful semantics by explaining entity omission for entity-less series and enforcing the 2-15 candidate count. It does not clarify the undocumented `time` parameter, but the schema covers the rest and the description complements rather than repeats 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 states a precise technical behavior: 'fits ONE multiple regression of the target on ALL candidates jointly' and distinguishes it from the sibling find_drivers by name. It clearly identifies the resource (driver decomposition) and the specific method (confounder-aware joint regression), far beyond the generic title.

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 explicitly says 'Use this instead of find_drivers when candidates may overlap...' giving a concrete alternative and the condition that selects it. It also clarifies supported data sources and the entity-omission case for private KPI series, so an agent knows when this tool applies.

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 destructiveHint=true and readOnlyHint=false, and the description adds meaningful context beyond them: irreversibility ('cannot be undone'), ownership restriction, the AUTARIO_API_KEY requirement, and the protected public-catalog contract. This is exactly the kind of behavioral disclosure that helps an agent avoid destructive mistakes.

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 core action and irreversibility are front-loaded in the first sentence, and every clause earns its place: ownership, public-catalog exclusion, API key. The pipe symbol ('owner can delete it | the public catalog') is an awkward separator, but there is no filler or 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 single-parameter, no-output-schema destructive tool, the description is nearly complete: it covers what happens (permanent full deletion), who may call it (owner), what is required (API key), and what is protected (public catalog). The only gaps are failure/return behavior (e.g., error if not the owner or dataset already deleted), which the idempotentHint partially addresses.

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% — dataset_id is fully documented as 'The UUID of the dataset to permanently delete.' Per the baseline rule, high coverage earns a 3 even without param detail in the description. The ownership phrase in the description slightly reinforces parameter intent but adds no new syntax or format information.

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

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

The description opens with a specific verb+resource+scope: 'Permanently delete a dataset you own, and all its data.' This clearly distinguishes the tool from sibling list/query/update tools and from clear_rows (which removes data but not the dataset itself). The public-catalog exclusion adds further precision about what is NOT deletable.

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-not guidance: public-catalog datasets (World Bank, FRED, Eurostat, OECD, SEC) are not deletable, and only the owner may delete. It also states the API-key prerequisite. It stops short of a 5 because no alternative tool is named for the excluded cases, but the routing constraints are 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by listing the output statistics and histogram, and by noting it works across many data providers. It does not disclose details like what happens for missing data or how the histogram is rendered, but with strong annotations this is acceptable.

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 with zero filler. The first sentence front-loads the core purpose, the second gives immediate usage guidance, and the third scopes data sources. 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?

For a read-only descriptive tool, the description lists the key output statistics well. However, with no output schema, it does not explain how the result object is structured or how the optional time parameter affects computation. This is serviceable but leaves a notable hole for an agent deciding whether to pass time.

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

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

Schema description coverage is 0%, so the description must carry the parameter semantics. It clarifies that indicator refers to verified autario indicators from named sources and that the call targets a single entity, but it leaves the optional 'time' parameter entirely unexplained and does not specify acceptable formats for entity or indicator. This is a meaningful gap.

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 and resource: 'Summary statistics for a single indicator+entity', then enumerates the exact statistics (n, mean, median, std, min/max, quartiles, skew, histogram). This clearly distinguishes it from sibling tools like compare_entities or correlate, which involve multiple entities or indicators.

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 'Use FIRST before running any test', giving a clear trigger condition and context (knowing sample size, completeness, distribution shape). It also scopes the tool to 'any verified autario indicator'. However, it does not name alternative tools or explicitly state when not to use it, so it stops short of full exclusion 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?

Beyond the readOnly/idempotent annotations, the description discloses ranking logic (topic-relevance, source quality tiers, coverage, recency), quality gates (is_public, completeness, scope, length), and output characteristics (tagline + sample facts). It also reveals token-efficiency behavior and how to interact to minimize cost. 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 longer than average but every sentence carries useful information: purpose, usage context, ranking logic, output value, and a token-saving tip. It is front-loaded with the core purpose and contains no filler. Slightly overlong due to the detailed tier breakdown, but justified.

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 adequately explains return values (quality-ranked list with tagline and sample facts). It covers selection criteria, quality filters, source scope, and usage guidance. Combined with rich annotations (readOnly, idempotent) and fully documented parameters, nothing critical is missing for safe and effective invocation.

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

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

Schema coverage is 100% and each parameter already has a meaningful description, so baseline 3 applies. The description adds context about ranking criteria and quality gates but does not materially enrich the meaning of the individual parameters beyond what the schema 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 states a specific verb and resource: 'Discover the most relevant verified datasets for a given topic,' with concrete catalog sources. It distinguishes itself from query_dataset by noting the results include taglines and sample facts so you can pick datasets without additional round-trips, and it clearly identifies the tool as a quality-ranked discovery search rather than a generic dataset query.

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 when starting an article, dashboard, or analysis on a topic,' giving a clear trigger context. It also references an alternative by explaining you can avoid further query_dataset round-trips. However, it does not explicitly contrast with search_datasets or other sibling discovery tools, so the when-not guidance is slightly incomplete.

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 safety profile is covered. The description adds useful behavioral detail: returns r, p-value, and R², max 30 candidates per call, processes candidates one at a time, and restricts to verified autario indicators. It doesn't cover edge cases or rate limits, but adds meaningful value beyond the annotations.

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

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

The description is dense but every sentence earns its place: purpose, use case, output format, limit, alternative, and supported data sources. Key information is front-loaded in the first sentence, and the alternative guidance is immediately actionable.

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 compensates well by naming return fields (r, p-value, R²), setting a candidate cap, and enumerating supported source families. The only notable gap is the absent semantics for the optional time parameter, but overall an agent has enough to select and invoke this 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%, so the baseline is 3. The description enhances the schema by clarifying that target_indicator is 'the KPI you want to explain' and candidates are 'candidate indicator IDs' with a hard max of 30. The time parameter is left undocumented in both schema and description, preventing a 5.

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 a specific verb ('Rank'), a clear resource ('candidate drivers of a KPI'), and a distinctive methodology ('order them by correlation strength'). It differentiates itself from the sibling decompose_drivers by noting when overlap exists, so an agent can distinguish this from related tools without opening schemas.

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 explicitly says when to use it: for 'what moves my KPI?' questions, and provides a clear when-not with an alternative: 'Use decompose_drivers instead when the candidates may overlap.' This gives actionable routing guidance beyond generic context.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds substantial behavioral detail: sequential dependency on get_app_context/get_my_workspace, owner-gating and visibility of foreign private artifacts, honest truncation for large data with preserved counts, and the option to use query_dataset for raw data. These go well beyond the annotations, and no contradiction exists.

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 information-rich, using pipe separators to break into logical chunks. It front-loads the core purpose and then adds contextual details. Although it is somewhat long, every sentence contributes value (access rules, truncation, alternatives). It is not overly redundant, so a 4 is warranted.

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 (3 params, no output schema), the description covers all essential operational aspects: when to call it (after listing artifacts), what it returns (saved view state plus inline data), limitations (owner-gating, truncation with notes), and alternatives (query_dataset for raw data). It also states read-only/no cost. An agent can invoke it correctly without further info.

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 all three parameters (slug, app_id, format) are already documented in the schema. The description adds little param-specific meaning; it refers to slug source ('from get_app_context / get_my_workspace') and app_id source ('from list_apps'), but those are already in the schema descriptions. Hence 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 a specific verb and resource: 'Load ONE saved artifact from an autario data app'. It defines what an artifact is (EXACT view state, listing specific types) and distinguishes it from related tools by explaining it returns the saved configuration/data rather than a guess. It clearly separates from siblings like query_dataset and get_app_context.

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

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

The description explicitly says 'Call after get_app_context / get_my_workspace listed the artifact slugs', giving a clear sequence. It also names an alternative for full raw data: 'query the app's datasets via query_dataset', and explains visibility rules (owner-gated) plus the truncation caveat. This is explicit when-to-use and when-not-to-use 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 readOnly, idempotent, and non-destructive; the description adds valuable behavioral context beyond that: it explicitly guarantees 'Secrets and credentials are never included', and it discloses that results differ for authenticated vs. unauthenticated callers (public manifest vs. personal reality). This is critical for an agent deciding whether to use the tool and how to interpret the response.

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-organized, front-loading the purpose ('data map... query app-first') before detailing the return payload and usage triggers. Every sentence contributes value, though the length and single-paragraph structure could be slightly tightened with bullet points. It remains focused and free of 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?

With no output schema, the description must inform the agent of what to expect, and it does: manifest components, connector-instance table details (column list, row count, dataset_id, last refresh), saved artifacts, and ready-to-run query examples. It also covers authentication differences and the exclusion of secrets. Minor omissions like error handling or pagination do not significantly weaken completeness for a read-only tool.

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

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

The input schema already provides 100% coverage for both parameters, so the baseline is 3. The description adds only one useful semantic nugget: 'app ids come from list_apps', which helps the agent source the required app_id. It does not elaborate on the format parameter, but that is already self-explanatory 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 a specific verb (query) and resource (app context), and explicitly differentiates it from related tools by framing it as 'the data map behind ONE autario app' vs. querying individual datasets. It also lists concrete connector providers and distinguishes authenticated vs. unauthenticated views, making the tool's 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 provides explicit when-to-use triggers with example user queries ('what does my <app> run on', 'query my Search Console data') and tells the agent that app ids come from list_apps, the natural prerequisite. It also references query_dataset and the REST endpoint as follow-ups, guiding the agent on how to consume the returned dataset IDs.

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 the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), and the description adds genuine context beyond them: the preview URL is 'private, never-indexed,' only the owner can run it, and it reads World Bank/FRED/Eurostat/connector data through the sandbox bridge. It also discloses that public_url is null while private and that next_step names the next call. No contradiction with annotations; only failure states and URL lifespan are left out.

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, front-loaded with the core purpose, then return-field semantics, then usage guidance — every sentence earns its place. The middle sentence carries a lengthy nested parenthetical about data sources, which is informative but slightly dense.

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 present, the description compensates well by enumerating the return fields and their meanings, while the single required parameter keeps complexity low. It explains reuse (shareable link after publish) and next-step routing, though it omits error cases and any expiry/refresh behavior of the preview URL.

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% — app_id is already documented as 'The app id' — so the baseline is 3. The description adds only a mild ownership constraint ('an app you own'), which is useful but does not meaningfully extend the parameter's semantics beyond what the schema 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 opening line states a concrete resource — the preview URL for an app you own — with a clear verb ('OPEN') and scope ('plus where it stands'). The description further distinguishes the tool by enumerating its unique outputs (preview_url, public_url, visibility, indexed, next_step), which separates it from siblings like list_apps and get_app_context. It never names a sibling explicitly, so it stops short of a 5.

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

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

The description explicitly anchors the tool in a workflow: 'Use it to hand a user something to click after create_app, and to check what is still missing before publish_app.' This tells an agent exactly when in the app lifecycle to call it. However, it offers no when-not-to-use guidance and names no alternative tools, so it misses the bar for a 5.

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

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

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 already establish read-only, idempotent, and non-destructive behavior. The description adds substantial context beyond that: it uses live market data joined with SEC filings, returns verified data from autario.com, requires citing the citation_url, and explains token-efficient behavior plus the exact trading-day window semantics for performance metrics.

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

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

The description is front-loaded with the core purpose and usage trigger, then efficiently covers metric semantics, defaults, citation requirements, and examples. The metric list is necessary rather than padding, and the examples are compact and illustrative. 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?

For a read-only lookup tool, the description is largely complete: it covers source, citation behavior, metric windows, defaults, and example mappings. The main gap is that it tells agents to use the tool for market cap and company financials, yet the available metric list contains no market-cap or financial-statement metric, which could cause over-triggering. There is also no output schema, but examples partially compensate.

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 already describes both parameters at 100% coverage, but the description adds meaningful semantics: the default metric set when metrics is omitted, the precise definition of perf windows (1w = 5 sessions, 1y = 252), and concrete query-to-parameter examples. This goes well beyond the raw schema 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 states a specific verb and resource: 'Get current stock metrics for a public company.' It also names the data source and explicitly ties the tool to stock price, market cap, performance, and company financials, which makes its purpose immediately recognizable to an agent.

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 an explicit trigger: 'Use this whenever a user asks about stock price, market cap, performance, or company financials.' It also instructs the agent to prefer this live source over outdated training data. However, it does not mention sibling alternatives or provide when-not-to-use conditions, so it stops short of full routing 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 readOnly, idempotent, and non-destructive behavior, so no contradiction exists. The description adds valuable behavioral context beyond annotations by defining the semantic meaning of the unit field and directing agents to use it verbatim in chart titles and to derive year-range suffixes from frequency plus data span.

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 dense paragraph with the core purpose front-loaded, followed by a compact field enumeration and two actionable usage notes. Every sentence earns its place, and there is no filler 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?

There is no output schema, so the description carries the full burden of explaining the return shape. It lists the complete metadata fields and adds non-obvious guidance about unit and frequency usage. Combined with well-documented parameters and safety annotations, the agent has enough information to invoke and use the tool correctly.

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

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

The input schema already covers both parameters at 100%, so the baseline is 3. The description does not add extra detail about dataset_id or format, though it does clarify the nature of the returned metadata, which indirectly helps the agent understand what the dataset_id refers to.

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

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

The description opens with a specific action ('Get full metadata') and a specific resource ('a specific dataset'), then enumerates exactly which metadata fields are returned. This clearly distinguishes it from siblings like get_dataset_schema and query_dataset by emphasizing metadata and ontology fields rather than schema or 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?

It clearly implies this is the tool to call when you have a dataset_id and need full metadata, and it adds downstream guidance for using the unit and frequency fields. However, it never explicitly contrasts this tool with sibling tools like search_datasets or get_dataset_schema, so there is no direct when-not-to-use 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 mark the call as read-only/idempotent, and the description adds substantive behavior beyond that: the shape/roles/cadence/cardinality/level_mix/ignore_cols/notes structure, the semantics-block provenance, and the constraint that 'autario refuses to combine columns of different kinds.' That turns a bare schema fetch into a predictable contract.

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 front-loaded with purpose and usage constraints, but it is long and covers many nested datasheet fields inline. Most of the detail earns its place because there is no output schema, though it could be tightened by moving field enumerations into the schema or a shorter form.

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 carries the full burden of explaining what the agent will receive, and it delivers: datasheet subfields, enumerated shape values, role mapping, cadence, cardinality, level_mix, ignore_cols examples, semantics provenance, and the combining restriction. An agent can call this tool and interpret the result without guessing.

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 explains dataset_id and format, including the format enum and the toon/compact/json tradeoffs. The main description adds no parameter-level meaning beyond the overall return contract, so the baseline 3 applies.

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 and resource: 'Get the column names, data types, total row count, AND a machine-legible datasheet for a dataset.' It also frames the tool's role against siblings ('Always call this before query_dataset') and clarifies the single_series case, so an agent can distinguish it from get_dataset_info, query_dataset, and get_entity_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?

It gives an explicit precondition: call before query_dataset and before charting, and states why (know columns / datasheet tells how to plot). It also names the alternative for single_series datasets ('query_dataset, not get_entity_data'), which is exactly the kind of routing guidance an agent 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?

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint false), the description adds meaningful behavioral context: the tool is read-only and never auto-fixes, fixes must be done by a human or an engine change, and the caller must be OAuth-authorized as the autario curator account or receive a permission error. It also says the report matches /admin/health and /admin/storage but is provided as data rather than screenshots. This is valuable behavioral disclosure that annotations alone do not 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 dense but front-loaded with the admin-only warning and the core purpose, and every major section (contents, behavior, auth, use cases) adds value for a complex admin tool. However, the single long paragraph packs many clauses together and could be tightened slightly. For example, 'This is the same report... as data you can reason over instead of screenshots' could be shortened. Still, it is appropriately informative for a tool with no output schema.

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?

This is complete for a complex admin-only health tool with no output schema. It covers access requirements, permission failure mode, the full inventory of report sections, the read-only no-auto-fix behavior, the trends option, and the exact questions that should trigger its use. An agent can confidently decide when to call it and what to expect without needing additional context from siblings or structured metadata.

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 three parameters are fully described in the input schema at 100% coverage, so the description does not need to repeat their mechanics. The description reinforces the purpose of trends ('did my change help?') but adds little beyond the schema's own explanation of trend_days and format. This matches the baseline 3 for high schema coverage.

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

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

The description states a specific verb and resource: get the machine-readable health report of autario's ingest engine. It enumerates the exact contents (ingestion funnel, dirty backlog, shadow-column coverage, per-provider health, failure patterns, queue state, alerts) and clearly marks it as ADMIN/CURATOR ONLY, which distinguishes it from general data tools in the sibling list. This is far from a tautology and leaves no ambiguity about 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?

The description provides clear trigger phrases ('how is the engine doing', 'what is broken', 'did the last fix work') and states that only OAuth-authorized autario curator callers can use it, with all other callers receiving a permission error. It also contrasts the tool with /admin/health and /admin/storage by emphasizing machine-readable output. It does not explicitly name sibling MCP tools as alternatives, so not a full 5, but the context is strong.

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 establish the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), and the description adds substantial behavior beyond that: the default response is a pre-computed indicator.stats block rather than raw rows, full=true switches to heavy wide data[] rows, and the join occurs automatically via shadow columns. The concrete token economics (17,000 raw rows down to roughly 200 tokens) is unusually honest about cost behavior.

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

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

The core capability is front-loaded in the first sentence and the description follows a logical flow: capability, default output, full option, parameter sourcing, then cost rationale. It is dense but organized; the closing TOKEN PRECISION paragraph partially repeats the heaviness warning from the full=true sentence, though the concrete 17,000-to-200-token comparison keeps it informative rather than redundant.

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 carries the full burden of explaining the return shape — and it delivers: it names every indicator.stats field (n, min, max, avg, first, latest, latest_change_pct, range_change_pct), row_count, x_range, per-value provenance, and even gives an example wide row ({time:'2020', gdp:3846, unemployment:3.8}). Combined with prerequisites, conditional behavior, and cost guidance, nothing an agent needs to call this tool correctly is missing.

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%, setting the baseline at 3, and the schema's own parameter descriptions are already strong (especially for full). The description adds real value on top: entity_id is enriched with the ISO-3166-vs-aggregate taxonomy ('EUU'/'WLD' beyond the schema's 'DEU'/'USA'), and the token-precision guidance ties the time and full parameters to concrete cost consequences.

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 and resource: 'Fetch data for ONE entity across MULTIPLE indicators, joined automatically on time via shadow columns.' It scopes the capability further ('even when the indicators come from different publishers') and brands it as the 'cross-dataset join' capability with no manual relationship setup needed, which clearly separates it from siblings like query_dataset or compare_entities. An agent can tell exactly what this tool is for without opening the 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?

Provides clear decision context: use the default summary output to answer 'current/highest/average value' questions, pass full=true only for plotting/export, and source entity/indicator IDs from list_indicators/get_entity_profile. The capped 'ONE entity' emphasis and cross-dataset-join framing imply exclusions, but no alternative tool is named for the when-not-to-use cases (e.g., multi-entity comparison via compare_entities), so it stops short of explicit routing.

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 declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: it requires authentication, is read-only with no cost, consolidates multiple app contexts into one call, and prevents dataset guessing. It does not detail potential size limits or failure modes, but the core behavioral traits are well disclosed.

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 longer than average and includes some stylized claims ('THE first call', 'no dataset guessing'), but the content is front-loaded with the concrete resource and return items, and nearly every clause carries selection-relevant information. The format and drill-down guidance justify the length.

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

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

For a tool with no output schema, the description provides a detailed inventory of what is returned: every activated/connected app, platforms, connector-backed tables with dataset_id/slug and row count and last refresh, saved artifact list, and a ready-to-run query example. It also states authentication requirements, read-only behavior, and appropriate next-step tools, making it complete for agent invocation.

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

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

The only parameter is format, and the input schema covers it completely with enum values, defaults, and descriptions for 'toon', 'compact', and 'json'. Since schema_description_coverage is 100%, the description does not need to add parameter detail, 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 states a clear verb and resource: it returns the calling user's entire workspace in one call, enumerating apps, platforms, connector-backed tables, saved artifacts, and a runnable query example. It also differentiates from siblings by naming get_app_context, get_app_artifact, and query_dataset, making its scope unmistakable.

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

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

The description is explicit about when to use it: 'THE first call when a user references "my <app>", "my dashboard", "my report" or asks what they have on autario'. It also routes to alternatives, saying to drill down with get_app_artifact(app_id, slug) or query_dataset(dataset_id) for rows, and explains that it replaces per-app get_app_context calls.

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, and the description adds substantial behavioral context: admin-only access, human-only page-view/funnel numbers, exclusion of own-pipeline renders and generic bots via bot_or_own, and a separate llm_crawler breakdown. No annotation contradiction exists.

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 admin-only gate and the core promise, but it becomes a dense run-on paragraph full of parenthetical detail, and it says 'three real signal sources' while listing more than three items. Bullets or clearer separation would make it easier 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?

For a zero-parameter report tool with no output schema, the description is unusually complete: it lists all report sections, data sources, metric definitions, and exclusion logic. An agent has enough information to invoke the tool correctly and interpret what it returns.

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 and the schema covers that fully, so parameter semantics are not a real burden. The description instead explains what the no-argument call returns, which is the appropriate compensation.

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 admin/curator-only report of autario's own traction, and enumerates the concrete signal sources: human reach, MCP/agent usage, signup funnel, activation metrics, and LLM crawler activity. This specificity makes it easy to distinguish from sibling analytics tools like audience_360, seo_360, or ai_visibility_360 without opening their schemas.

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 clear context for when the tool is appropriate: a single consolidated traction report for admins/curators, with no arguments required. It does not explicitly mention sibling alternatives or exclusion conditions, so it stops short of the highest 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 the tool read-only, idempotent, and non-destructive, so the description does not need to repeat that. It adds useful behavioral interpretation: peak |r| at positive lag means A precedes B by that many periods, and the list of supported data sources clarifies scope. No contradiction with annotations exists.

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 three sentences with no wasted words. The core statistical behavior is front-loaded, followed by a concrete interpretation rule and a practical use case. The data-source enumeration is useful and not overly verbose.

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 analytical tool with no output schema, the description explains the primary result semantics (peak correlation and lag direction). It would benefit from a note about what the full returned output looks like or how missing data is handled, but the current description is sufficient for an agent to select and invoke it correctly in most cases.

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

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

Schema description coverage is 80%, and the schema already documents the key parameters including 'a' as candidate leading series, 'b' as candidate lagging series, entity, and max_lag. The description adds a little semantic value by explaining the lead/lag interpretation and the indicator-source domain, but it does not meaningfully elaborate on the individual parameters 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 states a specific statistical operation ('Cross-correlation at multiple lags') and the exact question it answers ('does A lead or lag B?'). This clearly distinguishes it from the sibling 'correlate' tool, since it focuses on lagged relationships rather than contemporaneous 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 common-use example, 'is consumer confidence a leading indicator of retail sales?', effectively illustrates when to apply the tool. The specification that it runs on verified autario indicators also sets input expectations. However, it does not explicitly say when not to use it or name an alternative such as 'correlate' for non-lagged relationships.

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 safety profile is covered. The description adds valuable behavior beyond that: connected=true/false only appears when authenticated, data_scope distinguishes private vs public datasets, and it notes 'Read-only, no cost'. 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 front-loaded with the purpose and output fields, then adds necessary definitions of data_scope and connected, then closes with routing guidance. It is long but every sentence earns its place by reducing ambiguity for an agent choosing and invoking the tool.

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

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

There is no output schema, so the description's enumeration of returned fields (id, name, what it does, URL, data_scope, connected) is essential and sufficient. It also explains the authentication-dependent connected behavior and points to get_app_context for deeper detail, making the tool fully callable without additional lookups.

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 only parameter, format, is fully documented in the input schema with an enum, default, and format explanation, so schema coverage is 100%. The description itself adds no parameter-specific meaning, and none is needed; baseline 3 applies.

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 a specific verb and resource: 'List the autario data apps (the app catalog)' and enumerates the returned fields: id, name, description, live page URL, and data_scope. It distinguishes itself from siblings by naming get_app_context as the follow-up for a single app's data map.

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 explicitly tells the agent when to start here ('when a user mentions an app by name... or asks what apps exist') and routes to the alternative: 'then call get_app_context(app_id)'. This is clear context with an explicit next-step and no ambiguity.

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 openWorldHint=false. The description adds meaningful behavioral context beyond those: the server applies the same chartability gate as request_chart, every result carries chartable_reason, and auth restrictions produce a 403 for non-admins. No contradiction with annotations exists.

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 efficient; nearly every sentence adds distinct value such as auth, filtering, workflow, and return fields. Minor redundancy exists between "admin only" and "Non-admin keys receive 403," and the opening label is slightly verbose, but overall it is well-structured and 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?

With no output schema, the description compensates by naming all returned fields (dataset_id, chartable, chartable_reason, title, publisher, topic, unit, quality_tier). It also covers auth behavior, filtering semantics, ranking, and the follow-up pipeline, making the tool fully actionable for an agent without needing additional context.

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

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

Schema description coverage is 100% for the single limit parameter, including default and max values, so the description does not need to add much. It contributes only the context that results are ranked by relevance, which is implied but not schema-documented. This matches the baseline-3 expectation when the schema already fully describes parameters.

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 a specific verb and resource: list catalog datasets with no published chart yet, pre-filtered as chartable and ranked by relevance. It clearly differentiates this tool from sibling tools like list_charts (published charts) and request_chart (single dataset request) by framing it as the internal 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?

It explicitly states the tool is admin-only, that non-admin keys receive 403, and that third parties do not need it. It also gives a direct workflow for each returned dataset (request_chart preferred, otherwise get_dataset_info -> get_dataset_schema -> query_dataset -> create_chart_from_spec) and explains why the queue avoids the no_usable_series / sparse_multi_entity_data failures of request_chart.

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 readOnlyHint, idempotentHint, destructiveHint, so the bar is lower. The description adds useful behavioral context beyond annotations by specifying data sources (World Bank, FRED, etc.), rendering library (Plotly), and the exact return contents (chart IDs, titles, insights, linked datasets, creation dates).

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

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

The description is compact and front-loaded with the core action, then adds relevant source context and usage guidance. Every sentence contributes value; the data-source list is slightly verbose but helps set expectations about chart coverage.

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 still explains what is returned and how to use the results. It covers the tool's purpose, scope, return fields, and typical use cases, making it complete for a read-only listing tool.

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

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

The input schema already has 100% description coverage for all four parameters, including q, limit, format, and offset. The description does not add new parameter-level meaning, so the 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 begins with a specific verb and resource—'List published chart visualizations on Autario'—and clearly separates this from siblings like get_chart (singular retrieval) and list_chart_candidates (candidate charts). It also enumerates the returned fields, making the tool's purpose immediately identifiable.

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 this tool 'to discover existing analyses before building a new one' and to 'find a shareable autario.com/chart/{id} link for an answer.' This provides clear usage context, though it does not explicitly name alternative tools or state when not to use it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description does not contradict them. Beyond the annotations it adds concrete behavioral context: the returned entries carry live dataset_id and datasets[] with per-report materialization, refresh interval/last refresh time, the fact that connector creation happens in the Autario UI, and the API key requirement. These details are meaningful for a no-parameter tool.

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

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

The description is several sentences long but every sentence earns its place: purpose, use cases, return structure, and operational context. The pipe-delimited formatting packs information compactly. It is slightly dense and could be trimmed, but it is well front-loaded with the core purpose and stays on-topic.

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 zero parameters and no output schema, this description is exceptionally complete. It explains what each returned entry contains, how to use the dataset_id with query_dataset, when to call it, who creates connectors, and the credential/API-key boundaries. There are no missing operational details an agent would need to invoke this tool correctly.

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

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

The tool has zero parameters, so the schema coverage is 100% and there is nothing for the description to add about parameter semantics. Per the rubric baseline, a 4 is appropriate when no parameters exist; the description instead usefully explains what the response conveys (dataset_id, datasets[], refresh metadata), which belongs more to completeness than 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 opens with a specific verb and resource: 'List the platform connectors set up on this Autario account', then enumerates the connector categories (search, web, ads, etc.). It also distinguishes this tool from refresh_connector and names the alternative for querying the resulting dataset_id. This fully separates it from siblings without needing the 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?

The description gives explicit trigger phrases ('my Search Console data', 'my ad spend', 'my store orders', cross-platform weekly report) and states when to prefer it: 'call this instead of guessing which ones exist.' It also clarifies what this tool does not do ('never handles credentials') and points to refresh_connector for refresh operations, providing both when-to-use and an implicit when-not.

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 readOnly, idempotent, non-destructive, and the description adds behavioral context beyond that: it's a browse/discovery operation over a registry, and it returns indicator IDs. It does not describe pagination or ordering, but with the safety profile covered by annotations, this is sufficient.

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 deliver the resource definition, available attributes, and usage guidance with a sibling comparison, all without filler. The information is front-loaded in the first sentence.

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 discovery tool with seven optional parameters and no output schema, the description gives enough context about what the registry contains, why to use it, and how the IDs feed into other tools. It does not spell out the response format, but that is a minor gap for this read-only browse 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 every parameter is already described in the schema. The description repeats the semantic meaning of topic, unit, frequency, entity_type, and publisher, but does not add new format or constraint details, so it stays at the baseline.

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 and resource — 'Browse the Autario indicator registry' — and explains it is a semantic layer over major public catalogs. It lists what each indicator includes and explicitly contrasts itself with search_datasets, so an agent can distinguish 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?

It states the exact use case: 'discover what data is available before querying it, and to get the indicator IDs' needed by other tools. It also provides a clear alternative rule: 'Much more precise than search_datasets when you know what topic, publisher 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?

The description goes well beyond the readOnly/idempotent/non-destructive annotations by disclosing exact operational behavior: no currency conversion, no attribution deduplication, absence instead of zeros for no-report days, null ratios when the denominator is missing, and explicit error/empty-state behavior. This makes call outcomes highly predictable before invocation.

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 text is front-loaded with purpose and call triggers)Skip and uses labeled sections for scope and honesty rules Mend, which helps navigation. It is dense and somewhat long, with some repetition (e.g., 'one brand per call' appears more than once), so it earns high marks without being perfectly minimal.

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 present, the description fully compensates by enumerating all report sections (overview, channels, campaigns, daily), defining the metrics, explaining ratio semantics, and covering format choices, errors, and prerequisites. Everything needed to invoke and interpret the report is 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?

Even though the schema already documents every parameter, the description adds meaningful layer: default brand behavior, deprecated client alias, section-selection guidance for token efficiency, instance ownership errors, and fallback behavior for unusable custom dates. These details materially improve correct parameter choice beyond the raw schema.

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

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

The description names a specific resource — the caller's own brand marketing report — and pins it to a concrete server-side source (marketing_daily) and exact metric definitions. It is clearly distinguishable from sibling analytics tools by scope (own brand), data domains (Meta, Google, TikTok, Shopify, Amazon, GA4), and the deterministic/no-LLM guarantee.

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 gives explicit invocation triggers with example user questions, such as 'how did brand X do last week' and 'which campaign has the best ROAS'. It also states when not to expect an answer: non-caller brands error, unconnected accounts return a named empty state, and multi-currency totals become null rather than converted.

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 the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the description does not need to repeat that. It adds useful scope context—'runs on any verified autario indicator'—but it does not disclose that by default only summary statistics are returned, which is a meaningful behavioral trait beyond the annotations.

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

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

The description is compact, front-loaded with the core purpose, and uses examples efficiently. Every part adds value, and the pipe-separated examples make the usage pattern immediately understandable.

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 several undocumented parameters, the description is incomplete for safe invocation from scratch. The `time` parameter is entirely unexplained, and the description does not describe what the output looks like or how much data is returned by default.

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 only 40%, so the description needed to compensate for the undocumented parameters (entity, time, indicator). It somewhat clarifies indicator scope but does not explain the `time` parameter at all, and entity is only implied by the example 'German GDP' rather than explicitly defined.

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, with concrete examples like YoY/QoQ/MoM growth rates. It is specific about the operation and resource, but it does not explicitly differentiate itself from sibling analytics tools like rolling_stats 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 gives clear use cases ('Use for growth rates') and example queries ('how fast did German GDP grow'), which tells an agent when this tool is appropriate. It does not, however, name alternatives or state when NOT to use it.

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

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

Annotations are sparse (only readOnlyHint, openWorldHint, idempotentHint, destructiveHint, all false), so the description carries the burden. It discloses determinism ('no LLM on this path'), derivation rules (due date, status, parent progress), the value rule (never both manual and dataset, null with reason never zero), approval-flow stage behavior, and hard constraints like currency non-conversion and max nesting depth.

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?

Although long, the description is front-loaded with purpose and organized into clear sections (PROJECTS, OBJECTIVES, THE VALUE RULE, NEVER). Each section earns its place by covering a distinct aspect of behavior, and the length is justified by the tool's 41-parameter complexity and absence of an output schema.

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 explains what each action returns ('list' folds the board on one axis, 'get' returns one project with milestones and KPIs, 'objectives' returns every objective with key results and derived status). It also covers auth requirements, error-ish behavior (foreign id answers not found, loop refused), and important exclusions, making it sufficiently complete for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning not in the schema: the EITHER/OR value rule for KPIs and key results, the relationship between guards_id and the guarded key result's status, and the derived behavior of sort and parent progress. This helps an agent choose between manual_value, dataset_id/value_column, and key_result_id correctly.

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 project board with its objectives and key results', and enumerates the exact queries it answers ('what is my team working on', 'which key result has no project behind it'). It clearly scopes to the caller's own account and explicitly says it never reaches another account, distinguishing it from broader analytics 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?

It gives explicit call triggers ('Call it for...'), a full list of actions, and a 'NEVER' section that states what the tool does not do (never derives traffic light, never invents a key result, never reaches another account). It does not name sibling tools as alternatives, but the when/when-not guidance is otherwise strong.

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, the description discloses meaningful behavioral details: the action takes effect immediately, has no review queue, returns public_url, and the published app is deliberately not search-engine indexed. These details are not inferable from the schema or annotations and help the agent anticipate side effects.

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-organized, front-loading the core action and then covering timing, visibility modes, return value, SEO caveat, and usage trigger. A few phrases like 'next to AI Visibility 360 and the World Bank and FRED data surfaces' are illustrative but not essential, keeping it from a perfect score.

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 two-parameter, no-output-schema tool, the description is complete: it explains when to use it, what each visibility mode does, what it returns, the immediate effect, the non-indexing caveat, and how to reverse it. No critical behavioral information is missing.

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 both parameters fully, but the description adds valuable semantics for the visibility enum by explaining what each value means in practice: public gives a store tile plus URL, unlisted gives link-only access. The app_id parameter is not further enriched, so this is strong but not perfect.

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: 'Publish an app YOU own,' with a specific verb and resource. It goes further to distinguish publishing modes (public vs unlisted) and explicitly names the reversal sibling, unpublish_app, so an agent can separate it from publish_chart and other app-related tools.

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

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

The description gives an explicit trigger: 'Use it when the user says the app is ready to share.' It also explains that unpublish_app reverses the action, and the public/unlisted distinction provides decision guidance for different sharing intents.

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 only indicate it is not read-only, not destructive, and not idempotent. The description adds meaningful context: the requirement for AUTARIO_API_KEY and the verification gate. This goes beyond the annotations by clarifying auth needs and operational constraints, though it does not describe the exact side effects (e.g., whether it overwrites or creates a new chart) or the response format.

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

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

Three sentences, front-loaded with the primary purpose and the alternative. Every clause earns its place: the 'unless' clause defines scope, and the API key and verification-gate note add crucial operational constraints without fluff.

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

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

The description covers the purpose, the key alternative, and important constraints. It does not describe the return value or explicit side effects, but for a publishing tool with no output schema, the essential information for an agent to decide and invoke is present. The schema handles parameter details, so this is adequately 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 description coverage is 100%, so every parameter is already documented in detail. The description references the Plotly spec structure but does not add new semantic meaning beyond what the schema provides. Baseline 3 applies because the schema carries the parameter burden and the description adds little extra.

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

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

The description opens with a clear verb-resource pair ('Publish a chart') and a specific method (freeform Plotly spec). It immediately distinguishes itself from the sibling create_chart_from_spec, so an agent knows exactly what this tool does and how it differs from the nearest 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 names the preferred alternative ('Use create_chart_from_spec instead') and lists the exact conditions where this tool is appropriate (custom shapes, multi-axis layouts, animation frames). It also states the API key requirement and notes that brand attribution and insight verification gates apply, giving clear selection criteria.

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 idempotentHint=true, so safety is covered. The description adds meaningful behavioral context: aggregates stay numerically correct on text-stored values, token usage vs. raw row volume is called out explicitly, autario refuses to combine columns of different kinds, and the return shape (rows + per-category stats) is stated. These are behaviors the annotations cannot convey.

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 longer than most but is front-loaded with the core purpose and organized into scannable sections via pipes and bolded directives. Every clause earns its place, with concrete examples embedded (e.g., 'average GDP of Germany 2010-2020'). It is dense but well structured; a slightly tighter formatting would earn a 5.

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

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

Despite having no output schema, the description explains what is returned (rows as JSON plus statistics, or only the summary with summary_only), gives a full workflow hint (call get_dataset_schema first), and supplies both performance and correctness context. For an 11-parameter tool, an agent has everything needed 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?

Input schema covers all 11 parameters with descriptions (100% coverage), so the baseline is 3. The description goes further by giving usage advice for those parameters: use summary_only to avoid raw rows, non_null_only to drop empty rows, aggregate aliases in sort, and remember the semantics block before combining columns. This is additive, not merely restating 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 opens with a specific verb-resource pair ('Query the rows of ONE dataset') and enumerates exactly which data sources are covered (World Bank, FRED, Eurostat, OECD, WHO, IMF, ECB, US Census, SEC, uploads, connectors). It also names the sibling alternative (get_entity_data) and what makes it different, so an agent can distinguish without reading further.

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 routing: 'Reach for get_entity_data instead when you want ONE entity across SEVERAL indicators joined on time.' It also gives a prerequisite step ('Call get_dataset_schema first') and a token-efficiency rule ('Prefer aggregations or summary_only over pulling raw rows'). These are concrete, actionable usage conditions.

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 state destructiveHint=true and readOnlyHint=false, so the mutation behavior is declared. The description adds valuable context beyond annotations: the operation is 'deterministic fetch, no LLM cost,' requires AUTARIO_API_KEY, and returns row count and dataset_id. It also implies the table content is refreshed (overwritten), aligning with destructiveHint. No contradiction with annotations; the description enhances the safety/reliability picture.

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 of about four sentences, each serving a purpose: main action, scope, return value and follow-up, usage triggers, prerequisites and auth. It is front-loaded with the core function and avoids fluff. Slightly verbose in the middle, but efficient overall. It earns 4 because the information-to-length ratio is strong but could be tightened.

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?

This tool has only one required parameter, no output schema, and no nested objects, so complexity is low. The description covers everything an agent needs: what it does, when to use it, prerequisites, how to get the connector_id, what it returns (row count, dataset_id), how to consume the result (query_dataset / get_dataset_schema), auth, and determinism. No missing critical detail for correct invocation.

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

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

Schema description coverage is 100% for the only parameter, connector_id. The description reinforces its meaning by stating where to get it ('from list_connectors') and adds the prerequisite that the connector must already exist (owner sets it up at autario.com/manage). This goes slightly beyond the schema by explaining the id's provenance and setup requirement, earning a 4 rather than the baseline 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 opens with a specific verb and resource: 'Pull the latest numbers from one connected platform right now and refresh its hosted Postgres table on Autario.' This clearly distinguishes the tool from siblings like list_connectors (which lists connectors) and query_dataset/get_dataset_schema (which read datasets). It also generalizes across connector types (Search Console, Shopify, ads accounts, AI usage bills), making its scope 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?

Explicitly says when to use it: 'Use when the user says "get the latest" or wants fresh data before analysis or a cross-platform weekly report.' It also provides a prerequisite and points to the alternative tool for getting the connector_id: 'get the connector_id from list_connectors.' The condition that the connector must already exist (set up in the UI) is a clear exclusion for when not to use it. This is comprehensive routing 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 cover read-only, idempotent, and non-destructive behavior. The description adds useful behavioral context beyond annotations by stating the return payload (slope, intercept, R², interpretation) and the supported data sources (World Bank, FRED, Eurostat, etc.), which helps agents know what to expect.

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 tight sentences convey the method, output, use case, and data source scope without any filler. The most decision-relevant information is front-loaded, and 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?

For a read-only, moderately complex statistical tool with no output schema, the description covers the essentials: what it computes, what it returns, the supported universe of inputs, and when to use it. The only notable omission is detail on the optional 'time' parameter, but the core invocation path is well specified.

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 60%, with descriptions for x, y, and full but not for time or entity. The description clarifies the roles of x and y via the formula 'y ~ x' and implies entity is a single country/region, but it does not explain the 'time' parameter at all, leaving a clear gap.

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 names a specific statistical method ('Linear regression of y ~ x'), the resource ('one entity'), and the concrete outputs (slope, intercept, R², interpretation). It also differentiates from sibling tools like correlate by emphasizing prediction ('how does X predict Y?') and the single-entity scope, making it clear when this tool is the right choice.

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: 'Use for "how does X predict Y?" questions.' This gives clear context for invocation, though it does not explicitly mention when not to use it or name alternative tools for correlation or lag-based questions.

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 the annotations (readOnly=false, idempotent=false) by disclosing deduplication semantics (no duplicate rows, occurrences counter, escalation after three reports), routing of safe types to automatic re-ingest, and the authentication requirement. This is exactly the kind of behavioral nuance an agent 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?

Dense and front-loaded; every sentence carries information. The logical flow is strong: purpose → trigger conditions → evidence requirement → routing → repeat behavior. Slightly wordy and leans on ALL CAPS emphasis in three places, but nothing is wasted.

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 reporting tool with routing, deduplication, and escalation, every behavioral aspect an agent needs is covered: evidence requirement, safe-type routing, duplicate handling, escalation threshold, and auth. No output schema exists, so the mention of `occurrences` in the response is sufficient return-value guidance.

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

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

Schema already documents all 5 params at 100% coverage, so baseline is 3. The description adds operational value by mandating concrete numbers in `evidence` with examples, and by mapping real-world symptoms to finding_type categories (partial_ingest, unit_mismatch, zero_variance, etc.), which clarifies usage beyond the schema's field 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?

States a specific verb (Report) + resource (data-quality problem in a dataset or chart), enumerates concrete issue categories, and is unmistakably distinct from query/read siblings like get_engine_report or query_dataset. The first sentence alone gives a complete mental model.

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 scopes the tool to 'during a QA pass' and lists five concrete trigger conditions (truncated dataset, unit contradiction, bad labels, zero-variance column, misleading chart, stale data). It even provides a when-not-to guideline: 'only report again if you observed the problem again.'

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

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

With annotations giving only generic hints and no readOnly/destructive guidance, the description carries the behavioral burden and delivers richly. It discloses the two-step prepare/publish flow, that the prepare call does NOT publish, that the publish call verifies numbers, that the server runs no LLM, and that rejects return 422 with failing claims and anchors.

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 long and uses heavy capitalization, but the tool has a genuinely complex two-step flow, six optional parameters, auth constraints, and verification behavior. Nearly every sentence earns its place; it could be lightly restructured for readability without losing information.

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

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

Given the tool's complexity and lack of an output schema, the description is complete enough for an agent to invoke it correctly. It covers auth, the prepare/publish protocol, what the server returns, the number-hallucination gate, error response contents, and the relationship to sibling tools.

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

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

Although schema coverage is 100%, the description adds crucial parameter semantics beyond the schema. It explains that insight must be omitted on the prepare call and sent on the publish call, that every cited number must come from charted_entities, and that time/region/chart_type are soft preferences while dataset_id wins 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 states a specific verb and resource: it requests a high-level chart that the server builds from a catalog dataset, with the user writing only the insight. It clearly distinguishes this from create_chart_from_spec by saying you do NOT build a Builder spec, so an agent can tell siblings apart.

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 explicitly tells the agent when to use this tool over create_chart_from_spec: whenever a good chart is wanted without assembling a full Builder spec. It also gives exclusions and alternatives: non-admin keys receive 403 and third parties should use create_chart_from_spec / publish_chart.

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 disclose readOnly, idempotent, and non-destructive behavior, so the description's additive burden is lower. It adds useful context about the heavy full-output option and that default output is summary-only, but it doesn't mention window behavior at edges (e.g., how missing periods are handled) or the exact response shape. 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 sentences, front-loaded with what the tool does, followed by a clear usage directive and a scope qualifier. The 'Smooths noise, reveals trends | use it before...' phrase is slightly informal but information-dense and not redundant.

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 a read-only, no-output-schema tool with 6 params and 50% coverage, the description states the use case, supported sources, and default summary behavior. It does not clarify the meaning of required 'entity' and 'indicator' or the 'time' param, so an agent may still be uncertain how to fill required fields 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 50%: the schema already documents op, full, and window, leaving entity, indicator, and time with only names. The description reinforces that op values are mean/std/min/max/sum and multi-sources, but it adds little detail beyond the schema for the undocumented params.

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?

States a specific verb and resource (rolling window statistics for an indicator) and lists the available operations (mean/std/min/max/sum). Distinguishes itself from siblings like pct_change, lag_analysis, and correlate by the windowing concept and its stated 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?

Explicitly tells the agent when to use it: before claiming a turning point in a monthly FRED or Eurostat series. Also names the data sources it runs on, which implicitly says when it applies, and the 'verified autario indicator' qualifier sets a usage condition.

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/destructive hints, the description discloses meaningful behavior: private datasets are only returned to authenticated owners, other users' private data is never returned, ontology fields are present only when confidence is high, and token-precision semantics are described. It also enumerates exact return fields, which matters because there is no output schema.

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 long but dense and front-loaded: the core action appears first, followed by return fields, auth scoping, routing to alternatives, and a token-precision tip. The source and connector lists are extensive but earn their place by clarifying catalog scope; nothing feels redundant.

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 search/discovery tool with no output schema, the description covers the needed ground: what the search matches, what fields are returned, visibility rules, precise alternatives, and token economy. Combined with the annotation safety profile and full parameter schema, an agent has enough to invoke it correctly.

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

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

All six parameters already have rich descriptions in the input schema, covering 100% of schema fields, so the baseline is 3. The description reinforces the keyword concept and the auth-dependent visibility default, but it does not add material parameter details 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 first clause states a specific verb, resource, and action: 'Search the Autario data catalog by keyword'. It also explicitly differentiates itself from sibling tools list_indicators and discover_by_topic, so an agent can select it confidently.

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 says 'Use this first to discover available datasets before querying' and gives explicit routing rules: prefer list_indicators for precise topic/unit/frequency filtering and discover_by_topic for topic-driven article research. It also clarifies when private datasets are included, giving clear when-to-use and when-not-to-use 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 mark the tool as read-only, idempotent, and non-destructive, so the description does not need to repeat that. It adds useful behavioral context by specifying the additive model type, that it returns per-timepoint components plus summary amplitude, and that it runs on verified autario indicators, which goes 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 compact and front-loaded with the key formula and purpose. The parenthetical list of data sources adds somewhat more detail than strictly necessary, but it is still a short, readable description with no wasted 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?

The description covers the model, use case, return values, and supported data sources, which is solid for a read-only analytical tool. However, with no output schema and two required parameters undocumented in both the schema and description, there are meaningful gaps around how to specify the input series and interpret the returned components.

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 only 40%, and the description partially compensates by explaining what 'indicator' accepts (verified autario data sources) and what kind of output the user gets. However, required parameters like 'entity' and the optional 'time' parameter are left undocumented in both the schema and description, so the description does not fully make up for the coverage gap.

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 a specific mathematical operation ('Additive decomposition Y = trend + seasonal + residual') and a concrete use case ('strip the seasonal cycle... reveal the underlying trend'). This clearly distinguishes it from sibling tools like lag_analysis or rolling_stats, and the examples (retail sales, unemployment) further anchor what it 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?

The description says 'Use this to strip the seasonal cycle' and notes it is 'great for monthly or quarterly data', giving clear when-to-use context. It does not explicitly mention when not to use it or name alternatives, but the seasonal focus makes the appropriate context reasonably 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 readOnly=true and idempotent=true, and the description adds meaningful behavioral detail: the report is deterministic, server-side computed, uses the caller's own data as benchmark with a documented fallback, flags incomplete previous windows, and requires an authenticated autario account with GSC connection. The description doesn't contradict annotations, and the honesty-flag on trends is a genuine behavioral disclosure.

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 long, but dense with purpose and usage signal; every sentence earns its place, and the front section states the core value proposition before enumerating sections. It loses one point for length and the dense enumeration of section names that could be slightly tightened, but for a complex multi-section tool this length is justified.

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, idempotent report tool with zero required parameters and full schema coverage, the description fully covers what the tool does, when to use it, what data it consumes, its authentication requirement, its sections, and its edge-case behaviors (incomplete prior window, benchmark fallback). No output schema exists, but the description's section list effectively tells the agent what the report will contain.

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 (days, format, sections) are fully documented in the schema. The description adds context for the 'sections' default and the token-efficiency guidance, but it doesn't significantly extend parameter meaning 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 specifies an exact resource (the caller's own deterministic Google Search Console ACTION report), the computation method (server-side from connected GSC data), and a precise analytic unit ((query, page) pairs with concrete actions). It lists ten named sections mapping to specific user questions, which strongly distinguishes it from sibling tools like audience_360 and social_360.

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 enumerates trigger questions ('what should I write next', 'which page should I fix first', etc.), distinguishes itself from audience_360 ('deeper than audience_360'), lists which sections map to which intents, and even instructs the agent to request only needed sections. Sibling differentiation is explicit 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description adds substantial behavior: 'nothing re-derived, nothing estimated', 'a component the platform cannot report is DROPPED and the weights renormalized', 'a missing number is never read as a zero', 'hedged by design, never a claimed cause', and 'an id that is not yours... answers an error rather than a quietly shorter report'. 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 front-loaded with purpose and is very comprehensive, but it is extremely long and duplicates schema content (e.g., the sections parameter description is essentially repeated in the prose). While every sentence carries useful information, the overlap with the schema and the wall-of-text format keep it from being concise.

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 and the absence of an output schema, the description covers all necessary context: platform coverage, section-by-section semantics, limitations (e.g., Facebook/TikTok geo not available), edge cases (unconnected platforms, invalid instance ids), auth requirements, and the distinction from audience_360. Nothing an agent needs to select and invoke this tool correctly is missing.

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% – every parameter has a detailed description, including enums. The tool description does not add significant new parameter-level meaning; it largely repeats the schema's section definitions. Since the schema does the heavy lifting, a 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 opens with a specific verb+resource: 'the caller's OWN deterministic social performance report over their connected Facebook Page, Instagram, TikTok, YouTube and LinkedIn data, computed server-side'. It explicitly distinguishes itself from a sibling: 'Deeper than audience_360 (which answers "who comes from where")'. This makes the tool's role unmistakable.

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

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

The description provides concrete trigger questions ('how are my social accounts doing', 'is my account growing', 'which post worked best') and says 'Call it when a user asks...'. It also names the alternative audience_360 and explains the difference in scope. Auth requirements and connector prerequisites are also stated.

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 mutating and destructive behavior, but the description adds valuable context far beyond those hints: the public URL stops working, the preview URL remains accessible to the owner, data connections continue to function, nothing is deleted, and the operation is reversible via publish_app. This gives the agent an accurate mental model of the side effects.

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 no filler. It front-loads the core action and effect, then follows with explicit use-cases and reversibility. Every clause adds decision-relevant information.

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

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

For a single-parameter state-transition tool, the description fully covers what happens, what does not happen, who retains access, how data behavior changes, and how to reverse the operation. No output schema is needed because the effects are described thoroughly, and the sibling get_app_preview_url covers any URL retrieval need.

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 the single app_id parameter 100%, so the description does not bear a heavy compensation burden. It adds the useful ownership qualifier ('an app YOU own'), which helps the agent avoid using arbitrary app IDs, but otherwise does not need to explain parameter mechanics further.

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

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

The description uses a specific verb phrase ('Take an app YOU own back to private') and clearly identifies the resource and its effects: removal from the app store, public URL stops working, and the app remains available at the preview URL. It also explicitly distinguishes the action from publish_app, which is named as the reverse operation, making sibling differentiation effortless.

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 it: when a user wants an app off the store, or before shipping a change not meant for public view. It also names the inverse alternative, publish_app, making the decision boundary clear without requiring the agent to infer anything.

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 annotation hints, it discloses partial-update semantics ('Only the fields you pass change'), ownership behavior ('app you do not own answers not found'), runtime enforcement by the sandbox bridge, and the sharing restriction when share was never declared. This all aligns with readOnlyHint=false, idempotentHint=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?

The description is dense and front-loaded with the core purpose, which suits a complex nested-parameter tool. However, it is one long continuous paragraph with many parenthetical asides and compound clauses, which makes scanning slightly harder than a more structured layout would.

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 9-parameter mutation tool with nested objects and no output schema, the description provides everything needed to decide when to call it and how to invoke it correctly: ownership rules, field scope, examples for complex params, runtime enforcement, and the sibling tool that handles publishing.

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 schema coverage is 100%, the description adds meaning the schema alone lacks: consumed_datasets gets concrete op/dataset examples and connector behavior, share gets subject/section semantics and the 'never declared cannot be shared' rule, and tier is contextualized via the sandbox runtime model.

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 and resource: 'Update the manifest of an app YOU own', then enumerates exactly which fields are affected. It also differentiates from siblings by stating that publishing is deliberately handled by publish_app, so an agent cannot confuse manifest updates with access control.

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 gives explicit use cases: declaring data access after create_app, enabling secret-link sharing, and renaming or re-pointing an existing app. It also states exclusions clearly: apps you do not own answer 'not found', and this tool never changes who may open the app — that is publish_app's role.

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 destructiveHint=true and idempotentHint=true, so the description's added value is the ownership restriction and the implied requirement that the chart exists. It doesn't contradict annotations and adds useful context beyond them.

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

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

Two sentences with no filler. The primary action and key constraint are front-loaded, and every clause 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?

Covers ownership, what can be updated, and that the chart is already published. However, it omits the 'narration' parameter from the list of updatable fields, and it doesn't clarify that plotly_spec is required. Since the schema carries those details, this is a minor but real 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?

Schema description coverage is 100%, so the schema fully documents all parameters. The description mentions Plotly spec, title, and insight, which maps to three of five params, but adds no new meaning 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 a specific verb ('update') and resource ('existing chart you own'), and lists what can be modified ('Plotly spec, title, or insight'). It clearly distinguishes from siblings like publish_chart (creation) and get_chart (read).

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 the ownership constraint ('Only the API key that created the chart can update it') and the context ('previously published chart'). It gives clear when-to-use guidance, though it doesn't explicitly name alternatives or exclusions, which would push it to 5.

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

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

Annotations already indicate non-read-only, idempotent, and non-destructive behavior. The description adds genuinely useful behavioral context beyond these hints: the app runs in a locked sandbox with no outbound network access, data is accessed through the sandbox bridge, and re-uploading the same version replaces it in place.

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 carry useful information: purpose and constraints, runtime/security model, and recommended usage context. The description is front-loaded with the primary action 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?

For a tool with no output schema and only basic annotations, the description covers the core operational context: what can be uploaded, size limits, sandbox behavior, replacement semantics, and when to use it. It does not mention the response shape or any special permission requirements, which is a minor gap.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by defining the content parameter as a self-contained entry document with size and binary restrictions, and by clarifying version replacement 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 opens with a specific action on a specific resource: 'Upload or replace the code of an app YOU own'. It then adds concrete constraints (self-contained HTML/JavaScript, max 512 KB, no binary), which clearly differentiates this from generic upload or app-related tools.

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

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

The description explicitly states when to use the tool: 'ship a new build of an app you created with create_app, or to fix one after a user reports something.' It does not explicitly contrast with close siblings like write_app_artifact or update_app_manifest, so the exclusion logic is only partially 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 readOnly and idempotent, so the description adds real value beyond them by explaining the verdict semantics, relative difference, provenance, and the ambiguous-query fallback with candidate observations. The guidance to narrow time rather than picking a candidate is a meaningful behavioral disclosure.

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 earns its place: sources, when-to-use, required inputs, return semantics, and the edge case. The most important usage trigger is front-loaded, and the ambiguity fallback is explained efficiently at the end.

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?

Even without an output schema, the description covers purpose, invocation pattern, expected result, and a critical edge case with remediation. The input schema handles parameter formats, so nothing necessary for correct use is missing.

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 reinforces the expected-value parameter and the ambiguity issue around time, but it does not materially improve on the schema's own parameter descriptions. It also slightly implies expected is required before the schema clarifies it is optional for existence-only checks.

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 a specific verb ('Verify') and resource ('claimed value against the primary source'), and even enumerates the named sources. The explicit 'did you hallucinate that?' trigger clearly distinguishes this verification tool from data-retrieval and calculation siblings like get_entity_data or calculate.

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 tells the agent exactly when to use it: when a user questions a number or before presenting cited figures. It does not explicitly enumerate when not to use it or name sibling alternatives, but the context is clear enough that this is the verification/checking tool, not the general lookup 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to reassert safety. It adds valuable behavior details beyond annotations: confidence labels, reason strings, sharpen-suggestions, auto-aligned frequencies, and no inflated n-counts. It does not cover edge cases or failure modes, but the disclosure is strong for a read-only ranking tool.

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