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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe, read-only call. The description adds the content focus on 'safety guidance' and 'workflow,' but does not reveal any behavioral details beyond what the annotations already provide (e.g., output size, rate limits, or effects of params). No contradiction exists.

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

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

The description is one direct sentence with no filler, front-loading the verb and object. It is concise while still making the tool's purpose identifiable.

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 definition is adequate for a simple, safe meta-guidance tool with an output schema, so return format need not be spelled out. However, it omits any usage context and fails to explain the two optional parameters, leaving meaningful gaps in what the agent needs to decide when 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?

Schema description coverage is 0% and the description never mentions goal or project_path, leaving both parameters completely unexplained. Although their names suggest a purpose, the description fails to explain how, or whether, they influence the returned guidance or what values are valid.

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 clear resource ('recommended Architect MCP workflow and safety guidance'). It distinguishes this meta-guidance tool from the operational sibling tools (create_project, upsert_model, validate_project, etc.), so an agent can tell at a glance it is asking for guidance rather than performing a project operation.

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

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

The description gives no indication of when to call this tool instead of a sibling, nor any exclusions or prerequisites. 'Recommended workflow' weakly implies a general or pre-flight use, but the definition does not state that the agent should consult it before project operations or how it relates to the 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 destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuinely new behavioral context: secrets must be referenced by environment variable name only, and the underlying data-source branching rules. It does not, however, explain what destructive/overwrite behavior actually removes.

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?

Single dense sentence with the purpose front-loaded, which is good, but it packs three separate configuration branches and a credential rule into one clause chain, making it harder to parse than necessary.

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

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

The tool is complex (20 params, destructive, creates persistent state) yet the description covers only a fraction of the configuration surface, and the destructive/overwrite semantics flagged by annotations go unexplained. An output schema exists, so return values need not be described, but the input-side gaps remain significant.

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 only 5% across 20 parameters, so the description carries most of the burden. It explains the data enum, connection_kind, and secret naming, but leaves roughly fifteen parameters (primary_key, time_column, expected_revision, idempotency_key, overwrite, dry_run, project_path, etc.) undocumented in both schema and 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 gives a specific verb+resource ("Create a strict schema_version: 1 project") that an agent can distinguish from siblings like import_dbt_project or upgrade_project. It is slightly obscured by the unexplained "strict schema_version: 1" qualifier, so it stops short of a clean 5.

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

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

It routes the agent among parameter modes (data=starter vs data=external vs connection_kind for other warehouses) but never states when to choose this tool over siblings such as import_dbt_project or setup_project_dialog. The guidance is real but parameter-level rather than tool-level.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the main safety profile is covered. The description adds no behavioral detail beyond the returned content — no mention of whether it opens a database, how paths are used, or what happens when the relation is missing.

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 phrase that gets directly to what is returned and has no filler. It is a fragment, not a sentence, and misses a verb, but it is appropriately compact for a simple read-only tool.

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

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

With an output schema present, not describing return values is acceptable, and annotations cover read-only behavior. However, the tool has three parameters whose meaning is unresolved, and there is no guidance on when to choose this tool over related siblings, so the definition is incomplete for correct invocation.

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

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

Schema description coverage is 0%, and the description does not clarify relation, duckdb_path, or project_path. An agent cannot tell what the two path parameters mean or how they interact, so the description fails to compensate for the schema's lack of parameter documentation.

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 enumerates the returned metadata — columns with type/nullability/default and primary, unique, foreign keys — which makes the tool's purpose clear without being a tautology. It also differentiates from siblings like list_tables and profile_columns because it targets schema structure. It lacks an explicit verb like 'describe' or 'retrieve', so it falls just short of a 5.

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

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

There is no statement about when to use this tool versus siblings such as list_tables, profile_columns, or preview_query, and no mention of prerequisites or context. The intended use is only implied by the name and the listed output.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to repeat safety traits. It adds useful context about the two modes of comparison (path vs git ref) and implies the operation is a read-only diff. 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 a single sentence with no filler. The core verb and resource are front-loaded, and the two comparison modes are clearly stated. Every word earns its place.

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

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

For a simple read-only diff tool with an output schema, the description covers the essential purpose and the two optional parameters. It does not mention edge cases like mutual exclusivity, but given the output schema exists and annotations cover safety, this is sufficiently complete for an agent to use 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 0%, so the description must add meaning. It does explain that compare_path and base_ref are two alternative comparison targets, which clarifies their purpose. However, it does not specify whether they are mutually exclusive, precedence, or what happens if both are provided, leaving ambiguity.

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 ('Diff') and resource ('one project') and clearly distinguishes between two comparison targets ('another path' vs 'a git base ref'), which differentiates it from sibling tools like project_status or list_project_files. It is unambiguous about the operation.

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

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

The description implies when to use this tool (when you need to compare a project to another path or a git ref) but does not explicitly name alternatives or conditions that would select this over another tool. No exclusions or 'use this instead' guidance is provided.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that the tool returns three named categories of results, but it does not disclose additional behavioral context such as failure modes, perf expectations, or input constraints.

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

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

