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

No annotations are provided, so the description carries full burden. It discloses that the query will be stored as a Golden SQL example and explains that the description makes it useful to agents later, adding behavioral context. However, it does not mention permissions, validation, error handling, or side effects.

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

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

The description is two sentences with no filler. The primary action is front-loaded, and the second sentence adds a concise, valuable usage tip about the description field.

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 create operation, the description covers the core action and an important nuance about the description parameter, but it omits error conditions, validation behavior, or prerequisites. The output schema exists, so return values are not needed, but more context about what makes a valid golden SQL 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 coverage is 0%, so the description must compensate. It clarifies that golden_sql is the SQL query and knowledge_base_id identifies the knowledge base, and it specifically explains the purpose of the 'description' parameter. This adds meaning, but it does not detail formats or constraints for the parameters.

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

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

The first sentence clearly states what the tool does: 'Save a SQL query as a Golden SQL example on a knowledge base.' It uses a specific verb and resource, and the name 'add_golden_sql' plus sibling tools (list_golden_sql, delete_golden_sql) make its role unambiguous.

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

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

The description implies when to use the tool via the verb 'save' and provides a specific usage tip for the description parameter, but it does not explicitly mention when not to use it or name alternatives. Guidance focuses on parameter usage rather than tool selection.

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

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

