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

The annotation readOnlyHint: true covers the safety profile, and the description adds useful behavioral context: it is server-side, performs GROUP BY aggregations, and caps results at 1000. It also mentions a performance benefit (token savings). No contradictions 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 extremely concise—four short sentences, each earning its place: what it does, why it's beneficial, supported functions, and a key limit. There is zero fluff 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?

Given the high schema coverage and read-only annotation, the description covers the essential context: purpose, token efficiency, functions, and limit. It does not describe return format, but that is not critical here. It omits some advanced behaviors (e.g., approximate mode) that are well documented in the schema, so it remains complete enough.

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 92%, so the schema carries most parameter meaning. The description adds minimal extra insight, such as the 'limit capped at 1000' (not in schema) and enumerates the functions, but otherwise does not explain parameter semantics beyond what schema already provides. 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 clearly identifies the tool as 'Server-side aggregations (GROUP BY)', which is a specific verb-resource combination. It distinguishes itself from sibling tools like get_rows and sample_rows by explicitly noting that it saves tokens versus returning rows for the LLM to aggregate, and lists the supported functions.

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 on when to use it: when the LLM needs aggregated data rather than raw rows. It does not explicitly name alternatives like run_sql, but the token-saving statement implies a preference over row-returning tools. The 'limit capped at 1000' also sets expectations for scale.

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 readOnlyHint=true annotated, the description adds value by detailing behavior: the in-memory ring versus persistent SQLite sink, the prerequisite JDATAMUNCH_PERF_TELEMETRY=1 for persistent modes, and which tools are cached. It does not contradict the annotation and provides useful context beyond the safety flag.

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

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

The description is three concise sentences that front-load the core purpose and outputs. Each sentence adds distinct information: definition, return metrics, and window behavior details. No wasted words, and the structure leads with the most important 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?

With no output schema, the description lists the return values but does not specify the exact JSON structure. It covers the key aspects: operation, parameter effects, and environmental prerequisites. The sibling mention adds a minor contextual clue, though it could be confusing. Overall, it is sufficiently complete 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?

The schema already provides descriptions for all three parameters (top, tool, window), so baseline is 3. The description adds semantics by explaining the window parameter's behavior (session vs persistent modes) and naming the cached tools, which is not in the schema. This incremental value justifies a 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's function: 'Per-tool latency and cache-hit telemetry.' It lists specific outputs (p50/p95/max latency, error rate, slowest tools, cache hit rates), making it distinct from sibling tools which focus on data operations. The verb 'returns' is explicit and resource-specific.

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 on when to use the tool by explaining the window parameter modes and the environment variable requirement for persistent data. However, it does not explicitly state when not to use it or mention alternative tools for similar tasks, missing a direct exclusion clause.

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 readOnlyHint annotation, the description discloses the tool's composite nature, the exact four signal sources, the output as a verdict with ranked blockers and a recommended_action, and the defined verdict tiers. This adds substantial behavioral context that is not available from annotations or schema alone, setting clear expectations for 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 core content is packed into one informative sentence listing signals and output, followed by a concise list of verdict tiers. The final promotional sentence ('The killer feature...') adds no functional value and is mild fluff, preventing a perfect score.

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

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

The tool is relatively complex with no output schema, but the description covers the key return elements (verdict, ranked blockers, recommended_action), the verdict tiers, and the four input signals. It does not detail error handling or per-signal edge cases, but for an agent it provides sufficient context to invoke and interpret the result. This is slightly more than the bare minimum, so a 4 is appropriate.

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 67%, with column and window_days already described; the tool description reinforces that runtime traffic (and thus window_days) is one of the four signals. However, it adds no new meaning for dataset_id, which remains undocumented in both schema and description. Since coverage is moderate and the description does not fully compensate, a 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 clearly states a specific verb+resource: a composite preflight check on whether a column is safe to drop. It distinguishes itself from siblings by enumerating four fused signals (primary-key, foreign-key, cross-dataset name match, runtime traffic) and listing the verdict tiers, 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?

The description implies a clear usage context: use this tool when you need a preflight safety check before dropping a column, and it mentions that it fuses multiple signals, which hints at being a comprehensive alternative to simpler individual checks. However, it does not explicitly name sibling tools or state when not to use it, 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?

The description discloses that the tool pins a 16-string canary file, recomputes it on demand, and reports cosine drift. It also explains why drift matters (semantic ranking quietly degrades). Since annotations only state readOnlyHint=false, the description adds meaningful side-effect context beyond the annotation.

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 well-structured and front-loaded with the core purpose. It is slightly verbose but every sentence contributes context except the final sibling reference, which is somewhat obscure and could be omitted. Overall, it remains compact for the complexity involved.

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 and moderate complexity, the description provides sufficient context: why the tool exists, what it does, and how to use it. It could mention the exact return format (e.g., drift value and alarm boolean), but the schema and parameter descriptions fill most gaps. The description is adequate 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% with both parameters described. The description adds context for 'force' (establish baseline) and ties 'threshold' to the alarm condition, reinforcing the schema descriptions and clarifying the intended usage flow.

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 purpose: detecting embedding provider drift since a pinned baseline. It specifies the resource (embedding provider/canary file) and the mechanism (cosine drift), distinguishing it from schema drift or validation tools among 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 usage guidance is provided: call with force=true once to set the baseline, then again after a suspected provider change. It does not explicitly exclude alternatives or compare with other drift-related tools, but the context is clear enough for an agent to decide when this tool is appropriate.

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. The description adds meaningful context: schema_stability is omitted when fewer than 2 history snapshots, and runtime_coverage is an optional 7th axis that appears when traces are ingested. This discloses conditional behavior beyond the read-only hint, though it doesn't delve into other edge cases.

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 purpose, axes, and output format. The closing clause 'Mirrors jcm's six-axis health radar' adds little value and is slightly extraneous, but the rest is efficient and well-structured.

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, the description adequately specifies return values (scores, composite, grade) and conditional axes. It also explains the optional runtime axis and pairing with diff tool. The main missing piece is the dataset parameter semantics, but overall it is sufficient for a read-only health 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 covers two of three parameters (window_days, include_runtime) with descriptions, giving 67% coverage. The description itself does not elaborate on parameters. The required 'dataset' parameter lacks any description in both schema and tool description, leaving an important gap.

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

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