The description is a single front-loaded sentence with no filler or repetition of annotation details. Every word contributes to the core purpose.

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 three parameters, zero schema descriptions, and many closely related siblings, the one-line description is insufficient. It relies on the output schema for return shape but leaves parameter semantics and tool-selection context unexplained.

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

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

Schema description coverage is 0%, so the description needed to clarify project_path, base_ref, and compare_path; it mentions none of them. An agent cannot determine what base_ref and compare_path mean or how they relate to 'package change' from the 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 states a specific verb ('Return') and a concrete resource: behavior-change impact, reviewer teams, and risk for a package change. This clearly distinguishes it from siblings like diff_project or validate_project by naming its unique outputs.

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?

There is no guidance on when to use this tool versus related siblings such as diff_project, validate_project, or promotion_check. The phrase 'for a package change' gives only weak context, with no exclusions, prerequisites, or alternative routing.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered structurally. The description adds real context beyond them: atomic one-transaction writes, automatic foreign-key-to-entity-reference conversion, and the dry_run no-write path, plus which output fields report omissions.

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 packed sentences with the atomic-write behavior front-loaded, followed by the review prerequisite and preview flag, then the omission-reporting note. No filler text at all.

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

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

An output schema exists, so return values needn't be re-explained. However, for a destructive, revision-guarded, idempotency-keyed write tool with 10 mostly undocumented parameters, the description omits the concurrency/required-parameter contract that an agent needs 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 only 10% across 10 parameters, so the schema documents almost nothing. The description explains dry_run and hints at skip reporting, but leaves critical parameters unexplained: select syntax, expected_revision (a concurrency guard), idempotency_key, project_path/manifest_path/catalog_path relationships, and group/target_dir defaults.

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

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

States a specific verb pair (Create or update), the resource (package models from selected dbt models), and the distinctive behavior (single transaction, foreign keys rewritten as entity references). This clearly separates it from bulk-tuning siblings like upsert_model and from the review-only suggest_models_from_dbt.

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

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

Explicitly routes the agent to 'Review with suggest_models_from_dbt first' and explains dry_run=true as a preview mode. It gives concrete when-to-use context but does not state boundaries against other write tools such as upsert_model or upsert_relationship.

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, idempotentHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is fully covered. The description adds no extra behavioral detail (e.g., recursion, filtering, or path requirements) beyond restating the listing action.

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

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

The description is a single, front-loaded sentence with no filler. Every word contributes to understanding the tool's purpose, and the phrasing is direct and easy to parse.

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

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

The tool has one simple parameter, output schema exists, and annotations cover behavioral safety. The description supplies the key domain context (Semantic Rails project directory) and enough information for an agent to invoke it correctly. Minor gaps like recursion behavior are acceptable given the output schema and simplicity.

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 project_path is not described in the schema (0% coverage) and the description only implies it is the path to the Semantic Rails project directory. This is a reasonable inference, but the description does not explicitly define the parameter format, semantics, or constraints, leaving some room for ambiguity.

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 ('List'), a resource ('files inside a Semantic Rails project directory'), and naturally distinguishes this from siblings like read_project_file (which reads a single file) and list_tables (which lists tables). The purpose is unambiguous and immediately actionable.

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 no guidance on when to use this tool versus alternatives such as read_project_file or list_tables. There is no mention of prerequisites, when not to use it, or which scenarios call for a different tool. The usage context 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?

The '(read-only)' phrasing and safety profile are already covered by readOnlyHint/idempotentHint/destructiveHint. The description does add the useful context that it can target either a DuckDB package database or a standalone DuckDB file, but it does not disclose behavior such as how the source is resolved when both parameters are present.

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

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

One sentence, no filler, and the core object ('List tables and views') is front-loaded before the source scoping. Every word earns its place.

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

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

The short description is simple, and output schema plus read-only annotations reduce the burden, but the three optional parameters are unexplained and the two-target 'or' leaves ambiguity about when to supply duckdb_path versus project_path. An agent cannot reliably choose invocation arguments from this text alone.

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

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

With 0% schema description coverage, the description needed to explain schema, duckdb_path, and project_path, but it only mentions 'database or DuckDB file.' It never maps parameters to those targets, clarifies the optional schema filter, or explains the all-empty-default behavior.

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

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

The description names a specific verb and resource ('List tables and views') and scopes it to 'a DuckDB package's database or a DuckDB file.' This distinguishes it from siblings like describe_table, which targets individual tables, and list_project_files, which targets project files.

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 the obvious use—enumerating tables/views before working with them—but does not explicitly state when to choose this tool over describe_table or preview_query. It gives no exclusion criteria or alternative routing, leaving usage to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds only the 'copy-ready' aspect, which hints at output formatting but does not explain what the hints contain or whether they are exhaustive. It does not contradict annotations, but it adds minimal behavioral context beyond them.

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

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

The description is a single, short sentence that front-loads the purpose. It is concise and free of filler, though it is arguably too sparse to be maximally useful. Structure is fine, but content is minimal.

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 three optional parameters and an output schema, the description is inadequate. It does not explain the parameters' meanings, defaults, or how the output should be used. Although an output schema exists (not shown here), the description still needs to state that parameters are optional and what they control. An agent cannot correctly invoke this tool without external knowledge.

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

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