With no annotations, the description fully discloses behavioral nuances: the two distinct return paths, that all_offered_tables must come from generate_pipeline_sql, the warning that SQL is auto-generated and must not be validated, the instruction to 'Report the saved receipt and stop,' and the directive to pass sql/graph unchanged to save_pipeline_sql. This is rich, non-obvious behavior that the agent needs to know.

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 moderately long but every sentence contributes actionable information. It front-loads the core purpose in the first sentence, then uses short paragraphs for preferred usage, alternative usage, and a critical warning. No filler or redundant content—each line 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 complexity, the description covers the essential context: it is the second step of a two-step flow, it has two operational paths with different return values, it explicitly states what to do with the returned data (hand to save_pipeline_sql unchanged) and what not to do (validate against metadata). The output schema exists but the description still summarizes the return payloads, making the tool self-contained.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies the meaning of keep_tables and all_offered_tables (fully-qualified DB.SCHEMA.TABLE names, with all_offered_tables tied to generate_pipeline_sql's offered_tables) and explains the effect of save_to_version_id. However, it does not explain the remaining parameters (pipeline_id, knowledge_cluster_id, session_id, target_table, max_attempts), which are mostly self-explanatory but still lack explicit semantic guidance. The key ambiguous parameters are covered, so this goes 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?

The description opens with a specific verb-resource pair: 'Confirm the table selection and generate the SQL.' It explicitly identifies itself as 'Step 2 of 2,' clearly tying it to the preceding generate_pipeline_sql step, and distinguishes the two operational modes (with/without save_to_version_id). This removes ambiguity about the tool's role among the large sibling set.

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

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

The description gives explicit when-to-use and when-not-to-use guidance. It names the preferred path ('PREFERRED: pass save_to_version_id... the SQL is generated and saved in this single call') and the alternative path that requires handing sql/graph to save_pipeline_sql. It also names specific tools to avoid ('get_table_details or list_kb_tables') and explains why validating is wasted work, analogous to TDQS 4.3's explicit alternative naming.

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 no annotations, the description carries the full burden and excels by disclosing multiple behavioral traits: the verbatim question requirement, the retry-on-empty behavior, the 40-60s latency, and the warning that empty results are indistinguishable from failure. This goes well beyond basic expectations.

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

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

The description is front-loaded with the core purpose, and every subsequent sentence provides necessary operational detail. It is appropriately sized for the tool's complexity, with no redundant or filler 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?

The description covers usage, parameter behavior, failure modes, and gotchas (such as not telling the user 'there is no data'), and an output schema exists to document return values. This makes the tool fully comprehensible for an agent.

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%, but the description explains question, execute_query, session_id, and max_attempts in context, leaving only knowledge_cluster_id to be inferred from the tool's purpose. This substantial compensation warrants a score above baseline, though not 5 because a few parameter specifics (e.g., max_attempts default) are not explicitly stated.

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 ("ask") and resource ("the Data Analyst agent about a knowledge cluster"), clearly distinguishing it from sibling tools that manage sources, pipelines, and clusters. It also provides essential context about verbatim questions, making the purpose 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 gives clear context for when to use the tool (when a question about a knowledge cluster needs an answer) and provides operational guidance on execute_query, session_id, and empty-result behavior. It does not explicitly name alternative tools, so it falls short of 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. The phrase 'Check whether' implies a read-only operation, but the description does not state whether any state is modified, what the output format is, or what 'legally' means in this context. This is a meaningful transparency gap for a tool with no annotation support.

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 immediately communicates the tool's purpose. There is no redundant information or fluff, and the key subject/object structure is front-loaded and clear.

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

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

The tool is simple with one parameter and an output schema, so the description doesn't need to explain return values. However, it lacks richer context about the meaning of 'legally share,' error conditions, or whether this is a read-only dry-run. It is minimally adequate but has clear gaps in behavioral and usage context.

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 schema has one parameter, knowledge_base_ids, with 0% description coverage. The description only refers to 'a set of knowledge bases,' which roughly aligns with the parameter but does not explain what the IDs represent, whether they follow a specific format, or any constraints. It adds minimal semantic value beyond the parameter name and schema type.

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 identifies the tool's action ('Check') and its specific resource/purpose: whether knowledge bases could legally share one knowledge cluster. This distinguishes it from sibling tools like list_knowledge_clusters or create_knowledge_cluster, which focus on listing or creation rather than legal compatibility checking.

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 purpose implies usage: use this tool when you need to verify if a set of knowledge bases can share a cluster. However, it does not explicitly state when to use it versus alternatives, nor mention any prerequisites or exclusions. The usage context is only implicit, matching a score of 3.

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 no annotations, the description carries the full burden of disclosing behavior. It reveals the important refusal behavior for federated structured KBs, explains why (cannot query across them), and notes the exemption for unstructured document KBs. It does not mention permissions or side effects, but the create action is implicitly mutating and the verb makes that clear.

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 exactly two sentences, front-loaded with the primary action and immediately followed by the key constraint. Every word adds value, and there is no filler or repetition.

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 create tool with an output schema and many sibling tools, the description covers the core operation and the most critical limitation (federation). It could also mention that the referenced knowledge bases must already exist or that list_knowledge_bases can help discover IDs, but the essential context 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%, so the description must compensate. It adds meaning to 'knowledge_base_ids' by saying the cluster is created 'from knowledge bases' and clarifies that 'instructions' is optional. However, it does not add any detail to 'name' or 'description', leaving those to rely on their obvious 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 immediately states a specific action: 'Create a knowledge cluster from knowledge bases, optionally with instructions.' This clearly identifies the resource and operation, and the federation caveat helps distinguish it from sibling cluster tools like get_knowledge_cluster or delete_knowledge_cluster.

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 for when to use the tool (creating a cluster from existing knowledge bases) and explicitly states a when-not condition (refuses federated structured KBs). It does not name alternative tools for the refused case, but the exclusion is concrete and useful.

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 no annotations, the description must carry the full burden, and it does well by explaining the meaning of the key parameters and what the tool returns (pipeline id and first version id). It does not discuss idempotency, auth, or error behavior, but for a 'create' action, the disclosed semantics are adequate.

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

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

The description is three sentences with no fluff. It front-loads the purpose ('Create a data pipeline'), then provides a compact parameter explanation, and ends with the return value and its use. Every sentence 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 complexity (5 required parameters, no annotations, no schema descriptions) and the existence of an output schema, the description is complete enough: it informs the agent what to pass and what to expect in return, and it positions the tool in the workflow via 'both needed to save SQL.' Minor gaps exist, like not explaining what a 'pipeline' or 'first version' means, but these are not critical.

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 adds meaning to the most confusing parameters: source_id and knowledge_base_id are defined as write targets, and knowledge_cluster_id is defined as reasoning context. The remaining parameters (name, description) are self-explanatory, so the description fills the gap effectively.

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

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

The description opens with 'Create a data pipeline,' a specific verb+resource statement that clearly distinguishes it from sibling tools like generate_pipeline_sql, save_pipeline_sql, and delete_pipeline. It further clarifies that it creates a pipeline and returns IDs, reinforcing the creation role.

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 on how to use the tool: it explains that source_id and knowledge_base_id identify where the pipeline writes, and knowledge_cluster_id supplies reasoning context. It also states the returned IDs are 'needed to save SQL,' implying this tool should be used before saving SQL. However, it does not explicitly list when not to use it 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?

No annotations are provided, so the description carries the full burden. It only says 'Create' and gives parameter configuration details, but does not disclose behavioral traits such as whether the connection is validated, any side effects, required permissions, or idempotency. The config comparison to Snowflake is more about parameters than 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 concise and front-loaded with the purpose, followed by a necessary example and a brief contrast to Snowflake. It is efficient and easy to scan, though the example adds a bit of 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 no annotations and a relatively simple creation tool, the description provides useful context for the URL and schema, but lacks other important context like prerequisites, error behavior, or what happens after creation. The presence of an output schema reduces the need to describe return values, but the overall context is not fully complete.

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

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

Schema description coverage is 0%, so the description must compensate. It explains connection_url with an example and clarifies that schema is part of the Postgres configuration, but it does not add meaning for name, username, password, or description. Partial compensation only.

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

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

The description clearly states the action ('Create a new Postgres source connection') with a specific resource and differentiates from the Snowflake variant by mentioning config differences. It is a specific verb+resource+scope.

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 for when to use this tool (for Postgres sources) and contrasts it with Snowflake ('no account or warehouse'), implying the alternative create_snowflake_source. However, it does not explicitly state exclusions or when not to use 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?

With no annotations, the description carries the full burden. It discloses a significant behavioral trait: only 'oauth' is confirmed against the live API, and failure on this field is likely. This adds valuable context beyond the schema, though other aspects like idempotency are not addressed.

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 sentences, with the purpose front-loaded and the caveat succinctly placed. Every sentence adds value and there is no filler.

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

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

The tool has 9 parameters and an output schema, but the description provides minimal context beyond purpose and the authentication caveat. It does not explain required parameter relationships or prerequisites, though the output schema helps reduce the burden.

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 compensate. It explains authentication_type values and warns about reliability, which adds meaning. However, it ignores the other eight parameters, leaving them to rely on names alone.

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 'Create a new Snowflake source connection,' using a specific verb and resource. It is distinct from sibling tools like create_postgres_source and get_source, making the purpose unambiguous.

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

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

The description implies the tool is for Snowflake sources, but does not explicitly state when to use it vs alternatives like create_postgres_source. The authentication_type note provides operational guidance but not usage 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?

With no annotations, the description carries the burden of disclosing destructive behavior. It explicitly mentions the destructive flag requirement, which implies the operation is permanent and guarded. This adds meaningful context beyond the tool name alone.

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, immediately stating the action and the key prerequisite. 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 delete operation with two clearly named parameters and no output schema, the description covers the essential facts: what it does and the necessary environment setting. It could mention immediacy or side effects, but overall it is sufficiently complete for this 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?

Schema description coverage is 0% and the description does not explain either parameter. While 'golden_sql_id' and 'knowledge_base_id' are inferable from names, the description adds no explicit meaning, failing to compensate for the lack of schema documentation.

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

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

The description clearly states the action ('Delete') and the resource ('a Golden SQL example'), making the tool's purpose unambiguous. It also differentiates from siblings like add_golden_sql and list_golden_sql by the delete operation.

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

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

The description provides a clear behavioral prerequisite ('Requires BAIC_ALLOW_DESTRUCTIVE=true'), which is relevant for usage. While it doesn't explicitly contrast with alternatives, the scope is evident and no competing delete-golden-sql tool exists among 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?

The description discloses a key behavioral requirement (BAIC_ALLOW_DESTRUCTIVE=true) that goes beyond the schema, which is valuable. However, it does not mention whether deletion is irreversible, what data is affected, or any cascading consequences, leaving the full impact unclear.

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, with two short sentences that each add necessary information: the action and the required permission. There is no wasted wording, and it is well-structured for quick 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?

As a destructive tool with no annotations and no output schema, the description is too sparse. It lacks critical context such as irreversibility, what associated data is removed, or any safety net information, making it incomplete for an agent to fully assess consequences.

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 coverage, the description carries full responsibility for explaining the parameter, but it does not mention 'knowledge_cluster_id' at all. The parameter name is self-explanatory, but no additional semantic value is added.

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

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

The description clearly states a specific verb ('Delete') and a specific resource ('knowledge cluster'), which unambiguously distinguishes it from sibling tools like create_knowledge_cluster, get_knowledge_cluster, and list_knowledge_clusters.

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 offers no explicit guidance on when to use this tool versus alternatives (e.g., when not to delete, or any fallback options). It only implies usage through the tool name and description, but lacks contextual direction.

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

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

The description mentions the requirement for BAIC_ALLOW_DESTRUCTIVE=true, but provides no detail about the destructive nature, irreversibility, or side effects. With no annotations, the description carries full burden and falls short.

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, using two short sentences with no wasted words. It communicates the essential action and requirement 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 destructive tool with no annotations, output schema, or parameter explanation, the description is too sparse. It fails to convey the consequences of deletion or any additional context needed for safe 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?

The description does not mention the pipeline_id parameter at all. Schema description coverage is 0%, so the description should compensate but does not, leaving the agent without any guidance on how to specify 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 action ('Delete') and the resource ('a pipeline'), making the tool's purpose unambiguous. There is no other sibling tool that deletes pipelines, so it is adequately distinguished.

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

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

No guidance is given on when to use this tool or how it compares to alternatives. The only added context is the BAIC_ALLOW_DESTRUCTIVE=true requirement, which is a prerequisite rather than usage 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?

With no annotations, the description carries the full burden. It discloses ~15s latency and output composition, which is useful. But it does not state whether the operation is read-only, any auth requirements, failure modes, or how the agent handles ambiguous questions, leaving notable gaps.

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 focused sentences with no redundancy. It front-loads the core action and then adds concise, useful context about speed and output structure.

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

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

The description gives a good overview for a discovery tool and leverages the existing output schema (so return values are covered). However, it lacks explanation of the knowledge_cluster_id parameter and any prerequisites, making it not fully self-sufficient 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?

The description does not explicitly explain the parameters. 'Question' is implied by the context, but 'knowledge_cluster_id' is never mentioned, leaving a required parameter ambiguous. With zero schema documentation, the description fails to compensate.

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 it asks the Data Discovery agent for relevant tables and columns, and specifies the output includes tables, join relationships, and a per-table column shortlist. It distinguishes itself as a fast starting point before writing SQL, differentiating it from other table or SQL 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 says 'the best starting point before writing SQL,' giving a clear when-to-use context. However, it does not mention alternatives or when not to use it, so it lacks full exclusion 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?

No annotations are provided, so the description carries the full burden. It discloses branching behavior on outcome, the verbatim printing rule, the side effect of saving SQL when save_to_version_id is provided, the requirement to surface target_is_also_a_source conflicts, and the explicit prohibition on validating or summarising SQL. This is exceptionally transparent.

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?

Although long, the description is tightly organised with bullet points for outcome branches, bolded key directives, and front-loaded purpose. Every sentence conveys a necessary protocol detail, and there is no redundant 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?

The tool has 5 parameters, no annotations, and 0% schema description coverage, making this description the sole source of guidance. It covers all three outcome branches, the additional safety check for target_is_also_a_source, the UI selection workflow, and the save behavior. It fully prepares the agent to execute the correct workflow, making it complete for 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?

Schema description coverage is 0%, so the description must compensate. It thoroughly explains `instruction` (must be verbatim, no added hints) and `save_to_version_id` (pipeline version to save SQL). It also clarifies `session_id` usage across calls and for approve_table_selection. `pipeline_id` and `knowledge_cluster_id` are not explicitly defined but are inferable from context and the phrase 'knowledge cluster's own instructions.'

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

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

The description opens with 'Ask the Data Engineering agent to write pipeline SQL,' a clear verb+resource statement. It distinguishes from siblings like get_pipeline_sql and save_pipeline_sql by indicating this tool generates SQL through the agent, not retrieves or saves it.

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 extensive procedural guidance: when to pass save_to_version_id, how to handle each outcome, and when to call approve_table_selection. It also includes explicit 'do not' instructions (e.g., do not validate generated SQL, do not renumber the review prompt). However, it does not directly name alternative tools for comparison, so the 'vs alternatives' aspect is less 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?

With no annotations, the description carries the full burden of behavioral disclosure. It only says 'check the status' without indicating whether the operation is read-only, what status values can be returned, whether it blocks, or what errors may occur. This lack of detail fails to provide adequate transparency about the tool's 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, direct sentence that immediately conveys the action and context with no redundant or unnecessary words. It is front-loaded and to the point.

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

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

For a simple status-check tool, the description gives essential workflow context (tie to import_source_metadata) and the schema covers the parameter. However, it omits details about the response content, possible status values, and any potential errors. Given the absence of annotations and output schema, this is a minimally viable description but leaves notable gaps.

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

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

The schema has one required parameter (task_id) with 0% description coverage, and the description does not mention task_id at all. While the name 'task_id' is somewhat self-explanatory, the description does not explain that it is the identifier returned by import_source_metadata, nor does it clarify format or origin, leaving the agent to infer the relationship.

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 function: 'Check the status of a metadata import started by import_source_metadata.' This uses a specific verb ('check') and resource ('metadata import'), and explicitly ties it to a sibling tool, distinguishing it from import_source_metadata (which starts imports) and import_and_wait (which likely waits).

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 by referencing the originating tool ('started by import_source_metadata'), implying this should be used after initiating an import and specifically for status checking. It does not explicitly state when not to use it or name alternatives, but the workflow context is sufficiently clear for most cases.

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?

No annotations are provided, so the description carries the burden. It explicitly says 'Read', indicating a non-mutating operation, and adds 'with all versions' to clarify the scope. However, it does not disclose potential errors, auth requirements, or return structure beyond what the output schema may 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?

Single sentence, direct, with no filler. It communicates the operation and key detail (all versions) 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 tool has one parameter and an output schema. The description covers the core behavior (read all versions). It lacks explicit error handling or alternative guidance, but for a simple read with output schema, it is 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 schema has 0% description coverage for knowledge_base_id. The description mentions 'knowledge base' but does not explicitly define knowledge_base_id as the identifier or provide formats/source. The parameter name is self-explanatory, offering partial compensation.

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 'Read' and the resource 'instructions attached to a knowledge base', with the detail 'with all versions'. This distinguishes it from sibling tools like get_kc_instructions (knowledge cluster) and update_kb_instructions (write operation).

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

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

The description implies when to use: to read knowledge base instructions. It does not explicitly mention alternatives or exclusions, but the context is clear from the resource type. No guidance about when not to use (e.g., for clusters), but the intent is obvious.

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 no annotations provided, the description carries the full burden. It discloses an important behavior: the effective instructions may come from an older version when the active version is empty. This goes beyond the basic 'read' semantics and prevents misinterpretation of the returned content.

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

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

Two sentences, front-loaded with the primary purpose followed by a critical caveat. No redundant words or filler; every sentence adds necessary 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?

The tool is simple (one parameter) and the description covers the main caveat (active vs older version) that affects result interpretation. With an output schema present, return values are presumably structured. However, it does not address potential empty results or error handling, which reduces completeness slightly.

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 one parameter, knowledge_cluster_id, with no description (0% coverage). The description mentions 'a knowledge cluster' but does not add specific meaning to the parameter beyond what the name itself conveys. It fails to explain how to obtain the ID or any format expectations.

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

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

The description uses a specific verb ('Read') and resource ('knowledge cluster's instructions') and highlights 'with all versions' as a distinctive feature. This clearly differentiates it from siblings like get_knowledge_cluster (metadata) and get_kb_instructions (knowledge base instructions).

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 when one needs a knowledge cluster's instructions, but it does not explicitly contrast with get_kb_instructions or other alternatives, nor does it state when not to use this tool. The note about effective text provides contextual guidance but not explicit 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?

With no annotations provided, the description carries the burden of behavioral disclosure. It mentions the output contents (member knowledge bases, engines, instructions) and that the returned IDs are useful for other tools, which implies a read operation. However, it doesn't disclose potential errors, permissions, or any side effects. For a simple get-like tool, 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?

The description is concise, with two sentences and no redundant wording. It front-loads the core purpose ('KC detail') and then adds usage context. The first sentence is a fragment, but it is efficient. It earns its place without excessive detail.

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 low complexity (one parameter, no nested objects) and the presence of an output schema, the description is sufficiently complete. It states what the tool returns and provides a usage scenario. The output schema likely covers return value structure, so the description doesn't need to detail that. It reasonably supports selection and 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?

The schema has a single parameter (knowledge_cluster_id) with no description, and schema description coverage is 0%. The description doesn't explain the input parameter directly, but it does mention knowledge_base_ids in the output, implying the purpose of the cluster ID. It partially compensates for the lack of schema detail by contextualizing the result, but falls short of fully explaining the parameter 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?

The description clearly indicates this tool retrieves details of a knowledge cluster, specifically its member knowledge bases, their engines, and the KC instructions. This differentiates it from siblings like get_kc_instructions, which focuses narrowly on instructions, and list_knowledge_clusters, which lists clusters. The use of 'KC detail' is telegraphic but contextually clear, and the tool name reinforces its 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 second sentence gives explicit usage guidance: fetch this before asking questions if you want to inspect context, since knowledge_base_ids are needed by agent tools. This tells the agent when to use the tool (as a prerequisite) and why, even though it doesn't name specific alternatives or 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?

With no annotations provided, the description carries the burden of disclosing behavioral traits. It states the default behavior of using the active version when version_id is null, which is useful. However, it does not mention error handling, permissions, or other side effects, but for a read operation this is adequate.

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 two sentences containing only essential information. Every word earns its place, and it avoids redundancy with the schema.

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

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

Given the tool is a simple read operation with an output schema available, the description is sufficiently complete. It explains what is read and the default version behavior, which covers the main contextual needs. It does not over-explain, relying on the output schema for return 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 schema has 0% description coverage, so the description must compensate. It adds meaning for version_id by explaining the default behavior, and pipeline_id is implied as the pipeline identifier. However, it does not explicitly name or describe the parameters, leaving some ambiguity about their exact roles.

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 'Read[s] a pipeline's saved SQL and visual pipeline graph', using a specific verb and resource. It differentiates from siblings like save_pipeline_sql (write) and generate_pipeline_sql (create) by focusing on reading the saved artifacts.

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

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

The description implies usage by indicating it reads the saved SQL and graph, but does not explicitly state when to use this tool versus alternatives like generate_pipeline_sql or list_pipelines. The 'Defaults to the active version' note provides some context, but no explicit when/when-not or alternative guidance is 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?

The description discloses that connection config is included with secrets masked, which is a useful behavioral trait. However, with no annotations, it falls short of disclosing other behaviors such as error handling, permission requirements, or whether it returns only the current 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?

The description is a single concise sentence that front-loads the essential information and includes a useful caveat about secrets masking. 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?

Given the tool's simplicity (one parameter, output schema provided), the description is mostly sufficient: it states the tool retrieves full details and masks secrets. It could be improved by noting that source IDs are obtained from list_sources, but this is not a major 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?

The schema shows a single source_id string parameter, but the description does not explain how to obtain a valid source_id or its exact format. Schema descriptions are absent, and the description's mention of 'one source' only implicitly refers to 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 'Full detail for one source' clearly indicates this retrieves a single source's details, and the clarification 'including its connection config (secrets masked)' adds specificity. It distinguishes from list_sources by focusing on a single source, though it does not explicitly name the alternative.

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

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

No guidance is provided on when to use this tool versus list_sources or other source-related tools. The description simply states what the tool does without mentioning prerequisites 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?

With no annotations, the description carries the full burden and excels. It discloses batching behavior, page_size defaults depending on include_profiles (25 vs 200) with the reason (5 KB per profile, client rejects bigger pages), pagination via has_more and page, and that only one page is fetched per call. It also explains that an empty columns list is a normal state, not an error, and explicitly warns against misinterpreting it as a signal about generated SQL.

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 long but every sentence contributes essential operational detail. It is front-loaded with purpose, then moves through batching, paging, page_size logic, empty-columns semantics, and finally usage boundaries. No sentence is redundant or filler; the structure is logical and easy to navigate.

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 and the presence of an output schema, the description covers all major behavioral aspects: batching, pagination, size trade-offs, and common error conditions (empty columns). It also addresses the critical misuse case (validation of generated SQL). The only missing piece is knowledge_base_id semantics, but overall it is thorough enough for an agent to use it correctly in most scenarios.

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

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

Schema description coverage is 0%, so the description must compensate. It explains table_names (pass several table names), include_profiles (adds large profiling stats and affects page_size), page (pagination continuation), and page_size (defaults based on include_profiles). However, knowledge_base_id, a required parameter, is never mentioned or described, leaving a significant gap in understanding how to invoke the tool.

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

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

The description opens with a specific statement: 'Table descriptions and column-level detail for one or more tables.' This clearly identifies the verb (get details), resource (tables), and scope (one or more). It also distinguishes from siblings by stating it is 'for exploring a schema' and explicitly not for validation of generated SQL, a clear contrast with tools like generate_pipeline_sql and get_pipeline_sql.

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 clear usage context: 'This tool is for exploring a schema' and an explicit when-not: 'It is not a validation step for generated SQL; do not call it to check SQL before saving a pipeline.' It also provides guidance on batching and include_profiles. However, it does not name alternative tools to use for validation or other schema exploration tasks, so it stops short of a full 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?

With no annotations, the description carries the full burden of behavioral transparency. It states the tool returns discovered foreign-key relationships, implying a read-only operation, but it does not disclose whether the discovery involves computation, caching, or any side effects. No details about result limits or behavior are 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 a single short sentence with no filler or redundant information. It gets straight to the point and is easy to read.

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

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

The tool is low-complexity with one parameter and no output schema, but the description is still quite minimal. It does not explain the structure of the response, whether the relationships are exhaustive, or what 'discovered' means operationally. For a simple getter, this is borderline sufficient, but it leaves some contextual gaps.

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

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

The schema has one required parameter, knowledge_base_id, with no description (0% schema coverage). The description only mentions 'in a knowledge base,' which weakly ties the parameter to its role but does not explain its format, uniqueness, or how to obtain its value. This adds minimal semantic value beyond the parameter 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 clearly states that the tool provides discovered foreign-key style relationships between tables within a knowledge base. This distinguishes it from sibling tools like get_table_details or list_kb_tables, which focus on individual tables. However, the phrase 'Discovered' is a past-participle and lacks an imperative verb, making it slightly less direct than an explicit 'Get' or 'List'.

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 usage guidance is provided. The description does not mention when to use this tool versus alternatives, nor does it specify prerequisites or typical scenarios. There are no exclusions or alternative tool references.

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 no annotations, the description carries the full burden and does so well. It discloses blocking behavior (waits for completion), timeout semantics (continues server-side after timeout_s), return values (knowledge_base_id and final status), and a side effect (writes embeddings into destination_id), plus a caution about ownership.

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

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

The description is compact, front-loaded with the core purpose, and each of the three short paragraphs adds new information without redundancy.

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

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

The description covers the tool's behavior, timeout, side effects, and ownership, and the output schema presumably documents return values. However, the lack of parameter semantics for key required fields leaves the description incomplete for confident tool 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?

Only timeout_s and destination_id are given explicit meaning in the description. Other required parameters such as name, source_schema, and table_names are not described, and with 0% schema description coverage the agent has insufficient guidance for correct invocation.

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 it imports a source's metadata into a knowledge base and waits for it to finish. It explicitly identifies itself as a convenience wrapper over import_source_metadata + get_ingestion_task, distinguishing it from those 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?

The description explicitly names the underlying tools and explains this is a convenience wrapper, providing an alternative to using them separately. It also advises using a destination you own and mentions polling get_ingestion_task if the import continues after timeout, guiding when to use this tool vs the lower-level APIs.

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 no annotations, the description carries the full burden. It discloses that the tool is asynchronous, returns task_id and knowledge_base_id, writes embeddings into the destination, and requires an owned destination. This adds meaningful behavioral context beyond the schema fields.

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

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

The description is three concise sentences, front-loaded with the main purpose, followed by essential async details. Every sentence adds value with no redundancy or filler.

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

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

The description covers the async workflow and destination ownership, but with eight parameters and no schema descriptions, it leaves important gaps (e.g., what source_schema expects, what table_names should contain, how profiling_enabled/auto_generate_dictionary affect behavior). An output schema exists, so return values are covered, but parameter-level guidance is incomplete.

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

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

Schema description coverage is 0%, so the description must compensate. It only explains destination_id in detail ('get one from list_destinations', 'writes embeddings'). Other required parameters like source_schema and table_names are not described, leaving the agent to infer their meaning from names alone.

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

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

The description clearly states the action: 'Crawl a source's metadata into a new knowledge base.' It identifies the resource (source metadata), the target (new knowledge base), and distinguishes this from sibling tools by highlighting its asynchronous nature and return of task_id and knowledge_base_id.

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 provides concrete usage guidance: explains the asynchronous workflow, tells the agent to poll with get_ingestion_task, requires destination_id from list_destinations, and warns to choose a destination the agent owns. It does not explicitly name alternatives like import_and_wait, but the 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?

With no annotations, the description carries the full burden. It discloses that this is a pre-import operation ('before importing any of them'), implying no side effects. It doesn't detail return format or error behavior, but the output schema exists and the read-only nature is clear from 'List'.

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 sentences, front-loaded with the action verb, and contains no filler. Every word 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 simplicity of the tool (2 params, output schema present), the description covers the core purpose and usage context sufficiently. It lacks mentions of prerequisites like source existence, but the overall import workflow context is clear from 'Import Source table picker'.

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 mention source_id or source_schema by name or explain their meaning. 'source' is referenced generically, but source_schema is entirely omitted, leaving the agent guessing about that parameter's role.

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 resource ('tables a source exposes') and clarifies the temporal scope ('before importing any of them'). It distinguishes itself from sibling tools like list_sources (which lists sources) and discover_tables by positioning as the 'Import Source table picker'.

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 it: 'use it to choose what to ingest', and calls it the 'Import Source table picker'. It gives clear context for the import workflow, though it does not explicitly mention alternatives or exclusions, so it falls short of 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?

No annotations are provided, so the description carries the burden of behavioral disclosure. It clearly reveals that there is no server endpoint and the list is fixed in the frontend, which informs the agent that this operation is static and likely non-hazardous. This adds meaningful context beyond the empty schema, though it does not describe return structure (covered by output schema).

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

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

The description is two short sentences, front-loaded with the core purpose and followed by a clarifying note. Every word earns its place; no filler or repetition. It is an excellent model of concise tool documentation.

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, parameterless tool with an output schema, the description fully explains the unique behavior (static list, no server call). It is complete and sufficient for an agent to know what to expect. The siblings are numerous but the description clearly distinguishes this as a fixed enumeration 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?

The tool accepts zero parameters, and the schema coverage is 100% (empty schema). Per the baseline for zero parameters, the description need not compensate for missing parameter documentation. The description adds no parameter details, which is appropriate given there are none.

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 resource: "The connector engines this platform supports." It distinguishes the tool from siblings like list_sources and list_destinations by focusing on engine types. Though it lacks an explicit verb like "list", the tool name and noun phrase make the purpose unambiguous.

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

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

The description implies usage context by noting this is a static, frontend-fixed list with no server endpoint. However, it does not explicitly contrast with alternative tools or state when to choose this over list_sources or list_destinations. The guidance is implied rather than 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?

No annotations are provided, so the description must carry the behavioral transparency burden. It discloses pagination behavior ('read has_more and total, pass page=1, page=2...'), which is useful. However, it does not explicitly state that the operation is read-only or mention any other behavioral aspects like permissions or rate limits.

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

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

The description is three sentences: the first states the purpose, the second gives a use case, and the third explains pagination. Every sentence adds value, with no waste 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?

The tool is simple (2 optional parameters) and an output schema exists, so the description doesn't need to describe return values. It covers purpose, use case, and pagination adequately. While it doesn't mention error handling, that is less critical for a straightforward list operation.

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

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

The schema has 0% description coverage, so the description compensates by explaining the pagination pattern. It clarifies that 'page' is used to continue through pages and mentions reading 'has_more' and 'total', giving meaning beyond the bare integer parameters in 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 function with a specific verb and resource: 'List destinations'. It further defines what destinations are ('vector stores or warehouses that ingestion writes into'), which distinguishes it from sibling tools like list_sources and list_knowledge_bases.

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 an explicit use case: 'Needed to pick a destination_id for import_source_metadata.' This tells the agent when to use the tool. It also provides pagination instructions, though it does not explicitly mention when not to use it or name alternative tools.

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

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

With no annotations, the description carries the full burden. It discloses the pagination behavior and the read-only nature of the operation. It doesn't mention any side effects or permissions, but for a list tool this is acceptable. The pagination details add meaningful 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 two sentences, front-loaded with the core purpose, and the pagination guidance is concise. Every sentence earns its place with 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?

For a list tool with an output schema, the description covers the primary purpose and the non-obvious pagination behavior. It doesn't explain response fields, but the output schema covers that. It lacks a note about default page behavior, but overall it's complete enough for a simple listing 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%, so the description must compensate. It explains the 'page' parameter usage via pagination instructions, but doesn't explain 'page_size' or the exact meaning/format of 'knowledge_base_id'. Partial compensation, but not complete.

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' with a clear resource 'Golden SQL examples' and scope 'attached to a knowledge base'. This clearly distinguishes it from sibling tools like add_golden_sql and delete_golden_sql.

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 pagination usage instructions (read has_more/total, pass page=1,2,...). It doesn't explicitly name alternatives or when-not-to-use, but the list operation's purpose is self-evident in 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?

With no annotations, the description carries the full transparency burden. It discloses the paged nature of the response and instructs reading has_more/total and incrementing page, but does not mention permissions, error behavior, or other side effects. The read-only nature is only implied by the verb 'list'.

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

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

The description is only two sentences, with no filler. The first sentence states the core purpose, and the second concisely explains the pagination contract.

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

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

The tool is a simple list operation with an output schema. The description provides the essential purpose and pagination behavior, which is sufficient given the schema handles parameter details. It does not over-explain but could be slightly more complete by noting that knowledge_base_id is required, though the schema already marks it required.

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 compensate. It explains the page parameter's role in pagination, but leaves page_size and knowledge_base_id without explicit descriptions beyond their names. The pagination mechanism adds value for page and implicitly for has_more/total.

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 the tool 'List the tables inside a knowledge base' with a specific verb and resource, clearly distinguishing it from siblings like list_knowledge_bases and list_available_tables.

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 used to enumerate tables within a specific knowledge base, but provides no explicit comparison to alternatives like list_available_tables or discover_tables. The pagination guidance gives a how-to but not a when-to.

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 no annotations provided, the description carries full responsibility for behavioral disclosure. It goes beyond a basic listing by explaining pagination mechanics ('Read total and has_more, then pass page=1, page=2'), the page_size cap ('capped at 500'), the risk of breaking the 1 MB response limit, and the meaning of status SUCCESS. This provides rich contextual behavior beyond what annotations would typically convey.

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

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

The description is front-loaded with the core purpose and then expands into pagination details, limits, and usage recommendations. Each sentence contributes critical operational information, and the paragraph break improves readability. Although it is longer than a simple one-liner, the extra length is warranted by the paging complexity and does not contain 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?

Given the tool's paging complexity and the presence of an output schema, the description is highly complete. It covers the use case, pagination walk-through, page_size cap, response limit risk, and status field semantics. It does not need to describe return values because an output schema is provided. For a two-parameter paged list endpoint, this description leaves no major gaps.

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

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

The input schema has 0% description coverage, so the description must add meaning to the parameters. It explains that page is used for pagination ('pass page=1, page=2, ...') and that page_size has a cap ('page_size is capped at 500 - asking for more does not return more'). While this adds significant value, the default page=0 (from the schema) is not reconciled with the 'page=1, page=2' guidance, leaving slight ambiguity about the starting index.

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

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

The description opens with 'List knowledge bases (KBs) - the metadata imported via Data Ingestion, one page at a time,' which clearly identifies the action and resource. It also explains that each row links a KB to its source, differentiating it from sibling tools like list_sources and list_kb_tables. This is a specific verb+resource with clear distinction 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 explicitly states when to use the tool: 'use this to go from a source name to a knowledge_base_id.' It also provides usage guidance on pagination and recommends paging to find a specific KB rather than pulling everything at once. However, it does not explicitly mention alternative tools for scenarios where this tool should not be used, so it lacks explicit when-not-to-use 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It adds value by revealing pagination behavior: the response includes `has_more` and `total`, and the `page` parameter is used to iterate. This goes beyond the schema. However, it does not disclose potential edge cases (e.g., page indexing default of 0 vs. the description suggesting 1-based pagination), which is a minor gap.

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: the first sentence states the purpose, and the second provides essential pagination guidance. Every sentence adds value with no redundancy or filler. It is appropriately sized for a simple list 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?

For a simple list operation, the description is quite complete: it defines the resource, gives pagination details, and references the response fields (`has_more`, `total`). An output schema exists, so detailing return values is unnecessary. However, the inconsistency between the default `page=0` and the described `page=1` page numbering could confuse an agent, preventing a perfect score.

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 schema provides only names, defaults, and types for `page` and `page_size` with 0% description coverage. The description adds semantics for the `page` parameter by showing how to use it in pagination ('pass page=1, page=2, ...'), but it does not explain `page_size` or its relationship to pagination. The explanation partially compensates for the schema gap, but is incomplete for both parameters.

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

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

The description clearly states the tool's function with a specific verb and resource: 'List knowledge clusters (KCs)'. It also explains what KCs are ('the groupings of knowledge bases used by the agents'), which distinguishes it from the sibling tools like list_knowledge_bases (lists bases, not clusters) and get_knowledge_cluster (fetches a single cluster). This 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 provides clear context on when to use this tool (when you need a list of knowledge clusters) and includes practical pagination instructions ('pass page=1, page=2, ... to continue'). It does not explicitly mention alternatives or when not to use it, but the context and purpose are clear enough for an agent to select this tool appropriately.

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?

It discloses pagination behavior by instructing the agent to read has_more and total and pass page numbers, which is valuable behavioral context. No annotations are provided, so this detail helps, though it could mention more about authentication or response format.

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 succinct sentences, front-loading the core purpose and then adding the pagination detail. Every word earns its place, with 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?

Given the presence of an output schema, return values are covered. The description adds filter and pagination details, making it fairly complete for a list tool. It lacks explicit mention of ordering or potential edge cases, but is adequate for the tool's simplicity.

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

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

The description explains knowledge_cluster_id as an optional filter and hints at the page parameter syntax, but it does not explain page_size or the default page=0, and there's a slight inconsistency with examples using page=1. With 0% schema coverage, the description partially compensates but not fully.

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 'List data pipelines' with an optional filter by knowledge cluster, using a specific verb and resource. This distinguishes it from sibling tools like list_sources and list_destinations.

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

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

The description implies when to use this tool (when you need to list pipelines) and provides a specific use case with the optional cluster filter. However, it does not explicitly name alternatives or state when not to use 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?

With no annotations, the description fully discloses paging behavior (has_more/total, page increments), page_size cap (500), and return fields (source_id, name, engine type, account/database/schema). It also notes the default for source_type and the meaning of empty string.

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

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

Three concise paragraphs each serve a distinct purpose: overview, source_type parameter, and paging mechanics. No filler, clear organization, and front-loaded 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 an output schema exists, the description does not need to detail return values. It covers paging, parameter semantics, and the key decision of which sources can share a knowledge cluster. The page_size cap warning is valuable contextual 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 has no parameter descriptions (0% coverage). The description compensates by explaining source_type values and default, page usage for continuation, and page_size cap. This adds essential meaning beyond the raw 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 states a specific action with a resource: 'List configured data sources (source connections)'. It clearly distinguishes from siblings like get_source (single source) and create_* tools, and clarifies one-page-at-a-time semantics.

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 clear context for use: helps identify which sources can share a knowledge cluster, and warns not to assume one page is all. However, it does not explicitly name alternative tools or when-not-to-use scenarios.

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 no annotations provided, the description fully carries the behavioral disclosure burden. It discloses that this is a plain write, that the SQL is already validated, that the return is a compact receipt deliberately excluding the SQL body, and that passing only sql leaves the graph untouched. This goes beyond minimal disclosure and is highly transparent.

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 a clear purpose, a bullet list of negative instructions, and a section on return behavior. Each sentence adds value, and the formatting makes the critical warnings and usage guidance easy to parse.

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

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

Given the tool's complexity (write-only, partial update, integration with approve_table_selection), the description is complete. It covers the input source, the exact behavior, the return receipt, and the stop-after-confirm instruction. The presence of an output schema means return details need not be fully expounded, and the description still mentions the receipt contents.

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 adds meaning for sql and graph by specifying they come from approve_table_selection and must be passed byte-for-byte, and it explains partial update semantics. However, pipeline_id and version_id are not explicitly described, though their meaning is inferable from context.

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 saves SQL and/or the visual pipeline graph onto a pipeline version, a specific verb+resource combination. It distinguishes from siblings like get_pipeline_sql and generate_pipeline_sql by emphasizing the write-only nature and the 'save' action.

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 when-to-use guidance: it says to use get_pipeline_sql only if the SQL itself is genuinely needed later, and it lists explicit "do NOT" actions to avoid before/after the save. It also clarifies the partial update behavior, giving complete usage 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?

There are no annotations, so the description carries the burden of disclosing behavior. It does disclose the key behavior that this overwrite replaces rather than appends, which is useful. However, it does not mention irreversibility, permission requirements, or any side effects on active instructions, which would be important for a mutation 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 two short, direct sentences that front-load the primary action and resource. Every word earns its place, and it avoids repetition of schema details.

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 only two parameters and an output schema, the description covers the core purpose and the key behavioral nuance (replace vs. append). However, it lacks guidance on prerequisites, reversibility, or relationship to sibling tools, leaving some context gaps for a mutation operation.

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

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

Schema description coverage is 0%, and the description does not add meaning to the parameters beyond what the input schema already shows. The parameter names 'knowledge_base_id' and 'instructions' are self-explanatory, but no formats, examples, or constraints are given.

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 the specific verb 'Overwrite' and identifies the resource as 'the active instructions on a knowledge base.' It also explicitly notes the behavior 'Replaces, does not append,' which distinguishes it from append-style tools and makes the purpose unambiguous relative to 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 implies the tool should be used when one needs to replace knowledge base instructions, but it provides no explicit when-to-use or when-not-to-use guidance and does not mention alternatives such as get_kb_instructions or update_kc_instructions.

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 no annotations provided, the description carries the burden and explicitly discloses the destructive/replacing behavior ('Replaces, does not append') and the observable effect ('Verified to change the output'). This is strong behavioral disclosure, though it omits permission requirements or error scenarios.

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 tight sentences in the first paragraph state the purpose and key behavioral distinction; the second paragraph adds valuable domain context. No filler or repetition, making it highly efficient.

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

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

For a simple two-parameter update tool, the description covers what is overwritten, that it replaces rather than appends, and why it matters. Since an output schema exists, return value details are not required. A mention of idempotency or prerequisites would round it out, but the current content is largely 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%, but the description adds meaning to 'instructions' by explaining they control SQL generation (grain, dedup keys, etc.), which goes beyond the bare field name. However, it provides no additional detail about the format or constraints of either parameter, and knowledge_cluster_id is only implicitly identified.

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 ('Overwrite') and resource ('knowledge cluster's active instructions'), and clearly states 'Replaces, does not append' to distinguish from append-style updates. It differentiates from sibling tools like update_kb_instructions by targeting a knowledge cluster rather than a knowledge base.

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 clear context for when to use: it is 'high leverage' and steers the SQL generated by the Data Engineering agent, with concrete impact areas (grain, dedup keys, null handling, dialect, idempotency). It does not explicitly name alternatives or exclusions, but the context strongly implies its purpose.

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 no annotations, the description carries the burden of disclosure. It explains the tool's behavior (connectivity check, reveals environment/tenant/user) and adds context about the backend_url identifying the deployment. It does not mention side effects, but none are expected for a whoami-style 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 two sentences, front-loaded with the core purpose, followed by actionable guidance. Every sentence adds value, 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 tool has no parameters, an output schema exists, and the description covers purpose and usage context, it is complete for an agent to correctly select and invoke this tool. The environment-specific warning adds essential operational context.

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 has zero parameters, so the description is not required to explain parameter details. A baseline of 4 is appropriate because there is nothing to clarify beyond 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?

The description clearly states the tool's purpose with specific verbs ('Confirm', 'show') and resources ('connectivity', 'environment, tenant, and user'). This distinguishes it from all sibling tools, which focus on data operations, making the purpose unmistakable.

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 instructs 'Call this first in a session' and provides a strong rationale (everything is environment-specific, never assume deployment). This gives clear when-to-use guidance, and no alternatives are needed since the tool is uniquely foundational.

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