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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds useful behavioral context: 'Requires a lineage cache — will fetch all workspace nodes with detail=true on first call.' This goes beyond annotations.

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

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

The description is well-structured with an args section and clear bullet-like separation. Each sentence is concise and informative, with no wasted words.

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

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

Given the complexity of impact analysis, the description thoroughly covers what the tool does, its parameters, return values (impacted counts, nodes grouped by depth, critical path), and behavioral notes (caching). The presence of an output schema does not detract from the 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 coverage is 100%, but the description adds significant value by explaining the semantic difference between omitting columnID (analyzes impact of entire node) and providing it (only nodes/columns depending on that column). This goes beyond the schema's short descriptions.

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

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

The description clearly states the tool's purpose: 'Analyze the downstream impact of changing a node or a specific column.' It distinguishes between analyzing the whole node vs a specific column, which differentiates it from siblings like get_downstream_nodes.

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

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

The description provides clear context: analyze downstream impact before modifying a node. It explains the difference between using columnID or not. However, it does not explicitly state when not to use it or mention alternative tools like get_downstream_nodes.

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, openWorldHint, idempotentHint, and destructiveHint, so safety is covered. The description adds valuable context: it performs a whole-workspace scan at summary-level and returns a compact profile. There is no contradiction with annotations.

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

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

The description is concise, with a clear opening sentence, a paragraph for usage guidelines, and separated Args/Returns sections. No unnecessary words; every sentence adds 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?

Given the tool has only one parameter, rich annotations, and an output schema referenced in the description, the description fully explains the scope (whole-workspace summary scan) and return value (profile with adoption, layers, naming, recommendations). It is complete for its complexity.

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

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

Schema coverage is 100% (only workspaceID). The description's Args section repeats the parameter without adding extra meaning, format examples, or constraints. Baseline 3 is appropriate since schema already documents the parameter.

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

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

The description clearly states the tool analyzes workspace node patterns to detect package adoption, pipeline layers, data modeling methodology, and generate recommendations. It distinguishes itself from siblings like search_workspace_content and get_workspace_node by specifying it is for profiling/overview tasks, not for finding specific nodes.

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 when to use the tool (profiling/overview tasks) and when not to use it (finding a specific node), and provides direct alternatives: search_workspace_content, get_workspace_node, and cache_workspace_nodes. This gives clear guidance.

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

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

Annotations indicate write, idempotent, and non-destructive behavior. The description adds that it writes to sourceMapping.join.joinCondition, inspects columns, and auto-generates conditions. This complements the annotations without contradiction. It could mention overwriting behavior, but overall high transparency.

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

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

The description is well-structured: a purpose sentence, usage guidance, then bullet lists for args and returns. No unnecessary words, each sentence contributes. It is front-loaded with the key action.

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

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

Given 6 parameters, a described output object, and annotations, the description covers all aspects: what it does, when to use, inputs, outputs, and behavior. No gaps remain for an agent to misuse the tool.

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

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

Schema coverage is 100%, providing baseline 3. The description adds meaning beyond schema: explains purpose of each param, defaults for joinType, and clarifies joinColumnOverrides usage for mismatched column names. This adds significant value.

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 writes a FROM/JOIN/ON clause to a specific node property by analyzing predecessor columns and generating join conditions automatically. It uses a specific verb and resource, distinguishing it from sibling tools like convert_join_to_aggregation.

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

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

The description explicitly says to use for multi-predecessor nodes needing JOINs, and explains the automatic column matching. It does not mention exclusions or alternatives, but the context is clear and sufficient for selecting this tool.

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

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

The description provides extensive behavioral details beyond annotations: diff logic, what is not reverse-engineered, block-level diff, tail-clause diff, INSERT header diff, and specific rejection cases. This far exceeds the readOnlyHint and destructiveHint provided.

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 quite long but well-structured with sections and bullet points. The core purpose is front-loaded. While every sentence contributes value, the verbosity could be streamlined for quicker parsing.

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

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

Given the tool's complexity (4 parameters, no output schema), the description is exceptionally complete. It covers edge cases, detailed return structure, and diffing logic comprehensively, making it sufficient for an agent to invoke correctly.

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

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

