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

Annotations already declare destructiveHint=true, but the description adds critical behavioral context: plans are not persisted across server restarts, so a stale plan_id will fail. It also reinforces the destructive nature by capitalizing the warning. This goes beyond the annotation without contradicting it.

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 short, punchy sentences. The critical warning is front-loaded, and the requirements are stated in a separate line for emphasis. Every word earns its place; no fluff.

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

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

For a destructive tool with no output schema, the description covers prerequisites and session constraints. It doesn't describe the return value or side effects beyond 'changes real data,' but that's acceptable for a simple apply operation. The session-restart caveat is a useful completeness addition.

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

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

The input schema has 0% description coverage, leaving both parameters undocumented. The description compensates fully: it clarifies that confirm must be true and that plan_id must originate from a prior plan() call in the same session. This gives meaning to both parameters beyond their raw types and names.

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 applies a previously-previewed plan, with a specific verb (apply) and resource (plan). It immediately distinguishes itself from the sibling 'plan' tool by emphasizing that this action changes real data. The warning 'THIS CHANGES REAL DATA' leaves no ambiguity about the tool's purpose.

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

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

The description explicitly states the prerequisites: confirm=true is required and plan_id must come from a plan() call in the same session. This tells the agent exactly when and how to use the tool, and implies it should only be called after a plan() invocation. It also implicitly excludes use with stale plan IDs.

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

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

The description adds that this is a comparison operation and that the environment parameter is the target side, but it does not describe the output shape, error cases, or what 'current context' resolves to. The readOnlyHint annotation already covers safety, so the description is adequate but not rich.

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

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

One short sentence, starts with the operative verb, and contains no filler. It could not be meaningfully tightened without losing the only semantic content.

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

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

For a simple one-parameter, read-only tool, the description is minimally viable, but an agent still lacks guidance on what the diff result contains and how to resolve 'current context' or 'target environment' names. Those omissions matter because there is no output schema or parameter descriptions.

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 needs to define the environment string; it adds the crucial 'target' role relative to the current context. It stops short of saying where valid values come from (e.g., list_environments) or what format is expected.

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 operation ('Diff') and names both sides of the comparison ('current context' vs 'target environment'), which distinguishes it from non-diff siblings. However, 'current context' is left undefined, so the exact object being compared is somewhat vague.

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 phrasing implies a comparison/read-only use case, but it never explicitly says when to prefer this tool over siblings such as list_environments or plan, and gives no exclusions. Guidance is recoverable by inference, 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?

Annotations already declare readOnlyHint=true, covering the main safety behavior. The description adds no behavioral traits beyond that—it lists output content but does not discuss errors, missing models, or side effects. With annotations present, this is acceptable but not enriched.

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 efficient sentence with the core purpose front-loaded and a scannable list of returned fields. No filler or redundant information; 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 one-parameter, read-only tool with no output schema, the description sufficiently explains what the tool returns. The only notable gap is not mentioning that model_name likely comes from list_models, but this is a minor usability detail rather than a critical omission.

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 adds only minimal meaning—'one model' implies model_name selects the model, but it does not explain the expected format, where to source the value, or any constraints. 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 states a specific verb ('get') and resource ('one model') and enumerates the returned content (rendered query, columns, kind, owner, tags, description). Saying 'one model' clearly differentiates this from sibling list_models, which is about enumerating models.

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 that model_name is likely obtained from list_models. Usage context is only implied by the word 'one model'; no exclusions or selection criteria 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=true, so the description need not repeat safety. The description adds that it returns upstream dependencies, which is useful, but it does not disclose details like whether lineage is recursive, the depth of traversal, or the output format (list, tree, etc.). Given the read-only annotation covers the main behavioral trait, a mid score is appropriate.

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 core purpose ('Column-level lineage') and immediately clarifies the query. There is no wasted wording, and the essential information is delivered efficiently.

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 lineage tool with no output schema and no parameter descriptions, the description is incomplete. It fails to specify the structure of the returned data, whether lineage includes only direct or transitive dependencies, how results are ordered, or any constraints on model_name/column (e.g., case sensitivity). The agent would need additional context to interpret the tool's response 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 implies that 'model_name' identifies a model and 'column' is a column within it, but it does not explain parameter formats, required syntax, or provide examples. The description gives minimal semantic value beyond the parameter names, leaving the agent to guess acceptable values.

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 ('depend on') and resource ('column-level lineage'), clearly indicating it shows upstream dependencies for a given column in a model. This distinguishes it from siblings like get_model (which likely shows model details) and list_models (listing models). The phrasing 'which upstream models/columns does this column depend on' 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?

No guidance on when to use this tool versus alternatives. It does not mention scenarios like analyzing dependencies, debugging impact, or contrasting with get_model. There is no explicit 'use this when...' or 'instead of...' direction, leaving the agent to infer 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?

The readOnlyHint annotation already covers the safety profile. The description adds that the result is exhaustive ('every environment') and scoped to 'project's state', but does not disclose additional behavioral details such as ordering or whether environments are dynamic. This is acceptable but not enriching beyond the annotation.

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

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

A single, direct sentence that conveys the complete purpose without redundancy. 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 zero-parameter, read-only list operation with an output schema present, the description is fully sufficient. Nothing else is needed for an agent to select and invoke it correctly.

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

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