The description clearly specifies it is a 'six-axis health radar' for a dataset, names all six axes, and explicitly states the output format (0-100 scores per axis plus composite and A-F grade). It distinguishes from sibling diff_data_health_radar by noting the pairing, and from other health tools like get_dataset_health by its multi-axis scope.

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 mentions pairing with diff_data_health_radar for snapshot deltas, implying this tool is for current health snapshots. However, it does not explicitly state when not to use it or compare with alternative health tools like get_dataset_health, so it stops short of full when/when-not 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?

The description discloses that the operation is irreversible and requires re-indexing to use again, going well beyond the readOnlyHint=false annotation. It also specifies that the SQLite store is removed, providing concrete destruction details.

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

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

The description is three short sentences, each serving a distinct purpose: action, benefit, and consequence. No redundant 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?

For a simple delete tool with one parameter and no output schema, the description covers the core behavior, disk-space motivation, and irreversibility. It does not specify the return value or error handling, but that is arguably unnecessary for this level of complexity.

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 single parameter 'dataset' is fully described in the schema with 'Dataset identifier to delete (from list_datasets),' and the tool description adds no additional parameter information. Since schema coverage is 100%, the baseline of 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 clearly states 'Delete an indexed dataset and its SQLite store,' identifying the specific verb and resource. This distinguishes it from siblings like list_datasets or describe_dataset, which are non-destructive.

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 includes 'Frees disk space,' indicating the practical reason to use this tool. It does not explicitly reference alternatives or exclusions, but the context is clear enough for a delete operation.

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 readOnlyHint annotation already establishes the safe read-only nature. The description adds valuable behavioral context by disclosing caps on top_n and histogram_bins, and clueing the user into the type of output (distribution, histograms, temporal range). It does not contradict the annotation.

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 concise (three sentences) and front-loaded with the core purpose. Each sentence carries useful information: output types, column type handling, and caps. No unnecessary 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?

With no output schema, the description does a good job explaining the return shape (distribution, histogram, temporal range) and constraints. It could mention sample output or redaction behavior, but the schema covers those. Overall, it is sufficient for a 6-parameter tool with a clear purpose.

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 has 100% coverage for parameter descriptions. The description adds meaning beyond the schema by specifying maximum caps (top_n <= 200, histogram_bins <= 50), which are not present in the schema's default-based descriptions. It also clarifies how histogram_bins applies to numeric data.

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 purpose with a specific verb ('Deep profile') and resource ('single column'), distinguishing it from dataset-level tools like describe_dataset. It also specifies the types of profiling (value distribution, histogram bins, temporal range), making its function 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?

The description does not provide explicit guidance on when to use this tool versus alternatives like get_distribution or get_data_hotspots. It implies a 'deep profile' use case but lacks clear context, exclusions, or 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds useful behavioral context about auto-pagination on wide tables (60+ columns) and the performance benefit of a single call. It does not contradict annotations and provides meaningful additional detail about how the tool behaves.

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 tightly written with four sentences, each earning its place. It opens with a strong front-loaded label ('Primary orientation tool'), then explains outputs, value proposition, and edge-case handling. There is no fluff 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?

The tool is simple (3 params, no output schema), and the description covers all key aspects: what it returns (column metadata), why to use it (orientation), and how to handle wide tables. The return content is explicitly enumerated, so no essential information is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explicitly explaining the purpose of columns=[] and columns_offset in the context of pagination, which is not fully captured in the schema descriptions. This lifts the score above 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 clearly states the tool's function: 'Returns every column's name, type, cardinality, null%, and sample values.' It also positions itself as the 'Primary orientation tool,' which distinguishes it from sibling tools like describe_column and get_distribution. The verb+resource structure is specific and 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?

The description provides clear guidance on when to use the tool: 'Primary orientation tool' and 'A single call replaces reading the entire source file.' It also gives actionable instructions for wide tables (use columns=[] or columns_offset). However, it does not explicitly name alternative tools or state when NOT to use this tool, which prevents 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?

The description adds significant behavioral detail beyond the readOnlyHint annotation: it's a pure function, returns specific delta types, uses a 3-point threshold, and expects the radar sub-field. This gives the agent a clear model of the tool's behavior without contradicting 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?

Two sentences convey purpose, input format, and output details with zero waste. It is front-loaded with the primary action.

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 and minimal annotations, the description covers input requirements, return values (per-axis deltas, composite, grade change, lists, verdict), and threshold. It is complete enough for an AI agent to use effectively.

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?

Despite 100% schema coverage, the schema only describes parameters as 'object'. The description adds crucial meaning by instructing to pass the radar sub-field from two data_health_radar responses, making the expected input exact.

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 diffs two data_health_radar payloads, using a specific verb and resource. It distinguishes itself from sibling tools like data_health_radar (which generates the payload) and get_schema_drift (which compares schemas) by focusing on radar payload comparison.

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: pass the radar sub-field from two data_health_radar responses, with an example (yesterday vs today). However, it does not explicitly name alternatives or exclusion criteria, so it falls 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?

The description adds meaningful behavioral context beyond the readOnlyHint=false annotation, such as the prerequisite provider and the trade-off with lazy embedding. However, it doesn't disclose potential side effects like resource intensity or what happens to existing cached embeddings, preventing a perfect 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?

Three tightly written sentences cover purpose, usage context, and requirements. Every sentence earns its place, with no redundant or filler content.

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 is sufficiently complete for a tool with only two parameters and no output schema. It explains what, why, and prerequisites, though it doesn't address what happens at runtime (e.g., cost, duration) or post-conditions, so it's not 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 schema already thoroughly documents both parameters. The description adds no additional detail about the parameters themselves, keeping this at the baseline of 3.

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

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

The description clearly states the tool precomputes column embeddings for semantic search, using a specific verb and resource. It distinguishes itself from alternative lazy embedding in search_data by framing it as an optional warm-up to eliminate latency.

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 explains when to use this tool versus the alternative (lazily embedding via search_data with semantic=true), and mentions the required embedding provider. This gives the agent clear situational 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?

