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 real substance beyond that — that definitions are cited to a build definitions file 'where one exists' (signalling the citation may be absent) and that the row sample is grain-sorted and limited to five. It stops short of anything on cost, latency, or size of wide tables.

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, no filler, with the returned payload front-loaded and the invocation constraint in the second sentence. Every clause carries information an agent needs.

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 the return shape is documented structurally, and the description is thorough about sequencing against search_catalog. The only real hole is the undisclosed meaning of the `warehouse` enum, which matters because table names may not be unique across the three warehouses.

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

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

Schema description coverage is 0%, so the description must carry both parameters and only carries one: it clarifies that `table` is a single table name sourced from search_catalog. The `warehouse` parameter is never mentioned, and its enum values (doorstep, turnaround, ledger) are opaque without any explanation of what each warehouse contains.

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 ('Describe one table') and enumerates exactly what comes back: grain, every column with type/unit/definition, manifest figures that read it, and first five grain-sorted rows. That makes it distinguishable from search_catalog (naming) and run_sql (querying) 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?

'Call it for one table at a time, after search_catalog has named the table' gives an explicit prerequisite and ordering relative to a named sibling. The one-at-a-time constraint tells the agent to loop rather than batch, which is the key usage decision for 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?

Annotations already declare the operation read-only, idempotent, and non-destructive, while the description adds meaningful behavioral detail about ambiguous matches: the server prompts the client to choose, and non-interactive clients receive candidates with needs_choice set. This goes beyond the annotations, though it does not describe no-match handling or broader failure 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 definition is two sentences, front-loaded with the core purpose, and every clause contributes useful information about either entity kinds or ambiguity handling. There is no redundant restatement of the schema or annotations.

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

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

The tool has only two required parameters, rich annotations, and an output schema, so the description does not need to explain return values. It covers the key ambiguity behavior but leaves sibling-relative usage and no-match behavior implicit, leaving a small completeness 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?

With 0% schema description coverage, the description carries the burden and does add meaning by enumerating the kind values and mapping them to contexts such as metro/doorstep, carrier/airport/turnaround, and county/ledger. It also explains that name is resolved to canonical warehouse spelling and may produce ambiguous candidates, though individual enum values remain only loosely defined.

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

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

The description states a specific verb and resource: resolving a name to the canonical warehouse spelling, with several entity kinds enumerated. It is clear what the tool does, though it does not explicitly distinguish itself from sibling tools such as search_catalog or describe.

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 is implied by the need to resolve names and by the ambiguity-handling guidance, but there is no explicit statement of when to prefer lookup over alternatives or when not to use it. The ambiguity behavior gives useful context but does not fully cover tool selection.

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, closed-world, so the safety profile is covered. The description adds genuinely non-redundant behavior: a hard 50-result cap, key-sorted ordering, glob matching semantics, and the shape of each returned value (unit, published rounding, interval, display string).

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 dense sentences with no filler; the core action and scope lead, and the return-value detail follows. Nothing repeats the schema or annotations.

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 describing return values was optional but adds useful orientation; the glob semantics and limit make invocation unambiguous. The remaining gap is the unlabeled warehouse enum and the absent comparison to sibling retrieval 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?

Schema description coverage is 0%, so the description carries the burden. It handles key_or_pattern well — exact key, glob syntax with a concrete example, and the result cap. It says nothing about the warehouse parameter beyond implying it selects a manifest, leaving the three enum values (doorstep, turnaround, ledger) undifferentiated.

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: read values from a warehouse's published manifest, with a clarifier ('the numbers its own documents print') that pins down what 'published' means. It does not explicitly contrast with siblings like readback, lookup, or run_sql, so an agent must infer the boundary rather than being told.

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?

Retrieval mechanics are clear (exact key or glob such as ch5.*, capped at 50, sorted by key), which implies the usage pattern. But there is no statement of when to choose this over readback, lookup, search_catalog, or run_sql, and no excluded cases (e.g., values that were never published).

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 read-only/idempotent annotations, the description explains what the server actually does: it re-runs or looks up the source, converts units only where the catalog permits (fraction and percent), and returns agree/disagree plus the difference and the tolerance. It even defines the tolerance rule per source type (half a unit of published rounding for manifest keys, half a unit of display rounding for queries).

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 critical constraint, re-verify one number before stating it, is front-loaded, and the sources and tolerance rules follow logically. The middle sentence is dense with nested clauses and could be split, but 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?