Schema description coverage is 0%, so the description must compensate for undocumented parameters. The description does not mention host, port, or transport at all, nor does it hint at their purpose or defaults. An agent has no idea what values to provide or why they matter.

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 names a precise resource ('copy-ready client configuration hints') with a clear context ('for running Architect MCP'). It is unambiguous and distinct from sibling tools, which focus on queries, projects, models, or validation. An agent can immediately understand what this tool produces.

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 no guidance on when to use this tool versus alternatives, nor does it mention any exclusions or prerequisites. It does not explain that it is a configuration helper or that it might be used before setting up clients. No context about typical use cases is provided.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, and the description adds genuinely new behavior: an enforced 1-200 row cap, the meaning of 'truncated', the fact that extra rows are not counted (total_row_count null), and the critical disclosure that 'Values are real warehouse data' rather than mock preview data. These are traits an agent cannot derive from annotations or schema.

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

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

A single dense sentence that front-loads the core action before the truncation details. All clauses earn their place, though the run-on construction packing limits, truncation, and count semantics together slightly reduces readability.

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

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

An output schema exists, so return values need not be re-explained, and the description still usefully covers truncation semantics. However, for a tool whose primary parameter is an undocumented nested 'query' object and whose project_path is unexplained, the definition leaves the caller guessing on the most important input.

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

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

Schema description coverage is 0%, so the description carries the burden. It explains max_rows bounds (though the schema already encodes min/max/default) and gives a conceptual gloss for 'query' as a semantic query, but it says nothing about project_path and nothing about the shape of the query object, which is an open nested object (additionalProperties: true). Partial compensation only.

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

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

States a specific verb and resource: 'Run a semantic query on the package's warehouse', and clarifies the mechanism by likening it to 'the query server's execute'. Distinct from the sibling set, which is dominated by model/project CRUD tools and none of which execute queries. It stops short of 5 only because it never contrasts itself with a near-neighbor 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?

No explicit when-to-use guidance or when-not, and no named alternative. The reference to 'as the query server's execute does' describes equivalence of behavior, not a routing condition, so the agent gets no help deciding when to reach for preview_query.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the description's 'Read-only' is redundant. However, it adds real behavioral context about sampling limits, sample_limit=0 disabling samples, and the max_rows cap, which goes beyond the 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 a single compact sentence, but the parenthetical stacking makes it awkward and slightly ambiguous. Every phrase is information-dense, yet the lack of clear structure reduces readability.

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 output schema exists, so return-value documentation is not required, but the description leaves several parameters unexplained and does not clarify the relationship between 'up to 20 samples' and the sample_limit default. For a tool with six parameters, this is incomplete.

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

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

Schema description coverage is 0%, so the description must carry parameter semantics, but it only explains sample_limit and max_rows. Required parameters like relation and important optional parameters like columns, duckdb_path, and project_path are not described. The 'up to 20 samples' claim is also potentially confusing given the default sample_limit of 5.

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 what the tool produces: per-column counts, min/max, and samples. This is specific enough to identify it as a data-profiling tool rather than a schema or row-preview tool, though it never explicitly names a sibling to distinguish itself from.

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 read-only and sampling behavior implies this is for quick exploratory profiling, but there is no explicit guidance on when to choose it over alternatives like describe_table or preview_query. The description gives context but no exclusions or comparison to siblings.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and openWorld, so safety is covered. The description still adds real value beyond those fields: it warns that include_runtime_checks triggers runtime validation, examples, and tests that query the warehouse, a side-effect and external-access trait not captured by 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 tight sentences, front-loaded with the primary purpose and followed by usage timing and a caveat. Every sentence carries information; the phrasing is dense but not padded. Slightly cryptic 'pass it as expected_revision' costs it a point.

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

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

An output schema exists, so return-value detail is not required, and annotations carry the safety profile. Between the purpose, usage timing, and the warehouse-query warning, an agent has enough to call this correctly; the only lingering ambiguity is which downstream tool consumes expected_revision.

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 only 33%. The description meaningfully explains include_runtime_checks behavior and hints that the returned revision should be passed as expected_revision elsewhere, but it never clarifies full_report (only the schema does) or project_path. It partially compensates for the coverage gap, consistent with a 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 names a specific verb and resource set: return the package's revision, files, and parse report. That is concrete and lets an agent know it is a read/status tool rather than a mutation tool like upsert_model. It stops short of explicitly distinguishing itself from the sibling list_project_files, which also concerns files, so this is not a full 5.

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

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

It gives clear temporal guidance: 'Use first, and again when the package may have changed.' That tells the agent both the initial and refresh conditions. It offers no when-not guidance or named alternatives (e.g., when to prefer list_project_files or describe_table), so it misses the top tier.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds non-obvious operational context annotations cannot express: the check reaches out and queries the warehouse, which warns the agent about latency/cost and external dependency.

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 with zero filler: purpose first, optional-parameter behavior second, caveat last. Every sentence carries distinct information.

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

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