The annotations only provide readOnlyHint=false (a write). The description goes far beyond this by disclosing deterministic server-side assembly, fail-closed validation of evidence_refs against session retrieval, session-scoped persistence, the exact receipt format, immutable byte-identical reads, and that it 'never writes to your data.' This is exemplary behavioral disclosure.

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

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

The description is densely packed into three sentences, each earning its place: purpose, mechanics/validation, and access/constraints. It front-loads the primary purpose. Slightly long but well-structured; no redundant 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 there is no output schema, this description fully compensates: it specifies the exact receipt fields ({handoff_id, resource_uri, sha256, length, canonical:true}), the immutable resource URI, and critical constraints (appendices exactly once, no character limit). All 6 parameters are covered by the schema, and the description covers behaviors not in the schema, making it wholly complete for an agent to invoke and interpret results.

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 extra semantics beyond the schema: it gives concrete formats for evidence_refs ('<dataset>::<column>#column' or dataset names), explains the validation behavior ('unknown refs fail closed'), and mentions handoff/v2 claims binding evidence per claim. These details enrich parameter understanding beyond the schema alone.

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 'Finalize' and a defined deliverable: 'one canonical Markdown handoff for a completed data audit/analysis.' It clearly identifies this as the terminal documentation tool, distinct from siblings like summarize_dataset or run_sql, and references protocol/version identifiers (jdatamunch.handoff/v1) for precision.

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 states this is for a 'completed data audit/analysis,' giving a clear temporal context. It does not explicitly name alternative tools or when not to use it, but the context strongly implies the handoff should be finalized only after audit/analysis work is done, which is sufficient 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?

readOnlyHint=true covers safety, and the description adds meaningful algorithmic detail: the composite scoring signals, union-find clustering, and the four cluster categories. The 'investigate, not merge' warning gives an agent useful nuance far beyond what an annotation can express.

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: core behavior first, then signals, clustering, use cases, and a heuristic warning. The only somewhat peripheral line is the 'Mirrors jcm's find_similar_symbols' cross-reference, but overall it is efficient.

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?

Since there is no output schema, the description compensates by naming the cluster categories and the fusion mechanism. It doesn't spell out the return shape, but an agent receives enough guidance to choose and 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 description coverage is 100%, so all four parameters are already documented in the input schema. The description reinforces the conceptual idea of composite scoring, but does not need to repeat parameter mechanics; the baseline of 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 identifies a specific purpose and use cases: finding duplicate columns across datasets, surfacing naming drift, and detecting the same conceptual column spread across multiple datasets. It clearly distinguishes this from related sibling tools like find_unused_columns by emphasizing cross-dataset similarity.

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 to find...' and gives concrete scenarios, plus a caution that results are heuristic, so the agent knows the result is a starting point. It doesn't explicitly list when-not-to-use or alternatives, but the use-case framing and caveat are 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?

The description goes well beyond the readOnlyHint annotation by disclosing that it reads from runtime_query_calls, excludes primary-key candidates and audit fields by default, and refuses to run when no runtime data exists. It also explains the rationale for the refusal ('would otherwise trivially flag every column'), giving the agent insight into the tool's failure mode.

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 four sentences, each with a distinct purpose: statement of function, data source, exclusions, and error behavior. It is front-loaded with the core purpose and contains no redundant wording.

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 tool's purpose, data dependency, exclusions, and error condition, which is sufficient for a read-only list tool. The only minor gap is it does not explicitly describe the return format (e.g., a list of column names), but given the tool's name and purpose, this is reasonably inferable.

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 adds meaning to window_days by defining it as the look-back window for what counts as 'queried', and clarifies the default exclusion behavior for primary keys and audit fields, which maps to exclude_pk and exclude_audit. Since the schema already documents 4 of 5 parameters, this contextual explanation provides additional value beyond the schema 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 that the tool surfaces columns with zero or stale runtime traffic, specifying the resource (columns) and the condition (not queried within window_days). It distinguishes from siblings like find_similar_columns and check_column_drop_safe by its reliance on runtime query logs, though it does not explicitly name alternatives.

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 when to use the tool: after runtime data has been ingested via ingest_sql_log, and for identifying under- or un-used columns. It also warns that it refuses to run without ingested data, a clear precondition, but it does not explicitly state when not to use it or name alternative tools.

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 readOnlyHint annotation already marks this as safe, and the description adds that results are filtered to significant correlations, sorted by |r|, and capped at 200. This goes beyond the annotation, though 'significant' is vague and could refer to min_abs_correlation or statistical significance.

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

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

The description is three concise sentences that each add value: what it does, what it returns, and when to use it. 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 full schema coverage and readOnly annotation, the description covers the tool's behavior well. Minor gaps: the meaning of 'significant' and the availability of Spearman are not mentioned, but these are in the schema/params. Overall adequate.

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 describes all parameters with 100% coverage, so the baseline is 3. The description doesn't add specific parameter guidance beyond mentioning the top_n cap, which the schema already states. It doesn't clarify method options or column restrictions.

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

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

The description clearly states the tool computes pairwise Pearson correlations between numeric columns, specifies the output sorted by |r| descending, and distinguishes it from sibling tools like get_distribution or aggregate. It also notes filtering and a cap, making the 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 an explicit use case: 'Use this to discover relationships in the data without manual exploration.' However, it doesn't mention when not to use it or alternatives, so it's clear but lacks exclusions.

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 readOnlyHint annotation, the description discloses the fallback behavior when include_runtime is true but no traces exist, including the _meta.runtime_caveat. It also mentions versioning (v1.10.0) and the top_n cap, providing rich contextual 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 description is two sentences, front-loaded with the core purpose, and every clause adds value. No fluff 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?

Given the tool is read-only (as annotated) and there is no output schema, the description fully covers purpose, scoring inputs, edge-case behavior, and constraints. An agent can invoke it correctly without further documentation.

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 semantic context by explaining how include_runtime affects scoring and the caveat condition, which enriches the parameter's meaning beyond the schema's default value description.

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 ('Return') and identifies the resource ('highest-risk columns in a dataset') with a clear composite scoring method. It distinguishes itself from sibling tools by focusing on risk ranking and the optional runtime traffic signal.

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 its use case ('highest-risk columns') but does not explicitly state when to prefer it over alternatives like get_dataset_health or data_health_radar. No exclusions or alternative tool references are provided, falling under 'implied usage'.

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

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

