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

No annotations provided, so description must carry full burden. It discloses async operation and return type (job_id, TablePlanApplied). However, it does not cover permissions, side effects (e.g., table creation is irreversible), or error conditions for invalid plans. Adequate but incomplete.

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

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

Well-structured: summary, usage context, parameter list, return info. Front-loaded with key details. Parameter list is a bit lengthy but each line is functional. No unnecessary 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?

Covers purpose, usage context, parameter meanings, async nature, and return type. However, lacks examples, error handling, prerequisites (e.g., valid plan), and deeper explanation of parameter interactions. Adequate for a moderate-complexity tool but not comprehensive.

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

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

Schema description coverage is 0%, so description's parameter explanations are essential. Each of the 6 parameters (plan, debug, args, priority, verbose, client_timeout) gets a brief description. While some are vague (e.g., 'Additional arguments for plan application'), overall it compensates well for missing schema descriptions.

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

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

Description clearly states 'Apply a provided table creation plan to resolve schema conflicts and create a new table,' specifying the action, resource, and purpose. It distinguishes from siblings like 'create_table' and 'plan_table_creation' by focusing on applying an existing plan with conflict resolution.

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

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

Explicitly states when to use: 'when schema conflicts exist after plan creation and need manual resolution' and notes automatic handling when no conflicts. Provides a concrete example of a common conflict (two parquet files with same column but different datatype). Lacks explicit alternatives 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?

No annotations provided, so description carries full burden. Describes mutation (cancel) and return of updated status, but lacks details on failure modes, immediacy, or idempotency.

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?

Extremely concise: two sentences plus args/returns. 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?

Adequate for a simple single-parameter tool with output schema; could mention error handling for invalid or non-running jobs.

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

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

Only one parameter with schema description coverage 0%; description adds minimal meaning ('The ID of the job to cancel'), which is basic but useful.

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 cancels a running job using job_id, distinguishing it from siblings like get_job or list_jobs.

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?

Mentions 'running job' implying the job must be in a running state; no explicit guidance on when not to use, but 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?

No annotations provided, so description carries burden. Discloses constraints (must contain bauplan_project.yml and .sql/.py files) and return characteristics (job ID suggesting asynchrony). Does not mention side effects, permissions, or failure 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?

Description is concise, well-structured with a brief intro and clear Args/Returns sections. Front-loaded with purpose, no wasted words.

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

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

Covers key aspects: inputs, constraints, output as RunState. Given moderate complexity and presence of output schema, missing edge case behavior (e.g., missing required files) but overall sufficient.

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

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

Schema description coverage is 0%, but description fully compensates with detailed explanations for all three parameters: project_files (dictionary, required files), ref (branch name), parameters (templating, simple types, default). Adds constraints and purpose beyond schema types.

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

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

The description clearly states the tool runs a pipeline from source code files, specifying verb 'Run' and resource 'pipeline from source code files'. It distinguishes from siblings like 'project_run' but does not explicitly differentiate.

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

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

No guidance on when to use this tool versus alternatives like 'project_run' or 'run_query'. Description lacks context for selection without explicit exclusions.

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

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

With no annotations provided, the description should fully disclose behaviors. It mentions creation and confirmation but does not address error handling (e.g., what happens if branch already exists or from_ref is invalid), idempotency, permissions, or side effects. The format constraints for parameters are helpful but insufficient.

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

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

The description is concise, with a clear opening sentence and structured Args/Returns sections. Every sentence adds value, and there is no redundant information.

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

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

Given the tool's complexity (2 required parameters, output schema), the description covers parameter formats and return type. However, it lacks usage context (e.g., when to use vs. other tools) and behavioral details (e.g., idempotency, failure modes), which limits completeness for an AI 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 coverage is 0%, so the description must provide parameter meaning. It does so: 'branch' must follow format <username.branch_name>, and 'from_ref' can be a branch name or hash starting with '@' with 64 characters. This adds significant value 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 clearly states the tool creates a new branch in the Bauplan data catalog, specifies the branch name format <username.branch_name>, and returns a confirmation. This is specific and distinguishes it from sibling tools like create_table or create_namespace.

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

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

The description explains what the tool does but does not explicitly mention when to use it vs alternatives, nor does it provide prerequisites or conditions (e.g., when to create a new branch vs. using an existing one). Usage is implied through the parameter description.

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 provided, so the description must carry full burden. It mentions returning a success/failure object but does not explain behavior on duplicate namespaces, error conditions, or idempotency. Minimal useful behavioral details.

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

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