There are zero parameters, so the baseline is 4. The description adds useful context by giving environment name examples and clarifying the scope to project state, which helps an agent understand what the tool returns.

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 ('List') and a clear resource ('every environment that exists in this project's state'), with concrete examples (prod, dev). It is precise and easily distinguished from sibling tools like diff_environment or list_models.

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 case—listing all environments—but provides no explicit guidance about when to choose this tool over alternatives. It does not mention any exclusions, prerequisites, or relationships to sibling tools.

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

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

The readOnlyHint annotation already communicates that this is a safe read operation. The description adds that the result covers all models and includes specific fields, which is useful context, but there are no additional behavioral details such as pagination or ordering.

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, well-structured sentence with no filler. The operation and scope are front-loaded, and every remaining detail (kind, columns, owner, description) 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 parameterless list operation with a readOnly annotation and an output schema, the description is complete enough. It names the resource, scope, and visible attributes; nothing else is needed for an agent to select and invoke 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?

The tool takes zero parameters and the schema coverage is trivially 100%, so there are no parameter semantics to clarify. The description appropriately focuses on what the tool returns rather than inputs.

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 ('List every model'), the resource ('the SQLMesh project'), and the returned attributes (kind, columns, owner, description). This distinguishes it from siblings like get_model, which targets a single model, and list_environments, which lists a different resource.

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 explicit statement of when to use this tool versus alternatives. The phrase 'every model' implies a broad overview use case compared to get_model, but the description does not directly say 'use this when you need all models' or name 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?

Goes beyond the readOnlyHint annotation by explicitly stating it does not apply anything and describing the return value (plan_id) and its downstream use. This is useful behavioral context for an agent choosing whether to call the tool.

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

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

Two compact sentences with no filler. The core purpose is front-loaded, the non-applying behavior is stated immediately, and the return-value usage is explained efficiently.

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

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

The description adequately explains the tool's purpose and output for the simple workflow, but it omits parameter details and any caveats about plan creation or scope. With no output schema and sparse param descriptions, more guidance would improve completeness.

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 define either parameter. 'environment' is only mentioned generically in prose, and 'select_models' is entirely unexplained, so an agent cannot determine valid values or semantics.

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

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

Description clearly states the tool previews changes without applying them, using a specific verb ('Preview') and resource ('a plan against an environment'). It distinguishes itself from apply_plan by explicitly noting this is the dry-run 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?

Provides workflow context by explaining the returned plan_id should be passed to apply_plan to actually apply the plan. It implies when to use this tool, though it does not explicitly list exclusions or alternative selection criteria.

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 destructiveHint=true, and the description adds relevant behavioral context with 'THIS CHANGES REAL DATA' and the confirm=true requirement. It goes beyond the schema by explaining the cron-like due-interval behavior, though it does not detail the side effects or scope of the changes.

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

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

The description is compact and front-loaded, opening with the core action, immediately followed by a clear safety warning. Every sentence earns its place, and the distinction from siblings and confirm requirement are stated 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 description covers purpose, safety, sibling routing, and the confirmation requirement well. However, with no output schema and zero parameter documentation, the missing semantics of start, end, and environment leave gaps for an agent attempting to construct a correct call.

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 should compensate by explaining the parameters. It only adds meaning to confirm; start, end, and environment remain effectively undocumented, leaving the agent to guess their formats, meanings, and optionality.

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

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

The description identifies a specific verb and resource: 'Execute scheduled/due model runs for an environment.' It also differentiates from plan/apply_plan by clarifying it runs already-promoted models, so an agent can distinguish it from sibling tools.

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

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

It explicitly states when to use this tool versus alternatives: it handles due intervals like a cron trigger, not previewing or promoting structural changes. It also names the sibling alternatives and sets a firm requirement to pass confirm=true.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is known. The description adds that start/end bound the data checked, but it does not disclose what an audit produces, whether it can be long-running, or any other behavioral characteristics beyond the annotation. It is adequate but not rich.

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

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

Two short sentences, no filler, with the core purpose and the key parameter semantics both front-loaded. 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 tool with three optional parameters and no output schema, the description covers the selection scope and the two bounds, but it does not describe the nature of the audit results or clarify the expected format of start/end. It is minimally sufficient but leaves meaningful 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 carries the burden of explaining the parameters. It does add real meaning: model_name selects the model (and omitting it means all models), while start/end bound the data checked. This goes beyond the bare schema, though it still lacks format or interaction details.

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 audits for a model, with the all-models behavior clearly scoped. The mention of start/end bounds adds precision and distinguishes it from generic sibling tools like run_test or run.

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

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

The description implies when to use the tool (run audits for a model or all models) and clarifies the effect of omitting model_name, but it gives no explicit guidance about when not to use it or which sibling alternative to prefer. Usage context is present but alternatives and exclusions are absent.

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

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

The readOnlyHint annotation already signals a non-mutating operation, so the description does not need to repeat that. It adds value by clarifying the optional-model behavior (all tests when omitted), but it does not disclose whether test output, results, or artifacts are returned or recorded. This is adequate but not rich.

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

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

A single sentence with no filler, and the optional behavior is front-loaded. Every phrase contributes meaning, making it an appropriately concise definition.

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

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

For a tool with one optional parameter and no output schema, the description covers the essential calling decision: what runs when model_name is provided versus omitted. It is complete enough for an agent to invoke correctly, though return-value expectations are not described.

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 does so by explaining the only parameter's behavior: providing model_name targets one model, omitting it runs all tests. This adds meaning beyond the raw 'default: null' in the schema, though it could specify the expected format of model_name.

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 action ('Run unit tests') and a specific resource ('for a model'), with the scope clarified by the parenthetical 'or all tests if omitted.' It is clear and actionable, though it does not explicitly differentiate this from the sibling 'run' tool beyond naming the test domain.

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 tool is for running unit tests, but gives no explicit guidance on when to choose it over siblings like 'run' or 'run_audit.' There is no mention of prerequisites, intended contexts, or exclusions, leaving the selection decision to inference.

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