Annotations already declare readOnlyHint=true, and the description adds meaningful behavioral context: it explains what the grade represents, that it combines multiple components, and that it deliberately avoids judging whether actual values are correct. This helps agents set expectations. It could still name more details about return shape, but the existing text is effective.

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 sentences, each adding distinct information, with the core purpose front-loaded. The phrase 'for a dataset (B4)' is slightly cryptic and could confuse agents, but it does not materially hurt the definition.

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 simple one-parameter tool with no output schema, the description covers the purpose, the combined inputs, and a clear boundary of what it does not measure. It would benefit from naming the exact structure/format of the breakdown, but it is broadly 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 schema fully describes the single 'dataset' parameter as a string identifier, so the description does not need to add parameter-level syntax. The description adds no specific detail about the identifier format, but that is the low bar because schema coverage is 100%.

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

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

The description clearly identifies the tool as producing a composite quality grade (A–F) for a dataset, listing the specific factors that go into it. It also adds the caveat that it grades structure and completeness, not value correctness. However, it does not explicitly differentiate itself from related sibling tools like get_schema_drift or data_health_radar.

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 should be used when an overall dataset quality assessment is needed, especially for structural and completeness issues. It does not explicitly say when not to use it or which sibling tool might be a better alternative, so the agent must infer the use case.

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 readOnlyHint annotation already covers safety. The description adds meaningful context by explaining that snapshots are appended on every successful index_local and that n is capped at 50, which helps the agent understand the data freshness and limits. It does not contradict the annotation.

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 long, front-loaded with the primary action, and every clause adds value. It is efficiently structured with no 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 tool is a simple read operation with two well-documented parameters and no output schema. The description covers purpose, usage, and behavioral context, which is sufficient given the low complexity. Minor edge cases like empty datasets or missing dataset IDs are not addressed, but the description is still complete for typical 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 100%, so the schema already fully documents both parameters. The description's mention of 'n capped at 50' duplicates schema info without adding new meaning, so the baseline 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 uses a specific verb 'Return' and a specific resource 'the last N profile snapshots for a dataset', clearly stating what the tool does. It also distinguishes the tool by noting snapshots are appended on every successful index_local, which differentiates it from similar tools like get_schema_drift.

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 to detect schema/content drift over multiple ingests of the same dataset', providing a concrete use case. However, it does not mention when not to use it or name alternative tools, so it falls short of a full 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?

Beyond the readOnlyHint annotation, the description adds meaningful behavioral detail: it returns bin counts only, defaults to 20 bins, uses type-specific binning strategies, and never returns the underlying rows. This gives the agent a clear picture of output scope and side-effect profile. It could add a bit more about empty/missing-value handling, but the stated behavior is already strong.

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 purpose. The categorical mapping is dense but understandable. The mysterious 'B8' tag is the only element that does not add immediate value for an agent, which keeps this from a perfect score.

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

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

With no output schema, the description does enough by stating that it returns bin counts and not rows, and by describing the binning rules for each type. It doesn't fully specify the exact response shape or edge-case handling, but for the intended use it is sufficiently 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 covers 100% of parameters, but the description adds important semantic nuance beyond the schema, such as the default bin count of 20 and how the bins parameter applies differently depending on column type. This enriches parameter understanding without redundant repetition.

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 purpose ('Unified bin-counts for any column type') and precisely distinguishes the output from row-returning tools by saying it 'never returns the underlying rows'. The type-by-type behavior (numeric equal-width bins, datetime time-bucket bins, categorical top-n + 'other') makes the tool's function unmistakable and clearly differentiates it from siblings like get_rows or sample_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 gives clear usage context: it is a 'Token-cheap way to ask what does this column look like?'. This implies when to use it, but it does not explicitly name alternatives or state when not to use it. It provides enough context for an agent to select it for column distribution exploration, though it could be stronger with explicit exclusions.

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 context beyond the readOnlyHint: it explains the tool reads from runtime_redaction_log, which is populated only when ingest_sql_log runs with redact=True, and clarifies that an empty result is a meaningful outcome. This is valuable behavioral disclosure that annotations alone don't 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?

Three sentences, each earning its place: the function/return value, the populating dependency, and a critical edge-case clarification. Information is front-loaded, no redundant phrasing, and the description is compact yet rich.

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 moderate complexity, no output schema, and good annotations, the description covers the purpose, return value ('per-pattern counts'), filtering options, and an important empty-result interpretation. It is complete enough for an agent to select and invoke 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 documents 'source' and 'since_days' with descriptions (67% coverage). The description's phrase 'Filter by source and lookback window' merely restates the schema. It adds no new parameter semantics beyond what the schema provides, so the baseline 3 is correct.

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 function: 'Forensic accounting of PII redactions for a dataset' and specifies the output: 'Returns per-pattern counts from runtime_redaction_log'. It distinguishes itself from sibling tools by referencing the specific log and its population source (ingest_sql_log), making it uniquely 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 intended use case is explicitly stated: 'so operators can verify the chokepoint is firing on production traffic.' It also notes 'Empty result with no traces ingested is not an error,' which guides interpretation. However, it does not mention when to avoid this tool or provide alternatives, so a 4 is appropriate.

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 readOnlyHint annotation already covers non-destructiveness. The description adds important behavioral context beyond the annotation: filters are SQL-parameterized to prevent injection, results are capped at limit rows, the default limit is 50, and large-ish retrievals should use offset rather than raising the limit. It does not describe output shape or project redaction behavior, but the schema covers those details.

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. The first sentence identifies purpose, the middle sentences provide operator and projection guidance, and the final sentence covers pagination semantics. It packs useful decisions into a small number of sentences without 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 readOnly annotation, 100% schema coverage, and careful parameter descriptions already presenting limit, offset, redaction, filters, and projection, the description completes the picture by explaining how an agent should compose the key parameters and when to hand summarization off to another tool. There is no formal output schema, but the schema's redaction parameter already references _meta.redaction details.

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 has 100% parameter documentation, so the baseline is roughly 3; the description still earns extra by giving higher-level guidance that the schema does not: minimal columns projection reduces tokens on wide tables, and offset should be preferred to raising the limit. The operator list is redundant with the schema enum, so it is not perfect.

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

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

