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

No annotations are supplied, so the description carries the whole burden. It discloses the ordering of results (least-populated first) and that it operates on cached datasets, but never states that it is a read-only operation, whether it scans the full dataset (cost/latency implications of 'every field'), or what a 'complete-looking' result actually means in terms of the threshold. For an unannotated tool this leaves too much unstated.

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 clause, which is good. The remaining sentences are padded with quoted colloquial framing ('the automated version of ...', 'complete-looking') that restates the same idea rather than adding new 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?

An output schema exists, so return-value explanation is legitimately omitted, and the read-only nature of an 'audit' is implied. But with no annotations and zero parameter documentation, the definition does not give an agent enough to invoke it correctly — particularly how 'top' and 'threshold' shape results — which is the main completeness gap for a three-parameter tool.

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

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

Schema description coverage is 0% and all three parameters ('dataset_id', 'top', 'threshold') carry only titles and defaults. The description's 'least-populated first' hints at ordering and hence at 'top', but it never explains that 'top' is a result count or what 'threshold' (default 99) measures — a percentage cutoff, a minimum coverage, or something else. With three undocumented parameters, the description needed to compensate and does not.

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 gives a concrete verb and resource: scan every field of a cached dataset and return them ordered by population, least-populated first. An agent can tell this is a dataset-wide coverage audit rather than a query or a fetch. It does not differentiate itself from the sibling 'field_coverage', which sounds like an adjacent capability, 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 supplies a clear motivating scenario ('check field population before trusting a total') and rules out the manual alternative ('instead of hand-checking fields one at a time'). However, it never names a sibling tool as the alternative or states when this should be skipped in favor of 'field_coverage' or 'describe_dataset', so routing among siblings remains inferred.

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

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

No annotations are supplied, so the description carries the full behavioral burden, and it does disclose a lot: the returned metadata, that row count and date range exist only when the dataset is cached, and the interpretive pitfall of zero results for dates predating the data. What it omits is equally material — whether this is read-only (implied but unstated), the cost of probe=true, and whether an invalid or uncached dataset errors versus returning a partial profile.

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, and every subsequent sentence adds distinct information rather than restating. The long em-dash parentheticals pack in real value but make the middle of the description harder to parse on a first read.

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 an output schema present, the description is not obliged to enumerate return values, yet it does so with interpretive context the schema cannot convey (era-gap, recent-window traps). The remaining gap isoperational: where dataset_id comes from and whether probe is expensive, both of which matter for correct invocation.

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

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

Schema description coverage is 0%, so the description must supply all parameter meaning. probe is handled well — explicitly opt-in, default off, and tied to a named output (coverage_flags). dataset_id is never discussed: no format, no hint that it comes from search_datasets, no indication of what a bad identifier does.

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-and-resource statement: schema plus coverage profile for exactly one dataset. It implicitly separates itself from search_datasets and fetch_dataset by framing itself as the metadata/schema lookup, and the aside about querying with machine field names rather than display names signals its role in the workflow. It never names a sibling explicitly, so full differentiation is left to inference.

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?

Usage context is clear: call this to learn the machine field names before querying, and set probe=true when partial coverage could distort a total or rate. The era-gap warning explains the practical consequence of ignoring it. It stops short of naming alternatives (e.g. field_coverage, coverage_audit) or stating when this tool is the wrong choice.

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

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

With no annotations supplied, the description carries the burden and does well: it discloses the overwrite-on-rerun semantics, the exact cache path, and the latency risk for multi-million-row datasets. It does not mention authentication/app-token requirements, rate limits, or what happens on a mid-fetch failure, so it stops short of full 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?

Four sentences, front-loaded with the core action and side effect before the optional filtering and performance caveats. Every sentence carries distinct information, though the parenthetical path and the latency note could be tightened slightly.

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?

An output schema exists, so return shape need not be explained, and the description covers the caching model, overwrite risk, filtering options, and cost profile. Missing pieces are auth expectations and failure/partial-cache behavior, which matter for a network-backed fetch that writes to disk.

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

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

Schema description coverage is 0%, so the description must compensate. It explains that 'where' is a server-side filter and 'select' is a projection, which is real added meaning over the bare string types, but it gives no SODA/SoQL syntax, no quoting rules, and no examples. dataset_id is left entirely implicit.

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 (pull every row of a dataset), names the transport (SODA API), and the concrete side effect (cache as Parquet at data/raw/<id>.parquet) plus the downstream reason (SQL cross-referencing). This clearly separates it from describe_dataset (metadata) and query (SQL execution) among the 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?

Explicit routing guidance: check describe_dataset's cached/fetched_at before re-running, and prefer a $where filter when only a subset is needed. It gives both a prerequisite check and a condition for narrowing scope, which is exactly the when-to-use/when-not information 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?

No annotations are supplied, so the description carries the full burden, and it does well: it discloses what the tool computes (populated fraction, date span), that it emits a warning on recent-window patterns, and that a display name produces an actionable error listing real field names. It never states read-only status or cost/latency characteristics, which are the remaining behavioral gaps.

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

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

It is front-loaded with the core action and the 'recent-window trap' framing, then the return shape, then the imperative usage rule, then the input constraint. Each sentence carries information, though the parenthetical balance example and the framing clause make it slightly denser than strictly necessary.

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?

An output schema exists, so return values need not be explained, yet the description still covers the key ones and adds the error contract. Completeness is only weakened by the undocumented 'date_field' parameter and by not clarifying how dataset_id is obtained (e.g. via list_cached_datasets).

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

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