The description adds significant meaning to each parameter beyond the input schema. For 'sql', it explains accepted forms, auto-detection, and limitations. For 'dryRun', it clarifies preview behavior. The schema coverage is 100%, yet the description still enriches understanding.

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

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

The description clearly states the tool's purpose: 'Round-trip a user's edits on a rendered DDL/DML SQL document back to the cloud workspace node it came from.' It distinguishes itself from sibling tools by focusing on applying SQL edits diffs, not generic node updates.

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 implicitly guides usage by detailing the inputs from coa_dry_run_create and coa_dry_run_run. However, it lacks explicit alternatives or when-not-to-use guidance. It is clear but not perfectly explicit about when to choose this over other 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 description details behavioral traits beyond annotations: it explains the dependency on a lineage cache, initial fetch time, caching TTL (30 min), and defines 'documented' for nodes and columns. It also notes that column lists are capped at 200. Annotations already indicate read-only, idempotent, and non-destructive, and the description adds valuable context without contradiction.

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

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

The description is concise and well-structured: a one-sentence purpose, followed by clear sections for Args, Returns, and additional details. Every sentence adds value 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?

Given the tool's complexity (scanning all nodes, caching, reporting statistics), the description covers all necessary aspects: return structure, undocumented node/column listing limits, and caching behavior. No critical gaps are 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?

The single parameter 'workspaceID' is fully described in the schema (100% coverage). The description merely restates it as 'Workspace to audit', adding no extra meaning beyond the schema.

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

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

The description clearly states the tool's purpose: to scan all nodes and columns in a workspace and report documentation coverage statistics. It uses a specific verb ('audit') and resource ('documentation coverage'), and is distinct from sibling tools like 'list_workspace_nodes' or 'analyze_workspace_patterns'.

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

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

The description implies usage for auditing documentation coverage and mentions caching behavior, but does not provide explicit guidance on when to use this tool versus alternatives. No exclusions or comparisons to siblings are given.

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

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

Discloses key behaviors: parses intent, fuzzy-matches entities, selects node types, creates nodes upon confirmation, returns clarification questions when ambiguous. Annotations indicate write operation (readOnlyHint=false) and non-destructive, consistent with description.

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?

Description is well-structured with examples, clear flow, and no redundant sentences. Every sentence adds value, including the crucial note about STOP_AND_CONFIRM response. Front-loaded with main purpose and alternatives.

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 tool complexity (11 parameters, requires output schema which exists), description fully explains workflow, error handling (ambiguity), and integration with confirmation. No gaps identified.

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

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

Input schema covers all parameters (100% coverage), but description adds meaningful context: explains dryRun returns plan without creation, confirmed requires confirmationToken, repoPath fallback behavior, and targetNodeType auto-selection. This extra context justifies above baseline 3.

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

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

Clearly states the tool builds a Coalesce pipeline from natural language, with specific verb 'build', resource 'pipeline', and source 'intent'. Distinguishes from sibling 'create_pipeline_from_plan' by mentioning it as an alternative for dry-run plans.

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 explicit guidance: when to use (natural language intent), when to use dryRun, prerequisite of workspaceID and intent, required confirmation flow with confirmationToken, and fallback to clarification questions for ambiguity. Also mentions alternative tool create_pipeline_from_plan.

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

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

The description discloses that data is cached to disk and returns a resourceUri for accessing the cache, which goes beyond the annotations (idempotentHint, openWorldHint, etc.). No contradictions with annotations.

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

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

The description is concise: one sentence for purpose followed by a clear parameter list. It is front-loaded and every sentence serves a purpose 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?

Given the presence of annotations and the return description (cache metadata with resourceUri), the description is complete. It explains the tool's behavior, parameters, and output, leaving no significant 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?

Input schema coverage is 100%, and the description merely restates defaults already present in the schema (e.g., detail defaults to true, pageSize defaults to 250). It adds no new semantic information beyond the schema.

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

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

The description clearly states the tool's purpose: to fetch and cache all environment nodes to disk for efficient repeated access. It uses specific verbs ('fetch and cache') and identifies the resource ('environment nodes'), distinguishing it from sibling cache tools like cache_org_users or cache_runs.

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

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