The description states exactly what the tool does: filtered row retrieval using structured filters. It also distinguishes itself from aggregation tools by explicitly saying to prefer aggregate() for summaries, so an agent can understand its scope and role.

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 actionable guidance: use columns=[] to reduce tokens, prefer aggregate() for summaries rather than paginating through rows, and page with offset instead of raising the limit. These are concrete selection and invocation rules, not just restated intentions.

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 (safe read). The description adds behavioral detail: 'Pure in-memory comparison — no re-reading source files,' and discloses the output assessment format (identical/additive/breaking). 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 concise and front-loaded, stating the purpose first, then expanding to detection scope, behavior, and output categories in four sentences with no redundant information.

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

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

For a two-parameter, no-output-schema tool, the description is complete: it covers comparison dimensions, in-memory behavior, use case, and possible assessment results. No critical details are missing for effective 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?

Input schema provides 100% coverage with descriptions for dataset_a (baseline) and dataset_b (comparison target). The description itself adds no additional parameter semantics, so the baseline score of 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 'Compare schema (columns, types, nullability) between two indexed datasets' with a specific verb and resource. It distinguishes from siblings like describe_dataset (single dataset) and get_schema_impact (query impact), and clearly lists detection capabilities and assessment categories.

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: 'Useful for detecting schema changes between dataset versions.' However, it does not explicitly name alternatives or state when not to use this tool, though the context is unambiguous enough.

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 readOnlyHint annotation, the description adds substantial behavioral detail: walks inferred FK graph to max_depth, surfaces direct and transitive hits, normalizes blast_score to [0,1], and flags type_mismatch for retype_column. Explicitly states read-only, fully consistent 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 sentences, each contributing important info: the change types, the graph-walking algorithm, and the retype-specific edge case. No filler or repetition of schema details.

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 7 parameters, an inferred FK graph, and no output schema, the description covers key output semantics (blast_score normalization, type_mismatch flags) and explains the traversal logic. It does not describe return structure, but the absence of an output schema and the rich behavioral description make this acceptable.

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 covers most parameters (71% per context), with descriptions for kind, column, new_name, new_type, max_depth, window_days. The description enhances meaning by explaining how kind affects behavior (retype type_mismatch detection) and how max_depth controls graph traversal, adding value beyond 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 clearly states the tool computes transitive impact of column-level schema changes (drop/rename/retype), specifying both the action and the resource. It distinguishes from siblings like check_column_drop_safe by focusing on transitive FK graph traversal and blast_score normalization.

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 specifies the tool's context: assessing impact of column-level changes, especially for retype with type_mismatch flagging. It does not explicitly name alternatives or exclusions, but the context is clear enough for an agent to infer when 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?

The annotation readOnlyHint=true already establishes safety. The description adds valuable behavioral context beyond that by warning that savings are modelled estimates and not precise per-call measurements, which prevents an agent from overstating the confidence in results.

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. The first front-loads the action and result; the second adds an essential caveat. No words are 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?

Given zero parameters and no output schema, the description covers what is returned and its limitations. It could have mentioned the units or exact return shape, but for a simple no-arg stat tool this is sufficiently 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?

Input schema is empty, so parameter documentation is a non-issue. The description still clarifies scope with 'across all tool calls,' which gives all the semantic context needed for a zero-parameter call.

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: 'Return cumulative token savings and cost avoided across all tool calls.' It is immediately clear what the tool produces and how it differs from a per-call measurements tool, thanks to the second sentence explicitly marking these as estimates rather than per-call readings.

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 tells you the tool returns aggregate session-level savings, but gives no guidance on when to use this over any sibling tool. No alternative tools are named, and no exclusions or prerequisites are stated.

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

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

With only readOnlyHint=false provided, the description carries most of the behavioral disclosure burden and does so well: it explains profiling, statistics computation, SQLite loading, and incremental re-index skipping. It does not state whether re-indexing overwrites an existing dataset, which is 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 sentences with the main action and core behaviors front-loaded. The final sentence repeats the format list from the first sentence, but it adds value by making the rejection of other formats explicit.

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 operation with 8 parameters and no output schema, the description is sufficient for an agent to understand the tool's purpose, constraints, and defaults. The main missing piece is what the tool returns after indexing, but the side-effect-oriented nature of the tool makes this non-critical.

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 individual parameter descriptions already carry the semantic weight. The tool description mostly restates schema facts such as the incremental default and supported formats, adding little genuinely new meaning 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?

Starts with a specific verb and resource: 'Index a local data file (CSV, Excel, Parquet, or JSONL)' and clearly distinguishes itself from siblings like index_repo. It also names the concrete side effects: profiles columns, detects types, computes stats, and loads into SQLite.

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 establishes when the tool applies by listing supported file formats and explicitly stating that any other format is rejected. It also highlights the incremental flag's default behavior, but it does not explicitly compare against alternatives like summarize_dataset or validate_index.

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 signal readOnlyHint=false, so the description carries the burden of disclosing side effects. It explicitly states the tool downloads and indexes files, includes size/count limits, and explains token usage for private repos/rate limits. It does not mention overwrite or re-indexing side effects, but the incremental parameter hints at that 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 description is four sentences, front-loaded with purpose, and every sentence contributes meaningful information (file types, pipeline, naming, limits, token). No redundancy or 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?

Given the tool's moderate complexity (GitHub discovery, limits, auth, naming), the description covers essential operational details well. It lacks explicit post-index return behavior, but no output schema exists and the primary effect is indexing, so this is acceptable.

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

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

Input schema has 100% description coverage with clear parameter descriptions (url, incremental, github_token), so the baseline is 3. The description adds minimal parameter-specific context (e.g., GITHUB_TOKEN env var reference) but does not go beyond what the schema already 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 opens with a specific verb+resource ('Index data files from a GitHub repository'), then details the discovery and indexing process, supported file types, and dataset naming convention. This clearly distinguishes it from sibling index_local by specifying the remote source and naming 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?

