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

The annotations already flag this as destructive and not read-only, but the description adds critical context beyond annotations: it changes real data in the current physical snapshot table, validates against the operation vocabulary and model schema before running, writes outside SQLMesh state tracking, and FULL-kind rematerialization can silently undo the cleansing.

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

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

The description is front-loaded with the key warning that this changes real data. It then structures the default mode, approval mode, and SQLMesh caveat clearly. Despite its length, every section addresses a distinct operational concern for a high-risk 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?

Given the destructive nature, lack of output schema, 0% schema description coverage, and complex approval modes, the description is complete enough to call the tool correctly. It covers validation behavior, safety requirements, mode selection, and the important rematerialization side effect.

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 `plan` as coming from propose_cleansing_plan output, `plan_id` as coming from a registered and approved plan, and `confirm` as required. It only leaves `model_name` implicit rather than explicitly defined.

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: validate and apply a data-cleansing plan. It clearly distinguishes this write operation from siblings like propose_cleansing_plan, register_cleansing_plan, and approve_cleansing_plan.

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

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

Explicitly describes the two usage modes: pass `plan` directly by default, or pass `plan_id` when DATAVEIL_REQUIRE_PLAN_APPROVAL is enabled. It also states that approval must come from someone else and that confirm=true is still required, leaving little ambiguity about when to use each path.

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, 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?

Annotations already declare readOnlyHint=false / destructiveHint=false; the description adds the crucial behavioral fact that this is a non-executing gate action whose only side effect is recording an approver. It stops short of covering re-approval/idempotency, whether approval can be revoked, or what happens if the plan_id was never registered.

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?

Short, front-loaded, and every sentence carries weight: the first states the action, the second states the gate semantics that prevent a likely misuse. No filler or restatement of the name.

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

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

For a two-parameter mutation with no output schema and annotations covering the safety profile, the description supplies the highest-value missing context (approval is not execution). Minor gaps around repeat approval and preconditions keep it from a 5.

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

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

Schema coverage is 0%, so the description must carry parameter meaning. It partially does: 'records who approved it' maps to approved_by, and plan_id is implied by 'a plan registered via register_cleansing_plan'. But it gives no format, provenance, or validation details for either required string.

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?

Specific verb ('mark ... as approved') and resource ('a plan registered via register_cleansing_plan'), and the description makes clear this is distinct from apply_cleansing_plan, which actually executes. An agent can tell this apart from its two closest siblings without opening a schema.

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

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

Explicitly frames the two-gate model: this call records approval only, and apply_cleansing_plan still needs confirm=true. It names the alternative and the condition under which each applies, and warns against treating them as substitutes.

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 only annotation is readOnlyHint=true, and the description adds a meaningful privacy trait: cell values are not exposed in results. However, it says nothing about ordering, time window for 'recent', pagination, or whether the limit is a hard cap, which matter for a history-listing 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?

A single tight sentence with the core action front-loaded. 'Recent' is the only vague term, but the brevity leaves room that could have been spent on the undocumented limit parameter.

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?

Output schema exists and annotations cover the safety profile, so those burdens are lifted. Still, for a history-query tool the description omits filtering window, ordering, and limit semantics, leaving gaps an agent would hit on first 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% for the single parameter 'limit', and the description never mentions it — no meaning, default (20), or upper bound is conveyed anywhere. The one parameter an agent must set is effectively undocumented.

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

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

States a specific verb and resource ('Return recent dataveil audit events') plus a scope qualifier ('recent'). It does not distinguish itself from the sibling run_audit, so an agent can't immediately tell which one to call.

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 versus run_audit, no prerequisites, no exclusions. The agent must infer usage entirely from the name and the sibling list.

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

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

Annotations only say readOnly=false and destructive=false; the description adds the important behavioral rule that running operations can't be cancelled safely, which explains why cancellation is limited to queued jobs. It doesn't say what happens to a job after cancellation or whether it's reversible, so it stops short of full disclosure.

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

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

Two short sentences, zero filler, with the actionable instruction front-loaded followed by the single most important caveat.

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 one-parameter mutation with no output schema, the definition covers the essential behavioral constraint an agent needs before calling it. The main gap is not explaining where the job_id originates or what the caller gets back.

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?