An output schema exists, so return values need not be described, and the description covers the checks, the optional impact path, and the warehouse caveat. What is missing is guidance on valid environment values and the boundary with the validate_project/impact_project siblings.

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 only 20% (only full_report is documented inline). The description compensates for two of the five parameters by explaining that compare_path and base_ref trigger impact analysis, and full_report's summary-vs-full distinction is covered by the schema. environment and project_path remain unexplained, so coverage is partial.

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

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

States a specific verb and resource – returns whether a package is ready for an environment – and enumerates the four checks (parse, runtime, examples, tests). It is distinguishable from sibling reads like validate_project or project_status, though it never directly contrasts itself with them.

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 implies when to use the optional impact behavior ('Pass compare_path or base_ref to include impact'), which is genuine routing guidance. It gives no explicit when-to-use/when-not-to-use against siblings such as validate_project or diff_project, so usage must be inferred.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds a small behavioral constraint by specifying UTF-8 encoding, but does not disclose behavior for missing files, permission issues, or invalid paths. No contradictions with annotations exist.

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

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

The description is a single sentence with no filler or redundancy. It is front-loaded with the primary verb and resource, and every word contributes to the core meaning.

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 operation with an output schema and rich safety annotations, the description is minimally adequate. However, it lacks key contextual details such as how project_path should be specified fairly, what happens when the file does not exist, and when to use sibling tools for discovering file paths.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies that relative_path is a relative path, but project_path is left completely undefined. No information is provided about path formatting, separators, accepted encodings, or how the project path relates to the file path.

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 ('Read') with a clear resource ('project file') and a precise scope ('by relative path'). It is immediately distinguishable from siblings like write_project_file, archive_project_file, and list_project_files, especially when combined with the tool name and title.

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 no explicit guidance on when to use this tool versus alternatives. It does not mention that list_project_files should be used to discover available relative paths, or that write_project_file is the counterpart for modifications. Usage context is only implicit through the verb 'read'.

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

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

Goes well beyond the annotations by disclosing the mutation profile (write or replace a stored row), the validation failure mode (INVALID_CONFIG with nothing written for off-route paths or unknown entities/relationships), and the all-or-nothing transaction semantics ('one invalid or conflicting row refuses all'). The annotations only carry destructive/idempotent hints; the description adds the atomicity and failure behavior an agent needs.

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

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

Dense but front-loaded: purpose first, then failure semantics, then return values, then the bulk alternative, then atomicity. Every clause carries information, though the nested decisions syntax makes it slightly harder to scan than a cleaner single-purpose sentence.

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

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

An output schema exists, so return values (replaced row, summary) need not be spelled out, yet the description still flags them. Combined with the validation and transaction behavior, an agent has enough to call it correctly; the only real gap is that half the input parameters receive no textual explanation.

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 only 10% across 10 parameters, so the description must compensate. It usefully explains the single-pair fields (source_entity, target_entity, relationship_path, label) and the exact shape of the nested decisions array, but leaves expected_revision, idempotency_key, dry_run, full_report, and project_path entirely undefined in text.

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

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

States a specific verb and resource: record/replace a pair's graph.path_preferences row from a route decision, and specifies the default write-or-replace semantics. It is clearly distinguishable from the upsert_* siblings in subject matter, though it does not explicitly name an alternative tool an agent might confuse it with.

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

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

Tells the agent when to reach for it ('pass the decision of an AMBIGUOUS_PATH clarification option') and how to choose between the single-pair and bulk 'decisions' forms. It stops short of naming an alternative tool or an explicit when-not-to-use condition, so it is clear but 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?

Annotations already declare destructiveHint/idempotentHint/readOnlyHint, so the safety profile is covered. The description adds genuinely new behavior: the YAML is archived rather than lost, cascading deletion ('A model takes its entity and relationships along'), and a refusal condition tied to remaining metric references. It doesn't mention dry_run or the revision/idempotency protocol.

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

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

Front-loads the action and target kinds, then layers disambiguators and preconditions in subsequent sentences; nothing is padded. Four dense sentences pack a lot without wasted framing.

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

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

An output schema exists, so return values needn't be explained, and the cascade/archive/refusal semantics are well covered for a destructive operation. Still, with 9 params at 11% coverage and a destructive default (dry_run=false), the omission of dry_run and revision/confirmation mechanics is a real gap for an agent deciding how to call it safely.

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 only 11%, so the description carries most of the burden, yet it only illuminates two of nine params ('model' selection and the entity-keyed 'key'). Ambiguous fields like kind, dry_run, reason, expected_revision and idempotency_key are left entirely to 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?