The description gives clear context for when to use the tool: GitHub repository, file types, size limits, and auth requirements. It mentions 'same pipeline as index_local' but does not explicitly state when to use this over index_local or provide exclusions, so it stops short of full alternative 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?

Since annotations only provide readOnlyHint=false, the description adds meaningful behavioral detail: parsing formats, redaction of string/numeric literals plus cell-PII registry, roll-up into runtime_query_calls keyed by (fingerprint, table, column), and handling of unmapped tables. It does not address idempotency or overwrite semantics, but the disclosure goes well beyond the annotation.

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

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

The description is three concise sentences: main action, processing pipeline, and upstream/downstream context. Each sentence earns its place, and the front-loaded first sentence immediately conveys the tool's purpose. The version/phase reference is minor but does not detract.

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 one required parameter and no output schema, so the description adequately covers input formats, processing steps, persistence location, and relationship to other tools. It does not specify return values or failure modes, but for an ingest primitive this is a reasonable completeness level.

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, but the description enriches parameter meaning by explaining transparent .gz support, the redaction pipeline, and what 'unmapped' means. It translates parameter choices into runtime behavior without replacing the schema's own 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?

The description uses a specific verb ('Ingest') and clearly identifies the resource and destination: SQL log files (pg_stat_statements CSV or JSONL) into per-dataset runtime tables. It also names downstream consumers (find_unused_columns, check_column_drop_safe, data_health_radar), distinguishing it from the analytical sibling tools.

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

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

The description positions the tool as a 'foundational primitive' for specific downstream analysis features, making the intended usage context clear. It does not explicitly state when not to use it or offer alternatives, but the role as an ingestion step is evident from the phrasing and sibling tool list.

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

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

Annotations already declare readOnlyHint=true, and the description adds 'Idempotent' and 'no dataset context required'—behavioral traits that inform call timing and safety. This is useful additional context beyond the annotation, though it could go further by describing the return format or size.

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 concise and front-loaded with the primary action. Every sentence earns its place: the first states what it does, the second explains the benefit, and the third adds idempotency and sibling context. 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?

For a zero-parameter tool with no output schema, the description is remarkably complete. It explains the returned artifact, the motivation for using it, key behavioral traits, and sibling relationships. There are no significant gaps for an agent 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 tool has zero parameters, so parameter semantics are trivially complete. The description adds context about the tool's purpose and usage, which is appropriate given there is no schema to explain. It fully compensates for the absence of 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 clearly identifies the tool's function: returning the version-current CLAUDE.md/AGENT.md policy snippet for jdatamunch-mcp. It uses a specific verb 'Return' and a specific resource, and it distinguishes itself from siblings jcodemunch_guide and jdocmunch_guide by name.

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 a concrete use case: letting an agent keep a one-line CLAUDE.md reference rather than a static snippet that drifts. It does not explicitly state when not to use it or alternative tools, but the sibling mention helps orient the agent. This is clear contextual guidance, though not exhaustive.

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?

Given the readOnlyHint annotation, the description adds valuable behavioral context: it uses ATTACH DATABASE, caps row limit at 500, supports specific join types, and suggests projection to reduce tokens. It does not contradict the annotation and provides useful implementation details.

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 short, front-loaded set of 5 sentences that each add value: purpose, mechanism, join types, projection guidance, and row limit. 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 complex 13-parameter tool without an output schema, the description covers the core behavior, row limit, projection utility, and an alternative for summaries. It could mention prerequisites like the need for datasets to be indexed, but given full schema coverage, the description is sufficiently 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 descriptions cover 100% of parameters, so baseline is 3. The description adds meaning beyond the schema by explaining that columns_a/columns_b are for projection and can reduce tokens on wide tables, which is not fully captured in the schema. It also reiterates the hard row 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?

The description clearly states the tool's function: 'Join two indexed datasets via SQL JOIN.' It distinguishes itself from siblings by specifying it combines two SQLite stores via ATTACH DATABASE and supports specific join types, setting it apart from tools like run_sql or get_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 context on when to use the tool (joining indexed datasets) and advises 'Prefer aggregate() on join results for summaries,' offering an alternative for summaries. It lacks explicit exclusions (e.g., 'not for single-dataset queries') but is otherwise 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 signal a read-only operation, and the description adds useful scope: only datasets under the active storage_path are listed, and only indexed datasets appear. This gives agents accurate expectations without contradicting readOnlyHint.

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 with a distinct role: what is returned, when to call it, and a scope limitation. No filler or repetition; the most critical action ('call it first') is 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?

The description covers the returned fields, the recommended usage order, and the storage_path constraint. For a zero-parameter read-only listing tool, this fully equips an agent to invoke it effectively.

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 schema description coverage is 100%, so no parameter documentation is needed. The description does not add parameter-specific detail, but none is required; baseline 4 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: list every indexed dataset, and includes concrete output fields (row count, column count, source file). It also frames itself as the entry point for 'every other tool,' which distinguishes it from siblings like list_repos or describe_column.

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

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

Explicitly instructs 'Call it first' to find the dataset name needed by other tools and to confirm a file was indexed. It lacks explicit exclusions or comparisons to sibling tools, but the intended call order and use case are 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 provide readOnlyHint=true, so the read-only nature is captured. The description adds useful behavioral context by specifying that it only lists repositories indexed via index_repo and by declaring the exact return contents, which goes beyond the annotation and helps set expectations.

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

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

The description is three sentences, front-loading the primary action first, then the returned fields, then the scope limitation. Every sentence contributes essential information without redundancy or 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 zero-parameter, read-only list operation with no output schema, the description covers all necessary context: what is listed, which fields appear, and which repositories are excluded. Nothing appears missing for an agent to call the tool confidently.

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. The description adds no parameter-specific details, but none are needed because there is nothing for the caller to configure; the framing of the return contents makes the no-input action clear.

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, 'List', and the resource 'GitHub repositories indexed via index_repo,' immediately clarifying the tool's function. It further distinguishes the tool from siblings like list_datasets by enumerating exactly what is shown: repo name, HEAD SHA, dataset count, total rows, and dataset names.

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 defines the scope: 'Covers repos indexed with index_repo only; a dataset added by index_local is not listed here.' This gives clear guidance on when to use the tool, though it stops short of naming an alternative tool explicitly, leaving the agent to infer index_local as the alternative for local datasets.

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 readOnlyHint=true already present, the description adds a critical behavioral trait: 'Pure routing — no LLM call,' indicating deterministic, non-generative behavior. It also mentions 'ranked' output, but does not disclose behavior for unsupported intents or the exact output format, leaving some transparency 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?