Only one parameter, but schema description coverage is 0% and the description never mentions job_id — no hint about where the ID comes from (start_run/start_plan output) or its format. Some compensation is needed and only partially provided by the 'queued job' framing.

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 ('Cancel a queued job') and adds a scope constraint that the name alone doesn't convey. The word 'cancel' is unique among siblings, so it is reasonably distinguishable, but it never names job status/inspection counterparts to contrast with.

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

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

'Cancel a queued job' plus 'Running SQLMesh operations cannot be interrupted safely' implies the prerequisite that the job must still be queued, but this is left implicit rather than stated as a condition. No alternative tool (e.g. checking status first) is mentioned.

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?

readOnlyHint=true already tells the agent this is a safe, non-mutating read, so the description isn't carrying the safety burden. It does add useful scope detail (three things being summarized), but leaves unexplained how expensive drift computation is, whether snapshots are fetched or merely counted, or what the summary looks like.

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

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

A single front-loaded sentence with no filler. Slightly under-specified rather than bloated, but "current project drift" is compressed to the point of ambiguity.

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?

No output schema, so the description must convey what comes back; it lists three dimensions but not their form (booleans, counts, diff lists). With one undocumented parameter and overlapping siblings, the definition is minimum viable rather than 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?

One required parameter with 0% schema description coverage, and the description does nothing to define what an "environment" identifier is (name, ID, slug?) or where to obtain one. It mentions the word "environment" only as part of the resource list, not as parameter guidance.

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 ("Summarize") and enumerates the resources covered: environment existence, snapshots, and project drift. That is enough to distinguish it from a plain existence check, but it never contrasts itself with siblings like diff_environment or list_environments.

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 of when to call this versus diff_environment, list_environments, or run_audit — all of which live in the sibling set and overlap conceptually. The agent must infer the routing decision from the noun "health" alone.

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

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

The readOnlyHint annotation already establishes that this is a safe read operation, and the description adds useful context that output is bounded and column-filterable. However, it omits an important behavioral trait: the mask_sensitive parameter defaults to true, meaning sensitive data is masked by default. That omission is a notable gap for a data-preview 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?

A single sentence, front-loaded, with every word contributing meaning: verb, scope, optional filtering, and resource. There is no filler or redundancy.

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

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

With no output schema and 0% schema description coverage, the description should do more to explain the four parameters and return shape. It conveys the preview concept adequately but leaves masking behavior and pagination/return format implicit, which is incomplete for a tool whose schema is otherwise undocumented.

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 implies model_name ('model data'), limit ('bounded'), and columns ('column-filtered'), but says nothing about mask_sensitive, which is one of four parameters and has a security-relevant default. It covers most parameters at a high level but leaves a critical one 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 states a specific verb and resource: 'Fetch ... preview of model data.' It also names key scoping traits ('bounded', 'optionally column-filtered'), making it distinguishable from metadata-oriented siblings like get_model or list_models. It does not explicitly name an alternative sibling, so it falls 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?

The phrase 'preview of model data' implies sampling use, but the description gives no explicit when-to-use guidance and no exclusions against siblings such as profile_model or table_diff. The agent must infer that this is for quick row previews rather than profiling or diffing.

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

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

Adds real value beyond the annotations: readOnlyHint=false only says a write is possible, while the description clarifies that the default is a read-only check and that writes are gated behind confirm=true, reducing accidental mutation risk. It stops short of saying whether formatting rewrites files in place, whether it is idempotent, or what the check reports.

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, front-loaded with the purpose, followed by the safety-critical default-vs-write rule. 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?

There is no output schema, so the description should say what check mode returns (e.g., a list of non-conforming files) and what happens when paths is omitted. The mutation-safety story is complete, but the read-side result contract is not.

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 successfully explains check mode and the confirm gate, but the paths parameter (which defaults to null and presumably means all files) is never mentioned, leaving a third of the parameters undocumented in both places.

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

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

States a specific verb pair (check or format) and a specific resource (SQLMesh model and audit files), so an agent knows exactly what the tool operates on. It also implicitly differentiates itself from sibling tools like get_model or run_audit, which do not modify file formatting.

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?