Schema description coverage is 0%, so the description must compensate. It richly documents 'field' (must be a machine name from columns_field_name, display names error out) and implies 'dataset_id' must reference a cached dataset, but 'date_field' is never mentioned at all, leaving one of three parameters with no semantics anywhere.

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: probe how ONE field is populated across a cached dataset, and it explicitly reports the populated fraction plus the date range of populated rows. The capitalized 'ONE field' scopes it clearly against the dataset-level sibling coverage_audit, so an agent can tell them apart 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?

It gives an explicit trigger: 'Always run this before summing or rate-computing over a field', which tells the agent exactly when this tool is required. It does not name when-not-to-use cases or point to a specific alternative for whole-dataset checks, 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?

With no annotations, the description carries the behavioral burden and does well by disclosing the local cache path and the downstream constraint that only cached datasets can be queried or audited. It does not explicitly state read-only behavior, ordering, or edge cases such as an empty cache, but for a simple listing operation the key behavioral context is present.

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 front-loaded sentences with no redundant wording. The core behavior is stated first, followed by the useful dependency and alternative 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?

For a zero-parameter listing tool with an output schema, the description supplies everything needed to select and invoke it correctly: what is listed, where the cache lives, the constraint on downstream use, and the alternative for uncached datasets. Return values need not be explained because an output schema exists.

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

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

The tool has zero parameters, so the baseline is 4 and there is no parameter meaning for the description to add. The schema is empty and fully covered.

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 and resource: list dataset ids whose rows are cached locally in data/raw/. It also explicitly contrasts with fetch_dataset for datasets that are not cached, so the agent can distinguish it from sibling tools without opening schemas.

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

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

It clearly states when this tool is relevant by noting that only cached datasets can be queried in SQL or audited for coverage. It also names the alternative action, fetch_dataset, for datasets that are not yet cached.

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

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

With no annotations, the description carries the full burden and does so well: it discloses that it runs arbitrary SQL over local Parquet only, is a trusted single-user tool and not sandboxed. It also warns that every Socrata column is a string, requiring TRY_CAST for numeric work, and that join keys need normalization — behavioral context an agent cannot get from the 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-loaded with the core action and view-naming rule, then caveats and prerequisites. Dense but nearly every clause carries operational value; the parenthetical example and casting note are well placed. Minor redundancy in the closing prerequisite note, but nothing that should be cut.

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?

Output schema exists, so return values needn't be explained, and the description covers the tricky parts: type coercion, join-key normalization, view naming, and the non-sandboxed trust model. The only real gap is the undocumented `limit` parameter, which matters for large result sets.

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

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

Schema description coverage is 0%, so the description must compensate. It effectively documents the semantics of the `sql` parameter (SELECT-only, ds_* view namespace, string columns, TRY_CAST) but never mentions the `limit` parameter or its default of 1000, leaving one of two parameters undocumented.

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 ('Run a DuckDB SELECT over the cached datasets') and immediately explains the ds_<id> view naming with a concrete example. It also signals its distinct role as the 'cross-referencing step' for joins/aggregation, which separates it from single-dataset siblings like fetch_dataset and describe_dataset.

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

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

Gives explicit sequencing guidance ('Prefer describe_dataset + coverage_audit first so you know the fields exist and are fully populated') and names the exact scenario this tool is for: joining/aggregating across ds_* views. An agent knows both when to reach for it and which siblings to call before it.

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

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

With no annotations supplied, the description carries the full burden and does well: it discloses the write target (data/catalog.parquet), that no credentials are required, that the .env app token only raises the anonymous rate limit, and the return value. It stops short of saying whether the refresh replaces or merges existing cache entries, which matters for a cache-overwriting operation.

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

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

Front-loaded with the action and source, followed by payload contents, trigger conditions, constraints, and return value in that order. Dense but every sentence carries information; the parenthetical field list is the only mildly expendable element.

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 cache-refresh tool with an output schema already documenting the return shape, the description covers source, destination, scale (~280 datasets), prerequisites, rate-limit caveat, and invocation timing. Nothing an agent needs in order to call it 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly spends no words on argument syntax.

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 ('Refresh the local catalog cache') and names the exact upstream source (Socrata Discovery API), so the agent can distinguish it from read-only siblings like search_datasets or list_cached_datasets without opening a 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 two explicit trigger conditions — 'Run first if search_datasets reports a missing cache' and 'when the portal may have new datasets' — and routes the agent to the sibling that signals the need. This is the when-to-use guidance most definitions omit.

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

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

No annotations exist, so the description carries the burden, and it delivers the highest-value behavioral fact: columns_field_name vs columns_name, with the consequence spelled out ("silently returns zero rows"). It omits catalog staleness/freshness behavior and what limit does when exceeded, so the operational profile is incomplete but far above baseline.

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 action and closes with the workflow instruction; nearly every clause earns its place. The parenthetical about columns_field_name is deliberately verbose and valuable, though the italics/em-dash framing makes it denser than it needs to 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?

An output schema exists, yet the description usefully flags the one returned field that causes silent failures, so it is complete where it matters most for a simple two-parameter search. The remaining gap is catalog freshness and result-limit behavior, which an agent would still have to discover.

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

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

Schema coverage is 0%, so the description must compensate. It does define what keyword matches against (name, description, category, tags), which is genuine added meaning, but says nothing about the limit parameter (default 20, max, pagination), leaving half the parameters undocumented anywhere.

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 ("Search the cached dataset catalog by keyword") and immediately names the indexed fields (name, description, category, tags), which distinguishes it from list_cached_datasets and query without the agent needing to open 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?

Explicitly routes the agent forward: "Use this to find a dataset, then describe_dataset to get its full schema before querying" names both the alternative and the ordering condition. It stops short of the full sibling set — no guidance on when to prefer list_cached_datasets or when refresh_catalog is needed first.

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