The tool has an output schema, so the description doesn't need to detail return shape, and it still summarizes the verdict and tolerance semantics. Combined with the source enumeration and the 'every number must have an agreeing readback' requirement, 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?

The description explains the four mutually exclusive source modes (result_id with column and row, sql, manifest_key, catalog_key) and the unit-conversion constraint, which is more than the schema conveys in prose. It leaves warehouse, definition_id and evidence_unit unexplained in the description, relying on their schema descriptions instead.

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: re-verify one number, given a value, its unit, the display string and exactly one source. It is unmistakable from sibling tools like run_sql or lookup because it explicitly consumes their outputs (a result_id from run_sql in this request chain).

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 when to use it ('before you say it', 'Every number in an answer must have an agreeing readback') and restricts the input to exactly one of four source types, which is strong routing guidance. It never names a when-not condition or an alternative tool for a case it can't handle, 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?

Goes well beyond the readOnlyHint/idempotentHint annotations: it names what gets refused and how (clause named in the error), states the 500-row cap and 10-second timeout, and describes unqualified-name qualification. This is exactly the enforcement detail an agent needs before composing a query.

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: the single-statement rule leads, then restrictions, then limits, then returns. Sentences are long and clause-heavy but every one carries distinct information; minor trimming possible in the return-value list.

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 an output schema exists, the description needn't enumerate return fields, yet doing so confirms the result_id/readback workflow, which is genuinely useful. The only real gap is the missing contrast with sibling query/catalog tools for an agent deciding whether to write SQL at all.

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 for warehouse (scopes to one named schema; enum values are self-evident) and limit (capped at 500), and sql's purpose is obvious from the tool itself. It stops short of clarifying whether a caller-supplied limit below 500 is honored or how it interacts with the cap.

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 one read only DuckDB statement against one warehouse schema') plus exact scope limits (single SELECT/WITH, one schema). An agent can tell this apart from siblings like search_catalog, describe and readback 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?

Clearly defines the allowed case (single SELECT or WITH against a named warehouse schema) and the excluded cases (writes, ATTACH, COPY, INSTALL, LOAD, PRAGMA, SET, file functions, out-of-schema tables). It also routes the agent forward by telling it the result_id is meant to be cited in readback, though it never explicitly contrasts when to prefer search_catalog or describe over raw SQL.

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

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

Adds substantial behavior beyond annotations: lexical ranking, synonym-table query expansion with an example, return of the expanded query, capped hits (at most 20), per-hit unit and definition sentence, and kind-specific behavior for definitions. Annotations already confirm it is read-only, idempotent, non-destructive, and closed-world; the description adds rich operational context.

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

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

Front-loads the main action immediately and remains dense but purposeful. The synonym example and kind clarification earn their place, 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?

Given the output schema and annotations, the description covers the core search semantics, ranking, result shape, and kind filtering well. The main remaining gap is that the warehouse parameter is not explained despite the low schema description coverage.

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

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

With 0% schema description coverage, the description must carry parameter meaning. It explains query expansion, k's maximum of 20, and kind's one-kind-only behavior, including the definition kind, but it does not explain the warehouse parameter or its allowed values beyond implying the three warehouses exist.

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 catalog of the three warehouses for tables, columns, metrics, and manifest values. The purpose is clear, but sibling differentiation is only implicit through the 'before writing SQL' context; no sibling tool is named as an 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 a clear usage context: use it to find where a number lives before writing SQL, and notes that passing kind restricts the search to one kind. It does not state when not to use it or explicitly name alternatives such as lookup or describe.

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, non-destructive and closed-world, so the safety profile is fully covered. The description adds that the result is a fixed set of three warehouses with pin/tag and row/table counts, which is useful context but largely mirrors the 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?

Two sentences, front-loaded with what is returned and followed by the routing rule; nothing 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?

With zero parameters and an output schema present, the description only needs to frame purpose and timing, which it does well. Minor gap: it does not indicate whether the returned set is fixed or workspace-dependent.

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 no parameters, so the baseline is 4. The description correctly implies no inputs are needed to enumerate the warehouses.

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 ("List") and resource ("the three warehouses") and even enumerates them (doorstep, turnaround, ledger), plus the attributes returned. An agent can distinguish this from search_catalog/run_sql immediately.

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 "Call this first when you do not know which warehouse a question belongs to," giving a clear selection rule for a discovery step. It does not name the sibling tools that take over once the warehouse is known, so it falls just short of a full when/when-not treatment.

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