The description is structured with a brief summary and then Args/Returns. It is fairly concise, though the Args section could be more compact for only two parameters.

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 creation tool with an output schema, the description covers the basic return object but misses edge cases like namespace already existing or branch missing. Adequate but not 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 coverage is 0%, but the description adds valuable constraints: branch must follow '<username.branch_name>' format. However, it lacks details on namespace characters or lengths.

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 'Create' and resource 'namespace' with context 'in a specified branch', distinguishing it clearly from siblings like delete_namespace or get_namespaces.

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

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

No explicit guidance on when to use this tool versus alternatives, such as when a namespace already exists or prerequisites like branch existence. Usage is only implied by the action.

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?

Without annotations, the description carries the full burden. It discloses that the table is ICEBERG and not populated, and that it returns a TableCreated object. However, it omits details on error behavior (e.g., if table exists without replace flag) and does not mention permissions or side effects, leaving 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?

The description is front-loaded with a clear one-sentence summary, followed by a structured parameter list and a crucial note about not populating the table. It is concise (78 words) and well-organized, with no unnecessary 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?

Given the tool's complexity (6 parameters) and missing annotations, the description covers the basic purpose and parameter meanings, and references the output. However, it lacks details on the 'replace' behavior (e.g., success vs error when table exists) and does not mention relationships to sibling tools, leaving uncertainty for complex use.

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, but the tool description includes a parameter list with brief explanations (e.g., 'table: Name of the table to create', 'partitioned_by: Optional partitioning column'). This adds significant meaning beyond the raw schema, though some parameters like 'namespace' lack detail on defaults beyond the schema.

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

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

The description clearly states the tool creates an empty table from an S3 URI, specifying supported file types (parquet, csv, JSONL) and automatic schema inference. However, it does not differentiate from sibling tools like plan_table_creation or apply_table_creation_plan, which limits clarity about when to use this tool directly.

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

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

The description provides no guidance on when to use this tool versus alternatives (e.g., plan_table_creation). It does not mention prerequisites, exclusions, or typical use cases, leaving the agent to infer usage context without explicit 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?

No annotations are provided, and the description does not disclose behavioral traits such as idempotency, uniqueness constraints, error conditions, or side effects beyond creation. The return type is mentioned, but not enough context for safe invocation.

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

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

The description is fairly concise but has redundancy: the purpose is restated in the first paragraph and again in the docstring. The structure with Args/Returns is clear but could be more compact.

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 two required parameters and no annotations, the description is adequate but incomplete. Missing details on behavior when tag exists, how branches affect tagging, and error handling. The output schema exists but its content is not visible.

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

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

With 0% schema description coverage, the description partially compensates by listing args 'tag' and 'from_ref' with minimal explanations. However, it lacks constraints, formats, or examples, leaving room for ambiguity.

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

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