The description implies usage for repeated access to environment nodes, but does not explicitly compare to alternatives like list_environment_nodes or get_environment_node. While the caching intent is clear, explicit when-to-use guidance is missing for a 5.

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

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

Annotations already indicate idempotent and non-destructive behavior. The description adds transparency by stating it caches to disk and returns cache metadata with a resource URI. No contradictions; the side effect (writing to disk) is disclosed.

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

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

The description is extremely concise: one sentence for purpose, an Args list, and a Returns line. No unnecessary words; every part 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 3 optional parameters and an output schema, the description fully covers what the tool does, its parameters with defaults, and what it returns (cache metadata with resourceUri). No missing information.

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

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

Schema coverage is 100%, and the description adds value by summarizing default values (pageSize defaults to 250, max 500; orderBy defaults to id; orderByDirection enforces 'asc' or 'desc'). This goes beyond the schema by providing defaults in a concise format.

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 'Fetch and cache all organization users to disk for efficient repeated access.' This specifies a verb (fetch and cache), a resource (organization users), and a distinct purpose (efficient repeated access). Among siblings, list_org_users likely provides one-time listing, so this tool is well-differentiated.

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: for caching users to avoid repeated fetches. However, it does not explicitly mention when not to use or alternatives (e.g., list_org_users for one-time access). The context is clear but lacks explicit exclusions.

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

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

The description adds context beyond annotations: it reveals side effect (caching to disk), idempotency (efficient repeated access), and return format (resourceUri). Annotations provide idempotentHint=true, which aligns. No contradictions.

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?

Description is well-structured with Args and Returns sections, front-loading the main purpose. It is adequately concise, though could be tightened by removing redundant default mentions.

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 7 optional params and no output schema provided, the description explains the return format (cache metadata with resourceUri) adequately. It covers the essential behavior for an agent to use the tool correctly.

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

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

Schema coverage is 100%, so description adds marginal value. It provides defaults and limits (e.g., pageSize max 500) and clarifies parameter purposes, but does not introduce new meaning beyond the schema.

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

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

The description clearly states 'Fetch and cache runs to disk with optional filters', using specific verb (fetch/cache) and resource (runs). It distinguishes from siblings like 'list_runs' and 'get_run' by emphasizing caching behavior.

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

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

No explicit guidance on when to use this tool vs alternatives (e.g., 'list_runs' for one-time fetch). The description implies caching for repeated access, but does not state exclusions or alternatives.

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

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

Adds context beyond annotations: details trade-off (detail=false cheaper vs detail=true large snapshot), and client limitation (result resource link unreadable by clients like Snowflake Cortex Code). No contradiction with annotations.

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

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

Well-structured with main purpose, Args section, Returns section. Front-loaded with key info, no wasted words.

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

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

Complete for a caching tool with 5 params and output schema. Explains caching mechanism, resource link limitation, parameter behaviors. No 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 coverage 100% gives baseline 3. Description adds value: explains detail parameter cost trade-off, pageSize for collection, orderBy/orderByDirection for pagination. Above baseline.

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

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

The description clearly states the tool fetches and caches the entire workspace's nodes to disk, specifying the resource (workspace nodes) and action (fetch and cache). It distinguishes from siblings like search_workspace_content, get_workspace_node, etc.

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 says 'Run this ONLY when the user explicitly wants the whole workspace cached' and provides specific alternatives for targeted work (search_workspace_content, get_workspace_node, get_workspace_subgraph, analyze_workspace_patterns).

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

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

Beyond annotations (destructiveHint=true), the description adds detailed behavioral traits: immediate termination, potential inconsistent state, no undo. No contradiction.

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

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

The description is well-structured, front-loaded with purpose, and every sentence adds value 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?

For a destructive operation with annotations, complete schema, and output schema, the description covers consequences, parameter details, and return expectation, leaving no 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 coverage is 100%, but the description adds context like runID being numeric, orgID fallback logic, and confirmed param usage, providing meaningful added value.

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 'Cancel an in-progress Coalesce run' with a specific verb and resource, and it distinguishes from sibling tools like retry_run and 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?

