Autario

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?

Even with readOnlyHint/idempotentHint already declared, the description discloses substantial behavior beyond the annotations: the compatibility refusal with error_code incompatible_semantics, the ops that WOULD work, the override+reason audit path, and the computation block attached to every result. This is far richer than the annotations alone.

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

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

Front-loads purpose and operations, then layers in the guidances and refusal semantics. Dense and mostly earning its sentences, though the trailing provider list and the repeated restatement of override/reason add some 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 an 8-param tool with no output schema, the description covers purpose, operation set, error/refusal behavior, override path, returned computation block, and provider scope. An agent has everything needed to call it correctly, including the summary-vs-full tradeoff.

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 carries parameter meaning, and the description mostly restates it (override requires reason, reason is returned). The one genuine addition is the instruction to read the semantics field before combining, but otherwise the schema does the heavy lifting – 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?

States a specific verb (Create), resource (derived series), and enumeration of operations (ratio, ratio_pct, diff, sum, product) on two named operands. This clearly distinguishes it from siblings like correlate, pct_change, and regression, so an agent can orient 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?

Gives concrete use cases (debt-to-GDP, revenue-per-employee, yield spread) and a clear path for the refused case (override=true with a reason). It does not, however, explicitly route the agent away from adjacent siblings such as pct_change or correlate, so the when-not is only implied.

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

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

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?

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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's added value is the analytic behavior: entangled candidates with VIF > 5 or |r| > 0.8 are flagged not_separable rather than ranked with 'a confident wrong number', and the 2-15 candidate bound is stated. It does not mention cost, rate limits, or runtime for large scans, but the core computational behavior is unusually 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?

Front-loads the core concept in the first clause and every sentence carries information (method, flagging rule, return fields, when-to-use, data sources, limits). It is long for a tool description and the 'weather vs promo' illustration is decorative, but nothing is padded.

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 enumerates the return payload per candidate (standardized coefficient, raw slope, p-value, VIF, pairwise r, best lead/lag), plus input limits and supported data sources. For a statistically complex tool, an agent has what it needs to invoke and interpret it.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters including time-window formats and entity omission; the baseline is 3. The description roughly restates these (2-15 candidates, omit entity for private series) rather than adding format or syntax detail 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?

States a specific verb and resource ('fits ONE multiple regression of the target on ALL candidates jointly') and explains exactly how it differs from the sibling find_drivers ('use this instead of find_drivers when candidates may overlap'). An agent can distinguish it without opening either 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 names the alternative (find_drivers) and the condition that selects this one instead (candidates may overlap, or you need honest independent effect sizes). It also names the applicable data domains, so the selection decision is fully determined.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that: it names the data-source coverage (World Bank, FRED, Eurostat, OECD, IMF, WHO, ECB, US Census, SEC) and the fact that it works on any verified autario indicator, which tells the agent the input domain.

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 operation and its output fields, then the usage directive, then the source coverage. Every sentence carries information and none is 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?

There is no output schema, but the description compensates by enumerating the returned statistics, and the schema fully documents the parameters. Combined with annotations that cover the safety profile, nothing an agent needs to call this 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%, so all three parameters (indicator, entity, time) are already fully documented in the schema, including the time-window parsing rules. The description adds only the 'single indicator+entity' scoping, which is already implied by the required parameters, so 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?

States a specific operation (summary statistics) on a specific resource (a single indicator+entity series) and enumerates exactly what is computed (n, mean, median, std, min/max, quartiles, skew, histogram). This clearly separates it from statistical siblings like correlate, regression, rolling_stats, and 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?

Explicitly tells the agent when to reach for it: 'Use FIRST before running any test so you know what the data looks like', with the rationale (sample size, completeness, distribution shape). It stops short of naming a specific alternative tool or stating when-not to use it, so it falls just below the top tier.

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, idempotentHint, destructiveHint=false, and closed-world, so the safety profile is covered. The description goes further by disclosing the return contents (r, p-value, R² per candidate), the 30-candidate cap, and the data sources it operates on. It does not discuss cost, latency, or how ties/missing data are handled, but that is a minor gap against strong annotation coverage.

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

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

Front-loads the core verb and mechanism in the first clause, then layers purpose, return format, limits, alternative, and coverage. Every sentence carries distinct information with 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?

There is no output schema, so the description correctly fills that gap by naming the returned values (ranked list with r, p-value, R²). Combined with the candidate cap, the alternative tool, and the source coverage, an agent has everything needed 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?

