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

Annotations already provide readOnlyHint and idempotentHint, covering safety. The description adds context about 'basic attributes' vs 'precise Teradata-specific type codes', which is useful. However, it claims this is 'for a single Teradata table or view' while the parameters default to '%' (all databases/tables), creating an inconsistency about actual scope behavior that is not fully disclosed.

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

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

The description is well-structured: purpose, usage examples, alternative tool, then parameter list. It is mostly concise, though the argument list duplicates schema-provided information. Still, it front-loads the core verb and resource, and every sentence serves a clear role.

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 read-only listing tool with no output schema, the description covers functionality, examples, and alternative routing. However, it does not clarify the single-table promise against the wildcard defaults, nor describe the exact return format beyond 'column names, data types, and basic attributes'. Given the lack of an output schema, a bit more detail would make it fully complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description repeats the parameter descriptions already present in the schema but adds no new semantic meaning beyond what the schema provides. The wildcard defaults are documented in the schema, so no compensation is needed.

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

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

The description states a specific verb ('List'), resource ('column names, data types, and basic attributes for a single Teradata table or view'), and explicitly differentiates from sibling base_columnMetadata. An agent can distinguish this tool immediately, even before looking at schemas.

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

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

The description explicitly tells when to use this tool ('Use for straightforward questions like...') and when to use the alternative ('For precise Teradata-specific type codes... use base_columnMetadata instead'). Both conditions and the sibling name are given, leaving no inference needed.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds substantial behavioral context beyond those hints: it explains that the tool self-interrupts before MCP transport timeouts, returns partial data plus a `remaining_objects` continuation token, always includes three computed fields, uses HELP COLUMN for views with derived-table wrapper, and excludes stored procedures/functions/macros. There is no contradiction between description and annotations.

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

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

Though long, the description earns its length for a complex tool with 8 parameters across 0% schema coverage and no output schema. It is well structured with clear headers (Technical capabilities, LARGE-SCALE USAGE GUIDANCE, CONTINUATION PATTERN, Arguments, Returns), numbered strategies, and code examples. The purpose and sibling distinction are front-loaded, followed by actionable operational details. No filler or repetition is present.

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

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

With no output schema, the description fully documents return values: computed fields (ColumnTypeString, IndexTypeString, CharSetString, CaseSpecificityString), truncation metadata (remaining_objects, truncated, truncation_reason, elapsed_seconds), and the continuation pattern. It also covers edge cases like unsupported object types and view vs. table resolution paths, making it complete for an agent to invoke correctly without external knowledge.

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 fully compensate. It does: each of the 8 parameters (database_name, object_name, table_kind, max_workers, fields, exclude_objects, max_payload_kb, max_execution_seconds) is explained with purpose, defaults, and often examples. The object_name parameter's dual role as both target and continuation token is explicitly described, and the table_kind parameter includes unsupported object-type rationale.

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

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

The description opens with a specific verb and resource: 'Retrieve detailed technical column metadata for Teradata tables and views'. It names exact capabilities (type codes, character sets, decimal precision, nullability, index classification) and explicitly distinguishes itself from the sibling tool base_columnDescription by stating 'For a simple list of columns and types for a single object, use base_columnDescription instead.' An agent can immediately tell when to select this tool.

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

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

The description provides explicit usage direction: 'Use when the user needs precise Teradata-specific column information, not just basic column names and types' and names the alternative. It goes far beyond basic with a dedicated LARGE-SCALE USAGE GUIDANCE section featuring five numbered strategies (fields filtering, exclude_objects, parallelism, table_kind filtering, payload/time budgets), a continuation pattern with code examples, and a typical large-database call. It even clarifies when not to use it (simple lists) and names unsupported object types.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the read-only safety profile is covered. The description aligns with this ('List') and adds the persist behavior (materializing as a volatile table), which is useful context beyond the annotations. However, it doesn't disclose return format or ordering, and the persist detail is already present in the schema, so the added value is moderate.

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

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

The description is front-loaded with purpose and usage guidance, and the parameter documentation is cleanly separated. It's slightly longer than strictly necessary because the params duplicate the schema, but every sentence earns its place — especially the high-value exclusion guidance.

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

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

Complete for a simple, two-parameter tool with no output schema and both params optional. It covers purpose, scope semantics, persist behavior, and precise usage boundaries. Nothing an agent needs to call it correctly 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?

Schema description coverage is 100%, with both scope and persist fully documented in the input schema. The description's Arguments section largely restates what the schema already provides, adding minimal new meaning. Baseline 3 is appropriate when the schema carries the documentation burden.

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

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

States a specific verb+resource ('List all databases or schemas available in the Teradata system') that clearly distinguishes it from siblings like base_tableList. The explicit instruction not to use it for table-listing tasks further cements its unique role.

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

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

Provides exemplary when-to-use guidance: 'ONLY call when the user explicitly asks which databases or schemas exist.' It also gives an explicit when-not-to-use rule and instructs the agent to ask the user which database they mean instead of discovering databases first — precise routing with no ambiguity.

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

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

Beyond the readOnly/idempotent annotations, the description discloses the row_limit default (1000) and ceiling (50000), the 'truncated' metadata flag, and the persist option writing to a volatile table. It also tells the agent how to obtain more rows, including a path that bypasses the row limit.

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 content is well front-loaded and organized into arguments, truncation handling, and returns. It is slightly redundant — persist is 'recommended for large result sets' twice — but every major operational point is covered.

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 three-parameter tool with no output schema, the description supplies the missing return contract: formatted query results plus metadata, with 'volatile_table', 'truncated', and 'row_limit' fields. It also covers practical large-result behavior, so an agent can call and interpret the tool correctly.

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

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

With 0% schema coverage, the description fully explains sql, persist, and row_limit, including defaults and bound-parameter placeholders. One point is deducted because the description calls sql 'required' while the input schema marks it optional (default null), an inconsistency an agent may stumble on.

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

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

The description states a specific action: 'Execute a user-provided SQL query against Teradata and return the results.' It also distinguishes this tool from row-browsing by saying it is for explicit SQL with filters, aggregations, or JOINs, unlike base_tablePreview.

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 gives an explicit go condition ('ONLY when the user supplies an explicit SQL statement...'), an explicit don't-use condition ('Do NOT use for simply browsing or sampling rows'), and names the alternative (base_tablePreview). An agent can select this tool without inference.

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

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

Annotations declare readOnlyHint=true and idempotentHint=true, so the safety profile is already covered. The description adds useful behavioral context: it writes a file to disk, accepts comma-separated values for bulk retrieval, and returns file path/size/metadata. However, it doesn't disclose details like whether existing files are overwritten, whether the output directory is created automatically, or any permission requirements. With annotations covering the read-only/idempotent nature, a 3 is appropriate.

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

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

The description is well-structured: a clear first sentence, explicit usage routing, a compact argument list, and a returns note. It is slightly longer than strictly necessary because it repeats argument details that could live in the schema, but every sentence earns its place and the key scoping constraint 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?

For a 4-parameter tool with no output schema, the description covers the essential call contract: what it does, when to use it, all parameters with defaults, and the response type. Minor gaps remain (file overwrite behavior, directory creation, error handling for invalid object types), but the description is complete enough for an agent to select and invoke the tool correctly in most cases.

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

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

Schema description coverage is 0%, so the description must compensate. It does: it explains database_name with an example, table_name with an example and the comma-separated bulk behavior, object_type with the allowed values and default, and output_dir with its default. This adds meaning well beyond the bare schema, though it doesn't specify exact file naming or path validation behavior.

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

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

The description states a specific verb ('Extract... and SAVE'), a clear resource (Teradata table, view, or stored procedure), and the output artifact (.sql file on disk). It also explicitly distinguishes itself from base_tableDDL, which displays DDL without saving, so an agent can tell them apart without opening schemas.

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

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

The description gives explicit when-to-use guidance: 'Use this tool ONLY when the user explicitly wants to export, write, download, or persist DDL to a file.' It also names the alternative (base_tableDDL) and the condition that selects it ('Do NOT use simply to display or view DDL in the conversation'). This is clear routing with no inference required.

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

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

Annotations already establish read-only and idempotent behavior. The description adds useful context beyond that by explaining the persist option materializes a volatile table and returns its name. It does not contradict the annotations, since a volatile table is transient and does not imply a persistent mutation.

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 purpose, usage guidance, and sibling differentiation are all front-loaded and economically worded. The repeated argument list adds some redundancy with the schema but does not make the description bloated or hard 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?

