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

No annotations are provided, so the description carries the full burden. The read verb '查看' implies a safe read, and the enumerated return contents (PK, FK, indexes, row counts) tell the agent what to expect. However, it says nothing about whether the data is live or from the metadata index (siblings rebuild_metadata_index / metadata_index_status hint at caching), nor about permissions or latency.

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 whose output list is front-loaded, followed by the one imperative usage rule. Nothing is padded or 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?

An output schema exists, so return values need no explanation, and the description still summarizes them. Both required parameters are covered by the schema, and the invocation precondition is stated, leaving nothing critical missing for a read-only introspection tool.

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

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

Schema description coverage is 100%, and both parameters (schema, table) are already documented in the schema, including casing sensitivity and examples. The description adds no additional meaning beyond that, 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?

States a specific verb (查看/view) and resource (一张表/a table), then enumerates exactly what is returned: column names, types, nullability, comments, plus primary keys, foreign keys, indexes, and estimated row count. An agent can distinguish it from siblings like list_tables or sample_rows 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 mandates when to call it: '写 SQL 之前必须先调这个确认列名' (must call this before writing SQL to confirm column names). That is a clear precondition, but it names no alternative tools (e.g., find_variables, search_metadata) or conditions for choosing among 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?

With no annotations present, the description carries the behavioral burden and does so reasonably well: it discloses that the metadata index is English-only, that Chinese keywords return nothing, that stemming is applied, and that iterative re-querying is expected. It does not discuss result ranking, pagination, or cost/latency, which are minor gaps for a search tool.

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

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

The content is front-loaded with a bracketed role marker and a ★ callout for the critical keyword rule, and each sentence adds something (language constraint, example, stemming, retry policy). It is somewhat long, and the worked example could be tightened, but it does not feel 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?

An output schema exists, so the description needn't explain return values, and it covers purpose, keyword construction, and retry behavior adequately for a search tool. The main omission is disambiguation from the similarly named search_metadata sibling, which leaves the agent to guess which search surface to use.

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

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

Schema description coverage is already 100%, so the baseline is 3, but the description materially adds to the keywords parameter: the concept-expansion strategy, the 3-10 synonym count intent, and a worked example mapping a natural-language question to concrete terms. This goes beyond restating the schema by explaining what a good keyword set looks like.

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 bracketed label identifying this as the primary tool for finding variables and specifies semantic search over variable metadata (definitions, questionnaire text, labels, value labels) across the whole database. The verb+resource+scope are all clear. However, it never names the very similar sibling search_metadata, so the boundary between the two tools is left for the agent to infer.

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 strong, actionable guidance on how to invoke the tool — expand concepts into multiple English synonyms, prefer over-supplying, rely on stemming, and re-query with new synonyms rather than reporting no results. What it lacks is explicit routing: it does not state when to prefer this over search_metadata, run_query, or variable_stats, so no alternative-selection criteria are given.

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 provided, so the description carries the disclosure burden. It does describe the accessibility filter and the two returned aggregates, but says nothing about permission requirements or whether results are paginated or cached. Adequate for a zero-parameter read, but not rich.

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 short sentences: the first defines output and scope, the second gives the usage trigger. Zero filler 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?

An output schema exists, so return values need not be re-explained, and the description covers scope plus the recommended call order. Only the absence of any permission/access caveat keeps it from 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?

The tool takes no parameters, so there is nothing to disambiguate; baseline 4 applies. The description correctly does not waste space on parameter semantics.

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

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

States a specific verb and resource ('list all accessible schemas/data partitions') and adds the returned fields (table count, total size), which distinguishes it from siblings like list_tables and search_metadata. An agent can tell immediately what this tool returns.

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 first when exploring an unfamiliar database, which is a clear contextual trigger. It stops short of naming alternatives (e.g. list_tables or describe_table) for enumerating objects, so routing advice 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?

No annotations are provided, so the description carries the full behavioral burden. It does disclose meaningful output semantics — the two distinct section taxonomies, example code sets per survey family, and the caveat that they don't correspond — which is real value. It says nothing about read-only behavior, permissions, or cost, though for a listing tool that gap is modest.

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 is front-loaded in the first clause, followed by the two-category breakdown and the non-correspondence caveat. The enumerated examples (EC/ED/HH/HO/VL, WM/CH/BR/PR) tighten the sentences somewhat, but they are illustrative rather than 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?