Explains the two modes and which one is the default, plus the condition that switches to write mode (confirm=true). It does not name an alternative tool or say when not to use it, but the mode-selection guidance is clear enough for correct invocation.

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

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

The readOnlyHint annotation already establishes this as a safe read operation, and the description adds that it returns both status and result. However, it says nothing about polling behavior, terminal states, or what happens if the job ID is unknown, which would be helpful for an async job-status 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?

One clear, front-loaded sentence with no filler. Every word contributes to identifying the operation.

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 tool this is close, but with no output schema the description should say more about what statuses or result payloads the caller receives. The lack of job_id guidance also leaves a practical gap.

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

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

Schema description coverage is 0%, and the sole required parameter job_id is undocumented in both schema and description. The description does not explain the expected ID format, where to obtain it, or how invalid IDs are handled, so it fails to compensate for the schema gap.

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

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

States a specific verb ('Return') and resource ('current status and result') and scopes it to asynchronous plans or runs, which connects it to siblings like start_plan/start_run. It does not explicitly name how it differs from cancel_job, but the read-only status purpose is clear.

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

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

Usage is implied by 'asynchronous plan or run' — call this after starting one of those jobs — but there are no explicit when-to-use, when-not-to-use, or alternative-tool instructions. It relies on the agent inferring the async polling 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 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 safety profile is covered. The description's only extra nuance is the word 'direct', which implies non-transitive results, but it says nothing about depth limits, what happens for an unknown model, whether the result is paginated, or how upstream and downstream sets are separated.

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, front-loaded with the verb and no filler. It is efficient, though the terseness is closer to under-specification than to disciplined brevity.

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

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

With no output schema, the description is the only place the agent can learn the return shape, and it gives none: no indication of whether results are lists of model names, edges, or counts, nor how direction is represented. For a one-parameter lookup tool this is a significant 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% for the single required parameter 'model_name', and the description does not compensate. It never says whether the value is a bare model name, a fully qualified name, or an ID, which is a real ambiguity for a lookup tool in a toolset that also exposes 'list_models' and 'get_model'.

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 clear verb+resource pairing ('Return ... model dependencies') and narrows scope to 'direct upstream and downstream'. That is specific enough for an agent to know what it gets back. However, it never distinguishes this from plausible siblings like 'lineage' or 'model_impact', leaving the agent to guess which of the three to pick.

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 when-to-use guidance, no exclusions, and no mention of the overlapping siblings ('lineage', 'model_impact'). The agent must infer the intended use case from the name alone.

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?

The readOnlyHint annotation already establishes that this is a safe read operation. The description adds useful scope with 'all transitive upstream and downstream,' but it does not describe output shape, traversal limits, or any caveats.

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 wasted words. It states the core behavior immediately.

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

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

For a simple read-only tool, the description adequately states the returned scope, but it leaves gaps around parameter semantics, output shape, and routing relative to sibling lineage/dependency tools. With no output schema and no parameter documentation, those omissions matter somewhat.

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 is one required parameter, model_name, and schema description coverage is 0%, so the description should compensate. It never explains the parameter's expected format or naming conventions, though the parameter name itself is fairly self-explanatory.

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

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

The description gives a specific verb and resource: return all transitive upstream and downstream models affected by a change. It is clear what the tool computes, but it does not explicitly distinguish itself from close siblings such as get_model_dependencies or lineage.

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 phrase 'affected by a change' implies impact-analysis usage, but there is no explicit guidance on when to choose this tool over lineage or dependency tools. No exclusions or alternatives are stated.

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

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

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?

Consistent with readOnlyHint=true, and it adds genuinely useful behavior beyond the annotation: output is aggregate-only with no raw rows or samples, and reads come from 'its current physical snapshot table' rather than live data. It also points to the README for known limits, though it doesn't disclose failure behavior when the model isn't applied or any cost/latency characteristics.

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 output content is front-loaded in the first sentence and the prerequisite is stated second, with no filler. Slightly long due to the parenthetical example and README pointer, but each element carries information.

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

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