States a specific verb ('Remove') and enumerates the resource kinds (model, dimension, time, measure, metric, segment, relationship), which cleanly separates it from the upsert_* siblings. The parenthetical clarifies what a 'relationship' is here (a model's foreign key keyed by its entity), removing ambiguity about the target object.

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 discloses the precondition ('Refused if a metric would still name it') and a disambiguation rule ('model picks the model when several hold the key'), which imply when the call will succeed. However, it never states when to prefer this over or pair it with sibling tools such as impact_project or validate_project, nor recommends a pre-check workflow.

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 readOnly, idempotent, and non-destructive hints, and the description adds the interactive 'guided dialog' nature plus the conditional MCP elicitation behavior. This is useful context beyond the annotations strands, though it does not explain whether the dialog can produce side effects outside the session.

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

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

The description is a single sentence with no filler, repetition, or unnecessary detail. It front-loads the core action ('Start a guided project setup dialog') and adds the condition about MCP elicitation compactly.

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 four optional but undocumented parameters, the description is too thin. It lacks an explanation of what inputs mean, what a successful dialog returns, or how the guided process advances. The read-only annotation helps, but the strong parameter coverage gap makes the description insufficient on its own.

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

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

Schema description coverage is 0% and the description gives no information about goal, package_id, interactive, or project_path. With no parameter explanations in either the schema or the description, the agent has no way to know how to populate these fields correctly.

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 action and object: 'Start a guided project setup dialog.' It conveys a distinct interactive behavior, but it does not explicitly differentiate itself from sibling tools like create_project or import_dbt_project, so an agent might still wonder exactly what the dialog produces.

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?

No guidance is given on when to use this tool versus alternatives such as create_project. The only conditional mentioned is 'when requested and supported' for MCP elicitation, which is about a sub-behavior, not about selecting the tool itself.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), and the description reinforces that while adding real behavior: proposals above min_coverage versus a below_threshold bucket with the same evidence, and that project_path drafts upsert_relationship arguments. That output-shaping behavior is not derivable from 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?

Dense and front-loaded, with the core mechanic in the first sentence and parameter-specific notes following. A few phrasings are terse to the point of opacity ('stated as threshold', 'a few not found'), but no sentence is filler.

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

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

An output schema exists, yet the description still usefully sketches the result shape (proposals vs below_threshold vs draft arguments). The main residual gap is the two unexplained parameters (relation, duckdb_path) in a 0%-coverage schema, which the description should have covered.

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

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

Schema description coverage is 0%, so the description must carry the load. It explains min_coverage (default 0.95, threshold semantics), columns ('tries those columns against every key whatever their names'), and project_path (targets become package entities), but leaves relation and duckdb_path entirely unaddressed — notably duckdb_path is non-obvious.

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

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

States a specific verb+resource: 'Propose relationships from a table to other tables' keys from their values', and explains the evidence basis (coverage, misses, cardinality). It doesn't explicitly differentiate itself from the sibling suggest_one_per_key, so an agent must infer the boundary.

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 explains behavioral conditions of parameters (min_coverage threshold, columns overriding name matching, project_path switching targets to package entities) but never states when to prefer this over suggest_one_per_key or suggest_model, nor any preconditions/exclusions. Usage is implied through the threshold story rather than 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?

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful behavioral context by mentioning confidences, reasons, and draft upsert_model arguments, and it reaffirms read-only behavior without contradicting the 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 a single compact sentence that front-loads the action and output substance. 'Read-only' is redundant with the annotations but harmless; otherwise there is no filler.

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

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

The output schema covers return values and the annotations cover side-effect behavior, but the description still leaves unresolved questions about parameter semantics and when to invoke this tool instead of related siblings. It is minimally viable but not fully self-sufficient.

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

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

Schema description coverage is 0%, so the description needed to explain the three parameters. It only implies that 'relation' is the target relation and says nothing about duckdb_path or project_path, leaving the agent without enough information to set those correctly.

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 ('Propose') with a clear resource ('a relation') and lists the concrete outputs: key, times, dimensions, measures, and foreign keys. This distinguishes it from write/sibling tools like upsert_model, though it does not explicitly differentiate it from the closely named suggest_models_from_dbt.

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?

There is no guidance on when to use this tool versus alternatives such as suggest_models_from_dbt, describe_table, or upsert_model. The only contextual hint is 'Read-only', which implies it is a non-mutating exploration step, but no explicit conditions or alternatives are given.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: 'dbt never runs' and that keys/links/value sets come from dbt tests and contracts. It does not describe output format or error behavior, but the output schema exists to cover return values.

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, two sentences, and front-loads the core purpose. The read-only note is useful and the parenthetical about dbt never running is valuable context. Minor redundancy with annotations (read-only) but not wasteful.

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

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

For a read-only suggestion tool with an output schema and strong annotations, the description covers the main inputs and behavior. However, target_dir is unexplained, and there is no guidance on how the tool relates to suggest_model or when to prefer one over the other. Given the 0% schema coverage, the description should do more to document parameters.

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

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

Schema description coverage is 0%, so the description must compensate for the four parameters. It only explains 'select' (narrows by model name) and mentions manifest.json and catalog.json as sources, which maps to manifest_path and catalog_path, but target_dir is left unexplained. The description adds some meaning but leaves half the parameters undocumented.

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

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