Two concise sentences, front-loaded with the primary verb+resource and followed by key behavioral context. Zero 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 simple two-parameter read-only router, the description covers purpose, behavior, and supported intents. It lacks an explicit description of the return value format, but given the tool's simplicity and lack of output schema, this is a minor gap.

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

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

Schema coverage is 100%, so both parameters are already documented. The description adds value by enumerating the built-in intents (summarize, anomalies, compare, join, filter, trend, correlate), which helps the agent supply a valid `intent` value. No additional syntax is needed.

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: 'Map a natural-language intent into a ranked tool-call sequence for the given dataset.' This clearly distinguishes it from sibling execution tools (e.g., run_sql, aggregate) by positioning it as a pure planner/routing tool. It also lists supported intents, reinforcing its scope.

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 usage by stating it maps intent to a tool-call sequence, and the built-in intents list gives examples of when to use it. However, it does not explicitly compare against sibling tools or state when not to use it, so guidance is only implicit.

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 readOnlyHint annotation, it discloses execution constraints (PRAGMA query_only=1, 10-second budget, 500-row cap), dataset attachment semantics (first is main, others ATTACHed under schema names), and a naming example. This provides substantial behavioral context beyond the annotation.

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

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

The description is three tight sentences: purpose first, then constraints/behavior, then usage guidance. No wasted words, and every sentence adds distinct value.

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 safety, execution limits, dataset attachment, and usage scope. Given the tool's complexity (SQL execution with 6 params), this is comprehensive enough for an agent to select and invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds useful semantics for the 'datasets' parameter (order matters, first is main connection, others attached under schema names) and the row-cap limit, but most parameter details are already in the schema. This modest extra value justifies a 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 explicitly identifies the tool as a 'read-only sandboxed SQL escape hatch' that accepts single SELECT or WITH…SELECT statements, and differentiates it from structured tools by targeting HAVING/window functions/CTEs/multi-way joins. This clearly states both the verb/resource and its unique scope.

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 direct usage guidance: 'Use this for HAVING / window functions / CTEs / multi-way joins that the structured tools don't cover.' This also implies when not to use it (if structured tools cover the case) and names the alternative tool category.

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 readOnlyHint annotation signals the safe read-only nature, and the description adds behavioral details beyond that: sampling methods are named, seed behavior is described as deterministic only for random, and the disclaimer that a sample shows shape not distribution sets accurate expectations. The redaction-by-default behavior is only in the schema rather than described, but the annotation reduces the burden.

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 four sentences, front-loads the primary action and purpose, and each sentence carries distinct value. No wasted words or repetition of schema type information.

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

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

For a tool with one required parameter and schema descriptions covering all fields, the description supplies enough operational and selection context. The only notable omission is that the redaction-related parameters are not described in prose, but the schema fully documents them, so the gap is acceptable.

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 covers the parameters, so the baseline applies, but the description adds meaningful semantics on top: it explains the practical purpose of columns projection for wide tables, and clarifies exactly when seed has an effect. This improves the agent's ability to construct appropriate calls 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?

The description states a specific verb and resource ('Return a sample of rows') and immediately clarifies that the tool is for understanding data shape without schema knowledge. It explicitly contrasts itself with get_distribution, which helps an agent distinguish it from at least one sibling tool.

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 when-to-use guidance: use it for understanding data shape without prior knowledge, and use get_distribution when the actual spread is needed. It also provides practical guidance for wide tables and deterministic sampling, which helps the agent choose parameters appropriately.

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 readOnlyHint annotation, the description discloses that results are column-level IDs pointing to where to look, not the data itself. It also reveals the max_results cap and the requirement for an embedding provider via specific environment variables, adding valuable behavioral 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?

The description is three sentences, each earning its place: purpose, return semantics plus usage, and key constraints. It front-loads the primary action and is free of redundant detail.

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 tool's purpose, return value shape, workflow guidance, a critical limit, and semantic mode requirements. With no output schema present, it still explains what the caller receives. Given 7 parameters all documented in the schema, this is complete for a read-only search 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%, so baseline is 3. The description adds value by clarifying max_results is capped at 50 (schema only shows default 10) and by naming the specific embedding provider environment variables, which is not in the schema. This goes beyond the schema, meriting a 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 searches across column names and values, using a specific verb and resource. It further distinguishes itself by noting it returns column-level results with IDs, not the data itself, differentiating it from data retrieval 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 mentions 'Use before get_rows or describe_column', naming specific alternative tools and the intended ordering. It also provides constraints (max_results capped at 50) and prerequisites for semantic search, giving clear context for when to use the 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?