An output schema exists, so return-value documentation is not the description's burden; even so, the description supplies the interpretive key (two taxonomies that don't map one-to-one) that a schema alone would not convey. Combined with the schema's parameter guidance, an agent has enough 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 description coverage is 100% and the single 'survey' parameter is already documented in the schema, including the 'use list_surveys to see available values' hint and examples. The description adds no parameter-level syntax or format detail beyond what the schema provides, 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?

States a specific verb+resource — listing the sections a survey contains — and even defines the resource into two concrete categories (physical_sections, questionnaire_sections) with example codes. It does not explicitly contrast itself with siblings like list_tables or list_schemas, which could plausibly be confused with 'physical_sections' as a table-splitting scheme.

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 rather than stated: it's evident you call this to discover a survey's section structure, and the note that the two lists are not one-to-one helps interpret results. However, there is no explicit when-to-use/when-not or routing to alternatives, even though list_tables and list_schemas overlap conceptually with physical sections.

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 disclosure burden and does well: it reveals that results are permission-aware, distinguishing 'ingested and readable' from 'present but role lacks permission' from 'not ingested'. It does not mention cost, pagination, or latency, which keeps it short of a 5.

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 listed and what metadata accompanies each entry, followed by the permission/status nuance. The closing instruction to 'answer truthfully' is slightly prescriptive but earns its place by tying the three states to a concrete answering behavior.

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 explanation is not strictly required, yet the description still summarizes the per-survey fields and adds the permission-state nuance an agent needs to answer existence questions without over-claiming. Nothing essential is missing for a zero-argument 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 tool takes zero parameters, so the baseline is 4. There is nothing for the description to disambiguate, and it correctly spends no words on arguments.

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 (list survey projects) and names concrete examples (CSES / DHS / HSES / LFS) that distinguish it from sibling listing tools like list_tables and list_schemas. It also enumerates the fields returned, so an agent knows exactly what this tool answers.

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

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

Gives a clear trigger condition: when asked whether a particular survey exists, use this tool and answer according to the three-state distinction. It stops short of explicitly naming alternative tools (e.g., search_metadata) for other survey-discovery needs, so routing is implied rather than fully specified.

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 burden and does disclose a real behavioral trait: result sets can be very large (600+ tables) and filtering is advised. It also previews returned fields (comments, row estimates, size). It stops short of covering permissions or rate/limit behavior beyond the schema's limit field.

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, then the filter hint, then the large-schema warning, all in three compact sentences. The listing of returned fields is mildly redundant given an output schema exists, but nothing is bloated.

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 no explanation, and the description still adds the crucial large-schema caveat plus the sibling alternative. Complete enough for correct invocation, missing only minor operational detail.

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 schema, name_contains and limit. The description only restates the name_contains filter, adding no syntax or format 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?

States a specific verb (list) and resource (tables under a schema), and further specifies the returned payload (table comments, estimated row counts, size). It also distinguishes itself from the sibling search_metadata, so an agent can route between them 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 tells the agent to pair it with a filter (name_contains) and, when that isn't appropriate, to use search_metadata instead. It also warns that some schemas exceed 600 tables, giving a concrete condition that selects the alternative.

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 provided, so the description must carry the behavioral burden. It discloses the informational payload (build time, entry count, coverage per survey), which implies a non-mutating read, but it never confirms that the tool does not trigger a rebuild nor describes cost, latency, or behavior on a missing/empty index.

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 front-loaded sentence with no filler; the resource is named first and the returned fields follow immediately. 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?

With an output schema present, the description need not enumerate return values in detail, and it already names the main status fields. The only shortfall is the absence of guidance tying it to rebuild_metadata_index as the read/write pair.

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 beyond what the schema shows. The schema coverage is 100% and the empty property set is self-explanatory.

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 ('查看本地元数据索引的状态' - view the local metadata index status) and enumerates what the status comprises: creation time, entry count, and per-survey coverage. This clearly separates it from the sibling rebuild_metadata_index, though it does not name that sibling explicitly.

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 only implied: an agent can infer this is the read-side counterpart to rebuild_metadata_index, useful for checking index freshness. There is no explicit when-to-use statement, no condition that selects this over alternatives, and no stated prerequisites.

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 provided, so the description carries the full behavioral burden, and it does disclose key defaults: missing-value codes are excluded by default, kind='auto' resolves to bar vs histogram by data type, and weight triggers weighted aggregation. It omits any permission/auth or size-limit behavior, keeping it short of a 5.

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, then the auto-selection rule, then defaults and the weight caveat. Every sentence carries information with little waste, though the auto/weight sentences are somewhat dense.

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

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