The description states a specific verb and resource: 'suggest_model for each dbt model' from manifest.json and catalog.json, and notes that dbt never runs. It distinguishes from the sibling 'suggest_model' by the dbt-specific context, though it doesn't explicitly name the sibling. The read-only note and source files add clarity.

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 context: it is for dbt models using manifest and catalog files, and 'select narrows by model name' gives a filtering condition. However, it does not explicitly state when to use this tool versus alternatives like suggest_model or import_dbt_project, nor does it mention prerequisites like having a dbt project already imported.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotent, non-destructive), so the description's repetition of "Read-only" adds little; however it goes further by describing what the proposal contains (NULL-key rows, distinct keys, keys with several rows, per-column fixed vs varying, coverage) and by disclosing a side effect that is easy to miss — passing project_path additionally emits an upsert_relationship linking the row-grain model. That is real behavioral context beyond the structured fields.

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 key precondition is correctly front-loaded and the text is short, but it is one semicolon-chained run-on with heavy internal jargon, forcing the reader to re-parse clauses like "each column fixed or varying within a key" before reaching the actionable sentence about dry_run and expected_revision.

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

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

An output schema exists, yet the description still spends most of its length enumerating return contents while leaving two input parameters (relation, duckdb_path) undefined and never stating how this differs from the sibling suggest_model. Adequate for the read-only safety story, but an agent could still misuse the entry parameters.

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

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

Schema description coverage is 0%, so the description carries the full burden for four parameters. It only illuminates two: project_path (triggers the upsert_relationship output) and key ("tries one column set"). Neither relation (what identifier format?) nor duckdb_path (when to supply it) is explained anywhere.

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

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

The description names a specific verb-and-resource pair: it proposes a "one_per_key" model for a table that has no key of its own, and it enumerates the artifacts produced (diagnostics per candidate key, coverage, draft upsert_model args, and an upsert_relationship). It is dense jargon ('one_per_key', 'row-grain model') and never names the sibling suggest_model as the alternative, so differentiation is only implicit.

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?

"For a table with no key of its own" gives a real precondition, and "Read-only: apply the drafts with dry_run, then expected_revision" sketches a follow-up workflow. But there is no explicit when-not, no reference to suggest_model / suggest_links as the alternative for tables that do have a key, and "key tries one column set" is the only hint about how to steer candidate selection.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the mutation and safety profile is known. The description goes beyond that with genuinely additive behavior: the rewrite happens in one transaction (atomicity), it refuses any rewrite that changes an answer (a semantic-preservation invariant), and it details what dry_run previews. It omits failure/rollback specifics when dry_run=false, keeping it out of the top band.

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

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

A single front-loaded sentence that leads with the verb and resource, then appends the safety invariant and parameter notes. Dense but no filler; the semicolon-packed clause about dry_run and choices is slightly overloaded, which is the only thing keeping it from a 5.

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

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

An output schema exists, so return values need not be described, and annotations cover the safety profile. Still, for a destructive, transactional mutation with 0% schema coverage, the two undocumented concurrency/safety parameters (idempotency_key, expected_revision) are a real gap an agent would need to call this correctly in repeated or concurrent 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 0% for 5 parameters, so the description must carry the load. It explains dry_run (the default, previews rules/proof/diff) and choices ({key: option} answers pending choices), two parameters well. It says nothing about idempotency_key or expected_revision, which matter a lot for a destructive mutation, leaving 3 of 5 parameters undocumented in both schema and 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?

States a specific verb and resource: rewrite a package's legacy forms to the current ones, with the safety constraint that answer-changing rewrites are refused. This is clearly distinguishable from siblings like validate_project or diff_project. It stops short of naming those siblings explicitly, so it doesn't reach the top band.

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 the intended workflow by noting that dry_run is the default and that it previews rules, proof and diff, which guides an agent toward preview-then-apply. However, it never says when to prefer upgrade_project over validate_project, diff_project or impact_project, nor when a caller should pass dry_run=false.

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

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

Annotations already declare the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=true). The description adds useful context beyond them — that the spec is merged into an existing example rather than replacing it, and that the query must validate — but does not explain what merge-overwrite destroys or any auth/permission requirements.

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

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

Two sentences, front-loaded with the verb and resource, then the spec contract. Little waste, though it could be slightly tighter.

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

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

An output schema exists so return values need not be described. However, for a destructive, 8-parameter, nested-object upsert tool, the description omits the concurrency semantics of expected_revision, idempotency_key behavior, and dry_run, leaving real gaps an agent would want closed.

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 only 13% across 8 parameters. The description usefully expands the opaque 'spec' object (query, question, expected_shape with columns/min_rows/max_rows) and ties file_name to examples/<file_name>, but leaves example_key, project_path, expected_revision, idempotency_key, and dry_run completely undocumented, so it only partially compensates for the coverage 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?

States a specific verb (upsert) and resource (an example question in examples/<file_name>), and enumerates the spec's contents. An agent can distinguish it from sibling upsert_* tools like upsert_model and upsert_metric by the resource it targets.

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

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

Usage is implied rather than stated: 'spec merges into an existing example' conveys upsert semantics and 'The query must validate' gives a prerequisite, but there is no explicit when-to-use, when-not-to-use, or named alternative among the many sibling upsert 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?

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered; the description adds genuinely non-derived context: merge-on-default semantics, that replace:true rewrites while keeping the id, file placement rules, and the strict-package value_type gotcha. It omits dry_run behavior and expected_revision conflict semantics.

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

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