For a tool with three parameters, no output schema, and a clear sibling distinction, the description covers what the tool does, when to use it, when not to use it, and the effect of the persist flag. Nothing needed for correct invocation or selection 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?

Schema description coverage is 100%, so the input schema already fully documents all three parameters. The description's argument list essentially repeats the schema text ('Database name', 'Table or view name', 'If True, materializes result...') without adding new semantic detail, meeting but not exceeding the baseline.

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

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

The description opens with a specific verb ('Identify') and a precise resource ('tables that co-occur together in SQL queries'), making the tool's purpose immediately clear. It also distinguishes itself from sibling analysis tools by focusing on affinity/JOIN relationships rather than usage frequency.

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

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

The description explicitly states when to use this tool ('when the user asks which tables are queried together, what tables are related...') and names the exact alternative for different needs ('use base_tableUsage instead'). This gives an agent clear routing criteria without requiring schema inspection.

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

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

Annotations already declare readOnlyHint and idempotentHint, covering the safety profile. The description adds useful behavior beyond that: the optional persist flag materializes the result as a volatile table and returns the table name, and it clarifies the required input combination. It does not detail missing-table or permission errors, but with annotations in place this is adequate and does not contradict them.

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?

Purpose and usage guidance are front-loaded, and the displacement to siblings is compressed into short, direct sentences. The argument list duplicates the input schema, which costs a point, but the overall structure is scannable and free of filler.

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

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

Even without an output schema, the description explains what is returned (the DDL text with column types, constraints, primary indexes, and keys) and what persist does. It also covers the required input combination and routes alternative needs to the correct sibling tools. No critical information needed to select and call the tool 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?

Schema description coverage is 100%, so the baseline is 3. The description's argument list repeats the same one-line meanings already in the schema and adds little semantic detail. The most valuable parameter-related guidance, 'ask for clarification rather than guess or use empty database name', appears in the prose rather than as deeper parameter semantics.

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

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

States a direct action ('Return') and a specific artifact ('CREATE TABLE DDL statement for a Teradata table'), and enumerates what the DDL includes. It also distinguishes itself from siblings by naming base_saveDDL and base_columnDescription, so an agent knows exactly what this tool does and does not do.

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 provides the trigger condition ('Use when the user wants the CREATE statement...'), a mandatory precondition (ask if both table and database names are not specified rather than guessing), and named alternatives with their conditions ('To save DDL to a file... base_saveDDL', 'For just column names and types... base_columnDescription'). This is excellent routing guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds valuable behavioral context: the tool returns results from all databases when database_name is empty, and the persist parameter materializes results as a volatile table and returns the table name. This goes beyond the annotations and helps the agent understand side effects (volatile table creation) despite the read-only hint.

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

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

The description is compact and front-loaded with the core purpose, followed by parameter details and usage guidance. The clarifying-question sentence is slightly verbose but earns its place by preventing a common misuse. No redundant filler.

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

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

For a simple list tool with two optional parameters and no output schema, the description covers the main decision points: what it lists, how to scope it, and what persist does. It doesn't describe the return format, but the annotations and simplicity of the tool make that a minor gap. The clarifying-question guidance adds completeness for real-world 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?

Schema description coverage is 100%, so the schema already documents both parameters fully. The description repeats the parameter meanings but adds a usage nuance: the clarifying-question guidance for database_name. This is useful but not a major addition beyond the schema, so a baseline 3 is appropriate.

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

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

The description states a specific verb ('List') and resource ('all tables and views within a specific Teradata database or schema'), and clearly distinguishes the tool's scope from siblings like base_databaseList and base_tableDDL. It also explains the optional database_name behavior, making the tool's purpose unambiguous.

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

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

The description explicitly tells the agent when to use the tool (list tables in a specific database) and when not to (if the user doesn't name a database, ask a clarifying question instead of returning all databases). It also provides clear guidance on the persist parameter's effect, which helps the agent decide whether 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?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description's main pulse for behavior is safe. The description goes further by explaining the persist option materializes a volatile table and returns the table name, as well as clarifying that no SQL is required. It doesn't disclose the exact row limit or response format, but the core behavior is well covered.

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 leads with the purpose, then gives usage guidance, and then lists arguments. It is well-organized but the 'Arguments' section duplicates the input schema with no added detail. Still, it is a compact length and front-loaded with the most actionable 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?

For a simple preview tool, the description covers what it does, when to use it, and the significant persist side effect. Though no output schema exists, the description hints it returns rows and possibly a table name. It doesn't explicitly mention the number of rows or response format, which is a minor gap but overall adequate for an agent to safely invoke it.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description reproduces the parameter names and short descriptions but adds no new semantics beyond the schema (e.g., it doesn't explain row limit, table naming rules, or edge cases). Baseline 3 is appropriate.

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

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

The description states a specific action ('Return a quick sample of the first few rows') on a specific resource (Teradata table or view), and explicitly distinguishes it from base_readQuery by noting the lack of SQL/filter usage. This clearly sets it apart from siblings like base_readQuery and base_tableList.

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

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