Schema description coverage is 100%, so all four parameters are already documented in the schema, and the description largely reiterates them (target indicator, candidates, 30 max). It adds only the framing that candidates are tested 'one at a time' and ranked, which is marginal over the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb and resource: rank candidate drivers of a KPI by correlation strength, given a target indicator plus multiple candidates. It explicitly distinguishes itself from the sibling decompose_drivers, so an agent can route correctly without opening either 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 the triggering scenario ('what moves my KPI?' questions), a hard constraint (maximum 30 candidates per call), and an explicit alternative with the selecting condition: use decompose_drivers instead when candidates may overlap. Nothing about when-not-to-use is left to inference.

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 declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds real context beyond them: preview_url is private and never-indexed, public_url is null until publish, and the ownership constraint (non-owned apps answer not found, per schema). It stops short of rate-limit or freshness detail, but that is minor for a read 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?

Purpose is front-loaded in the first clause, followed by the return-value enumeration and then usage. The parentheticals (sandbox bridge, data sources) add flavor that is somewhat expendable, but each sentence still 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?

There is no output schema, so the description must carry the return contract, and it does: it enumerates preview_url, public_url, visibility, indexed, and next_step with meaning for each. For a single-param read tool, nothing an agent needs 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?

Only one parameter and schema coverage is 100%, so the schema already documents app_id fully. The description reinforces ownership semantics but adds no syntax or format beyond the structured field. Baseline 3 is appropriate when the schema does the work.

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+resource (get/open an app's preview URL) and immediately scopes it to 'an app you own.' The preview_url vs public_url distinction plus the explicit mentions of create_app and publish_app let an agent separate this from list_apps, get_app_artifact, 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?

'Use it to hand a user something to click after create_app, and to check what is still missing before publish_app' gives explicit when-to-use conditions and names the alternative lifecycle calls. Nothing is left to inference about where this fits in the create/publish flow.

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 readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered, but the description adds that it never starts a run, never changes config, and requires AUTARIO_API_KEY. It also discloses the full return shape (health states, per-dataset data_as_of, reports[], next_step), which is valuable given no output schema 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 purpose and triggering conditions are front-loaded, then the return contract is spelled out. The state enumeration and return-field list make it dense and long, but with no output schema each element carries informational weight rather than 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?

With no output schema and a single low-risk parameter, the description compensates by fully documenting the returned health states, per-dataset semantics, report outcomes, and the next_step action contract. Nothing an agent needs to call and interpret it 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?

There is a single parameter, connector_id, with 100% schema description coverage, so the schema does the heavy lifting (baseline 3). The description only implicitly ties the id to list_connectors output and adds no format or edge-case detail 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 names a specific verb and resource (explain the state of one connected platform) and enumerates the exact facets it reports: freshness, delivered/empty/missing reports, and who must act. It explicitly scopes to a single connector and clarifies it is diagnostic rather than an action tool, distinguishing it from siblings like refresh_connector.

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 trigger conditions: use when list_connectors shows a non-ok state or before telling the user to sign in again, naming the sibling tool whose output drives the decision. The read-only clause ('never starts a run and never changes the configuration') further routes the agent away from refresh_connector.

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

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

Annotations already declare 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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds value beyond that: it states authentication is required (API key or OAuth), that there is no cost, and that the call aggregates in one round-trip what would otherwise be one get_app_context per app. It does not discuss pagination or limits for users with many apps, which is the remaining gap.

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

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

Front-loaded with the core purpose and the trigger condition, which is the right ordering. The long platform enumeration and the persuasive clauses ('no dataset guessing, no hallucinated numbers') cost tokens, though the platform list does help match user phrasing like 'my Instagram dashboard'.

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

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

No output schema exists, so the description must describe the return payload — and it does, listing platforms, connector tables with dataset_id/slug/row count/last refresh, saved artifacts, a query example, and the shared_with_you section. Combined with the auth and cost notes, an agent has everything needed to call and interpret 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?

There is a single optional parameter (format) and schema description coverage is 100%, with the enum values and defaults fully documented in the schema itself. The description adds no format guidance, but with one well-documented enum param the baseline is a 4 rather than something lower.

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+resource ('YOUR data-app workspace in ONE call') and enumerates the exact contents returned, so the agent knows precisely what comes back. It also distinguishes itself from siblings by naming get_app_context as the thing it replaces and get_app_artifact/query_dataset as drill-downs. An agent can route to it without opening any 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?

Explicit trigger conditions are given — 'THE first call when a user references "my <app>", "my dashboard", "my report"' — plus the alternatives for narrowing (get_app_artifact for a saved view, query_dataset for rows). Both when-to-use and when-to-use-something-else are covered.

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 readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuine value beyond that: how to read the output ('peak |r| at positive lag means A precedes B') and which indicator sources are supported.

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

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

Front-loaded with the core operation, then interpretation and an example, then data-source coverage. Each sentence earns its place; the provider list is the only slightly expendable element but it usefully signals 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?

For a statistical tool with no output schema, the description covers what is computed, how to interpret the result, and the supported data universe. It omits return-shape details (e.g. whether a table of lag correlations is returned), which keeps it just short of fully complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes slightly further by tying the parameters to interpretation – the positive-lag convention clarifies the role relationship between `a` (leading candidate) and `b` (lagging candidate) rather than just restating their labels.

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 analytical operation (cross-correlation at multiple lags) and its interpretive purpose ('does A lead or lag B?'), so the agent understands exactly what is computed. However, it never names or distinguishes itself from the sibling tool `correlate`, which is 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?

Gives concrete usage context via an example ('is consumer confidence a leading indicator of retail sales?') and the interpretation rule for the result. It does not, however, state when NOT to use it or point to `correlate` for same-period correlation, 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 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?

Goes well beyond the readOnly/idempotent annotations: it discloses the full returned shape (dataset_id, datasets[], refresh interval, last refresh, health), enumerates all eight health states, and prescribes behavior for each (refresh once on stale, hand over next_step.url on needs_sign_in, explain reports on reports_missing). It also notes the AUTARIO_API_KEY requirement and that it never handles credentials.

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

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

Front-loaded with purpose and the alternative to use, and nearly every sentence is decision-relevant. It is dense and long, and part of the health-state remediation guidance overlaps what refresh_connector and get_connector_status arguably own, but nothing 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?

There is no output schema, so the description carries the full burden of explaining return values and does so in detail, including the health state machine and per-dataset age. An agent has everything needed to call it and interpret 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?

The tool takes zero parameters, so the baseline is 4 and there is no schema surface for the description to elaborate on. The description's field-level detail is about the response, not inputs, so it cannot raise this dimension 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?

States a specific verb+resource ('List the platform connectors set up on this Autario account') and enumerates the connector categories covered. It is clearly distinguishable from get_connector_status and refresh_connector, which handle per-connector detail and refresh respectively.

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

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

Explicitly says to call it 'instead of guessing which ones exist', gives concrete user phrasings that should route here ('my Search Console data', 'my ad spend', 'a cross-platform weekly report'), and states the read-only boundary (connectors are configured in the Autario UI). It also routes follow-up work to query_dataset and get_connector_status.

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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds useful scope context (works on any verified autario indicator, listing providers), but discloses nothing about computation details, edge cases, or what happens with sparse series.

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

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

Front-loaded with the core purpose, followed by usage cues and then source coverage. The provider enumeration (World Bank, FRED, Eurostat...) is somewhat list-heavy but still serves the scope claim; overall it is tight and readable.

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 5-parameter read-only computation with no output schema, the description plus a fully documented schema cover the essentials — what it computes, when to use it, and which data sources apply. The schema's 'full' description handles the return-shape question, so the description need not repeat it.

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

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

Schema description coverage is 100%, so the schema already documents entity, indicator, period, time, and full in detail. The description adds no parameter-level meaning beyond what is in the schema, making the baseline 3 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?

States a specific computation (period-over-period percentage change) applied to a specific resource (an autario indicator), which is far more precise than a generic 'calculate'. It does not, however, distinguish itself from siblings like calculate, compare_entities, or rolling_stats, so an agent still has to infer which statistical tool applies.

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 context — 'Use for growth rates (YoY, QoQ, MoM)' — reinforced by concrete example questions ('how fast did German GDP grow'). It stops short of naming exclusions or the alternative tool to pick when you want levels rather than changes.

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 declare write/idempotency/open-world flags; the description adds substantial behavior beyond them: 403 refusals naming the refused field for editor-role leads, admin-approval gating of new projects into inbox, the null-with-reason rule (never zero) for unreadable values, target_reason history that cannot be rewritten, and cross-account 'not found' semantics.

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 one-line summary plus quoted trigger phrases are front-loaded, and the PROJECTS/OBJECTIVES/VALUE RULE/NEVER headers give usable structure for a 44-parameter tool. However it is very long and several sentences duplicate what the schema descriptions already state (parent depth limits, target_reason length, country_values behavior), so not every sentence is strictly additive.

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 return-value burden and does so: 'get' returns a project with milestones and KPIs, 'objectives' returns objectives with derived status, history and backing projects, and 'list' exposes linkable key_results. Combined with the derived-vs-typed rules, an agent has what it needs to call 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 and the schema already documents every parameter. The description still earns credit by explaining cross-parameter interactions the schema cannot: country_values makes target/current derived and ignores a typed target, aggregation controls how countries roll up, and guards_id turns a key result into a guardrail. It adds real semantics, though a good share repeats schema-level detail.

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?

Opens with a specific verb+resource+scope: the caller's own project board with objectives and key results, read and written deterministically. It then enumerates the concrete sub-actions (list/get/create/update on projects, plus objectives and key results) and the trigger questions each answers, so an agent can tell exactly what this tool covers 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 lists when to call it via quoted user intents ('what is my team working on', 'which key result has no project behind it', etc.) and which action handles writes. It also states negative conditions in the NEVER section (never derives traffic light/progress, never invents key results, never reaches another account) and the account requirement, leaving little to inference.

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 carry the safe-read profile (readOnlyHint/idempotentHint/destructiveHint=false), and the description still adds real behavioral context: aggregates are numerically correct despite text storage (no lexicographic min/max), the engine 'refuses to combine columns of different kinds', null-heavy datasets warrant non_null_only, and the token-cost contrast (~17,000 raw rows vs ~200 tokens). That is information an agent cannot get from the annotations or 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?

Front-loads scope, then alternatives, then token strategy — good ordering, and the pipe-delimited opening keeps the enumeration compact. It is on the long side with some restatement (the mostly-null dataset point appears twice, and the aggregation rationale is repeated). Every sentence still does work, so it lands just short of 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?

For an 11-parameter, mutation-free analytical tool with no output schema, the description covers return shape (rows plus per-category statistics, or summary only), the safety-relevant combination restriction, and the required citation. Minor gap: it claims returns 'as JSON' while the format parameter defaults to 'toon', a small internal inconsistency an agent must reconcile on its own.

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 nonetheless adds meaning by explaining *why* and *when* to use summary_only (finished per-column stats with NO raw rows) and non_null_only (drop empty rows), and by framing aggregate/groupby as the token-efficient path with a worked example. It does not restate sort/filter/fields syntax, which the schema already covers well.

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?

Opens with a specific verb+resource ('Query the rows of ONE dataset'), enumerates the data universe it covers (World Bank/FRED/Eurostat/... plus uploads and shared tables), and explicitly carves out the sibling it is not ('Reach for get_entity_data instead when you want ONE entity across SEVERAL indicators'). An agent can select this over query-adjacent siblings without opening either 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?

Gives explicit routing rules ('Prefer aggregations or summary_only over pulling raw rows'), a concrete worked example ('average GDP of Germany 2010-2020 => aggregate=avg(value) + filters'), named alternatives (get_entity_data, get_dataset_schema), and a precondition ('Call get_dataset_schema first and read its semantics block'). When-to-use, when-not-to-use and prerequisites are all present.

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

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

Beyond the annotations, the description discloses substantial behavior: a rate limit (one run per connector per 10 minutes, retry_at), non-error empty outcomes, and explicit refusal states (needs_sign_in with next_step.url, already_running, too_soon). It also notes determinism/no LLM cost and the AUTARIO_API_KEY requirement. This aligns with the annotations (readOnlyHint=false, destructiveHint=true for a table rewrite, idempotentHint=true) rather than contradicting 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?

The description is long but front-loads the core action and scope before drilling into outcomes and edge cases. Each sentence carries distinct information (return shape, error states, rate limit, single-call rule), though it is dense enough that a slightly tighter phrasing could improve scanability.

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 thoroughly by enumerating the return fields (status, rows, dataset_id, health with per-report outcomes and next_step) and the possible failure/refusal states. An agent has everything needed to call it correctly and interpret 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?

There is a single parameter with 100% schema coverage, so the schema already documents connector_id fully. The description only echoes this ('Get the connector_id from list_connectors'), adding no format or semantics beyond what the schema states, 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 leads with a concrete verb+resource: 'Pull the latest numbers from one connected platform right now and refresh its hosted Postgres table on Autario.' The clause listing connector types (Search Console, Shopify, ads, AI usage bill) further pins down what it operates on, clearly separating it from siblings like get_connector_status or list_connectors.

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 triggering conditions ('Use when health.state is stale or never_ran, or the user says get the latest') and a hard usage constraint ('Call it ONCE per question, never in a loop'). It also routes the agent to list_connectors to obtain connector_id, and states what the tool will NOT do (cannot change settings, reports, schedule or login).

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 non-destructive. The description adds useful context: it returns an interpretation, runs only on verified indicators, and returns slope/intercept/R². It doesn't mention rate limits or failure modes, but the schema's 'full' parameter covers the heavy-token caveat.

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

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

Four sentences, front-loaded with the core operation and output, then use-case, then data scope. No filler, though the data-source enumeration is slightly long.

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 read-only nature, full schema coverage, and no output schema, the description is nearly complete for invocation: it names the operation, the output fields, the data source constraints, and the use case. It omits failure behavior for invalid indicator IDs, but that is 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?

Schema coverage is 100% with detailed descriptions for each parameter, including the 'full' token warning and time-window syntax. The description adds no parameter-level detail beyond the schema, 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?

States a specific operation (linear regression of y ~ x), its scope (one entity), and its output (slope, intercept, R² and interpretation). This clearly distinguishes it from siblings like correlate or decompose_drivers.

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

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

Provides a use-case framing ('how does X predict Y?') and states the data universe it runs on (verified autario indicators with named sources). It does not explicitly differentiate from correlate or lag_analysis, but the framing is clear enough to route most queries.

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 declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds that it smooths noise and reveals trends, and lists supported data providers, but does not disclose return format, rate limits, or authentication needs beyond what annotations and schema 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 the core operation and then adds usage guidance and data coverage. It is appropriately sized, though the provider list in the final sentence is somewhat lengthy and could be trimmed without losing much.

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 rich schema (100% coverage) and no output schema, the description supplies enough purpose and usage context to select and invoke the tool. It could be more complete by mentioning when not to use it versus statistical siblings, but the core gaps are minor.

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

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

Schema description coverage is 100%, so all six parameters already have detailed documentation, including op, full, time, entity, window, and indicator. The description repeats the op values and indicator sources but adds no syntax or semantic meaning beyond the schema, making the baseline 3 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 computational operation and resource: rolling window statistics (mean/std/min/max/sum) for an indicator. It does not explicitly differentiate itself from statistical siblings such as pct_change, lag_analysis, or correlate, so it falls 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?

It gives a clear use case: use before claiming a turning point in a monthly FRED or Eurostat series. It also notes the tool runs on any verified autario indicator. However, it does not explicitly name when to use alternatives or when not to use this tool.

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

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

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 declare readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds real value beyond them: what is returned (per-timepoint components plus summary amplitude) and the data coverage (any verified autario indicator across World Bank, FRED, Eurostat, OECD, IMF, WHO, ECB, US Census, SEC). It omits any caveat about minimum series length or frequency requirements.

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

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

Front-loaded with the model formula and the core purpose, then supporting context. The pipe-separated clauses are slightly clipped and the source list is long, but every element is on-topic 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?

With no output schema, the description must describe returns, and it does ('per-timepoint components + summary amplitude'). Combined with the annotation coverage and full schema descriptions, an agent has enough to call it correctly; only edge-case behavior (short series, non-seasonal data) is unaddressed.

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 period, time, entity, indicator and full are all documented in the schema itself. The description only adds a general statement about indicator eligibility ('any verified autario indicator'), which the indicator parameter description already covers via list_indicators/get_entity_profile. Baseline 3 applies when the schema does the heavy lifting.

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

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

Names a specific statistical technique and its additive model (Y = trend + seasonal + residual) and states the concrete outcome: strip the seasonal cycle to reveal the underlying trend. This is clearly distinguishable from siblings like decompose_drivers, find_drivers, rolling_stats, and correlate without opening any 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?

Gives a clear usage context ('great for monthly or quarterly data (retail sales, unemployment)') and the analytical goal, which is more than most siblings offer. It does not, however, state when NOT to use it or name an alternative tool (e.g. trend-only smoothing vs decompose_drivers), so the routing guidance is 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?

With annotations only flagging destructive/idempotent/openWorld, the description supplies the substance an agent actually needs: the app leaves the store, the public URL breaks for others, the owner retains preview access, data connections continue working, nothing is deleted, and publish_app restores it. That covers effects, ownership prerequisite, and reversibility beyond the structured hints.

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 action and its scope are front-loaded, and the usage trigger is placed last where it belongs. The clause about continuing to read World Bank/FRED/connector data is a slightly verbose aside, but overall there is little waste.

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

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

For a single-parameter state-changing tool with no output schema, the description covers effects, ownership constraint, reversibility, and when to call it. An agent has everything needed to invoke and explain the result correctly.

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

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

Schema description coverage is 100%, and the schema already documents app_id including the ownership/not-found behavior. The description adds no format or syntax detail beyond the schema, 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 concrete verb+resource ('Take an app YOU own back to private') and states the outcome (leaves the app store, public URL stops working). It is unmistakably distinct from publish_app, which it names as the inverse operation.

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 two explicit triggering conditions: 'when a user wants an app off the store' and 'before shipping a change they do not want strangers to see.' The alternative (publish_app) is named along with the direction it moves state, so the agent can choose without inference.

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 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, idempotentHint, destructiveHint=false and openWorldHint=false, so safety and idempotency are covered. The description adds genuinely useful context: the auto-selection mechanism (same topic + entity_type), the cross-source reach across six named data providers, frequency auto-alignment to avoid inflated n-counts, and the return shape with confidence labels and sharpen-suggestions. This is well beyond the annotations, warranting a solid mid-high score.

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

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

Front-loads the core purpose in the first clause, then layers in auto-selection, return format, frequency handling, and the sibling alternative. Dense but nearly every sentence carries distinct information, with only minor redundancy around candidate omission.

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

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

No output schema exists, so the description carries the burden of explaining returns, and it does: a ranking with confidence labels, reason strings, and sharpen-suggestions. Combined with input behavior and the sibling routing hint, an agent has everything needed to call 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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by explaining that auto-selection picks candidates sharing the same topic and entity_type, and that frequencies are aligned to the coarser common grain. These details are not present in the 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 and resource ('rank which other metrics best explain the outcome') and frames the exact question it answers. It distinguishes itself from siblings by naming find_drivers as the alternative, so an agent can route without opening any 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 says 'Use this instead of find_drivers when you want a narrative-grade answer', giving both the alternative and the selecting condition. It also clarifies the omission path for candidates, so the agent knows it need not supply them.

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 carry negative hints (readOnly=false, idempotent=false, destructive=false), so the description carries the behavioral burden. It discloses ownership ('owned by you'), access behavior ('someone else's private app answers not found'), persistence (read back later via get_app_artifact), and create-vs-patch semantics. This is exactly the kind of context beyond annotations that 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?

The description is dense and front-loaded with the core definition, then moves to parameters, usage, and permissions. Every sentence carries information, though the inline '|' separator and the list of examples make it slightly less polished than it could be.

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 7-parameter write tool with no output schema, the description explains the artifact concept, when to create vs patch, and permission behavior. It does not state the return value of the write call, and the 'required when creating' nuance for type is only in the schema, not the description, leaving a small 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 coverage is 100%, so the baseline is 3. The description adds meaningful parameter semantics: type is a free-form label with examples, spec and/or data may be supplied, and artifact_id toggles create vs patch. It does not add details for visibility or app_id, but the schema already documents those.

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 ('Save an ARTIFACT into an app') and then defines what counts as an artifact with concrete examples (Plotly spec, saved report, board, screener view). It also names the read-side counterpart get_app_artifact, so an agent can distinguish writing from reading without opening 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?

It gives explicit when-to-use context: 'Use it right after create_app to seed the app with something real, or whenever a user asks you to save a view.' It also distinguishes create vs patch via artifact_id. It does not enumerate exclusions against other write-like siblings such as create_chart_from_spec or write_rows, but the primary selection 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 provide minimal behavioral signal, so the description carries the burden. It discloses schema auto-inference, text-only storage, the 10,000-row limit with a multi-call strategy, and the AUTARIO_API_KEY requirement.

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?

A single dense sentence front-loads the core action and then packs only high-value constraints and requirements. No filler words or redundant restatement of the 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?

For a low-complexity, two-parameter write tool with no output schema, the description covers ownership, allowed data sources, limits, storage behavior, and authentication. Nothing essential is missing for the agent to call it correctly.

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

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

The schema already fully documents both parameters with an example. The description adds useful semantic context by explaining that values are stored as text and the schema is inferred from the first batch.

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 operation, append rows, to a specific resource, an existing dataset you own, and clarifies origin via create_dataset. This distinguishes it from sibling create_dataset and clear_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?

Clearly indicates when to use the tool: to append data to a dataset you own, with examples of acceptable data sources. It does not explicitly contrast with alternatives like clear_rows, but the usage context is unambiguous.

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