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 readOnlyHint=false, destructiveHint=true, and idempotentHint=true, and the description adds useful context: the file is moved (not copied) to .architect/archive/, and exactly one file is affected. But it does not disclose that expected_revision acts as a concurrency guard or what dry_run does, which are material behavioral traits for a destructive operation.

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

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

Two sentences with the primary action front-loaded and zero filler. The semicolon splicing 'Move...' with 'remove_object removes...' is grammatically awkward because the subject shifts, but it is compact and every clause earns its place.

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

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

For a destructive tool with 6 parameters and a required expected_revision, the description is too thin: it does not explain the optimistic-concurrency guard, the idempotency key's role, or dry-run behavior. The output schema covers return values and annotations cover the safety profile, but the operational contract for safe invocation 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 compensate, yet it only maps to relative_path (the package file to move) and loosely implies project path context. expected_revision, idempotency_key, dry_run, and reason receive no semantic explanation; their self-descriptive names hint at purpose but do not convey critical mechanics like the revision check gating the archive operation.

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+destination: 'Move one package file into .architect/archive/'. The second clause explicitly contrasts it with remove_object ('removes one object'), so an agent can distinguish archiving from deletion without opening schemas or guessing from the name 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?

Names remove_object as the direct alternative and states its contrasting behavior ('removes one object'), which implies archive_project_file is for preservation/moving while remove_object is for deletion. However, it lacks explicit when-not conditions or prerequisites (e.g., 'use only if the file is not referenced'), so some inference remains.

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 mark this as non-read-only, idempotent, and destructive. The description adds useful behavior beyond that: it enforces a strict schema_version 1, and requires secrets to come from environment variables only. These are non-obvious constraints that help the agent understand side effects and security needs, so it earns a 4.

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 dense sentence that packs key information without fluff. It front-loads the core action and then branches into data and connection details. It is appropriately compact for the amount of content, though a slightly more structured format (e.g., breaking into two sentences) could improve 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?

Given 19 parameters, 0% schema coverage, and no description of return values, the description is far from complete. It addresses only the data and connection_kind branching, leaving many parameters undefined and no guidance on how idempotency or overwrite behaves. The output schema exists but the description does not mention what the tool returns. For a tool of this complexity, more is needed.

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

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

Schema description coverage is 0%, so the description must compensate. It explains 'data' (starter/external) and 'connection_kind', but says nothing about the other 17 parameters, including required ones like package_id, expected_revision, and idempotency_key. Many parameters have defaults that are not explained, leaving the agent to guess their meaning. This is a significant gap for a complex tool.

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 ('Create') and a precise resource ('a strict schema_version: 1 project'), which is unambiguous. It also differentiates from siblings by mentioning dbt as a source, implying this tool is for creating a project from scratch rather than importing one. The purpose is clear and distinct.

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 conditional guidance for data (starter vs external) and connection_kind based on warehouse type, and notes the environment-variable secret requirement. However, it does not explicitly say when to use this tool versus alternatives like import_dbt_project or setup_project_dialog. The dbt mention hints at an alternative but leaves the choice 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?

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 mark the tool as destructive and idempotent; the description adds useful behavioral context: the operation happens 'in one transaction,' dry_run previews without writing, and skipped_models/skipped_references report omissions. It does not elaborate on the destructive nature, but the annotation covers that.

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

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

Three sentences with no filler: the main action is front-loaded, followed by workflow guidance and output expectations. Every sentence adds useful 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 import tool with required fields like expected_revision and idempotency_key, the description is too thin on parameter semantics. It does mention dry_run and skipped output, and an output schema exists, but the required non-obvious parameters are not explained.

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, but it only clarifies dry_run and the idea of 'selected dbt models' (select). Required parameters like expected_revision, idempotency_key, and project_path are left unexplained, leaving the agent to guess their meaning.

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

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

The description clearly states a specific verb and resource: 'Create or update package models from the selected dbt models in one transaction, writing their foreign keys as entity references.' It also distinguishes itself from the sibling suggest_models_from_dbt by positioning that tool as a prior review step.

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

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

The description gives explicit workflow guidance: 'Review with suggest_models_from_dbt first' and explains that 'dry_run=true previews without writing.' It does not explicitly enumerate when not to use the tool or compare with other upsert tools, but the workflow context is clear.

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

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