The description warns about data inconsistency and no undo, implying caution, but does not explicitly state when to use vs alternatives like retry_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 indicate destructiveHint=true. The description adds that it removes all cached artifacts from disk, confirming the scope. It does not contradict annotations and provides additional context about the action's permanence, though it could mention impact on ongoing operations.

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?

Description is extremely concise: one sentence for purpose, then a clear Args and Returns section. Every sentence adds value. No unnecessary words.

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

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

For a simple cache-clearing tool with one optional parameter and an output schema, the description provides all necessary context: what it does, the safety confirmation step, and the return structure. No 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 coverage is 100% with a description for the confirmed parameter. The tool description repeats this information without adding new semantics. Baseline score of 3 is appropriate.

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

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

Description clearly states the verb 'clear' and resource 'data cache', specifying it removes all cached artifacts. No sibling tools perform cache clearing, so no differentiation needed.

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?

Description explains when to use (to clear cache) and provides a guideline that the confirmed parameter should be set after user explicit confirmation. However, it does not explicitly discuss when not to use or alternatives, but for a simple maintenance tool, this is acceptable.

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

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

Beyond annotations (destructiveHint=true), description details that it writes files, requires confirmed:true, skips existing nodes unless overwrite:true, and explains dry-run behavior (no files written). No contradiction with annotations.

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

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

Well-structured with clear sections, front-loaded purpose, and no unnecessary words. Every sentence adds 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?

Covers all aspects: destructive behavior, parameters, dry-run, profile resolution, return shape, and a usage pattern. No gaps given the tool's complexity.

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

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

Despite the input schema showing no properties, the description thoroughly explains each parameter (projectPath, location, all, include, overwrite, dryRun, profile, confirmed) and their roles, effectively compensating for the empty schema.

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

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

Clearly states the tool scaffolds source-node YAML files from warehouse tables, distinguishing itself from sibling tools like coa_remove_warehouse_sources and coa_list_warehouse_sources via a usage pattern mention.

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 explicit usage constraints: exactly one of location or all, dry-run option, profile resolution, and a recommended pattern to preview with coa_list_warehouse_sources first.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds behavioral context: it writes a file, is safe to re-run, includes a known issue about profile fall-through, and requires confirmed=true. This adds value beyond annotations without contradiction.

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

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

The description is well-structured with clear sections (main action, important notes, known issue, destructive warning, args, returns). Every sentence provides useful information, though it could be slightly more concise without losing clarity.

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

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

Given the tool has 3 parameters, output schema, and side effects, the description covers purpose, usage warnings, known issues, destructive nature, and return format. It fully equips the agent to understand when and how to use the 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 100%, so the schema already documents all parameters. The description does not add additional semantics beyond what the schema provides (e.g., confirmed requirement is also in schema). Baseline score of 3 is appropriate.

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

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

The description clearly states the tool runs 'coa doctor --fix' to write a starter 'workspaces.yml' file, seeded from 'locations.yml'. The verb 'writes' and specific resource distinguish it from siblings like coa_doctor, coa_create, etc.

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

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

The description provides clear usage context: it is safe to re-run, will not overwrite existing valid files, and warns that placeholder values must be replaced before using coa_create/coa_run. It also mentions the known issue about profile configuration. It lacks explicit when-not-to-use or alternatives but provides strong guidance overall.

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 explicitly states DESTRUCTIVE: modifies warehouse schema, requires confirmation, and details pre-flight checks and V2 notice. This adds significant context beyond the destructiveHint annotation, which is already true.

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 with clear sections (DESTRUCTIVE, pre-flight, V2 NOTICE, Args, Returns) and front-loads the purpose. It is informative but could be slightly trimmed; however, it earns its length.

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

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

Given the tool's destructive nature, 5 parameters, and output schema, the description covers behavior, required confirmation, preflight checks, V2 details, and return structure comprehensively. No gaps identified.

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

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

The description adds meaning to parameters beyond the schema, e.g., explaining confirmed must be true to execute, and clarifying include/exclude selectors. Since schema coverage is 100%, the description still adds value.

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 executes 'coa create' to run DDL (CREATE/REPLACE) for selected nodes against the configured warehouse. It distinguishes itself from sibling tools like coa_dry_run_create by indicating destructive behavior and required confirmation.

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

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