Three dense sentences that front-load the operation and its field list, then behavior, then the gotcha. No filler, though the path/template fragment is slightly compressed at the cost of readability.

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

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

An output schema exists so return values need not be described, which helps. But for a destructive, 10-param, 5-required tool, the absence of any explanation for expected_revision (optimistic locking) and idempotency_key leaves a real gap in what an agent needs 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 only 10% across 10 params, so the description must carry the load. It partially does — explaining spec fields, file_name/group via the path template, and replace — but leaves dry_run, expected_revision, idempotency_key, and project_path entirely unexplained in both schema and 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?

States a specific verb+resource ('Upsert a metric') and enumerates the spec fields (kind, measure or inputs, value_type, label, synonyms, description), so an agent knows exactly what is being created or updated. It does not explicitly contrast itself with the many upsert_* siblings (upsert_model, upsert_segment, etc.), so differentiation rests on the resource noun alone.

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 it ('a new metric goes in X, an existing one stays in its file') and offers a conditional hint ('replace: true rewrites it'), but never states when to prefer this over upsert_model/upsert_segment or what prerequisites (e.g. an existing package) are needed. Usage is inferred rather than directed.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the baseline is lower. The description adds rich behavioral detail beyond annotations: how replace rewrites a model and lists dropped_fields, how merge semantics preserve other fields, how calendar behaves, and that a non-default calendar is refused in this release.

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

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

The description is front-loaded with the core purpose and every clause adds semantic detail, with no obvious filler. However, it is a single dense, run-on paragraph that is difficult to scan, especially for a tool with 20 parameters.

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

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

An output schema exists, so return values need not be explained, and annotations cover the safety profile. Still, for a complex upsert tool with 20 parameters and only 5% schema description coverage, the description is incomplete because it omits semantics for several required parameters and operational fields.

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 only 5%, so the description must carry the parameter burden. It explains the most ambiguous optional parameters (calendar, replace, one_per_key, primary_key, entities) well, but leaves many required and operational parameters unexplained, including project_path, model_id, entity_key, relation, expected_revision, idempotency_key, dry_run, and group.

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: 'Upsert a model and its graph entity.' It also differentiates scope from the related sibling by stating 'Relationships also go through upsert_relationship.' An agent can identify the tool's core purpose immediately.

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

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

The description implies use through the verb 'upsert' and gives substantial parameter behavior, but it does not explicitly state when to choose this tool over other upsert or model-related siblings. The only routing guidance is 'Relationships also go through upsert_relationship,' which is useful but limited to one alternative.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds real behavioral depth beyond that: it discloses the write-refusal failure mode ('otherwise unrecorded route changes refuse the write') and the side effect that name writes graph.relationships.<name>. It does not explain the implications of destructive/upsert behavior or rollback, keeping it short of a 5.

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

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

The description is compact but written as dense, jargon-heavy run-on sentences that are hard to parse on first read, and the most critical constraint (write refusal) is buried at the end. Sentences mostly earn their place, but front-loading and readability suffer.

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

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