With no output schema, the description correctly spends its budget describing what comes back (aggregate stats, format signatures, no raw rows) and flags the applied-model requirement. A small gap remains around error/edge behavior and result structure, but for a single-parameter read tool this is close to 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 coverage is 0%, so the description must carry the single model_name parameter; it does add meaning by implying the name must refer to an already-applied model with a physical snapshot table. But it doesn't say how to obtain valid names (e.g., via list_models) or whether a qualified/unqualified name form 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?

States a specific verb and resource ('Aggregate-only profile of a model's columns') and enumerates the concrete outputs: null rates, distinct counts, numeric stats, and generalized string format signatures. It also explicitly distinguishes itself from row-returning siblings by stating 'Returns no raw rows or samples', which differentiates it from fetch_model_data without opening either schema.

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

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

Provides a clear and non-obvious precondition ('The model must already be applied (see plan/apply_plan)') and routes the agent to plan/apply_plan for the prerequisite step. However, it never explicitly names an alternative for raw-row inspection (fetch_model_data) or states when-not to use this tool, leaving that comparison 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?

With only readOnlyHint=true in annotations, the description adds substantial behavioral context: it does not call an LLM, does not propose a plan itself, returns aggregate-only profiling data, exposes sensitivity classifications, and defines the accepted operation vocabulary and parameter constraints. This is exactly the kind of contract-level detail an agent needs before invoking 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?

The description is structured and mostly front-loaded, with the key contract details in the first sentence and the critical 'does not propose itself' clarification immediately after. It is somewhat longer than necessary and the initial 'propose a data-cleansing plan' phrasing is slightly in tension with the later disclaimer, but no sentence is wasted.

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

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

There is no output schema, so the description must carry the return-value burden, and it does so reasonably well by explaining the profile, sensitivity classifications, vocabulary, and plan object shape. It still leaves some detail about the exact response structure and model_name format implicit, but an agent has enough to call it correctly and use the result.

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 would ideally explain model_name. It says the data is 'for a model,' which implies the single required parameter identifies the model, but it provides no format or selection details. With only one self-descriptive required parameter, the gap is moderate rather than severe.

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 specifies the concrete resources returned: an aggregate-only profile, per-column sensitivity classification with match_rate, and a closed operation vocabulary. It also distinguishes this tool from apply_cleansing_plan by naming it as the consumer of the finished plan. The only ambiguity is that the tool name says 'propose' while the description explicitly says it does not propose a plan itself.

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 clearly tells the agent to use the returned contract to build a plan and then pass that plan to apply_cleansing_plan. This establishes the workflow and names the relevant alternative. It does not give explicit when-not-to-use guidance, but the intended usage 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?

Consistent with readOnlyHint=true — explicitly says 'Read-only: nothing is applied here' and adds valuable context beyond annotations: immediate validation against operation vocabulary and model schema, plus the returned plan_id. Missing only edge behavior such as what happens on validation failure.

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

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

Front-loads the purpose and the gating condition, then the validation behavior, then the return/workflow. Every sentence adds information, though it runs slightly long across four short paragraphs.

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?

No output schema, but the description explains the return value (plan_id) and the downstream chain, which covers a lot. The significant remaining gap is the opaque 'plan' parameter — for a tool whose whole job is accepting a plan, not describing its shape leaves the agent under-prepared.

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 hints that 'plan' is validated against the operation vocabulary and model schema, but never describes the plan's structure or what model_name refers to, leaving both required parameters under-specified.

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 ('Register a cleansing plan') and explicitly contrasts with apply_cleansing_plan. However, it does not distinguish itself from the sibling propose_cleansing_plan, which sounds nearly identical in intent, leaving some ambiguity about which registration tool to pick.

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

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

Explicitly names the gating condition (DATAVEIL_REQUIRE_PLAN_APPROVAL=true), names the alternative to use otherwise (apply_cleansing_plan), and lays out the full workflow chain (register → approve → apply). An agent has everything needed to decide when to call it.

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

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

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.

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

readOnlyHint=true already tells the agent this is a safe, side-effect-free read. The description adds the categories of data returned (server, project, safety, capability), which is useful context, but it says nothing about cost, latency, or whether the response shape varies by server state.

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

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

A single front-loaded sentence with no filler. It is efficient, though the one-line format leaves no room to prioritize which metadata category matters most.

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

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

With no parameters and no output schema, the description carries the burden of explaining what comes back, and it only names four metadata categories without detail. That is adequate for a simple introspection tool but leaves the agent guessing about response structure.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain; baseline is 4. The description correctly does not waste space describing arguments.

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

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

States a specific verb and resource ('Return server, project, safety, and capability metadata') and enumerates the metadata categories. It is recognizably distinct from siblings like environment_health or list_models, though it does not explicitly contrast with them.

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

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

Usage is only implied: an agent can infer this is the discovery/metadata call to make first, but the description gives no explicit when-to-use or when-not-to-use guidance and names no alternatives.

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

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

Annotations already declare readOnlyHint=true, and the description consistently presents this as a preview operation. It adds useful async context by noting that the tool runs in the background and returns a job ID, but it does not explain job lifecycle, polling, or cancellation 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 a single front-loaded sentence with no wasted words. It efficiently conveys the core async behavior and return value.

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

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

For a two-parameter asynchronous tool with no output schema and no schema descriptions, the definition is too sparse. It should explain the parameters and indicate how the returned job ID is used, such as with get_job_status or cancel_job.

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

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

Schema description coverage is 0% for both optional parameters, and the description does not mention environment or select_models at all. With low coverage, the description should compensate, but it provides no parameter 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 states a specific action and outcome: starting a plan preview in the background and returning a job ID. It is clear what the tool does, but it does not distinguish it from siblings such as plan, apply_plan, or start_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?

There is no explicit guidance on when to use this tool versus alternatives. The phrase 'in the background' weakly implies an asynchronous workflow, but it does not mention polling with get_job_status or choosing this over plan/start_run.

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 and destructiveHint=true, so the agent knows this mutates state. The description usefully adds that execution happens in the background and that confirm=true is required, but it never explains what the destructive action actually does, whether it can be cancelled, or how the run is tracked (get_job_status exists as a sibling).

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, both earning their place, with the core action front-loaded before the prerequisite. The brevity is appropriate in structure though it contributes to the under-specification noted elsewhere.

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?

This is a destructive, mutating tool with four undocumented parameters, no output schema, and no annotation-derived detail on effects. For a background job starter, the description should explain the date range semantics, environment scoping, and how to follow the run, none of which is present.

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% across four parameters, so the description carries the full burden. It only clarifies confirm=true and leaves start, end, and environment completely undefined in both schema and description, including what format the date strings expect or what environment means.

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 ('Start a scheduled model run') and adds the key behavioral qualifier 'in the background.' It is clear what the tool does, but it never distinguishes itself from close siblings like run, start_plan, or apply_plan, leaving the agent to infer which entry point applies.

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?

'Requires confirm=true' is a prerequisite, not usage guidance. There is no statement of when to choose start_run over run/start_plan/apply_plan, nor any when-not condition, despite several overlapping 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 declare readOnlyHint=true and the description is consistent with a read-only comparison. It adds genuinely non-obvious behavior: console output is suppressed and the MCP client receives JSON. It does not explain what the 'differences' contain, how row-level comparison keys work, or how mismatched schemas are reported.

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 with the core action front-loaded and no filler. The trailing note about suppressed console output is mildly tangential but does carry real information, so nothing is seriously 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?

With 7 parameters, 0% schema coverage, no output schema, and only a readOnly annotation, the description carries most of the burden and does not meet it. Key semantics (what `source`/`target` accept, what `on`/`where`/`skip_columns` do, output shape) are unaddressed for a fairly complex comparison tool.

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

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

Schema description coverage is 0% across 7 parameters, so the description must compensate. It explains only `select_models` ('choose the models to compare'); `on`, `where`, `skip_columns`, `limit`, `source`, and `target` are left entirely unexplained, including whether `on` is a join key for row comparison.

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: 'compare two tables or environments and return structured schema/row differences.' That is clear and concrete. However, it does not distinguish itself from the sibling tool `diff_environment`, which appears to cover overlapping ground (environment comparison), so an agent cannot tell from this text alone which one to pick.

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 second sentence gives a conditional instruction ('When comparing environments, pass select_models'), which is a usage hint. But there is no statement of when to use table_diff versus diff_environment, list_environments, or fetch_model_data, and no prerequisites or exclusions are stated.

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