An output schema exists so return values need no explanation, and the description covers the decisions an agent must make: chart type resolution, missing-value handling, and weighting. Nothing required 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?

Schema coverage is 100%, so baseline is 3, but the description adds genuine meaning beyond the schema for kind ('auto' resolution logic), weight (survey weighting semantics), and include_missing (default exclusion). This goes past merely restating the parameter list.

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 ('把一个变量画成图') and explains the rendering target ('图会直接显示在网页上'). It distinguishes itself from sibling stats tools like variable_stats by being a visualizer, but never names a sibling explicitly, so it stops short of a 5.

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

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

Provides real conditional guidance for one parameter ('调查数据展示总体分布时应该加权'), but gives no guidance on when to reach for this tool over describe_table, variable_stats, or sample_rows. Usage context is implied rather than framed against alternatives.

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

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

No annotations are provided, so the description must carry the behavioral burden. It clearly implies a read-only operation ('读出') and discloses that it returns authoritative handwritten documentation containing pitfalls, and that it takes precedence over other tools. It does not explicitly state side-effect safety or permissions, leaving a minor 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?

Three tightly written sentences: first states what it reads, second explains its value and contents, third gives usage conditions and precedence. It is front-loaded and free of 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?

With an output schema present, return values are covered. The description supplies purpose, content, usage triggers, and precedence, which is complete for a read-only guide tool with one optional parameter.

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 itself documents the single optional 'section' parameter with examples. The description adds no additional syntax or format details for the parameter, 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 verb (读出/read out) and three specific resources (public._guide, public._catalog, public._data_issues). It distinguishes itself from sibling metadata tools by declaring itself the authoritative handwritten source and specifying it should be consulted first for MICS, cross-dataset, and join work.

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 call it (MICS data, cross-dataset/cross-country comparisons, joining multiple tables) and instructs to call it first. It also establishes precedence over other tools' inferential descriptions. However, it does not specify when not to use it or name specific alternative tools, so it falls short of the top 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?

With no annotations, the description carries the full behavioral burden, and it does disclose a valuable trait: the operation costs roughly 10 seconds to 2 minutes depending on data volume, which tells the agent this is expensive and slow. However, it says nothing about whether the rebuild is idempotent, whether it blocks concurrent queries, or whether it can fail partway.

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: what it does, then the conditions that require it, then the cost. Every sentence earns its place and nothing is repeated from structured fields.

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, and the description covers purpose, trigger conditions, and latency. What remains thin is failure/concurrency behavior for a long-running mutation, but for a parameterless maintenance command this is close to 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 tool takes zero parameters, so there is no parameter semantics for the description to add; the baseline for a parameterless tool is 4. Schema coverage is also 100%, so nothing is left 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+resource ('重建本地元数据索引' / rebuild the local metadata index) that is unambiguous and clearly distinct from the read-only lookup siblings like search_metadata and metadata_index_status. It stops short of explicitly naming the sibling that reports index state, so an agent must infer that distinction 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?

Gives two concrete trigger conditions: after new surveys/variables are added to the database, and after being granted access to a new schema. That is clear 'when to use' context. It does not state when NOT to run it or point at metadata_index_status as the cheaper way to check whether a rebuild is actually needed.

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 behavioral burden and does so well: it discloses the read-only enforcement (SELECT/WITH/EXPLAIN), a hard 500-row cap, and a 30-second timeout — exactly the operational traits an agent needs. It omits what happens on rejection or how to page past 500 rows, so it is strong but not exhaustive.

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 what the tool does before the constraints, then syntax and domain tips. Every sentence carries information, though the weighting advice sits slightly apart from the query-execution mechanics.

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 described, and the description still covers safety, limits, timeout, and identifier-quoting pitfalls. With no annotations to lean on, the remaining gap is error behavior and pagination semantics beyond the 500-row ceiling.

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 real semantics: the allowed statement classes for the sql parameter, the requirement to double-quote uppercase identifiers, and the weight-column convention for aggregate metrics. The limit parameter's 500-row ceiling is stated, though the description doesn't explain how it interacts with the server-side 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+resource ('执行一条只读 SQL 查询并返回结果') with the scope qualifier '只读'. It is clearly distinguishable in practice from metadata-oriented siblings like describe_table and sample_rows, but it never names an alternative, so it stops short of explicit sibling 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 defines the usage envelope (read-only statements only, 500-row cap, 30s timeout, weighting advice for aggregate metrics), which implicitly tells the agent when this tool applies. However, it never says when to prefer run_query over describe_table, sample_rows, variable_stats, or plot_variable, so routing guidance 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?