An output schema exists, so return values need not be explained, and annotations cover safety. Still, for an 11-parameter mutation tool the definition omits concurrency (expected_revision) and idempotency_key semantics and any sibling routing, leaving the agent to guess how this fits alongside upsert_model and record_route_decision.

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 only 9%, so the description must carry parameter meaning. It does add genuine semantics for cardinality (many_to_one / one_to_one), columns (key-order significance), from_entity (may be a row-grain model's id), name (target path), and keep_existing_routes (failure-mode semantics). But it leaves project_path, to_entity, expected_revision, idempotency_key, dry_run, and full_report undocumented in both schema and 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 opening 'Relate two entities: columns on from_entity's model hold to_entity's key' names a specific verb and resource, and the relationship-vs-model distinction separates it from upsert_model/upsert_metric. However it never names a sibling or states the boundary explicitly, so differentiation relies on inference from the resource noun.

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?

Conditional guidance is present in the body ('a pair with two roles needs it', 'Set keep_existing_routes=true to...'), which tells the agent when certain fields matter. But there is no when-to-use/when-not-to-use guidance relative to sibling tools such as upsert_model or record_route_decision, so usage is only implied.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, yet the description adds real beyond-schema behavior: fields merge by default, replace:true rewrites the object while preserving its id, and membership requires where/metric_filters/time-window or the call is refused. It omits concurrency behavior for expected_revision, which keeps it short of a 5.

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

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

Compact and front-loaded: destination and payload first, then merge/replace semantics, then the fatal validation gotcha. The 'Gotcha:' framing is informal but signals priority well; every clause carries 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 9-parameter, 5-required mutation tool with a nested free-form spec, the description covers the essential write semantics and key validation, and an output schema exists so return values need not be explained. It remains thin on the required expected_revision/idempotency_key contract and dry_run, which matter for a destructive, idempotent upsert.

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 only 11% across 9 params, so the description must compensate. It usefully characterizes the otherwise opaque spec object (entity, basis_metric, label, membership) and the replace/file_name flags, but leaves project_path, segment_key, expected_revision, idempotency_key, dry_run, and full_report unexplained.

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

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

States a specific verb (upsert), the exact resource (a segment) and its destination (segments/<file_name>), plus the fields it carries (entity, basis_metric, label, membership). This clearly separates it from siblings like upsert_metric, upsert_model, and upsert_relationship without needing the schema.

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

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

No explicit when-to-use vs alternatives guidance, but usage is implied through the merge/replace conditional and the membership validation rule, which tells the agent when a given call shape will succeed. An agent must infer the alternatives from sibling names rather than being routed by the description.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the bar is lower, but the description adds real value by explaining that 'spec merges into an existing test' (clarifying the upsert/destructive semantics) and by stating validation preconditions ('Queries must validate'). It does not disclose what is lost on overwrite or auth/permission requirements.

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

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

Front-loaded with the action and file location, then spends its length on the only genuinely opaque parameter. Dense but every clause about the spec kinds earns its place; could be tightened with the field list in a more scannable form.

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

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

With an output schema present, return values need not be covered, and the complex nested spec is well documented. It is still incomplete for a destructive 5-required-param mutation because revision/idempotency/dry_run semantics go unmentioned.

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 13%, so the description must carry the load, and it does so for the opaque 'spec' object (additionalProperties:true) by documenting all six kinds and their required fields. It leaves test_key, expected_revision, idempotency_key, file_name and dry_run unexplained, which is the remaining 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?

States a specific verb+resource ('Upsert a package test in tests/<file_name>') that cleanly distinguishes it from the sibling upsert_model/upsert_metric/upsert_segment tools. An agent knows exactly what artifact is being written and where.

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

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

Usage is implied through the enumeration of spec.kind variants and the note that queries must validate, but there is no explicit when-to-use versus when-not guidance and no alternative tool is named (e.g. vs upsert_example or validate_project). Adequate but incomplete routing.

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

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

Adds genuinely useful behavior beyond the annotations: several modes query the warehouse and may build a seeded DuckDB file, and impact has a parameter prerequisite. This side-effect disclosure is the kind of context readOnlyHint/idempotentHint do not convey, though there is mild tension with readOnlyHint=true since a file is created as a byproduct. It omits auth requirements and per-mode failure behavior.

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

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

Three sentences, front-loaded with the mode list, then usage guidance, then the gotcha. Every sentence carries distinct information (modes, when-to-use, side effects/prerequisites) with no filler or repetition of the schema.

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

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

An output schema exists, so return values need not be described, and the modes plus prerequisites plus side effects cover the core invocation path for a 6-parameter tool. The unexplained 'environment' parameter and the unaddressed overlap with impact_project/diff_project keep it from being 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 only 17% (only full_report is documented), so the description must compensate and largely does: it enumerates the valid mode values (the schema has no enum), explains what parse/runtime do, and links compare_path/base_ref to the impact mode. The 'environment' parameter is never explained anywhere, leaving a 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?

States a specific verb+resource ('Validate the package') and enumerates the six modes (parse, runtime, examples, tests, impact, release), so an agent knows what the tool does and its scope. However, it does not differentiate itself from siblings that clearly overlap, notably impact_project and diff_project, even though the 'impact' mode covers the same ground. Terminology also drifts between 'package' and the tool's 'project'.

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

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

Gives explicit sequencing advice ('Use parse after each change', 'runtime ... before trusting answers') and states a prerequisite for the impact mode ('needs compare_path or base_ref'). It stops short of naming when NOT to use it or pointing to the overlapping sibling tools (impact_project, diff_project) that an agent might otherwise pick.

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 destructive=true, idempotent=true, readOnly=false, so the safety profile is covered. The description adds genuinely useful non-annotation context: writes are atomic ('one transaction') and the final package is validated as a whole. However, it never says what 'archive' destroys, how expected_revision conflicts are handled, or what happens when validation fails.

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

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

A single front-loaded sentence with the core action first and the qualifying constraint second. No filler, no restated title.

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

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

An output schema exists so return values need not be described, but with 7 parameters at 14% schema coverage and zero usage guidance, the description is far too thin for a destructive, revision-guarded batch write. Conflict handling and failure/rollback behavior are unaddressed.

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

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

Schema description coverage is only 14% across 7 parameters (only full_report is documented), so the description must compensate but adds nothing about files, project_path, expected_revision, idempotency_key, reason, or dry_run. Critical inputs like the optimistic-concurrency revision and the idempotency key are left entirely unexplained.

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

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

Names a specific verb pair (write or archive) and resource (files), plus a distinguishing scope detail (single transaction with whole-package validation). An agent can separate it from read_project_file and list_project_files. It stops short of naming the sibling tools it is a counterpart to.

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?

No explicit when-to-use or when-not-to-use guidance. Nothing tells the agent how this relates to diff_project, validate_project, or read/remove_object, nor when to prefer it over those tools. Usage is only implied by the name.

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