The description adds valuable behavioral details beyond the readOnlyHint annotation: it scans up to 20 other datasets' PK candidates, uses a containment threshold of ≥95%, and is sample-based with 500 distinct values per source column. It also specifies that only non-PK source columns are considered. This gives the agent a clear model of the tool's operation and limitations.

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 information-dense, with three sentences each adding meaningful context: the core action, the matching criteria, and the sampling methodology. No filler or redundant restatements of the tool name or schema are present.

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 a single parameter, no output schema, and a read-only annotation, the description is remarkably complete. It covers the source dataset scope, the search process, the similarity threshold, the dataset limit, and the sampling behavior. It fully equips an agent to understand what the tool does and what to expect without needing additional documentation.

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 describes the lone 'dataset' parameter as 'Source dataset identifier' (100% coverage), so the description adds only marginal value by reinforcing that it is the source dataset. The baseline of 3 applies because the schema carries the semantic weight; the description does not introduce additional parameter details or format expectations.

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 purpose with a specific verb ('Discover') and resource ('FK candidates'), and scopes the operation to a source dataset against other indexed datasets. It distinguishes itself from sibling tools like join_datasets (which likely executes joins) and suggest_keys (which suggest keys within a 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?

The description gives clear context for when to use the tool: detecting foreign key candidates from a source dataset to other indexed datasets. It does not explicitly mention alternatives or when not to use it, but the scope and constraints (up to 20 datasets, containment threshold) effectively imply the appropriate use case.

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 useful context beyond the readOnlyHint annotation by explaining the output contains a confidence score and the evidence behind it (e.g., integer columns, UUID format, nulls, uniqueness). It also discloses that candidates are ranked from profile statistics rather than from an authoritative system, which is an important truth. It does not cover error cases or edge behavior, but for a read-only tool this is a meaningful and positive disclosure.

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

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

The description is compact and begins with the core purpose, then expands to the output format and a caution. Every sentence contributes value, and there is no redundant or trailing wording that would waste an LLM's attention. Despite the include of the ambiguous 'B5' label, the overall structure remains efficient.

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 simple, read-only tool with one required parameter, the description adequately explains what output to expect (confidence score plus reasons) and the caveat that results must be confirmed. It does not describe error behavior for unknown datasets or case involving empty or malformed input, but that is a minor gap given the low complexity and presence of the annotation.

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 the only parameter dataset already described in the schema as a 'Dataset identifier' (100% coverage), the description does not add further meaning to the parameter itself. The extra detail about the tool's output is helpful but does not alter how the parameter should be understood. This puts the score at the baseline of 3.

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

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

The description clearly states the tool's purpose: it ranks principal-key candidates for a dataset. It uses a specific verb and resource, making it easy to distinguish from obvious alternative behaviors like joining or describing data. However, it does not explicitly compare itself with any sibling tool (e.g., suggest_joins), so the differentiation is implicit rather than stated directly.

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 little guidance about when to choose this tool instead of other options. It does mention that candidates are statistically derived and thus need confirmation, but that is more about interpreting the result than about when to invoke the tool. No alternative tools or use cases are mentioned, so the agent must infer the appropriate scenario.

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

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

The description discloses the exact behavior: reads profiles from index.json, generates summaries, and writes them back, plus the constraint 'No re-parsing of source files.' This goes beyond the readOnlyHint=false annotation by specifying the mutation target and mechanism. It stops short of stating whether existing summaries are overwritten in place, but 'writes them back' implies that.

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

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

Three sentences, each dense with information: purpose, mechanism/requirement, and an alternative invocation path (index_local). No filler or repetition; the key action is 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?

For a single-parameter tool with no output schema, the description provides ample context: what it does, how it works, prerequisites, side effects, and when it's redundant. It's complete enough for an agent to decide whether and how to invoke 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?

The schema already fully documents the dataset parameter as a 'Dataset identifier (from list_datasets)' with 100% coverage. The description adds a meaningful constraint: the dataset must already be indexed, which is not in the schema, adding nuance beyond the identifier type. This justifies a score above the baseline of 3.

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

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

The description opens with a specific verb and resource: 'Generate natural-language summaries for a dataset and all its columns.' It further clarifies the scope by stating it operates on already-indexed datasets and reads/writes index.json, distinguishing it from raw-file parsing tools and sibling describe tools.

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

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

The description clearly states the prerequisite that the dataset must already be indexed ('Works on already-indexed datasets') and notes that summaries are auto-generated during index_local, implying this tool is only needed when summaries were not created there. However, it does not explicitly name alternative tools like describe_dataset for structured metadata, leaving some room for 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?

The description discloses key behavioral details beyond the readOnlyHint false annotation: invalid or non-numeric weight names are rejected, values are clamped, scope precedence is defined, and effects apply at query time. It also clarifies reset semantics and that no other tool consumes these weights, making side effects understandable.

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

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

The description is dense but each sentence earns its place: usage modes, precedence, validation behavior, tunable names, and effect scope are all covered without redundancy or filler. It is front-loaded with the core purpose and quickly moves into actionable details.

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 tells the agent what to expect on inspection (effective weights and their source) and fully explains all invocation paths and scoping rules. Nothing central to choosing or calling the 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?

Although schema coverage is 100%, the description adds meaningful semantic value by enumerating the ten tunable weight names, the set_weights shape, and the precedence of dataset scoping. It clarifies that set_weights is an object of number values and that unknown names are rejected, which goes beyond the bare 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 names the tool as inspecting, setting, or resetting search_data's column-ranking weight vector. It specifies the exact resource and actions, and differentiates itself from jcodemunch/jdocmunch by noting weights are tuned explicitly here.

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 invocation guidance: omit args to inspect, pass set_weights to override, use reset=true to clear, and scope with dataset. It also clarifies precedence (per-dataset wins over global, global wins over built-ins) and that only search_data reads these weights, which helps route the agent away from inappropriate uses.

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 though readOnlyHint=true is already supplied, the description adds substantial behavioral transparency by detailing what operations are performed (PRAGMA integrity_check, cross-checking row count and column list against index.json, verifying index.json content hash), what stale-lock info it reports, the expected overall_status return values, and its explicit non-coverage of data correctness. This is far beyond what annotations alone reveal.

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 purpose, then enumerates the exact integrity checks, then mentions the stale-lock signal and return values, and ends by constraining what the tool does not do. Each sentence contributes distinct information without 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?

With a single simple parameter, readOnlyHint=true, and no output schema, this description carries all needed operational context. It explains what the tool checks, what special state it detects, what values `overall_status` can be, and the boundary against data correctness. Nothing important is missing for an 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?

Schema description coverage is 100%, with the single `dataset` parameter already described as "Dataset identifier." The description does not add new or deeper meaning to that parameter, so the baseline score of 3 applies. It correctly focuses on the operation rather than restating the parameter.

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: "Verify an indexed dataset's on-disk integrity." It then names concrete checks (SQLite PRAGMA integrity_check, row count and column list against index.json, index.json content hash), making its function unmistakable and clearly distinct from sibling tools like summarize_dataset or get_dataset_health.

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 clearly scopes when to use the tool: it validates physical index integrity rather than underlying data correctness, and it explicitly surfaces stale-lock state from interrupted index_local runs. It does not list sibling alternatives, but the context is clear enough for an agent to know this is the integrity-validation tool rather than a general health or data-quality tool.

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