No annotations are provided, so the description carries the full burden. Sampling implies a read-only, non-destructive operation, but the description never states that explicitly, nor does it mention the 50-row cap or any access requirements. It adds genuine context about why one samples (missing-value encodings, field formats), which lifts it above a bare minimum.

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 tight sentences with zero waste; the action is front-loaded and the rationale follows immediately. Nothing is padded or repeated from 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?

An output schema exists, so return values need no explanation, and all four parameters are documented in the schema. The description covers purpose and use context adequately; only the read-only/safety framing and routing against siblings are absent, which is a minor gap for a low-risk sampling tool.

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

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

Schema description coverage is 100%, so the schema already documents schema, table, columns and limit (including the 1-50 bounds and the advice to specify columns on wide tables). The description adds no parameter-level syntax or format detail beyond that, 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?

States a specific verb+resource: sample a few real rows from a table, and goes further by naming the goal (confirming value shapes, missing-value codes like 96/97/98/99, field formats). This is far more concrete than a bare 'sample_rows' restatement, though it does not explicitly contrast itself with run_query or describe_table.

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 use context — use it to verify how values are actually encoded and formatted, especially sentinel missing-value codes. It does not name alternatives (e.g. run_query for filtered pulls, describe_table for schema-only inspection) or state when-not-to-use, so it stops short of the top band.

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 burden and does disclose the key behavioral trait: matching is exact substring only, with no synonyms or stemming, unlike find_variables. It doesn't cover auth/permission needs, but the output schema exists and return shape is not its job. Solid disclosure of the most decision-relevant 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?

Front-loaded with purpose before the guidance note, and the two sentences each carry information. The starred alternative note is longer but earns its place by preventing misuse against find_variables.

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 needn't be explained, and the description covers scope, matching limitations, and the alternative tool. For a 3-parameter search tool this 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?

Schema description coverage is 100%, so limit and schema are fully documented in the schema already, establishing a baseline of 3. The description adds only a hint about keyword content (English words), which the schema also states, so little value beyond structured fields.

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

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

States a specific verb and resource (keyword search over physical structure: table names, table comments, column names, column comments) and explicitly contrasts itself with find_variables. An agent can distinguish this from list_tables, describe_table, and find_variables 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 both when-to-use ('I roughly know the table/column name, help me locate', or view a table's comment) and when-not-to-use, naming the sibling find_variables and explaining what that tool searches instead. It even explains why find_variables is better for semantic queries (stemming, relevance ranking).

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 provided, so the description carries the full behavioral burden, and it does disclose non-obvious behavior: missing-value codes are auto-detected from metadata rather than heuristically guessing 96-99, codes are reported separately, and the tool explicitly signals when value labels cannot be resolved. This is meaningful transparency, with only auth/performance characteristics left unaddressed.

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 content is front-loaded with the core purpose and then details the missing-value handling, which is the most valuable differentiator. It is dense but each clause (counts, distribution, descriptives, weights, missing-code logic) earns its place, 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?

An output schema exists, so return values need not be explained, yet the description still clarifies the semantics of what is returned (valid vs non-null, code meanings). Combined with the absence of annotations, the description covers the behavioral surface an agent needs; only cross-tool routing guidance 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 four parameters (table, column, schema, weight) are already documented in the schema. The description adds only a light framing note that sampling weight columns are surfaced, which does not go beyond the schema's own explanation. 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 names a specific verb and resource: computing statistics for a single variable, enumerating exactly what is returned (non-null counts, valid counts after missing-code exclusion, value distribution with code meanings, numeric descriptives, available weight columns). This is clearly distinct from sibling tools like describe_table or plot_variable, though no sibling is named explicitly.

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 scope of the outputs — an agent can infer this is the tool to reach for when it needs per-variable summary statistics. However, there is no explicit when-to-use versus alternatives (e.g., describe_table vs run_query vs plot_variable) and no stated prerequisites or exclusions.

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