Annotations already provide readOnlyHint=true, 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 indicate read-only and idempotent behavior, and the description aligns with this. It adds valuable context about the truncation behavior and that values are real warehouse data, which goes beyond annotations. No contradictions are present, and the description enriches the agent's understanding of what happens during execution.

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, concise sentence that front-loads the action and resource, then immediately details the return behavior. There is no redundancy or filler; every phrase adds meaningful information.

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

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

With an output schema present (not shown but implied), the description need not explain all return fields, but it does mention truncation and total_row_count, which are keys. It covers the essential behavior for a read-only query tool. Some details like error handling or the exact format of the query object are omitted, but given the annotations and output schema, it is largely 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 0%, leaving the description to clarify parameter meanings. It explicitly documents the max_rows range (1-200) and the effect of truncation, and indicates that 'query' is a semantic query. It does not explain project_path, but that is self-evident from the tool's name and context. The description compensates well for the schema's lack of detail.

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

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

The description clearly states the action ('Run a semantic query'), the resource ('the package's warehouse'), and the behavior of returning rows with truncation and total_row_count. It distinguishes itself from sibling tools like file management or validation tools, as it is the only query execution tool among the listed siblings.

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

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

The description gives no explicit guidance on when to use this tool vs alternatives, nor does it mention any conditions for use. It only implies that it executes queries like the server's 'execute' but does not explain when a preview might be preferred over other operations (e.g., for validation vs. full execution). No exclusions or alternative recommendations are 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, 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, and non-destructive behavior accessories. The description adds a valuable behavioral gotcha: enabling include_runtime_checks triggers runtime validation, examples, and tests that query the warehouse. This is material context beyond the structured annotations and can affect cost or side effects.

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, front-loaded with the tool's outputs, and uses a clear 'Gotcha' label to highlight the important caveat. Every sentence contributes useful information without redundancy.

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

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

The output schema and annotations carry a lot of the return-format and safety details, so the description can focus on workflow and caveats. It covers when to use the tool and the main gotcha, but the unresolved 'expected_revision' reference and missing project_path guidance leave small gaps.

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

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

The description usefully explains include_runtime_checks by describing what it causes, which goes beyond the boolean name and default. However, project_path is never described, and with 0% schema description coverage the description should compensate more. The 'expected_revision' phrase also introduces confusion because it is not a schema parameter.

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

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

The description states a concrete output: the package's revision, files, and parse report, which makes the tool's purpose clear and distinct from sibling operations like validate_project or diff_project. However, the parenthetical '(pass it as expected_revision)' is ambiguous because expected_revision is not listed in the input schema, preventing a top score.

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

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

The description gives explicit workflow guidance: 'Use first, and again when the package may have changed.' This tells the agent when to call the tool, though it does not name alternatives or state when not to use it, so it stops short of exhaustive usage direction.

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 valuable behavioral disclosure: 'Gotcha: it queries the warehouse.' This warns about a potential external dependency beyond the annotations, which is useful for agents expecting a purely local operation. No contradiction with annotations.

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

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

Two concise sentences with no fluff. The purpose is front-loaded, and the gotcha is placed at the end as a useful warning. It is efficient and readable, though it could include a bit more parameter detail without becoming verbose.

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

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

Given the presence of an output schema, return values are covered there. The description explains the core purpose and the gotcha, but misses guidance on when to use this tool over siblings, and leaves required parameters unexplained. For a 4-parameter tool with zero schema coverage, it is adequate but has clear gaps.

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 explain parameters. It explains compare_path and base_ref (for impact) but gives no explanation for the required project_path and environment, which are the most critical. The list of checks (parse, runtime, examples, tests) indirectly suggests the meaning of environment, but not explicitly. The description only partially compensates for the lack of schema 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 clearly states the tool's purpose: returning whether a package is ready for an environment, listing the specific components checked (parse, runtime, examples, tests). It also notes the optional impact inclusion via compare_path or base_ref. However, it does not explicitly distinguish itself from sibling tools like project_status or validate_project, so it's not a perfect 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?

The description provides no guidance on when to use this tool versus alternatives. It only explains parameter usage ('Pass compare_path or base_ref to include impact') but does not mention any exclusions or alternative tools. For a read-only check with many siblings, the agent gets no routing information.

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?

Beyond the destructiveHint/readOnlyHint annotations, it discloses archiving of YAML, cascade behavior for models (entity and relationships go along), refusal conditions, and that impact output lists behavior changes and remaining referencing files. This is substantial behavioral context.

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

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

Three dense sentences front-load the action and object, then add necessary edge-case behavior without fluff. Every sentence contributes operational 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 destructive tool with an output schema and annotations, the description covers core behavior, cascades, and refusal. It omits mention of dry_run and revision/idempotency semantics, but those are partially inferable from parameter names and the schema.

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

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

Schema description coverage is 0%, so the description must compensate. It explains kind, key, and the model disambiguation, but it does not explain required project_path, expected_revision, idempotency_key, or optional reason and dry_run. The compensation is partial at best.

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

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

The description opens with a specific verb and enumerates the exact object kinds it removes (model, dimension, time, measure, metric, segment, relationship), plus the archiving side effect. This clearly distinguishes it from sibling upsert/archive/impact tools.

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

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

It gives clear operational context: the model parameter disambiguates when several models hold a key, and removal is refused if a metric still names the id. It does not explicitly name alternative tools or when-not-to-use conditions, but the conditions are concrete enough for an agent to decide.

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?

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 declare readOnlyHint=false, destructiveHint=true, and idempotentHint=true. The description adds useful behavior beyond those annotations: it specifies that spec merges into an existing example (merge semantics) and that the query must validate. This provides context about state changes that annotations do not cover. No contradiction with annotations.

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

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

The description is two concise sentences with no filler. The core action is front-loaded, and the spec details are given in a compact, structured form. Every sentence contributes to understanding the tool's behavior.

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

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

The tool is complex (7 parameters, nested spec, output schema, idempotency key, revision) and the schema has no descriptions. The description only covers the spec contents and merge behavior, leaving the other parameters and the output semantics unexplained. It does not address idempotency, expected_revision, dry_run, or the output. Given the complexity and low schema coverage, the description 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 compensate. It only explains the 'spec' parameter (query, optionally question, expected_shape) but leaves the other six parameters (project_path, example_key, expected_revision, idempotency_key, file_name, dry_run) completely unexplained. The names are somewhat self-explanatory but not enough for a tool with this many parameters. The description fails to provide meaning for most parameters.

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

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

The description clearly states the tool's purpose: 'Upsert an example question in examples/<file_name>'. This distinguishes it from sibling upsert tools (upsert_model, upsert_relationship, etc.) because it targets a specific resource type. The verb 'upsert' and the resource 'example question' are specific and unambiguous.

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

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

The description implies usage by describing the spec content and merge semantics, but it does not explicitly state when to use this tool versus other upsert tools or provide exclusions. It mentions a prerequisite ('The query must validate') which is helpful, but there is no explicit routing to alternatives. The context of siblings makes the intended use clear, but the description itself could be more prescriptive.

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, but the description adds valuable specifics: fields merge by default, replace:true rewrites while keeping the id, and a gotcha about strict packages requiring an explicit value_type. These details go beyond the annotation flags and help the agent predict behavior.

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

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

The description is three sentences, front-loaded with the core purpose and then covering file placement and merge/replace behavior. The gotcha is appended at the end, which is fine. No filler or redundancy; it is efficient for its length.

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

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

Given the complexity (9 parameters, 5 required, a nested spec object, and an output schema), the description is insufficient. It does not explain the meaning of required parameters like expected_revision or idempotency_key, nor the effect of dry_run or group. An agent would need to infer or seek additional documentation to call this tool correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the contents of the spec object but does not clarify key top-level parameters like project_path, metric_key, expected_revision, idempotency_key, dry_run, group, or file_name. The required parameters are not described, making it hard for an agent to know how to populate them 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 the action ('Upsert a metric') and the resource, listing the spec components (kind, measure or inputs, value_type, label, description). It also explains the file placement rules, which distinguishes it from sibling tools like upsert_model or upsert_relationship. The purpose is unambiguous.

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

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

The description implies it is for creating or updating metrics, but it does not explicitly state when to use this tool versus alternatives such as upsert_model or upsert_relationship. No exclusions or alternative routing are provided, though the resource type is clear enough for basic 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?

Beyond the annotations, the description usefully explains merge vs. replace behavior, that replace keeps only id, entities, and calendar_id, and that dropped fields are returned in dropped_fields. It also discloses calendar-related state changes. This aligns with the destructiveHint and idempotentHint annotations, so there is no contradiction.

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

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

The description is dense and run-on, with parenthetical asides and unexplained jargon such as 'time.fill' and 'kind: date dimensions.' The most important behavioral distinction (merge vs. replace) is buried near the end rather than front-loaded in a scannable structure.

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 destructive 18-parameter mutation tool with zero schema descriptions, this is incomplete. It covers calendar and replace behavior but omits semantics for required fields, prerequisites, and concurrency/revision expectations. The presence of an output schema lowers the need to describe return values, but the operational 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 0%, so the description must carry the parameter-semantics burden, but it only meaningfully explains calendar and replace. Most of the 18 parameters, including required ones like relation, primary_key, expected_revision, and idempotency_key, are left unexplained. The phrase 'default "default"' conflicts with the schema's calendar_id default of "", and 'time.fill' is ambiguous.

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 clear verb and resource: 'Upsert a model and its graph entity,' and the title narrows it to a semantic model. This broadly distinguishes it from sibling upsert_* tools by object type, but it never explicitly names an alternative or clarifies the graph-entity concept.

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 choose this tool over upsert_metric, upsert_relationship, or upsert_segment, and no exclusion criteria. The 'model' wording implies the target resource, but the description provides no explicit when-to-use or when-not-to-use context.

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 convey idempotent and destructive behavior, so the description is not obligated to restate them and does not contradict them. However, the description adds no behavioral context beyond the schema/annotations, such as what the destructive operation replaces or how idempotency and expected_revision are enforced.

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 compact two-sentence definition with no filler, and the core relationship semantics are front-loaded. It could be slightly clearer by tying the cardinality note to the parameter name, but overall it is efficient.

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

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

For an 8-parameter destructive/idempotent mutation with zero schema descriptions, the definition leaves too much unexplained: required revision and idempotency semantics, dry-run behavior, and project scoping are absent. It is only minimally viable for an agent to call 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 0%, so the description must carry parameter meaning. It explains the central relationship parameters—columns, key order, cardinality, from_entity, and to_entity—but leaves project_path, expected_revision, idempotency_key, and dry_run 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?

The description names a specific operation ('Relate two entities') and clarifies the data model notion—columns on from_entity's model hold to_entity's key in key order. It is clearly distinct from the sibling upsert_model/upsert_metric tools by focusing on relationships, though it does not explicitly compare itself to 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?

There is no guidance on when to use this tool instead of the many sibling upsert_* tools, nor any prerequisites or exclusions. The agent must infer that relationship creation differs from model/metric/segment upserts based only on the name.

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 idempotentHint and destructiveHint, and the description adds valuable behavior beyond them: fields merge, replace rewrites while keeping the id, and membership requires specific filters. It does not contradict 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 concise and front-loaded with the core purpose, then merge/replace behavior, then the critical gotcha. Every sentence earns its place, though the dense punctuation in the final sentence 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?

Given an 8-parameter schema with 5 required fields, no schema descriptions, and no guidance on required parameter semantics, the description is incomplete. It explains some spec behavior and the replace flag but omits the meaning of essential fields and how they relate to the operation.

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 of explaining parameters. It clarifies file_name, replace, and parts of spec, but leaves required parameters like project_path, segment_key, expected_revision, and idempotency_key unexplained. An agent would not know how to correctly populate these fields.

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

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

The description clearly states the operation ('Upsert'), the resource ('a segment'), its location ('segments/<file_name>'), and the core fields ('entity, basis_metric, label, membership'). This differentiates it from sibling tools like upsert_metric or upsert_model.

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. It does not mention when not to use it, nor does it point to sibling tools for other object types. The 'Gotcha' sentence is about input constraints, not usage 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 idempotentHint and destructiveHint. The description adds value by stating that 'spec merges into an existing test', clarifying the update semantics, and noting that 'queries must validate' with a special condition for validate_fails_with_code. However, it does not disclose error behaviors, conflict handling, or the impact on unspecified fields beyond the merge statement. The description aligns with annotations without contradiction.

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 focused paragraph that front-loads the main purpose and then provides necessary spec details. Every sentence adds information about behavior or constraints, with no filler. It is compact and readable for the complexity involved.

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

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

For a tool with 7 parameters, a nested spec object, and an output schema, the description falls short. It covers the spec.kind structure thoroughly but omits explanations for key parameters like expected_revision (likely a concurrency check), idempotency_key (for idempotent retries), and dry_run (preview mode). The merge behavior is mentioned but its implications on existing test fields are not detailed. The presence of an output schema reduces the need to describe return values, but the description still lacks essential usage context for the other required inputs.

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 document all parameters. It thoroughly explains the spec object and its supported kinds with their required sub-parameters, but it leaves other required fields (project_path, test_key, expected_revision, idempotency_key) and the dry_run flag unexplained. The description compensates only partially for the missing schema 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 clearly states the verb 'Upsert' and the resource 'a package test in tests/<file_name>', with detailed enumeration of allowed spec.kind values. This distinguishes it from sibling upsert_* tools (model, metric, relationship) by focusing on the test resource. It is specific and unambiguous.

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

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

The description conveys when to use the tool (for creating or updating package tests) by explaining the spec structure and requirements, but it does not explicitly contrast with alternatives or state when not to use it. There is no mention of specific scenarios where a different tool (e.g., upsert_model) would be more appropriate. The guidance is implied but not explicit.

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

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

Beyond the annotations, the description discloses that runtime, examples, tests and release query the warehouse and may build a seeded DuckDB file, plus the special prerequisite for impact. This gives the agent important behavioral expectations that annotations alone do not capture. The idempotent/read-only annotations are not contradicted; building a seeded file is presented as a side effect consistent with a non-destructive cache-like operation.

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

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

Three compact sentences deliver the purpose, recommended usage order, and important gotchas with zero filler. The main purpose is front-loaded and every clause adds useful 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?

Given the output schema exists, the description need not explain return values. The mode list, usage order, warehouse side-effect warning, and impact prerequisite cover the behavioral and invocation context an agent needs to call the tool correctly. The required project_path is simple enough to leave to the schema.

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 meaning. It effectively explains the valid mode values and the relationship between impact, compare_path, and base_ref. It does not explicitly describe project_path or environment, though their names and the context make their roles reasonably inferable.

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

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

The description clearly states the action ('Validate the package') and enumerates the distinct modes (parse, runtime, examples, tests, impact, release). This makes it easy for an agent to distinguish validation from sibling tools like project_status or preview_query.

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 explicit usage directives: use parse after each change, and run runtime before trusting answers. It also notes that impact requires compare_path or base_ref, providing meaningful when-to-use context. It stops short of saying when not to use this tool or how it compares with alternative tools.

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

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

Annotations already carry the read-only, idempotent, and destructive hints, so the description only needs to add context. It does so by specifying UTF-8 encoding and the critical overwrite=false behavior. This is genuinely useful beyond the structured annotations, though it could further mention revision checking or dry-run 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?

The description is only two sentences with no filler. The 'Gotcha' section front-loads the most important operational caveat. It is concise without being overspecified.

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 five required parameters and zero schema descriptions, the tool needs substantial contextual explanation. The current text ignores expected_revision and idempotency_key, which are non-obvious contract parameters, and does not explain dry_run behavior. An agent could guess at some fields, but would lack the necessary context to invoke the tool reliably.

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 all seven parameters. It only clarifies the overwrite parameter and leaves content, project_path, relative_path, expected_revision, idempotency_key, and dry_run unexplained beyond their names. This is insufficient for an agent to correctly construct a valid call.

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

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

The description clearly states the tool's action ('Write') and resource ('one UTF-8 package file'). This distinguishes it from sibling tools like read_project_file and archive_project_file by the write operation. The terse phrasing still conveys the essential purpose without ambiguity.

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 about when to use this tool versus alternative tools such as upsert_model, import_dbt_project, or archive_project_file. The description only states an operational gotcha ('overwrite: false refuses an existing file') but does not explain prerequisites, exclusions, or selection criteria.

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