It provides explicit 'when to use' ('explore or peek at a table's contents without specifying conditions') and 'when not to use' (the user provides WHERE clause, filter, or explicit SQL) conditions, naming the alternative tool (base_readQuery).

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, covering the safety profile. The description adds the persistence behavior (materializing as a volatile table when persist=True), but this is also present in the input schema, so it adds only modest value beyond structured fields. There is no contradiction.

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

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

The description is compact and front-loaded: purpose, usage triggers, and alternative are stated in the first two sentences. The Arguments block is redundant with the schema but not bloated, and the overall length is appropriate for a two-parameter tool.

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

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

For a read-only reporting tool with two optional parameters and no output schema, the description adequately conveys what is reported (access frequency, per-user patterns, popular objects) and how optional parameters behave. It could describe output shape more concretely, but the coverage is sufficient for correct invocation.

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

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

Schema description coverage is 100%, and the input schema already documents both database_name and persist with the same wording. The description repeats those explanations rather than adding new semantic detail, so it meets the baseline but does not elevate it.

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

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

The description opens with a specific verb and resource: 'Report access frequency and per-user query patterns for tables and views in a Teradata database.' It also explicitly differentiates itself from the sibling tool base_tableAffinity by noting that co-occurrence analysis belongs to that tool, so an agent can select correctly.

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

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

The description gives explicit trigger conditions: 'Use when the user asks how often tables are accessed, which tables are most popular, or which users are running queries against a database.' It also provides a when-not and alternative: 'For discovering which tables appear together in the same queries, use base_tableAffinity instead.'

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

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

Annotations already mark the tool as read-only and idempotent. The description adds useful behavioral context beyond annotations by requiring clarification for missing database names and explaining that persist materializes a volatile table and returns its name. No contradiction with annotations.

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

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

The description is well-structured and front-loaded with the main purpose, followed by usage guidance and parameter notes. It is slightly redundant with the schema's parameter descriptions, but every sentence earns its place.

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

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

For a simple two-parameter read-only tool with full schema coverage and no output schema, the description is nearly complete. It covers scope, sibling alternatives, required argument behavior, and the persist side effect; only the exact return format is left unspecified.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description repeats the parameter details rather than adding meaning beyond the schema, which meets the baseline but does not exceed it.

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

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

The description states a specific verb and resource: 'Show disk space allocation for a specific named Teradata database.' It also explicitly differentiates itself from sibling tools dba_tableSpace and dba_systemSpace, so an agent can distinguish it immediately.

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

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

The description provides explicit when-to-use guidance ('when the user asks how much space a particular database is using'), a clear guardrail ('If no database name is provided, ask for clarification — do not call with an empty database name'), and names alternative tools for different scopes.

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

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

Annotations already declare readOnlyHint and idempotentHint, covering the safety profile. The description adds meaningful behavioral context by disclosing that setting persist to True materializes results as a volatile table and returns the table name, which is not implied by the annotations alone.

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

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

The description is short, front-loaded with the purpose, and includes a clear usage trigger. The argument explanation slightly duplicates the schema, but this is minor and does not bloat the description.

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 low-complexity tool with one optional parameter and strong annotations, the description covers the core behavior and usage context. It does not detail the exact return format beyond 'version and release information', but this is a minor gap given the simplicity of the tool.

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

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

Schema description coverage is 100% for the single persist parameter, so the baseline is 3. The description repeats the same parameter text as the schema without adding new meaning or clarifications, so it neither improves nor harms parameter understanding.

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

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

The description states a specific action ('Return the Teradata database software version and release information') tied to a concrete resource, which clearly differentiates it from the many sibling dba_* tools. It also names the exact user intent that triggers it, leaving no ambiguity about what the tool does.

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

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

The description explicitly states when to use it: when the user asks what version of Teradata is running. It doesn't mention alternatives or when not to use it, but among the sibling list there are no other version-focused tools, so the guidance is clear and sufficient.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is known. The description adds valuable behavioral detail about the persist parameter (materializing as a volatile table and returning the table name), which goes beyond the annotations. It does not contradict the annotations. No further side effects are disclosed, but given the read-only nature, this 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 is well-structured: a clear purpose sentence, a usage guideline, and an Arguments section. It is front-loaded with the purpose and usage. The Arguments section is slightly redundant given the schema, but it is concise and not verbose. It earns a 4 rather than 5 due to minor redundancy.

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

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

For a reporting tool with no output schema, the description does not fully specify the return format. It only mentions that when persist is true, a table name is returned; otherwise the result shape is left implicit. Given the complexity and sibling tools that likely return tabular data, more detail on output would improve completeness. It is 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 description coverage is 100%, so all parameters are documented in the schema. The description repeats the parameter explanations in the Arguments section without adding any new semantics. Per the rubric, when schema coverage is high, baseline is 3, and the description does not elevate it.

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

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

The description states a specific action ('Report') on a clear resource ('Teradata product features') with a date-range scope. It distinguishes itself from sibling tools like dba_tableUsage and dba_resusageSummary by focusing on feature adoption rather than table or resource usage. The purpose is unambiguous and not a tautology.

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?

Explicit 'Use when' conditions are provided, covering feature adoption, capability usage, and utilization changes. However, it does not mention alternatives or explicitly state when not to use this tool, which is the only gap from a full 5.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, covering the safety profile. The description adds that this is a system-level report rather than a per-user delay report, and mentions the persist behavior of materializing a volatile table. However, this is also present in the input schema and no additional behavioral traits like required privileges or side effects are disclosed beyond what annotations already imply.

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: the first sentence states purpose, the second gives usage context, and the third identifies the sibling alternative. The Arguments list is redundant with the schema but remains brief and scannable. No wasted words, though duplication with the input schema prevents a perfect score.

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

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

The tool is a simple read-only reporting tool with three parameters and no output schema. The description covers what the tool does, when to use it, which sibling to use instead, and all parameters. It does not describe the exact return fields, but the phrase 'showing when and how much' gives a reasonable indication. Overall, an agent has enough to invoke the tool correctly.

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

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

Schema description coverage is 100%, so the input schema already documents start_date, end_date, and persist. The description's Arguments section simply repeats those descriptions verbatim, adding no new meaning or clarifying detail 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 uses a specific verb and resource: 'Report Teradata workload management flow control events' and adds the scope 'showing when and how much the system throttled or delayed queries due to resource constraints.' It also differentiates from the sibling dba_userDelay by explicitly noting that individual user queue waits are not covered.

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 states explicit trigger conditions: 'Use when the user asks about system throttling, flow control delays, or how often the workload manager imposed restrictions.' It also names the alternative for the excluded case: 'For how long individual users personally waited in queues, use dba_userDelay instead.' This leaves no ambiguity about tool selection.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds meaningful behavioral context: it reports system-wide resource consumption, supports multiple breakdown dimensions, and the persist parameter's side effect (materializing a volatile table and returning its name) is disclosed. No contradiction with annotations.

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

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

The description is well-structured: a clear opening sentence, explicit usage guidance, and a compact parameter list. It is slightly longer than necessary because it repeats parameter descriptions already present in the schema, but the front-loaded purpose and usage guidance make it efficient and scannable.

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 read-only reporting tool with 9 optional parameters and no output schema, the description covers the core purpose, usage context, and the one side-effecting parameter (persist). It does not describe the return format or result shape, but since there is no output schema and the tool is a report, a brief note on what the result looks like would be helpful. Still, the essential information for selecting and invoking the tool is present.

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

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

Schema description coverage is 100%, so the schema already documents all 9 parameters. The description repeats the parameter list but adds no new meaning beyond what the schema provides. Baseline 3 is appropriate because the schema carries the heavy lifting; the description does not need to compensate.

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

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

The description states a specific verb ('Report') and resource ('system-wide resource consumption') and enumerates the breakdown dimensions (time period, application, workload type, complexity class). It also explicitly distinguishes itself from dba_tableUsageImpact by noting it is not tied to a specific database, which differentiates it from the closest sibling.

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

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

The description gives explicit when-to-use guidance: 'Use when the user asks for system-level resource breakdowns, workload profiles, or consumption trends over a date range — not tied to a specific database.' It also names the alternative tool (dba_tableUsageImpact) and the condition that selects it (per-database or per-user impact within a named database). This is clear routing guidance.

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

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

Annotations already declare readOnlyHint and idempotentHint, covering the safety profile. The description adds meaningful behavioral context beyond that, particularly the persist behavior: materializing results as a volatile table and returning the table name. This is a real side effect the agent should know. It could mention output format details, but the added context is solid.

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

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

The description is compact and front-loaded: a clear purpose statement, a usage trigger, a default-behavior note, and a minimal Arguments block. Every sentence earns its place and there is no filler or duplication beyond the necessary parameter 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?

The tool is simple, has only two optional parameters, full schema coverage, and safety annotations. The description covers purpose, usage triggers, defaults, and the persist side effect. The only notable gap is that no output shape is described despite there being no output schema, but this is minor for a reporting tool of this simplicity.

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

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

Schema description coverage is 100%, and the input schema already documents both parameters fully. The description repeats the same parameter explanations, adding no new semantic meaning beyond usage context. This meets the baseline for fully schema-documented 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 states a specific verb ('Report') and resource ('currently active session information for a specific user or all users'). This clearly differentiates it from sibling DBA tools like dba_userSqlList or dba_tableSpace, which target different resources.

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

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

The description explicitly defines when to use the tool: 'when the user asks about open connections, active sessions, or currently logged-in users.' It also gives guidance on the default '*' behavior and states that no clarification is required. It lacks explicit when-not-to-use or alternative tool routing, so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, covering safety. The description adds useful behavioral context beyond that: the persist parameter 'materializes result as a volatile table and returns table name', which is a concrete side effect not implied by the annotations. It does not elaborate on volatile table lifetime, but that is a minor gap.

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

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

The description is front-loaded with the core purpose, then gives usage conditions, sibling alternatives, and the parameter explanation. Every sentence earns its place; there is no fluff or repetition.

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

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

For a simple read-only aggregate tool with one optional parameter, the description is nearly complete. It covers scope, when to use, alternatives, and the persist behavior. With no output schema, it could arguably state the return format when persist=false, but that is reasonably implied by 'Show total disk space usage.' Minor gap only.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's persist line repeats the schema description almost verbatim, adding no additional semantic value beyond what the schema already provides.

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

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

The description states 'Show total disk space usage across the entire Teradata system, aggregated over all databases' — a specific verb, resource, and scope. It also explicitly differentiates from siblings by naming dba_databaseSpace for single-database queries and dba_tableSpace for table-level details.

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

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

It provides explicit when-to-use guidance: 'Use when the user asks about warehouse-wide storage, total system capacity, or overall disk consumption across all databases.' It also names the exact alternatives and the conditions that route to them, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint and idempotentHint, lowering the burden on the description. The description adds useful behavioral context: results are ranked by size, persist materializes a volatile table and returns its name, and empty database_name is an invalid call. No contradiction with annotations is present.

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 main description is front-loaded with purpose, usage trigger, and exclusion guidance before the arguments list. The argument list is somewhat redundant with the schema, but it is clearly formatted and does not undermine readability.

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

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

For a tool with five parameters, no output schema, and several related siblings, the description is fully sufficient. It covers what the tool does, when to use it, how to avoid invalid calls, which siblings to route to, and the meaning of every parameter including the persist 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 100%, so the schema fully documents every parameter. The description essentially repeats the same parameter information rather than adding new meaning beyond the schema, which lands it at the baseline score.

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

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

States a specific verb and resource: 'Show table-level disk space usage within a specific Teradata database, ranked by size.' It also explicitly distinguishes itself from sibling tools dba_databaseSpace and dba_systemSpace by scope, so an agent can select it accurately.

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?

Gives direct trigger conditions: 'Use when the user asks which tables are largest or consuming the most storage within a named database.' It explicitly warns against calling with an empty database_name, instructs the agent to ask for a database if unnamed, and names alternatives for database-level and system-level space.

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

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

Annotations already provide readOnlyHint and idempotentHint, and the description adds meaningful behavioral context beyond those: the requirement for an explicit table name, and the persist parameter's effect of materializing a volatile table and returning a table name. It does not contradict the annotations, as the volatile table appears to be ephemeral rather than a persistent write.

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 core guidance is front-loaded in the first two sentences and the exclusion is stated immediately. The Arguments section is somewhat redundant with the input schema, but it is brief and does not obscure the tool's purpose. Overall, every important behavioral rule earns its place.

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

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

Given there is no output schema, the description reasonably covers what the tool does, when to use it, when not to use it, and the key parameter behaviors including persist. It does not detail the exact return shape of the SQL statement list, but the tool name and core description make that reasonably inferable. This is complete enough for reliable invocation.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description repeats the parameter descriptions almost verbatim without adding extra semantic depth, such as value formats, edge cases, or more concrete examples. A baseline 3 is appropriate because the description does not meaningfully surpass 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 opens with a specific verb and resource: 'Retrieve SQL statements that have been executed against a specific named table.' It also explicitly distinguishes itself from dba_userSqlList by stating this is not for user-based SQL history, making the tool's scope unambiguous.

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

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

The description gives explicit when-to-use guidance: 'Use when the user asks what queries have run against a particular table.' It also provides a clear exclusion with an alternative: 'Do NOT use for SQL history by user — use dba_userSqlList.' The strict condition about requiring an explicit table name, and asking for clarification otherwise, is exceptionally 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?

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds useful behavior beyond annotations: the persist parameter's side effect of materializing a volatile table and returning its name, plus the guardrail to ask for a database name when missing. No contradiction with annotations.

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

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

Purpose and usage guidance are front-loaded and tight, with an explicit alternative and guardrail. The 'Arguments' section is redundant with the input schema, which is a minor efficiency loss, but it does not bloat the description significantly.

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 is largely complete for a read-only analytics tool: it states purpose, triggers, prerequisites, and the behavior of the persist flag. It does not describe the normal (non-persist) return value shape, but given the clear purpose and annotations, this is not a critical gap.

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

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

Schema description coverage is 100%, so the baseline is 3. The description repeats the parameter documentation without adding deeper meaning beyond telling the agent that database_name is required and must not be empty; this adds little over 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 opens with a specific verb and resource: 'Identify which users and tables are driving the most query and resource activity within a specific Teradata database.' It clearly differentiates the tool from siblings by scoping to a named database and by naming the alternative for system-wide metrics.

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?

Explicit trigger conditions are given ('who is hitting a named database hardest, which users are most active, or which tables generate the most load'), a hard precondition is stated (database name required, else ask for clarification), and an alternative tool, dba_resusageSummary, is named for different 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?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds useful context about queue-based wait behavior and excludes flow control, but does not elaborate on aggregation, units, or response shape. This is adequate but not deeply transparent.

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

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

The core guidance is front-loaded in two clear sentences followed by a sibling alternative. The argument list is slightly redundant given the schema already documents all parameters, but it is compact and does not undermine 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?

For a read-only reporting tool with a simple date-range interface and no output schema, this description is largely complete: it states what is measured, when to use it, how to parameterize it, and which sibling to choose instead. It could mention what the returned data looks like, but this is a minor gap.

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

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

Schema description coverage is 100%, and the description's argument list largely duplicates the schema text. It adds no new semantic meaning beyond what the schema already provides, so baseline 3 is appropriate.

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

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

States a specific verb and resource: 'Report how long Teradata users waited in the query queue before their queries began executing.' It clearly distinguishes this tool from dba_flowControl by naming the sibling it is not.

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 tells the agent when to use this tool ('user wait times, queue delays, or how long users had to wait') and when to use dba_flowControl instead ('system-level throttling and workload management flow control events'). No inference is required.

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description adds meaningful behavioral detail beyond them: it warns against empty user_name, instructs the agent to ask for clarification when no user is named, and discloses that persist=True materializes a volatile table and returns its name. This is useful, non-obvious 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 compact, front-loaded with the core behavior, and uses structured argument notes. The Arguments block partly duplicates the input schema, but it is brief and earns its place by emphasizing the required user_name constraint and the persist side effect.

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 3-parameter tool with full schema coverage and no output schema, this description is complete. It covers purpose, invocation conditions, exclusions, an alternative tool, required parameter behavior, and the main optional side effect. An agent has enough context to decide when and how to call it.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description restates those descriptions and adds the 'do not pass empty string' guard, but it does not add substantially new semantic detail such as value formats, bounds, 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 opens with a specific verb and resource: 'Retrieve SQL statements executed by a specific named user.' It clearly distinguishes this tool from dba_tableSqlList, which handles SQL history by table, and from the other siblings by anchoring on a named user account.

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

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

The description gives explicit when-to-use guidance (user asks what queries a person/account has been running), a hard precondition (must name a specific user, otherwise ask for clarification), and an explicit alternative: use dba_tableSqlList for table-focused SQL history. This leaves little ambiguity.

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

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

Annotations declare readOnlyHint=true and idempotentHint=true, and the description does not contradict them—it clearly describes a read-only composite analysis. Beyond the annotations, it discloses the internal execution (shared edge fetch, in-memory sharing), the exact return structure, and performance characteristics (1 SQL round-trip vs 4). It also details the critical type requirement for container_pattern (string not array), which is essential behavioral context.

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

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

The description is long but densely packed with essential information: purpose, performance rationale, use cases, parameter documentation, return structure, and examples. It is front-loaded with the composite nature and benefit. Minor redundancy exists in the performance bullet points and the examples, but every section earns its place. The use of headers and bullet lists improves scannability.

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 (composite of four analyses, 6 parameters, no output schema), the description is exceptionally complete. It explains the return structure with a concrete JSON example, provides three usage examples covering edge cases (exclusions, custom top_n_roots), and explicitly directs the user to graph_edgeContractDDL for the required edge_repository. The annotations cover read-only and idempotent behavior, leaving nothing critical unexplained for an agent to call the tool correctly.

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

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

Schema description coverage is 0%, so the description must fully document parameters. It does: for each parameter it gives type, default, purpose, and examples, with explicit syntax guidance for container_pattern (wildcards, CSV format) and edge_repository contract. The description goes well beyond the schema by explaining the semantics of max_depth_up (0 = skip) and the required nature of edge_repository despite schema listing it with a default.

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 composite nature ('runs findRootObjects, connectedComponents, detectCycles, and bfsLevels in a single MCP call') and the key benefit of a shared edge fetch. It clearly identifies the resource (database lineage graph) and the specific analyses performed, distinguishing it from the individual sibling tools. The verb 'runs' and the enumeration of sub-analyses leave no ambiguity about what the tool does.

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

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

The description provides explicit 'Use this for' scenarios (migration readiness, pre-migration analysis, dashboard data population) and contrasts with individual tools by explaining the performance benefit of avoiding multiple calls. It implicitly tells the agent to prefer this tool when multiple analyses are needed simultaneously, and refers to sibling tools (e.g., graph_edgeContractDDL) for required edge_repository. This is strong guidance 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?

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description never contradicts them. It adds substantial behavioral context beyond the annotations: multi-source BFS with deterministic lexicographic tie-breaking, direction conventions (upstream = dependencies, downstream = consumers), the upstream_level=NULL semantic for in-degree-zero roots, filter application order (SQL WHERE → Python post-filter → BFS depth cap), single SQL round-trip, and O(V+E) complexity. These are exactly the subtle behaviors an agent cannot infer from annotations alone.

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

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

This is a long description, but it is sharply structured with clear headers (purpose, when-to-use, key distinction, arguments, returns, technical notes) and front-loads the critical scoping constraint (BFS distances, not lineage paths) before parameter details. The length is largely justified because the schema provides zero parameter documentation and there is no output schema. The technical implementation notes are somewhat verbose (e.g., the Option B fix history) and could be trimmed, but every section earns its place for an agent needing to call this correctly.

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 6-parameter tool with 0% schema coverage, no output schema, and no enums, this description is remarkably complete: every parameter has semantics, defaults, and examples; the response shape is shown with a full JSON sample including direction values and cycle_candidates semantics; and edge cases (NULL levels for in-degree-zero roots, tie-breaking, filter order) are documented. Nothing an agent needs to invoke it correctly 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?

Schema description coverage is 0%, so the description carries the full burden — and it delivers detailed semantics for all six parameters: CSV syntax with concrete single-root and multi-root examples for root_node_list, the '0 = skip' sentinel for both depth parameters, fnmatch %→* pattern semantics for exclude_objects and include_containers, and container-matching rules. It loses a point because of a schema/description conflict: the schema declares edge_repository with default '' while the description claims it is 'Required parameter — no default,' which could mislead an agent deciding whether to supply it.

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?

Opens with a precise verb+resource statement: 'Compute BFS shortest-path hop distances from one or more root nodes.' It then distinguishes itself from graph_traceLineage by explicitly stating what it returns ('distances and wave groupings, not dependency paths or edge detail'). An agent can immediately tell this apart from its graph siblings without opening any schema.

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

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

Contains a dedicated 'WHEN TO USE THIS TOOL vs graph_traceLineage' section listing six concrete use cases (deployment ordering, migration waves, nearest-root assignment, cycle candidates, blast-radius counting, distance queries) and an explicit 'Do NOT use' block naming the alternative. The 'KEY DISTINCTION' section further routes the agent to graph_findRootObjects for name discovery before calling. This is exactly the explicit when/when-not/alternatives guidance the rubric rewards.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses key behavioral details: it is a pure-Python implementation, requires no stored procedure, issues a single SQL SELECT, and runs Union-Find in the MCP server process. It also documents the full response structure, which is especially valuable since no 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 is long but well-organized with headers, bullets, examples, and a return-structure breakdown. Every section adds necessary information for correct invocation, and the critical parameter caveat is highlighted.

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, three parameters, and absent output schema, the description is complete: it covers the algorithm, scope, parameter contracts, response fields, and use cases. An agent has everything needed to select and invoke this tool correctly.

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

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

Schema description coverage is 0%, so the description carries the full burden, and it does so thoroughly. Each parameter gets semantics, examples, defaults, matching behavior, and a critical STRING-not-array warning for container_pattern. The edge_repository contract and how to generate it via graph_edgeContractDDL are also given.

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

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

The description opens with a specific verb and resource: 'Identify all Weakly Connected Components (WCC) in the dependency graph.' It then defines the component semantics clearly, which distinguishes this from sibling graph tools like graph_detectCycles, graph_findRootObjects, and graph_traceLineage.

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 'Use this tool for' bullet list gives explicit application contexts, including pre-filtering before cycle detection and blast-radius estimation. It does not name specific sibling alternatives or state when not to use it, but the guidance is clear enough for an agent to route correctly.

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

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

Goes well beyond the readOnlyHint/idempotentHint annotations by disclosing that it is a pure-Python implementation, issues a single SQL SELECT, runs WCC partitioning and iterative DFS entirely in the MCP server process, and returns a specific response structure. This gives an agent a clear model of execution cost and 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 long but tightly structured: summary, use cases, arguments, and return format. Each section carries necessary information, with examples and field lists that an agent needs for correct invocation. There is no filler or repetition.

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

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

For a tool with no output schema, the description supplies a detailed response structure, field names, parameter examples, and the expected edge_repository format. It also references graph_edgeContractDDL for generating the contract, making it self-sufficient for correct 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?

Although the input schema has 0% description coverage, the description's Arguments section fully documents all three parameters with types, defaults, wildcard/CSV semantics, examples, requiredness, and the edge repository contract. This fully compensates for the sparse 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?

Description opens with a precise verb+resource: 'Detect circular dependencies (cycles) in the dependency graph.' It clearly distinguishes this from sibling graph tools like traceLineage or connectedComponents by naming the exact outcome (cycles) and the method (WCC partitioning + DFS cycle detection).

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 an explicit 'Use this tool for' list covering graph integrity validation, circular reference finding, stub-then-replace patterns, topo-sort debugging, and pre-deployment checks. It does not name alternative sibling tools or state when not to use it, so it stops short of full when/when-not 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?

Beyond the readOnly/idempotent annotations, the description discloses that the conn argument is ignored, output is template text, and TABLE vs VIEW behavior differs (sample DML only for TABLE). It also enumerates the response payload keys, so the agent knows exactly what to expect.

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-organized with sections and a one-line summary up front, and the AI-Native shortcut is valuable context. However, it is somewhat redundant with the schema's parameter descriptions and includes the confusing conn argument.

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

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

The description covers purpose, non-execution behavior, column contract, the AI-Native product shortcut, argument defaults, and return payload structure. With an output schema also present and annotations already declaring read-only/idempotent behavior, nothing essential 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?

Schema coverage is 100%, so the schema already explains target_database, object_name, and output_type. The description mostly repeats that content and, worse, lists a conn argument that is absent from the input schema with additionalProperties:false, which could mislead an agent into passing an invalid parameter.

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

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

The first sentence states a precise action ('Generate DDL') and resource ('Graph Edge Contract-conforming table or view'). It clearly distinguishes this from the sibling graph_* analysis tools by being a DDL-generation utility rather than a graph traversal/analysis tool.

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

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

The description explicitly says no database connection is required and no SQL is executed, so the agent knows when this is a safe offline generation step. It also gives a concrete alternative: for AI-Native Data Products, use the existing lineage_graph view directly and pass its fully-qualified name rather than generating DDL.

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description adds meaningful algorithmic context: it 'queries the edge repository,' identifies 'objects that appear as sources but never as targets,' and applies exclude/object-type filters before returning results. It does not disclose potential performance costs or return-size limits, but the read-only and idempotent annotations lower the burden here.

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

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

The description is long but well-organized with clear sections: overview, use cases, parameter details, examples, and technical implementation. The repeated emphasis on the string-type container_pattern is justified by the likely array-passing mistake, though some 'Technical Implementation' points restate earlier content.

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

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

The description is thorough for a 5-parameter tool with no output schema: it defines every parameter, gives positive and negative examples, and describes return format options. It is not fully complete because of the edge_repository requirement contradiction and the extraneous conn argument in examples, which could mislead an agent despite the otherwise rich 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?

With 0% schema description coverage, the description compensates extensively: it documents wildcards, CSV formatting, string-vs-array pitfalls, whitespace trimming, defaults, and examples for every parameter. However, it says edge_repository is a 'Required parameter — no default,' while the schema marks it optional with a default of ''; the example calls also include a 'conn=connection' argument that is not in the schema and would violate additionalProperties:false.

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

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

The description opens with a specific verb and resource: 'Find root objects (objects with no upstream dependencies) in specified containers.' It then explains what root objects are and why they matter, which clearly differentiates this from lineage-tracing and graph-analysis siblings like graph_traceLineage and graph_bfsLevels.

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 'Use this for' section gives explicit scenarios such as 'Finding starting points for downstream impact analysis' and 'Identifying source tables and base objects in data pipelines.' It does not name alternative sibling tools or provide negative guidance ('do not use when...'), so it stops short of full when-to-use-versus-alternatives clarity.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses the hybrid implementation, the fact that Python constructs server-side recursive CTEs, that only reachable subgraphs cross the network, and that results are deduplicated and merged. It also explains per-pattern CTE execution, giving a strong behavioral model.

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

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

The description is long but well-structured with clear sections: overview, implementation notes, examples, use cases, arguments, and return structure. Given the tool's seven parameters and zero schema coverage, every section earns its place and the front-loaded purpose and examples aid quick understanding.

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

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

With no output schema, the description provides a detailed return structure including nodes, upstream/downstream edges, summary fields, and edge row field names. Combined with exhaustive argument documentation, an agent has everything needed to select, invoke, and interpret results without opening schemas.

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 fully compensates by documenting all seven parameters with types, defaults, ranges, and examples. It also clarifies that object_name is a STRING, not an array, and explicitly warns that edge_repository is required despite the schema default, which is valuable semantic guidance.

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

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

The description opens with 'Analyse object dependencies in Teradata', naming a specific verb, resource, and system. It further clarifies that it finds both upstream dependencies and downstream dependents, and provides concrete pattern examples, making it easy to distinguish from sibling graph tools.

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

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

The description includes a dedicated 'Use this for' section with concrete scenarios such as impact analysis, lineage tracing, and pre-deployment validation. It does not explicitly name alternative sibling tools or say when not to use this tool, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description doesn't need to repeat those. It adds useful behavioral context by stating 'reads directly from a Teradata table — do NOT use base_readQuery to pre-fetch data first', which clarifies the data-access pattern and implies an efficient read operation. It also mentions the return type (dict) which is not in the schema. This enriches the behavioral picture without contradicting annotations.

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

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

The description is a single paragraph that is front-loaded with the core purpose, immediately followed by essential usage directives. Every sentence serves a distinct function: statement of action, explicit anti-pattern, parameter specification, and grouped alternatives. There is no repetition or filler. The length is appropriate for the amount of guidance provided.

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 the tool is a simple charting operation with no output schema and only three straightforward parameters, the description covers everything an agent needs to select and invoke it correctly: purpose, parameter roles, usage conditions, and alternatives. The annotations cover safety, and the return type is stated. No crucial information is missing for correct execution.

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

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

Schema description coverage is 100% (each parameter has its own description), so the baseline is 3. The description adds semantic value beyond the schema: it specifies that `labels` is 'typically a date or time field' and that `columns` accepts 'one or more y-axis numeric columns'. This clarifies the expected column types and cardinality, which helps the agent select appropriate values. The description also ties the parameters to the chart's purpose, enriching the structured schema data.

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

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

The description states a specific verb and resource: 'Generate a line chart that reads directly from a Teradata table'. It clearly distinguishes the tool from siblings by explicitly stating what it is not for (proportional breakdowns, spider comparisons) and naming the alternatives. This leaves no ambiguity about the tool's primary function.

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

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

The description provides explicit when-to-use guidance ('Use for time-series, trend lines, or sequential data') and explicit when-not-to-use guidance with named alternatives ('Do NOT use for proportional category breakdowns — use plot_pie_chart or plot_polar_chart... Do NOT use for multi-dimensional spider comparisons — use plot_radar_chart'). It also instructs against using a sibling tool (base_readQuery) for pre-fetching, which is a clear usage directive.

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description adds behavior beyond this: it reads directly from a Teradata table and must not be preceded by a base_readQuery fetch. It does not describe the return structure in detail, but the annotations cover the safety profile and the description adds meaningful operational 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?

Every sentence earns its place. The key instruction to avoid base_readQuery is front-loaded, parameter mapping is compact, and sibling alternatives are named in a single sentence. There is no verbose or redundant text.

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 three-parameter chart tool with read-only annotationshol, the description fully covers what an agent needs: when to use it, how to map arguments, and which alternatives exist. The lack of a detailed output schema is not a material gap for a simple chart-plotting tool whose return is declared as a dict.

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

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

Schema coverage is 100%, so the schema already documents all three parameters. However, the description adds semantic roles: table_name is the source table, labels is the categorical column, and column is the numeric value column. This clarifies how the parameters relate to the pie chart's construction beyond the generic schema text.

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 (generate a pie chart), the data source (Teradata table), and the exact parameter roles. It also differentiates from sibling tools by explicitly naming plot_polar_chart and plot_line_chart as alternatives for different chart 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?

The description explicitly says when to use this tool ('proportions, shares, or how a total breaks down by category') and when not to, including both the prohibition against base_readQuery and pointers to alternative chart tools. This leaves no ambiguity about 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?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds meaningful behavioral context by stating the tool reads directly from a Teradata table and must not be preceded by base_readQuery, which is a non-obvious integration detail beyond the annotations.

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

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

The description is compact and front-loaded: it states the action, the critical negative instruction, the parameter mapping, the intended trigger context, and the sibling alternative in a few sentences. Every sentence earns its place with no filler or repetition.

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

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

For a simple chart tool with three required string parameters, read-only annotations, and no output schema, the description covers what the tool does, how to call it, when to use it, and what not to call first. Nothing essential is missing for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description restates the mapping from table_name, labels, and column to their roles, but adds no additional syntax or format details beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: "Generate a polar area chart that reads directly from a Teradata table." It clearly distinguishes itself from plot_pie_chart and explicitly warns against using base_readQuery first, so an agent can identify the correct tool without opening schemas.

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

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

The description gives explicit when-to-use guidance: "Use when the user explicitly asks for a polar chart or polar area chart." It also names an alternative for a different case: "For standard pie-style breakdowns, use plot_pie_chart instead," and states the do-not-do action of avoiding base_readQuery.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds a meaningful behavioral constraint: it reads directly from a Teradata table and explicitly warns 'do NOT use base_readQuery to pre-fetch data first.' This goes beyond the annotations and helps the agent avoid an incorrect invocation pattern.

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

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

The description is compact and front-loaded with the core purpose, immediately followed by the critical integration constraint and the usage guideline. Every sentence adds operational value; there is no filler or repetition of schema details beyond what is useful.

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

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

The tool is simple with three documented parameters and safe read-only annotations. The description covers when to use it, what it reads, and how to invoke it, and it states the return type as dict. Nothing essential is missing for an agent to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description restates the mapping ('table_name, labels, columns') and adds that columns can be one or more value columns, but this adds little meaning beyond what the anyOf schema type already conveys. Baseline 3 is appropriate.

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

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

States a specific verb plus resource: 'Generate a radar chart... that reads directly from a Teradata table.' It also names synonyms (spider/web chart) and clearly distinguishes it from plot_line_chart and other plotting siblings. An agent can tell exactly what this tool does.

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

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

Provides explicit selection criteria: 'Use when the user asks for a spider chart, radar chart, web chart, or multi-dimensional comparison across categories.' It also names the alternative for time-series or trend data (plot_line_chart), giving a clear when-to-use versus when-not-to-use distinction.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds the key behavioral detail that it returns summary statistics for ALL columns in a single call, and explains the persist parameter's effect (materializes as a volatile table and returns table name). This adds value beyond the annotations.

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

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

The description is compact and front-loaded: the core purpose and scope are stated in the first sentence, followed by usage guidance and a brief parameter list. Every sentence earns its place, and the parameter list is a useful quick reference without being verbose.

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 read-only summary tool with 100% schema coverage and no output schema, the description is largely complete. It explains the tool's scope, when to use it, and the persist behavior. The only minor gap is that it doesn't describe the exact structure of the returned summary statistics, but since there is no output schema and the tool is read-only, this is a minor omission.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description repeats the parameter names and brief meanings but doesn't add much beyond the schema. The persist behavior is already in the schema description, so the description adds minimal extra semantic value.

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

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

The description states a specific verb ('Get summary statistics') and resource ('ALL columns in a table in a single call'), and explicitly distinguishes it from the sibling qlty_univariateStatistics for single-column detailed stats. This makes the tool's purpose immediately clear and differentiates it from similar tools.

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

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

The description explicitly says when to use this tool ('when the user asks for an overview, profile, or summary of every field in a table') and names the alternative for single-column statistics (qlty_univariateStatistics). This gives clear usage guidance and exclusion criteria.

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

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

Annotations already declare readOnlyHint and idempotentHint, lowering the burden. The description adds valuable behavior beyond that by explaining the persist flag: 'If True, materializes result as a volatile table and returns table name.' This clarifies a side-effect-like optional behavior without contradicting the read-only annotation.

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

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

The opening purpose and usage guidance are concise and front-loaded, but the Arguments section duplicates the input schema verbatim for all four parameters. Since the schema already covers those definitions, that repetition reduces the efficiency of the description.

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

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

The description covers the key invocation details: operation, relevant user requests, required vs optional parameters, and the persist branch that returns a table name. With no output schema, it could more explicitly describe the default return format when persist is false, but the first sentence and title make the intended result clear enough.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's Arguments section largely repeats the schema's parameter descriptions and adds no new semantic detail beyond noting that database_name is optional and column_name is required, which is already reflected in the schema's required list.

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

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

The description opens with 'Get the unique (distinct) values present in a specific column of a table,' which states a clear verb, resource, and scope. It also differentiates the tool from siblings by tying it to user requests for 'unique values, categories, or entries' in a named column.

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

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

It explicitly says 'Use when the user asks what unique values, categories, or entries exist in a named column' and clarifies that both table_name and column_name are required, telling the agent to ask for clarification if column_name is missing. It does not name alternative sibling tools, so it stops short of full exclusion guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds useful context about the optional persist behavior materializing a volatile table and returning a table name. The description does not contradict annotations, and while it could describe the exact output format more fully, it adequately reveals scope and side effects.

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

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

The description is well-structured and front-loaded: a clear purpose statement, explicit use conditions, and a brief argument list. The argument list duplicates the schema somewhat, which costs a little, but the overall length is still reasonable and every major clause contributes.

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 analysis tool, the description covers what it returns, when to use it, when not to use it, and optional persistence behavior. No output schema exists, but the column-level summary and the mention of null counts per column give sufficient expectation; more detail about the exact return structure would be nice but is not critical.

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

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

Schema description coverage is 100%, with each parameter already documented in the input schema. The description repeats the parameter meanings without adding material detail beyond what the schema provides, so it meets the baseline but does not elevate comprehension further.

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 lists column names containing NULL/missing values in a table and returns a column-level summary. This immediately distinguishes it from related qlty tools that handle negative values, row-level missing data, or statistical summaries.

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

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

The description explicitly says to use this tool when the user asks which columns have nulls or how many nulls exist per column, and explicitly warns against using it to retrieve data rows, directing the agent to qlty_rowsWithMissingValues instead. This is strong routing guidance with a clear alternative.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds behavioral context by noting that it returns the list of affected column names, and clarifies the persist option materializes a volatile table. This is meaningful beyond the annotations.

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

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

The description is concise, front-loaded with the main purpose, and then lists parameters. The second sentence could be considered slightly repetitive with the schema, but overall it's compact 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?

For a read-only analysis tool with full schema coverage and no output schema, the description is fairly complete. It states what it returns (list of affected column names) and when to use it. It doesn't mention edge cases like tables with no numeric columns, but that's a minor gap given the tool's simplicity.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description repeats the parameter names and brief hints but adds little beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly identifies what the tool does: it identifies which numeric columns in a table contain negative values. It distinguishes itself from siblings like qlty_missingValues and qlty_distinctCategories by focusing specifically on negative values, and it even includes usage examples ('negative numbers, values below zero'). This is a specific verb+resource combination.

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

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

The description explicitly states when to use this tool: 'Use when the user asks about negative numbers, values below zero, or columns with anomalous negative entries.' Although it doesn't name sibling alternatives, among the qlty_* siblings this is clearly the negative-value-specific one. It gives clear 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?

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds useful behavioral context beyond annotations: it returns raw records rather than a summary, and it documents that persist=True materializes a volatile table and returns the table name. Minor details like row limits or pagination are not disclosed, but this is acceptable for a read-only fetch.

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 core guidance is well front-loaded and the do/don't usage sentences are efficient. However, the 'Arguments:' section essentially repeats the schema's parameter descriptions, which adds unnecessary length without earning its place. Overall, the description is helpful but not maximally 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?

For a tool with only two required parameters and clear sibling differentiation, the description conveys the essential return behavior ('returns the records themselves') and the optional persist side effect. Even without an output schema, an agent has enough information to call the tool and interpret the result; pagination details would be a nice addition but are not critical here.

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

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

Schema description coverage is 100%, and the argument list in the description mirrors the schema descriptions nearly verbatim. Therefore, the description adds no additional semantic meaning beyond what the input schema already provides, so the baseline score of 3 is appropriate.

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

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

The description opens with a specific action: 'Retrieve the actual data rows where a specific column is NULL or missing.' It explicitly distinguishes itself from a column summary and even names the sibling tool qlty_missingValues, making its purpose unambiguous.

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

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

The description clearly states when to use this tool ('when the user wants to SEE or FETCH the rows'), provides a hard exclusion ('Do NOT write a SQL query with base_readQuery... always use this tool'), and routes column-level summaries to qlty_missingValues. This gives an agent complete decision guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds useful behavioral context beyond this: the persist option materializes the result as a volatile table and returns the table name, and the operation is scoped to a single numeric column. There is no contradiction with annotations.

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

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

Two sentences of core guidance followed by a compact argument list. Purpose and usage guidance are front-loaded, and every sentence earns its place without filler.

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

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

The definition covers purpose, usage conditions, an alternative tool, all parameters, and the persist side-effect. The only gap is the lack of default return format (what is returned when persist is false), but given the low complexity and the presence of annotations, this is minor.

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

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

Schema description coverage is 100%, so the baseline is 3. The description repeats the parameter list and their meanings without adding new semantics beyond what the schema already provides. It does clarify the effect of persist ('materializes result as a volatile table') which is already present in the schema, so no additional value is gained.

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

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

The description states a specific verb ('Calculate') and a clear resource ('mean and standard deviation for a single numeric column'). It also distinguishes itself from sibling tool qlty_univariateStatistics by explicitly naming it as the alternative for a fuller statistical profile, giving agents an immediate basis for differentiation.

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

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

The description provides explicit when-to-use guidance: 'when the user asks specifically for standard deviation, the spread of values, or just mean and variability'. It also names an alternative tool for other cases, leaving no ambiguity about 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?

Annotations already declare readOnlyHint and idempotentHint, and the description adds useful context about the persist option materializing a volatile table and returning a table name. The only minor omission is the return behavior for the ordinary non-persist case, but this is not severe given the annotation coverage.

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 and front-loads the core purpose before alternatives. It includes a mini parameter list, which is slightly redundant with the schema, but the text is dense and every part adds usable context.

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 lacks an output schema, so the description should clarify what the agent can expect when persist is false. It only mentions the returned table name when persist is true, leaving the normal result shape implicit. Otherwise, all key usage and routing information is present.

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

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

Schema description coverage is 100%, so the schema already explains all four parameters. The description repeats the same parameter descriptions without adding deeper semantics, such as formatting expectations or constraints on numeric columns, so it stays at the baseline for fully covered schemas.

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

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

The description states a specific action, 'Calculate full univariate statistics for a single numeric column', and enumerates the outputs (min, max, mean, standard deviation, quartiles, percentiles). It also explicitly differentiates itself from qlty_standardDeviation and qlty_columnSummary, making its scope immediately clear.

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

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

It gives a direct 'Use when' condition: when the user asks for a complete or comprehensive statistical breakdown of one specific column. It also names concrete alternatives with their selection criteria, such as using qlty_standardDeviation for just mean/std and qlty_columnSummary for all columns.

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?

On its own terms the description is remarkably transparent: it discloses prefix stripping, table creation, BYOM/IVSM embedding paths, TD_VECTORDISTANCE cosine similarity, top-k retrieval, and detailed answering and language constraints. However, it expressly discloses write behaviors - 'Creates query table if it does not exist' and 'Both approaches store embeddings in configured output table' - which directly contradict the annotation readOnlyHint=true. An agent relying on that annotation would expect zero environment modification and could be surprised (or fail) in a read-only environment where DDL is prohibited; per the contradiction rule this scores 1.

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

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

The description is well-structured with clear section headers and a front-loaded overview, and the answering rules mostly earn their space. But it is bloated with repetition: silent execution is stated roughly five times, no-paraphrasing/quote-directly about four times, and no-external-knowledge about three times across CRITICAL ANSWERING RULES, LANGUAGE RESTRICTIONS, BEHAVIORAL REQUIREMENTS, and EXECUTION. Roughly a third of the text is redundant reinforcement of the same constraints.

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 complex end-to-end pipeline with no output schema, coverage is strong: workflow steps, configuration sources, technical implementation details, result contents (chunk text, similarity score, metadata fields), fallback answer phrases, and document-reference format are all specified. Gaps remain around explicit return structure, error/failure behavior, and the un-annotated requirement for write privileges, but the operational contract an agent needs to answer correctly is substantially 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?

With 0% schema description coverage, the description must carry the parameter burden, and it partially does: question is clearly the user query, including the '/rag ' prefix-stripping behavior, and k maps to retrieval count via 'Returns the top-k matching chunks' with 'Default chunk retrieval count is configurable' as fallback. But neither parameter is ever explicitly mapped by name, and k's exact contract (overriding the configured default, null behavior) is left to inference.

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?

Opens with a specific verb-object pair ('Execute complete RAG workflow') plus a purpose ('answer user questions based on document context'), and immediately clarifies the scope: a single-step pipeline triggered by a /rag-tagged query. This differentiates it from sibling sql_Execute_Full_Pipeline, which handles the SQL pipeline instead. The tool's function is unmistakable even before reading the workflow details.

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?

Gives an explicit trigger condition ('when a user query is tagged with /rag') and an explicit exclusion ('RAG mode only triggers with explicit /rag prefix - do not enter RAG mode implicitly'), plus 'no additional tools needed' to discourage tool chaining. However, it never names sibling alternatives for non-RAG query types (e.g., base_readQuery or sql_Execute_Full_Pipeline), so routing is implied by the /rag condition rather than explicitly contrasted with alternatives.

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

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

Annotations already declare readOnlyHint and idempotentHint, covering the safety profile. The description adds useful behavioral context beyond annotations: it mentions the requirement for a role name and explains the persist behavior, including that it materializes a volatile table and returns the table name. This is a meaningful disclosure of the non-default 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 well-structured: purpose first, then usage guidance, then differentiation, then a brief parameter list. It is slightly longer than necessary because the arguments section duplicates the schema, but every non-duplicated sentence adds value and the key information 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?

For a two-parameter read-only tool with no output schema, the description provides enough context to select and invoke it correctly. It explains role-level scope, differentiates from user-level siblings, and covers the persist output behavior. It does not describe the default return format, but the verb 'List' plus the read-only annotations make the expected behavior reasonably clear.

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

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

Schema description coverage is 100%, so the schema already documents both role_name and persist. The description repeats the same parameter meanings without adding significant new syntax, formatting, or edge-case information. Baseline 3 is appropriate because the schema carries the semantic load.

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

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

The description opens with a specific verb and resource: 'List the database-level permissions granted to a named Teradata role.' It clearly distinguishes itself from sibling tools sec_userDbPermissions and sec_userRoles by explicitly naming them and the difference between role-level and user-level queries.

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

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

The description gives explicit when-to-use guidance ('Use when the user asks what access rights a ROLE has...') and explicit when-not-to-use guidance with named alternatives ('Do NOT confuse with user-level queries — use sec_userDbPermissions... or sec_userRoles...'). An agent can route correctly without inferring.

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

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

The annotations already declare readOnlyHint and idempotentHint, and the description adds useful context by clarifying that only directly granted permissions are included. It also discloses the persist behavior: materializing to a volatile table and returning a table name. It does not detail the exact return fields, but the read-only annotation and list semantics reduce that gap.

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

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

The main purpose and usage guidance are front-loaded, and the description is compact enough for an agent to parse quickly. The argument list is somewhat redundant with the schema, but it is short and not distracting.

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 is sufficient for this tool: it has simple parameters, full schema coverage, read-only/idempotent annotations, and no output schema. It covers scope, alternatives, and the persist behavior. It could be more explicit about the non-persist return format, but that is a minor gap given the clarity of the main 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?

The input schema covers both parameters completely, each with a clear description. The description's argument section repeats the schema descriptions without adding extra meaning, defaults, validation details, or examples beyond what is already present.

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

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

The description states a specific verb ('List'), a clear resource ('database-level access permissions'), and a precise scope ('granted directly to a specific Teradata user across all databases'). It also distinguishes itself from sec_userRoles by explicitly noting that it is not for viewing roles.

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

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

It provides explicit when-to-use guidance: 'Use when the user asks what a named user can DO in each database.' It also gives a direct exclusion and alternative: 'Do NOT use to see what roles a user has — use sec_userRoles for that.'

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

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

Annotations already cover readOnly and idempotent hints, lowering the burden. The description adds the requirement of a user_name and discloses the persist side effect: materializing a volatile table and returning its name. It does not describe response format, but safety traits are well covered.

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?

Compact and front-loaded: purpose, usage triggers, exclusions, and arguments are presented in a clear order with no filler. Every sentence earns its place.

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

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

For a simple read-only listing tool, the description covers required input, optional persist behavior, return behavior for persist, and sibling alternatives. No output schema exists, but the return concept is sufficiently implied for correct invocation.

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

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

Schema coverage is 100%, and the argument descriptions in the tool description are nearly identical to those in the input schema. The description adds no extra parameter-level meaning beyond what the schema already provides.

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 uses a specific verb ('List') and resource ('roles currently assigned to a specific Teradata user account'), and explicitly differentiates from sec_rolePermissions and sec_userDbPermissions. An agent can immediately identify what this tool does.

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 an explicit when-to-use trigger ('when the user asks which roles a named user HAS') and two explicit when-not-to-use exclusions with named alternatives. Selection guidance is unambiguous.

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 provide idempotentHint=true but no read-only guarantee. The description adds useful behavioral context: it consumes pre-computed statistics, does not re-run clustering, applies thresholds from sql_opt_config.yml, and returns ranked/categorized results. No contradiction with annotations.

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

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

The description is long but well-organized with clear sections, bullet lists, and front-loaded purpose. Some redundancy and a missing step in the workflow list slightly reduce polish, but the structure makes the content scannable and useful.

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

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

For a tool with no output schema, the description covers metrics, categorization, decision frameworks, and output format. It could be more explicit about exact return fields and preconditions, but an agent has enough information to invoke it correctly.

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

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

Schema description coverage is 0%, but the description compensates thoroughly by listing every valid sort_by_metric value with its meaning and giving limit_results a practical role in focusing on top clusters. This is far 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?

The description clearly states the tool 'analyzes pre-computed cluster statistics to identify optimization opportunities without re-running the clustering pipeline.' This specifies a distinct verb, resource, and scope, and differentiates it from pipeline-execution and query-retrieval siblings.

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

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

It positions the tool as 'Perfect for iterative analysis and decision-making' and provides a typical workflow with sorting and limit_results. It does not explicitly name alternative tools or state when not to use it, but the context is clear enough.

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

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

Annotations already mark this as non-read-only and idempotent; the description adds that it 'extracts', 'creates', 'converts' tables, and requires 'sufficient space in feature_ext_db for intermediate and final tables.' It does not detail overwrite behavior, but the write side effects and prerequisites are disclosed beyond the annotations.

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

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

The description is long but well-structured with bold sections, numbered workflow steps, metric definitions, use cases, and prerequisites. The purpose is front-loaded; while some use-case bullets restate the purpose, the organization makes the length acceptable for a complex pipeline.

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?

It covers the full pipeline, metrics, configuration, prerequisites, and downstream tools, which is substantial for a tool with no output schema and only two optional params. It does not specify exact output table names or return behavior, but an agent has enough to invoke and understand the side effects.

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 carries the burden. It explains max_queries as 'top {default_max_queries} queries by CPU time (configurable)' and optimal_k as 'creates {default_optimal_k} clusters by default (configurable via optimal_k parameter)'. It doesn't give exact defaults or value ranges, but adds semantics the schema lacks.

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

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

The description opens with a specific verb+resource: 'executes the entire SQL query clustering workflow to identify and analyze high CPU usage queries for optimization opportunities.' It clearly distinguishes this tool from downstream siblings by framing it as the full pipeline and listing sql_Analyze_Cluster_Stats and sql_Retrieve_Cluster_Queries as follow-up steps.

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 targets DBAs and performance analysts and gives a post-run workflow: 'After running this tool, use: 1. sql_Analyze_Cluster_Stats ... 2. sql_Retrieve_Cluster_Queries ...'. This gives clear context for when it precedes siblings, though it does not state explicit when-not-to-use conditions.

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 provide idempotentHint=true and readOnlyHint=false, but the description adds substantial behavioral detail: available sort metrics, automatic performance categorization with configurable thresholds, query selection strategies, and expected output contents. It does not contradict the annotations, and it goes far beyond what the structured fields reveal.

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

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

The description is long but exceptionally well-structured with headers, bold terms, and bullet lists. The core purpose is front-loaded, and every section—metrics, categories, workflow, output—earns its place given the 0% schema coverage and absence of an output schema.

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

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

For a tool with no output schema, the description is remarkably complete. It explains what the output includes (SQL text, metrics, context, categories), how to sort queries, how categories are derived, and the recommended workflow. An agent has enough information to invoke it correctly and interpret results.

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

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

Schema description coverage is 0%, so the description must compensate. It thoroughly explains the 'metric' parameter with a full list of options and their meanings, and it addresses 'limit_per_cluster' via the query limit strategy. The required 'cluster_ids' parameter is only indirectly explained through the workflow reference to clusters from sql_Analyze_Cluster_Stats, but the context is sufficient.

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

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

The description opens with a clear verb+resource statement: 'RETRIEVE ACTUAL SQL QUERIES FROM SPECIFIC CLUSTERS FOR PATTERN ANALYSIS'. It then details capabilities and explicitly references the sibling sql_Analyze_Cluster_Stats as the upstream step, making it easy to distinguish from cluster-level statistics tools.

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

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

The description provides a 'TYPICAL OPTIMIZATION WORKFLOW' and explains when to use this tool: after cluster identification, to move from cluster-level analysis to query-level optimization. It also gives a query limit strategy and mentions sql_Analyze_Cluster_Stats as the source of clusters. However, it does not explicitly state when not to use this tool or name other alternatives.

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