The description provides clear context: requires confirmed=true after user approval, runs pre-flight checks, and notes V2 behavior. It does not explicitly mention when not to use or compare to alternatives, but the guidance is sufficient for appropriate use.

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 behavioral context beyond annotations: it explicitly warns 'DESTRUCTIVE: modifies the deployed environment' (matching destructiveHint=true), details the confirmation requirement ('confirmed must be true to execute'), and clarifies the validation scope ('Does NOT re-validate project contents — validates the plan structure only'). This is valuable additional transparency. A minor gap: it doesn't mention whether the operation is synchronous or async, but the return format suggests synchronous. Still, strong.

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

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

The description is well-structured: a concise purpose sentence, a warning line, prerequisites, then a clear 'Args' list, and a 'Returns' line. It is efficient but slightly redundant with the schema (the Args list largely mirrors the schema properties). However, the structure aids quick comprehension. Minor redundancy prevents a 5.

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

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

Given the tool's complexity (destructive, confirmation requirement, plan prerequisite, return format), the description covers all essential aspects: purpose, behavioral traits, prerequisites, argument details, and return schema. The presence of an output schema reduces the burden, but the description still provides complete context for safe and correct invocation.

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

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

With 100% schema coverage, the description still adds significant meaning: it re-explains each parameter in a clear 'Args' list, emphasizing the critical points (e.g., 'plan: path to coa-plan.json', 'confirmed: must be true to execute'). It goes beyond the schema by grouping optional parameters and explaining the 'profile, token' fallback behavior. This fully compensates for any dependency on schema.

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

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

The description clearly states 'Apply a plan JSON to a cloud environment. Changes environment schema/state.' This is a specific verb+resource combination that distinguishes the tool from siblings like coa_plan (which produces the plan) and coa_run (which runs a pipeline). The purpose is unambiguous.

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

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

The description provides explicit usage guidance: 'The plan file must exist (produced by coa_plan). Does NOT re-validate project contents — validates the plan structure only.' and 'Requires confirmed=true.' It clearly indicates when to use (after coa_plan) and the needed confirmation. While it implies not to use without a plan, it could explicitly name the alternative (coa_plan) for when-to-use differentiation, but the guidance is strong.

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

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

Annotations indicate read-only and idempotent. The description adds caching behavior (defaults to disk cache, can refresh with 'refresh' parameter) and describes the 'source' field in the return value. No contradictions.

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

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

The description is concise and well-structured: a summary sentence, then bullet points for parameters and return value. No fluff, front-loaded with purpose.

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

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

Given the output schema exists, the description does not need to detail return format, but it provides a brief summary. It covers usage, parameters, and behavior completely for a documentation tool.

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

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