The description clearly states the action ('Create a new tag') and the resource ('in a specified branch of the user's Bauplan data catalog'). It distinguishes from sibling tools like delete_tag, get_tags, etc.

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

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

No guidance on when to use this tool versus alternatives. The description lacks prerequisites, when-not-to-use scenarios, or references to other tools.

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

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

Annotations are not provided, so the description carries the full burden. It discloses the return type (success/failure) but does not mention irreversible effects, prerequisites, or error handling, making it 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 very concise, with no unnecessary words. It front-loads the main purpose and includes an Args/Returns structure that is clear and easy to scan.

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 low complexity (one parameter) and the presence of an output schema, the description covers the core aspects: purpose, parameter format, and return type. It could mention permissions or preconditions but is largely complete.

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

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

The description adds a formatting constraint (<username.branch_name>) to the single required parameter, which is not present in the input schema (0% schema description coverage). This adds meaningful value beyond the schema.

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

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

The description clearly states the verb 'delete' and the resource 'branch', and distinguishes it from sibling tools like create_branch, merge_branch, and get_branches.

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 formatting requirement for the branch parameter, offering clear context. However, it does not explicitly state when to use this tool versus alternatives, nor does it exclude any use 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?

With no annotations, the description should disclose behavioral details like destructiveness, reversibility, or authorization needs. It only says 'Delete a namespace' without further context, leaving significant 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?

The description is somewhat repetitive (first paragraph restated in the second). It includes useful Args and Returns sections but could be more streamlined.

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, the description explains the operation and parameters fairly well, but lacks details on error conditions, prerequisites, or side effects, making it incomplete for a destructive action.

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

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

Despite schema coverage reported as 0%, the description includes an Args section that explains each parameter and provides a format constraint for the branch parameter (<username.branch_name>), adding value beyond the schema.

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

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

The description clearly states it deletes a namespace from a branch in the Bauplan data catalog. It specifies the resource and action, but does not explicitly differentiate from sibling delete tools like delete_branch or delete_table.

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

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

The description provides no guidance on when to use this tool versus alternatives, nor does it mention prerequisites or exclusions. The agent must infer from the tool name alone.

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

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

No annotations exist, so the description must convey behavioral traits. It only states 'Delete' (destructive), but lacks details such as irreversibility, permission requirements, potential cascading effects, or what the TableDeleted return object contains (though output schema exists).

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

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

The description has a clear structure (purpose, args, returns), but the first two sentences are repetitive ('Delete a specified table...' and 'Delete a table...'). Could be trimmed to one sentence.

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 2 required parameters and output schema, the description is borderline adequate. It lacks context about the destructive nature, comparison to sibling tools (e.g., delete_branch, revert_table), and any usage prerequisites, leaving gaps 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?

With 0% schema description coverage, the baseline is 4, but the description adds minimal semantic value: 'table' is described as 'Name of the table to delete' and 'branch' with a format constraint. It does not explain the role of 'branch' or how to obtain a valid branch 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 identifies the action ('delete') and resource ('table'), and the context signals show sibling tools like delete_branch and delete_namespace, so this tool is distinct. However, the first two sentences are redundant, slightly reducing clarity.

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

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

No guidance on when to use this tool versus alternatives (e.g., revert_table, delete_branch). No mention of prerequisites or implications, leaving the agent without decision support.

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 should fully disclose behavior. It only mentions returning a success/failure object, but does not address side effects, permanence, or conditions for failure.

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

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

The description is concise and structured with Args/Returns, every sentence adds value, though it could be more informative.

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?

Missing important context like error handling, what happens if tag doesn't exist, and whether deletion is irreversible, leaving gaps for an AI 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%, and the description only adds that 'tag' is a name, without constraints, format, or examples.

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 'Delete' and the resource 'tag', distinguishing it from sibling tools like 'create_tag' and 'has_tag'.

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

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

No guidance on when to use this tool versus alternatives, or prerequisites like the tag must exist before deletion.

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

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

Discloses that the response can be large and that limit should be used. No annotations exist, so the description carries full burden. It does not mention permissions, scope, or side effects. For a read-only tool, this is acceptable but could be more explicit about 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, front-loaded with purpose and critical note, and structured with clear Args and Returns sections. Every sentence adds value without redundancy.

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

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

Covers purpose, parameters, and return type (BranchesOut with names and hashes). Given the tool's simplicity and the presence of an output schema, the description is mostly complete. Lacks details on error handling or ordering, but these are not critical for a basic list 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 that 'name' is a substring match, 'user' filters by user, and 'limit' is a maximum with default 10. This adds significant meaning beyond the schema's type definitions.

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

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

Clearly states 'Retrieve branches from the user's Bauplan data catalog as a list', specifying the resource (branches) and action (retrieve/list). Distinguishes from siblings like create_branch and delete_branch by being a read 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?

Provides a strong usage guideline: 'NOTE: This can return a large response. Always use limit parameter.' This advises on when to use and how to avoid issues. However, it does not explicitly mention alternative tools (e.g., has_branch) or when not to use.

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

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

No annotations are provided, so the description carries full responsibility for behavioral disclosure. It mentions the return type but does not declare side effects (e.g., read-only nature), authentication needs, or error conditions. The description adds context beyond the schema but is insufficient for a safe read operation.

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

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

The description is front-loaded with a concise summary and then a structured docstring for parameters and returns. However, there is slight redundancy (first sentence repeats the summary). Overall clear and well-organized.

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

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

Given the tool's complexity (7 parameters, no annotations, output schema exists), the description covers all inputs and return structure. It lacks handling of edge cases (e.g., branch not found) or pagination details, but is sufficient for typical agent use.

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

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

The input schema has 0% description coverage, leaving parameters undefined. The description's docstring compensates fully with detailed explanations for all 7 parameters, including formats for ref (hash/branch), filters (substring match), and default for limit. This is critical 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 the tool retrieves commit history for a specified branch in the Bauplan data catalog. It specifies the resource (commits), action (retrieve), and scope (branch-specific). This distinguishes it from sibling tools like get_branches or get_tags.

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 the tool's purpose but does not explicitly instruct when to use it versus alternatives. It implies use for commit history retrieval but lacks exclusionary guidance or comparisons with siblings like get_branches.

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 takes on the full burden of behavioral disclosure. It explains the return type ('Prompt object with detailed instructions') but does not mention side effects, idempotency, or authentication requirements. The tool is likely read-only, but this is not stated.

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

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

The description is well-structured with an Args section and a Returns section, making it easy to parse. It includes a bulleted list of use cases. While somewhat lengthy, every sentence adds value, and the main purpose is front-loaded.

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 (not shown but indicated), the description adequately explains the return value. It covers all possible inputs and notes how the output is used for further planning. It is complete for a tool that provides contextual guidance.

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 only specifies the 'use_case' parameter as a string with no description or enum. The description compensates by explicitly listing all allowed values ('pipeline', 'data', etc.), adding critical semantic information beyond the schema.

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

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

The description clearly states the tool's action ('Get detailed instructions') and the resource ('specific Bauplan use cases'). It enumerates specific use cases, making the purpose unambiguous. It distinguishes itself from sibling tools by being the only tool providing instructional guidance for high-level tasks.

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 specifies when to use the tool ('to solve the task') and hints at its role in suggesting further tool usage. However, it does not explicitly state when not to use it or mention alternative tools for similar purposes.

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 stand alone. It describes a read-only operation (retrieve) and details the return fields, including the human_readable_status mapping. While it does not explicitly state that the tool is read-only or that it has no side effects, the action verb 'retrieve' implies a safe operation, and the detailed return spec adds transparency.

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

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

The description is well-structured with a summary, Args, and Returns. It front-loads the main purpose. However, there is minor redundancy: the first two sentences both convey 'get details of a specific job by its ID.' Trimming this would improve conciseness.

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

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

Given the tool's simplicity (one parameter, no annotations, existing output schema), the description provides complete context. It explains the job retrieval, the meaning of human_readable_status, and lists all return fields with types and descriptions. An agent can fully understand the tool's behavior without additional information.

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

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

The input schema has one required parameter (job_id) with no description. The description fills this gap with an Args section: 'job_id: The ID of the job to retrieve.' This adds full meaning beyond the schema, achieving high semantic value despite the schema's 0% coverage.

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

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

The description clearly states the purpose: 'Retrieve details of a job by job ID.' It specifies what the tool does (retrieve details) and the resource (job by ID). Among sibling tools like list_jobs or cancel_job, this is distinct and unambiguous.

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

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

The description effectively communicates when to use the tool (when you have a job ID and need full details). Although it does not explicitly exclude alternatives, the context of sibling names like list_jobs and cancel_job makes the usage context clear. Missing explicit 'when not to use' guidance prevents 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 provided; description does not disclose behavioral traits beyond the obvious read operation. Does not elaborate on side effects, expected output structure, or performance implications, leaving gaps for the agent.

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?

Includes a concise summary followed by structured args. While efficient, the docstring style adds some redundancy (e.g., re-explaining ref format). Still, it is well-organized and front-loaded.

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

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

Covers all parameters and return type (NamespacesOut) adequately. Given the presence of an output schema, the description is sufficiently complete for a list retrieval tool, though it could clarify the substring match behavior.

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 adds comprehensive parameter explanations (ref format, namespace substring match, limit default). This adds significant meaning beyond the bare schema types.

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

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

Description clearly states 'Retrieve namespaces for a branch from the user's Bauplan data catalog as a list', using specific verb and resource. It effectively distinguishes from sibling tools like create_namespace and delete_namespace.

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 basic parameter guidance (e.g., 'Use limit to reduce response size') but lacks explicit when-to-use vs alternatives. No mention of when not to use or comparison with sibling tools like has_namespace.

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 provided. Description explains that ref can be a branch name or commit hash, which adds behavioral context. However, it does not explicitly state that the operation is read-only or discuss any 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?

Description includes Args and Returns sections which are clear. It is not overly verbose, though the ref explanation could be slightly more concise.

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

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

Given that an output schema exists, the description need not detail return values. It adequately covers the core purpose and parameters. Lacks discussion of edge cases like invalid ref, but acceptable for a retrieval 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 parameter descriptions are missing (0% coverage), but the tool description fully explains both parameters: ref format in detail and namespace as optional filter. This significantly aids correct usage.

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

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

Clearly states 'retrieve schemas of all data tables' with verb and resource. Distinguishes from siblings like get_table (single table) and get_branches (branches).

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

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

No explicit guidance on when to use this tool versus alternatives. Does not mention when to use get_schema over get_table or other query 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 provided, the description carries full burden for behavioral traits. It states it retrieves schema but does not disclose whether it is read-only, required permissions, error behavior for missing tables, or side effects. The only added detail is namespace default, which is minimal.

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 Args and Returns sections and front-loads the purpose. However, it is slightly verbose; for example, the Args section repeats information that could be inferred from the schema. It earns its place but could be tighter.

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 value details are covered. However, with no annotations, the description lacks completeness on behavioral aspects (e.g., idempotency, auth, errors). For a 3-parameter read tool, it provides adequate but not comprehensive 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?

Input schema has 0% description coverage, so the description must add meaning. It explains 'ref' as a commit reference with format details, 'table_name' as the specific table, and 'namespace' with default. This provides semantic context beyond the schema's type-only definitions.

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

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

The description clearly states the specific action ('retrieve the schema') and resource ('specified data table in the user's Bauplan data catalog'). The mention of returning a schema object further clarifies purpose. Among siblings, only 'get_schema' could overlap, but the description explicitly ties to a table name, distinguishing 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 explains the parameters but provides no guidance on when to use this tool versus alternatives like 'get_schema' or 'list_tables'. It does not mention optimal scenarios, prerequisites, or exclusions, leaving the agent without context for 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?

Describes retrieval operation with filters and return type, but does not explicitly state it's read-only or any side-effect information. With no annotations, the description carries the full burden and is adequate but minimal.

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 paragraphs with some repetition (e.g., 'Retrieve tags' and 'Get the tags'). Could be more concise without the second paragraph that repeats the first.

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 tool with only two optional parameters and a return type mentioned, the description covers functionality completely. No unmet expectations given the output schema exists.

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?

Adds meaning beyond schema by describing filter_by_name as substring match and limit as maximum number to return. Schema has 0% description coverage, so description compensates well.

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

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

Clearly states it retrieves tags from 'user's Bauplan data catalog as a list', distinguishing from create_tag, delete_tag, and has_tag. Includes optional filters for narrowing results.

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

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

No explicit guidance on when to use this vs. alternatives (e.g., has_tag for existence check). Usage is implied but not contrasted with sibling tools.

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

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

Without annotations, the description carries the full burden. It discloses that the tool returns a UserInfo object with username and full name, implying a read-only operation. Could explicitly state no modification, but the verb 'retrieve' is sufficient.

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 contains redundancy by stating the same purpose twice ('Retrieve user information...' and 'Get information...'). It also includes empty 'Args:' and 'Returns:' sections, adding clutter.

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

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

For a simple read-only tool with no parameters and an existing output schema, the description fully covers what the tool does and what it returns. No additional context is needed.

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

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

The tool has zero parameters, so schema coverage is 100%. The description does not need to add parameter details. Baseline 4 applies as per guidelines.

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 retrieves user information of the current authenticated user, using a specific verb and resource. It is distinct from all sibling tools that perform other operations.

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

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

No explicit when-to-use or alternatives are provided, but the tool's purpose is straightforward and no sibling tool provides the same function. Usage is implied by the description.

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 provided, so the description carries the burden. It discloses the return type (an object indicating existence with details) but does not mention that the tool is read-only, safe, or whether it requires specific permissions. The description adds some value but lacks full transparency.

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

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

The description repeats the same idea in two sentences ('Check if a specified branch exists...' and 'Check if a specific branch exists...'), which is redundant. It could be more concise by merging into one sentence while keeping the args/return section.

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 existence-check tool with an output schema (not shown but present), the description adequately covers purpose, parameter semantics, and return type. It does not mention error handling or edge cases, but these may be implied by the output schema.

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

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

Schema description coverage is 0%, but the description explains the 'branch' parameter as 'Name of the branch to check for existence', adding meaning beyond the schema's type-only definition. This compensates well for the schema gap.

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

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

The description clearly states the tool's verb ('Check if exists') and resource ('branch'), and explicitly distinguishes existence checking from sibling tools like create_branch, delete_branch, or get_branches, which have different purposes.

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

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

The description implies usage for existence checks, but does not explicitly mention when to use this tool versus alternatives like get_branches (which lists all branches) or has_table (for tables). No exclusions or prerequisites are stated.

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

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

No annotations are provided, and the description does not disclose any behavioral traits beyond the basic operation. It does not mention authentication, rate limits, or side effects, which is acceptable for a simple read-only check. The description is adequate but not rich.

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

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

The description is concise with two sentences plus structured Args/Returns sections. Every sentence adds value, and there is no redundancy or unnecessary information. It is well-organized and easy to parse.

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

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

The tool is simple, and the description covers the core functionality and parameters. An output schema exists, so return values are documented externally. However, it lacks information on error cases or permissions, which would be helpful for 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?

The input schema has 0% description coverage, so the description carries the full burden. It thoroughly explains both parameters: namespace as 'Name of the namespace to check for existence' and ref as 'The ref, branch name or tag name to check the namespace on.' This adds significant 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 clearly states the tool's purpose: 'Check if a specified namespace exists', specifying the verb 'check' and the resource 'namespace'. It also includes the context of a branch, distinguishing it from sibling tools like create_namespace or get_namespaces. The description is specific and unambiguous.

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

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

The description implies when to use the tool (to check namespace existence), but does not explicitly state when not to use it or provide alternatives. Given siblings like has_branch and has_table, the context is clear, but no explicit guidance is provided.

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

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

No annotations provided, and the description does not disclose behavioral traits like read-only nature, authentication needs, or error cases. While 'check' implies no side effects, this is not explicitly stated, leaving ambiguity.

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

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

The description is concise: one sentence for purpose, followed by parameter details. It is front-loaded with the core action and avoids extraneous 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?

Given the simplicity of the tool and presence of an output schema (TableExists), the description covers inputs and output adequately. However, it lacks differentiation from sibling tools and does not provide context on when this check is useful.

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 compensates by defining both parameters: 'table' as the table name and 'ref' with detailed format (hash or branch name following 'username.name' pattern). This adds significant meaning beyond the schema.

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

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

The description clearly states the tool checks if a table exists in a branch, with specific verb ('check'), resource ('table'), and scope ('in a given branch'). It naturally distinguishes from siblings like has_branch or has_namespace by focusing on 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?

No explicit guidance on when to use this tool versus alternatives (e.g., get_table, list_tables). The description only states what it does without mentioning prerequisites 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?

No annotations are provided, so the description must cover behavioral aspects. It mentions the return type (TagExists object indicating existence) but does not state side effects (none expected) or whether it is idempotent. For a simple existence check, this is adequate but could be more explicit.

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 brief (two sentences) and includes structured Args and Returns sections. Every sentence is informative 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?

Despite the tool's simplicity, the description fully explains the action, parameter, and return type. An output schema exists, and the description complements it well. No critical information is missing.

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

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

With 0% schema description coverage, the description adds necessary meaning to the 'tag' parameter: 'Name of the tag to check for existence.' This clarifies its purpose beyond the schema's simple type declaration.

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 explicitly states the action ('Check if a specified tag exists'), the resource ('tag in the user's Bauplan data catalog'), and the method ('using a tag name'). This clearly distinguishes it from sibling tools like 'create_tag' or 'get_tags'.

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 checking existence of a single tag, which is distinct from 'get_tags' (listing all). However, it does not explicitly state when to use or not use this tool, nor mention alternatives. The purpose is clear enough to infer usage.

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 disclose behavioral traits. It mentions the return type (success/failure with job details) but lacks crucial details: whether the import is synchronous or asynchronous, whether it appends or replaces data, permissions needed, and 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 relatively concise, with purpose stated upfront and an Args list for parameters. It could be slightly more compact by integrating parameter descriptions more efficiently, but overall it is well-structured and front-loaded.

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 explains parameters and return type, but given the tool's complexity (data import) and lack of annotations, it omits important behavioral details like idempotency, overwrite behavior, and side effects. An output schema exists but its content is not used to reduce need for description. Overall, it is adequate but 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?

The input schema has 0% description coverage, so the description's Args section adds value: it explains that 'table' must exist, 'search_uri' is for searching data files, 'branch' is a branch name, and 'namespace' defaults to 'bauplan'. This provides meaningful context beyond the schema's types.

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 imports data into an existing table, specifying verb ('import') and resource ('data into a specified existing table'). It distinguishes from sibling tools like create_table (which creates a new table) and run_query (which queries data).

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 after the table exists ('table needs to exist beforehand'), but it does not explicitly state when to use this tool versus alternatives (e.g., project_run, run_query_to_csv) or provide conditions for not using 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?

No annotations are provided, so the description must fully disclose behavior. It states it retrieves a list with filters and returns a JobsList, but does not mention side effects, performance, authorization, or error handling. Minimal beyond basic function.

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 uses a clear docstring format. Every sentence contributes meaning, though it could be slightly more streamlined. No wasted 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?

Given 5 parameters and no annotations, the description covers purpose and parameter details. However, it lacks information on filter combination logic, pagination, sorting, and error handling. The existence of an output schema partially compensates, but gaps remain.

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 adds significant value by explaining each parameter's purpose and providing format examples for time fields (e.g., '%m/%d/%y %H:%M:%S'). The description compensates well for the lack of schema descriptions.

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

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

The description clearly states 'Retrieve a list of jobs in Bauplan' with optional filters, specifying the verb and resource. It implicitly distinguishes from sibling 'get_job' which retrieves a single job.

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 lists optional filters but does not explicitly state when to use this tool versus alternatives (e.g., get_job). Usage context is implied but not explicit, lacking 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?

No annotations provided, so the description fully bears responsibility. It describes a read-only operation without side effects, and mentions the return type. Could add details about pagination or limits, but is transparent enough.

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?

Concise single-sentence purpose, followed by structured Args and Returns sections. The IMPORTANT note is a useful addition without verbosity. 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 two parameters, no annotations, and presence of output schema, the description covers key aspects: parameter details, usage guidance, and return type. Lacks error handling or limits, but adequate for a straightforward list 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 description explains both parameters in detail, especially ref with its format rules, adding significant value beyond the basic schema types. Schema coverage was 0%, so the description compensates 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 the tool retrieves a list of tables in a specified branch or reference, using a specific verb and resource. It distinguishes from siblings like get_schema and get_table by focusing on listing all 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?

Includes explicit instruction to use this tool before generate_code to ensure table existence. Lacks explicit when-not-to-use or alternative tools, but provides clear 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, description carries full burden. It states the merge action and return type but does not disclose side effects (e.g., overwriting, permissions needed, conflict handling). Minimal 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?

Description is concise and includes a clear list of arguments and return value. It is front-loaded with the main action. A few words could be trimmed, but overall 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?

Given the tool's complexity (merge operation), missing annotations, and no schema descriptions, the description provides parameter explanations and return type but lacks preconditions, error scenarios, and behavioral details. Adequate but with clear gaps.

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

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

Schema coverage is 0%, but description compensates by naming each parameter and adding format constraint (<username.branch_name>). Provides basic meaning for source_ref, into_branch, commit_message, and commit_body, adding value beyond the bare schema.

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

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

Clearly states it merges a source branch into a target branch, specifying the resource (Bauplan data catalog) and action. However, it does not differentiate from sibling tools like create_branch or delete_branch, leaving some ambiguity.

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

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

No explicit guidance on when to use this tool versus alternatives. Mentions branch name format but lacks context such as prerequisites (branches must exist) or conflict scenarios. No reference to sibling tools.

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

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

No annotations provided, so the description bears full burden. It discloses that the tool attempts to create a table based on schemas, returns a plan, and auto-applies if no conflicts. However, it does not detail error handling, authorization needs, or what happens to existing data.

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 a run-on sentence containing a misplaced parenthesis. The structured 'Args' section is helpful, but the overall text could be more concise and better organized.

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

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

Given an output schema exists, the description covers the main purpose, parameters, and outcome. However, it lacks details on error scenarios (e.g., conflicts) and how to proceed if auto-application fails. Still fairly complete for a planning 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%, but the description provides clear, concise explanations for all 6 parameters in the 'Args' section, adding meaning beyond the raw schema. This compensates well for the lack of schema-level descriptions.

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

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

The description clearly states the tool generates a YAML schema plan for importing a table from S3, and distinguishes it from siblings like 'apply_table_creation_plan' by noting automatic application if no conflicts. The verb 'plan' and resource 'table creation' are specific.

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

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

The description implies usage for planning before applying, but does not explicitly guide when to use this tool versus 'create_table' or 'apply_table_creation_plan'. It mentions automatic application, leaving uncertainty about conflict handling.

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 provided, so description carries full burden. It mentions return behavior and dry_run mode, but does not disclose side effects, idempotency, auth requirements, or other behavioral traits.

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

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

Description is well-structured with Args and Returns sections, but could be slightly more concise. Each section earns its place, but some sentences are verbose (e.g., parameter descriptions).

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

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

Given 6 parameters, 2 required, no annotations, and a described output, the description covers parameters well and mentions return type. Lacks behavioral details but is generally complete for invoking the tool.

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

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

Schema description coverage is 0%, but the description compensates fully with detailed Args section explaining each parameter's purpose and defaults. Adds meaning beyond the schema for all 6 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 runs a pipeline from a directory and data ref, returning a job ID. It distinguishes from siblings like code_run and run_query by specifying the source as a project directory.

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

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

Description implies when to use (running a project pipeline), but lacks explicit guidance on when not to use or how it differs from siblings like code_run or run_query. No exclusions or alternative mentions.

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 provided. The description mentions reversion and returns a success/failure object but does not disclose side effects, required permissions, or destructive potential (e.g., overwriting data when replace=true).

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

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

The description is repetitive, restating the same idea in the first sentence and then in bullet points. Could be more concise and front-loaded.

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

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

Despite an output schema, the description lacks important details like the behavior of the 'replace' parameter, format of source_ref, or implications of reverting. Incomplete for a 4-parameter tool with no schema coverage.

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%. The description only lists parameter names without explaining their meanings (e.g., what is a 'source_ref'?) or providing additional context beyond the schema.

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

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

The description clearly states the action ('Revert') and the resources (table, source ref, target branch). However, it does not differentiate from sibling tools like 'merge_branch' or 'create_table', which could be confused.

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

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

No guidance on when to use this tool vs alternatives. Missing context such as prerequisites (e.g., branch must exist) 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 provided, the description carries the full burden for behavioral disclosure. It explains that the tool executes a query and returns results, but does not explicitly state that it is read-only (no side effects), nor does it mention authentication needs, rate limits, or error handling. The description is adequate for a query tool but lacks explicit safety cues.

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 main purpose and includes structured Args and Returns sections, making it easy to parse. However, it repeats information (the second sentence mirrors the first paragraph) and could be slightly more concise without losing clarity.

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

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

Given the tool's complexity (3 parameters with a complex ref format) and the presence of a similar sibling 'run_query_to_csv', the description covers the basics but does not differentiate when to use which tool. It mentions the return type (QueryOut) but lacks context on output format or integration with other tools. The description is adequate but not fully complete for an agent to make optimal choices among siblings.

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

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

Schema description coverage is 0%, so the description must add meaning. It provides detailed format rules for the 'ref' parameter (hash starting with '@' and 64 characters, or branch name in 'username.name' format) and explains 'query' as a SQL query. 'Namespace' is only described as 'Optional namespace', which is minimal. Overall, it adds significant value beyond the schema, especially for 'ref', but could improve on 'namespace'.

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

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

The description clearly states the tool executes a SQL SELECT query on the Bauplan data catalog and returns a QueryOut object. It uses specific verbs and resources, and the mention of returning a QueryOut object distinguishes it from the sibling tool 'run_query_to_csv', which likely outputs CSV.

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

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

The description provides no guidance on when to use this tool versus alternatives like 'run_query_to_csv' or other data operations. It does not specify when not to use it or any prerequisites, leaving the agent without decision support.

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 shoulders the burden. It discloses the limitation that only scalar types are supported and that complex types cause failure. It doesn't mention potential side effects (e.g., file overwrite) but given it's a SELECT query, destructive behavior is unlikely.

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

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

The description is well-structured: a brief summary followed by a note about type limitations and a parameter list. It is concise without unnecessary 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 output schema exists (QueryToCSVResult), the description covers inputs, constraints, and return type sufficiently. It could mention the output schema contents, but the detail of 'success/failure' 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?

All five parameters are described in plain language, including their purpose (path as output file path, query as DuckDB SQL, etc.), types, and defaults. Since schema coverage is 0%, the description compensates well.

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

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

The description clearly states the tool executes SQL SELECT queries and saves results to CSV. It specifies the resource (user's Bauplan data catalog table), verb (execute), and distinguishes from sibling 'run_query' by noting its limitation to scalar types.

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 advises against using when queries return complex types, and directs to the alternative 'run_query' tool. It also mentions optional parameters and defaults, providing clear when-to-use context.

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