Schema coverage is 100%, but the description adds value by listing well-known topics, explaining subtopic usage for 'command' and 'schema', and clarifying the 'refresh' parameter's effect on cache.

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 fetches documentation sections, uses the verb 'Fetch', specifies the resource ('section of COA's self-describing documentation'), and distinguishes itself from siblings that perform actions on nodes or 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?

The description explains when to use (to get documentation), lists well-known topics, and describes parameterized usage. While it does not explicitly state when not to use or name alternatives, the sibling context implies its specific role.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds critical behavioral context about profile resolution differences and the known issue, going beyond what annotations cover.

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 purpose and input details, then the known issue. While the known issue paragraph is lengthy, it's important and well-structured. Minor verbosity but 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?

Given the tool's diagnostic nature and output schema, the description explains what is checked, the known limitation, and uses the input schema well. It provides sufficient context for an agent to use the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description restates parameter purposes (projectPath as COA project root, workspace with default 'dev') but adds no new meaning beyond the schema descriptions.

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

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

The description clearly states the tool runs 'coa doctor' to check data.yml, workspaces.yml, credentials, and warehouse connectivity. It specifies a diagnostic/validation role, which distinguishes it from siblings like coa_deploy or coa_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?

The description includes an explicit known issue (CD-16983) explaining when not to rely solely on this tool (green result doesn't guarantee auth matching for plan/deploy) and advises to suspect profile divergence. This provides clear when-not-to-use and alternative debugging steps.

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?

While annotations indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, the description adds substantial behavioral context: it forces --dry-run --verbose, runs entirely offline without API calls, reports per-node pass/fail, explains non-zero exit code meaning, and warns about V2 node pitfalls and the limitation that it doesn't validate column existence. No contradiction with annotations.

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

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

The description is lengthy but well-structured with sections (OUTPUT SHAPE, LIMITATION) and front-loads the core purpose. Some redundancy exists (e.g., dry-run explained twice), but the complexity warrants the detail. Slightly verbose but organized.

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

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

Given the tool's complexity (dry-run with special output behavior and limitations), the description covers output shape, failure handling, V2 node bugs, and cross-tool comparisons. The output schema exists, so return values are not needed. Complete for an agent to use correctly.

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

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

Schema coverage is 100%, but the description adds significant value: it explains `include`/`exclude` as node selectors with examples, mentions workspace defaults to 'dev', and provides context for the node selector syntax. This goes beyond the schema descriptions.

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

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

The description clearly states 'Preview the DDL that `coa create` would execute, without hitting the warehouse.' It specifies the verb (preview), resource (DDL), and explicitly distinguishes from `coa create` and cloud commands. The purpose is unambiguous and differentiated from siblings.

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

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

The description explains when to use this tool (preview DDL offline) and explicitly warns against confusing it with scheduler-aware cloud commands like `coa deploy`/`coa plan`/`coa refresh`. It also clarifies that `coa create` and `coa run` are offline local-dev commands, providing clear context and exclusions.

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

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

Description adds significant value beyond annotations: it reveals offline nature, no authentication needed, output shape (pass/fail per node), non-zero exit code meaning, and limitation that dry-run doesn't validate column/type existence. Annotations already indicate read-only and idempotent, but description enriches with operational details.

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

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

Description is well-organized with sections (OUTPUT SHAPE, LIMITATION) and concise bullet points. Every sentence adds value, no 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?

Despite formal output schema not fully detailed, description explains output shape, exit code interpretation, and limitations. Covers key aspects needed for correct use: offline, no auth, column validation caveat. Comprehensive for a dry-run 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?

Input schema has 100% description coverage, so description adds minimal new meaning. It gives examples for include/exclude but mostly restates schema. Baseline 3 is appropriate.

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

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

Description clearly states it previews DML from `coa run` without hitting warehouse, forcing --dry-run --verbose. It distinguishes from sibling tools like coa_dry_run_create and coa_run, and clarifies it's offline vs cloud commands.

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 warns not to confuse with coa deploy/plan/refresh, tells when to use cortex for schema validation, and advises to scan full stdout for exit codes. Provides clear context for when to use this tool vs 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds operational detail: wraps a command and returns a specific structure. No contradictions and adds value beyond annotations.

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

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

Description is concise, uses bullet points for args/returns, and front-loads the core purpose. No unnecessary words.

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

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

Covers purpose, usage differentiation, returns structure, and parameter list. With full schema and annotations, the description is adequate. Could add more about the command context but not necessary.

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

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

Schema covers both parameters with descriptions. Description merely restates parameter names and types without adding new context. Baseline 3 is appropriate given high schema coverage.

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?

Clearly states 'List all nodes defined in a local COA project (pre-deploy)', providing a specific verb and resource. Distinguishes from sibling list_environment_nodes by specifying scope (local vs deployed).

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 differentiates from list_environment_nodes and states it is for pre-deploy listing. Gives clear context for when to use this tool.

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

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

Annotations already declare read-only and non-destructive behavior. The description reinforces this with 'Read-only: ... writes nothing' and adds useful context about profile resolution. No contradictions.

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

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

The description is well-structured, front-loaded with the core function, followed by modes, usage guidance, behavioral notes, and parameter list. Every sentence adds value 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?

Overall comprehensive for a list tool: covers modes, usage, behavior, and returns. However, the return structure is only partially described (e.g., 'json?' is vague) and the actual output shape for details is not specified.

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 is empty, so the description carries full parameter information. It lists five parameters with types and notes mutual exclusivity of 'location' and 'all'. However, it lacks format details for parameters like location or profile.

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

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

The description clearly states the tool's main function: listing warehouse tables visible to storage locations in a COA project. It distinguishes itself from sibling tools by explicitly referencing coa_add_warehouse_sources and explaining how this tool is used as a precursor.

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

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

The description provides explicit guidance on when to use each of the three modes (summary first, location-specific for detail, all mode cautiously) and gives concrete use cases like identifying un-imported tables before adding sources.

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 indicate non-destructive and non-read-only. Description reinforces non-destructive nature and adds context: reads local project, diffs, writes plan file, attaches preflight warnings if V2 artifacts detected, and is safe to call without confirmation. No contradictions with annotations.

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

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

Description is well-structured: front-loaded with main purpose and safety, then prerequisites, special notes, and arg list. The arg list is somewhat redundant with schema but not overly verbose. It earns its space with essential information.

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

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

Given complexity (8 params, output schema exists), the description covers all necessary aspects: purpose, behavior, safety, prerequisites, special V2 notice, argument summary, and return shape. Agent has sufficient information for correct invocation.

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

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

Schema coverage is 100% with detailed descriptions. The description's 'Args' section adds some context beyond the schema, such as default output path and fallback behavior for profile/token. While schema provides complete semantic coverage, the description offers slight additional value.

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 generates a deployment plan by reading the local project, diffs against target, and writes a plan JSON. It uses specific verb 'generate' and resource 'deployment plan', and distinguishes from sibling coa_deploy which applies the 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 states the tool is non-destructive, safe to call without confirmation, and that the plan is applied via coa_deploy, providing clear when-to-use guidance. It also lists prerequisites (credentials, environmentID) and notes the V2_DETECTED preflight warning behavior.

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 explicitly states 'DESTRUCTIVE: modifies warehouse data' and the need for confirmed=true, which adds behavioral insight beyond the annotations (destructiveHint=true). It also warns about forceIgnoreEnvironmentStatus potentially causing failures, providing valuable behavioral context.

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

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

The description is fairly concise but includes a parameter list that largely duplicates the schema. It is well-structured with clear sections (description, destructive note, args, returns), though the args section could be trimmed for even better conciseness.

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

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

The description covers the tool's destructive nature, required confirmation, and the return structure. Given the output schema exists, it doesn't need to detail return values further. It could elaborate more on how include/exclude node selectors work, but overall it's adequate.

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

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

The input schema has 100% description coverage, so the schema already explains all parameters. The description repeats the parameter list but does not add significant new meaning beyond the schema's own descriptions.

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

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

The description clearly states the tool's purpose: 'Run DML for selected nodes in a deployed environment.' It specifies that it operates purely on the cloud environment and does not require a local project, distinguishing it from other tools that may need local context.

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

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

The description provides usage context, noting that it requires confirmed=true and is destructive. It also mentions that it doesn't require a local project. However, it does not explicitly compare with sibling tools like coa_run or coa_deploy, leaving some ambiguity about when to choose this tool over 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?

Highlights destructive nature, confirmation requirement, CLI wrapper behavior, and profile limitation, adding context beyond annotations. However, the parameter contradiction with schema reduces clarity.

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?

Well-structured with clear sections and front-loaded purpose. Slightly verbose but each sentence adds value. Could be more concise.

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?

Covers behavior, return shape, usage pattern, alternatives, and limitations. Lacks full alignment with input schema due to parameter mismatch, otherwise comprehensive.

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?

Describes 5 parameters with detailed semantics, but the input schema declares no properties. This mismatch makes the parameter information unreliable and misleading, severely undermining usefulness.

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?

Clearly states 'Delete scaffolded source-node YAML files from the project' with specific verb and resource. Distinguishes from sibling 'coa_list_warehouse_sources' by pairing suggestion.

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 explicit when-to-use context (re-onboarding, cleanup after schema rename), required flags, profile limitation with workaround, and pairing with list tool. Covers when-not-to-use implicitly by noting unmanaged files are not removed.

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

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

Annotations already indicate destructiveHint=true, but the description reinforces this with 'DESTRUCTIVE: modifies warehouse data.' It adds value by detailing the need for confirmed, timeout, preflight warnings for V2 projects, and return structure. No contradiction with annotations.

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

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

The description is concise with a clear one-line summary followed by key behavioral notes. It uses a clean structure but could be more streamlined; no wasted sentences.

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

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

Given the tool has 5 parameters, annotations, and an output schema, the description is fairly complete. It covers purpose, behavioral traits, and return format. It references coa_create for additional details, which is acceptable.

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

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

All 5 parameters are described in the schema (100% coverage). The description adds some context (e.g., confirmed must be true, include example, projectPath mentions data.yml), but much of this is already in the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool runs DML (INSERT/MERGE) to populate selected nodes. It uses a specific verb+resource combination. However, it does not explicitly distinguish itself from siblings like coa_create or coa_dry_run_run, though it mentions shared pre-flight checks.

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

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

The description mentions the requirement for confirmed=true and a 30-minute timeout. It references coa_create for pre-flight checks, but does not provide explicit when-to-use or when-not-to-use guidance compared to alternatives like coa_dry_run_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 indicate read-only and idempotent behavior. The description adds value by disclosing a known false-positive issue and detailing the return format (command, exitCode, stdout, etc.), which goes beyond the annotations.

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

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

The description is concise and front-loaded with the core action. It includes a known issue, arguments, and returns without extraneous details. Every sentence contributes useful information.

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

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

Given the tool's complexity, the presence of annotations, full schema coverage, and an output schema, the description is fairly complete. It covers what is scanned, a known issue, and the return format, but could benefit from more guidance on interpreting results or prerequisites.

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 100% schema description coverage, the description's argument list largely restates the schema. No additional semantics or examples are provided beyond what is in the schema, so the added value is minimal.

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 runs `coa validate` and scans YAML schemas, storage locations, column references, and types. It provides a specific verb and resource, but does not explicitly differentiate from sibling tools like `coa_doctor` or `coa_describe`.

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

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

The description mentions a known issue with false positives that do not block related tools, offering some context for when validation results may need interpretation. However, it lacks explicit guidance on when to use this tool versus alternative validation or diagnostic tools.

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

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

Annotations already indicate idempotent, non-destructive, open world. Description adds that it analyzes type definition and existing config, and can be invoked after manual edits, implying it fills without overwriting. No contradiction.

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

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

Two short paragraphs plus bulleted Args/Returns. Front-loaded purpose, no wasted words.

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

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

Provides enough context for understanding when and how to use, including return shape. Could elaborate on 'intelligent' aspects but sufficient for typical usage.

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

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

Schema covers all 3 params (100% coverage). Description adds meaningful context for 'repoPath' (type definition lookup) and includes returns section. Baseline 3 exceeded by extra clarity.

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

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

The description clearly states the verb 'Run intelligent configuration completion' on a specific resource 'workspace node', and differentiates from siblings by noting that creation tools call it internally but it can be invoked separately.

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 says when to use: after manual edits or as standalone. Does not list alternatives but context implies completion is handled internally by creation tools. Good but not exhaustive.

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

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

Annotations declare readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds rich behavioral details: it automatically generates JOIN ON clauses, writes the complete FROM/JOIN/ON/GROUP BY clause, replaces columns, infers datatypes, sets column-level attributes, validates GROUP BY, and runs config completion. No contradiction with annotations.

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

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

The description is well-structured: purpose statement, bullet list of automatic actions, example, then parameter list. It is front-loaded with the main purpose. While somewhat verbose, every sentence adds value given the tool's complexity.

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?

Despite having 7 parameters, the description covers all aspects: what it does, how it works, what it returns, and provides an example. The output schema is implied to exist, and the description explains the return value sufficiently.

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

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

Schema description coverage is 100%, so baseline is 3. The description's 'Args' section reiterates parameters with brief descriptions, but also provides a concrete example with values mapped to parameters, which adds meaningful context beyond the schema definitions.

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

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

The description clearly states the tool converts a join node into an aggregated fact table with GROUP BY. It distinguishes itself from sibling tools like 'apply_join_condition' by specifying it is the required follow-up after creating a multi-predecessor node. A concrete example is provided.

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 this is the required follow-up after creating a multi-predecessor node, providing clear context. It does not explicitly list when not to use it or alternatives, but the context is strong enough.

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