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

With no annotations provided, the description carries the burden of disclosing behavior. It explains optional parameters (test_connection), default values (include_schemas defaults to ['*']), and post-usage requirements. It also details two distinct db_type behaviors. It does not mention error handling or side effects, but overall is informative.

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 for each db_type and common parameters. It includes examples but remains focused. Slightly verbose due to examples, but structure aids 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?

Given 9 parameters, 0% schema coverage, no annotations, and existence of an output schema, the description covers the key aspects: parameter usage, conditional behavior, and post-usage steps. It omits output details but the output schema exists. Adequate for the tool's complexity.

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

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

Schema description coverage is 0%, so the description must compensate. It provides detailed explanations for url, sqlserver_url, linked_server, snowflake_database, include_schemas, exclude_schemas, and test_connection with examples. It does not explain 'name' or 'db_type' in depth, but these are self-explanatory.

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

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

The description clearly states 'Add a new database source to config.yaml and optionally test the connection,' specifying the action and resource. It also distinguishes this tool from siblings like list_sources or refresh_metadata.

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

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

The description explains when to use the tool (adding a database source) and provides context for different db_types (sqlserver, snowflake). It explicitly recommends calling refresh_metadata afterwards. However, it does not explicitly state when NOT to use or compare to alternatives.

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

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

With no annotations, the description must disclose behavioral traits. It specifies 'SQL code only', but lacks details on side effects (e.g., overwrite behavior), permissions, or error conditions. The output_file parameter description adds some constraints, but the main description omits key 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 a single concise sentence with no redundant information. However, it could be slightly more informative while remaining concise, hence 4 rather than 5.

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

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

Given the tool's simplicity, the description covers the essential action and the constraint from the output_file parameter. However, it omits usage context, error handling, and expected output, making it minimally adequate.

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

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

Input schema coverage is 100% with descriptions for each parameter. The tool description adds little beyond the schema, so baseline 3 is appropriate. It does not elaborate on format or additional constraints 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 clearly states the action ('Write') and the resource ('stored procedure definition (SQL code only) to a file'), distinguishing it from siblings like 'get_stored_procedure' which likely returns the definition without writing to a file.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives (e.g., get_stored_procedure) or prerequisites. Usage is implied by the purpose but lacks explicit when-not-to-use or context information.

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

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

The description implies a read-only operation by stating 'Return' and clarifies bidirectional join detection. With no annotations provided, the description carries full burden; it does not disclose potential side effects, permissions, or edge cases (e.g., no joins found), nor does it explain the output structure beyond referencing FK-defined joins.

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

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

The description is extremely concise, using only two sentences to convey the core purpose and usage format. It front-loads the main action and provides a concrete example, with no unnecessary words.

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

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

Given three required parameters, no annotations, and an output schema, the description is inadequate. It fails to explain the 'source' parameter, does not compare with sibling tools like suggest_joins, and omits error handling or default behavior. The output schema exists but that does not compensate for missing usage context.

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

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

Schema coverage is 0%, so the description must compensate. It partially does by specifying the format for table_a and table_b. However, the 'source' parameter is left completely unexplained, and the schema provides no descriptions either. This leaves ambiguity about what 'source' refers to.

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 returns FK-defined direct joins between two tables, including the 'either direction' detail. However, it does not differentiate from sibling tools like list_all_foreign_keys or suggest_joins, which may have overlapping functionality.

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 specific format for table names ('schema.table') with an example, which helps correct usage. However, it lacks guidance on when to use this tool versus alternatives, and does not mention prerequisites or context for the 'source' parameter.

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

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

No annotations provided, so description carries burden. It discloses that python style uses cursor.nextset() to collect result sets. It implies the tool generates code without executing the procedure, which is clear.

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

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

The description is concise, front-loaded with the main purpose, and efficiently presents style options. Every sentence adds value without redundancy.

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

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

Given the output schema exists (not shown), the description need not detail return values. It covers the main purpose and style behaviors, but could mention that the procedure must exist in the metadata cache. Still adequate.

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

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

Schema coverage is 100% with basic parameter descriptions. The description adds value by explaining how the 'style' parameter affects output format, which is not evident from schema alone.

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

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

The description clearly states the tool generates a call template for a stored procedure, distinguishing it from siblings like get_stored_procedure which retrieves definition. It specifies the resource and action with two style variants.

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

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

The description explains when to use each style (SQL vs Python) and what they produce. It lacks explicit when-not-to-use or alternatives, but the context is sufficient for an agent to choose 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?

With no annotations, the description carries full burden for behavioral disclosure. It only states the return value, but does not indicate side effects, authentication needs, or that it is a read-only operation. The description is minimal and lacks transparency beyond the basic function.

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

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

The description is a single sentence, concise and front-loaded. However, it could add a few more words to improve clarity without becoming verbose, such as specifying that the source is a database connection name.

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

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

Although an output schema exists, the description is incomplete for such a simple tool. It fails to define the 'source' parameter adequately, and given the sibling tools, more context about when this tool is relevant would help. The description feels underdeveloped.

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%, yet the description does not clarify the 'source' parameter beyond the examples which are actually dialect values, not source identifiers. The meaning of 'source' remains ambiguous (e.g., source ID, name?), and the description adds minimal value 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 clearly states the tool returns the SQL dialect for a source, with specific examples like 'mssql' and 'snowflake'. The verb 'Return' and resource 'SQL dialect for a source' are precise, and the tool is well-distinguished from siblings like add_database or list_sources.

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

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

No guidance on when to use this tool versus alternatives, such as list_sources or get_stored_procedure. There is no mention of context, prerequisites, or exclusions, leaving the agent to infer usage solely from the description.

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

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

With no annotations, the description must convey behavioral traits. It discloses that the tool returns parameters, dates, and definition, but does not mention side effects (none expected), authentication needs, or performance considerations. The description is adequate for a read-only metadata retrieval but lacks depth.

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

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

The description is a single, well-constructed sentence that immediately states the verb and resource. It is concise (15 words) and front-loads the key information without any redundant or extraneous content.

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

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

Given the presence of an output schema (which likely describes return fields), the description provides adequate high-level context about the return content. However, the lack of parameter documentation and usage guidance leaves gaps for a complete understanding, especially for an agent matching inputs to 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?

The input schema has 0% description coverage, and the tool description does not explain the meaning or usage of the three parameters (name, schema, source). The only guidance is from parameter names, which may not be self-explanatory. The description fails to add value for 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 clearly states the tool retrieves full metadata for a stored procedure, listing specific elements (parameters, create/modify dates, definition). This distinguishes it from sibling tools like list_stored_procedures (which only lists names) or search_stored_procedures.

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 does not explicitly guide when to use this tool versus alternatives. However, the name and content imply it is for retrieving detailed metadata of a specific procedure, which differentiates it from listing or search tools. No explicit when-to-use or when-not-to-use guidance is provided.

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

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

With no annotations, the description carries full burden but only states it 'gets' data. It does not disclose whether authorization is required, error behavior for missing tables, or performance implications. The read-only nature is implied but not explicitly confirmed.

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, compact sentence with no unnecessary words. Every part serves the purpose.

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

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

Although an output schema exists, the description omits key context: all three parameters are required and lack descriptions. The agent cannot determine valid values or the relationship between parameters, making the tool hard to invoke correctly.

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

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

Schema description coverage is 0%, and the description adds no parameter details. It does not explain the meaning of 'source', 'schema', or 'table' beyond their names, leaving the agent without guidance on required values.

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

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

The description clearly states it retrieves columns and foreign key relationships (both inbound and outbound) for a specific table. This distinguishes it from sibling tools like list_tables, which only lists table names, and list_all_foreign_keys, which returns all FKs across tables.

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

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

No guidance is provided on when to use this tool versus alternatives. For instance, it does not suggest using list_all_foreign_keys for a global view or search_tables for fuzzy matching. The agent must infer context from sibling names.

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

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

No annotations are provided, and the description gives minimal behavioral context. It does not explain what information about each foreign key is returned (e.g., column names, referenced tables), nor does it mention any potential performance implications or ordering.

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

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

The description is a single sentence with no wasted words, but it is too brief and fails to include important details. Conciseness is good, but it sacrifices completeness.

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 lack of annotations and minimal description, the tool's behavior is not fully specified. Although an output schema exists, the description does not leverage or refer to it, leaving the agent uncertain about the return format and parameter details.

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%, yet the description does not clarify the meaning of the 'source' and 'schema' parameters. The agent cannot determine what value to provide for 'source' (e.g., database name, connection string) from the description alone.

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

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

The description clearly states the verb 'return', the resource 'foreign keys', and the scope 'in a schema'. This distinguishes it from sibling tools like list_tables or list_schemas, which return different objects.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention any prerequisites, limitations, or situations where a different tool (e.g., find_direct_joins) would be more appropriate.

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

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

With no annotations and a minimal description, behavioral traits like read-only status, permission needs, or pagination are not disclosed. The description does not compensate for the lack of 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 but too brief. It saves space but under-specifies, missing opportunities to add value without verbosity.

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

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

Given the presence of an output schema, the description could be lean, but it still lacks essential context about the parameter and potential limitations. The tool simplicity does not excuse the 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?

The only parameter 'source' is not explained beyond the schema type 'string'. Schema coverage is 0%, and the description adds no meaning (e.g., what constitutes a source, where to find it, format expected).

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

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

The description 'List all schemas for a given source' clearly states the action (list), the resource (schemas), and the scope (for a given source). It is specific and distinguishes from sibling tools like list_tables or list_sources.

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

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

No guidance is provided on when to use this tool versus alternatives, such as when to use list_sources first. There is no mention of prerequisites or context for the required parameter.

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

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

No annotations are provided, so the description carries the full burden. It mentions the 'local metadata cache' as a data source, but does not disclose whether the operation is read-only or if it triggers any side effects.

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

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

The description is a single concise sentence that efficiently conveys the tool's purpose with no superfluous 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?

The tool is simple with no parameters and an output schema exists. The description adequately explains the action and data source, though it could mention that the operation is safe or read-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?

There are no parameters, so the baseline is 4. The description adds no parameter-specific information, which is acceptable as schema coverage is 100%.

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 ('list') and the resource ('database sources'), and it distinguishes from sibling tools like list_tables and list_schemas which cover different objects.

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

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

The description implies usage via context ('available in local metadata cache'), but provides no explicit guidance on when to use this tool over alternatives or any prerequisites.

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

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

No annotations provided, so description carries full burden. It states 'list names' but omits behavioral details like whether it returns only names or additional metadata, permissions needed, or pagination 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?

Single sentence with no waste, but could be slightly expanded to clarify parameters. Nevertheless, it's appropriately short.

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

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

Given 2 required parameters, no annotations, but an output schema exists. The description is too minimal; it omits crucial context about parameter semantics and result details, which the agent needs to invoke correctly.

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

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

Schema description coverage is 0%, yet the description fails to explain the required parameters 'source' and 'schema'. It mentions 'a given schema' but does not define either field, leaving the agent guessing.

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

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

The description clearly states the verb 'list' and the resource 'stored procedure names', and scopes it to 'a given schema'. It distinguishes from siblings like get_stored_procedure (single) and search_stored_procedures (search).

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

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

No guidance on when to use this tool versus alternatives (e.g., search_stored_procedures, get_stored_procedure). The description does not mention when listing all names is appropriate or not.

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

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

With no annotations, the description carries full burden but omits behavioral traits like read-only nature, permissions, error behavior on missing schema, or what 'source' refers to.

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

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

The description is extremely concise with one sentence, front-loading the action. However, it could include more detail without becoming 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 simple list tool with an output schema, the description is minimal. It lacks context on prerequisites, edge cases, or parameter behavior, but the output schema reduces need for return value details.

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

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

Schema description coverage is 0%, and the description only clarifies 'schema' by mentioning it's given. The 'source' parameter is left completely unexplained, adding minimal 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 'List all tables in a given schema' with a specific verb and resource, clearly distinguishing it from siblings like 'get_table' (single table) and 'list_schemas' (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 implies usage for listing tables in a schema but provides no explicit guidance on when not to use it or alternatives. It does not mention that 'get_table' is for a single table.

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

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

No annotations were provided, so the description carries full responsibility. It discloses the operation is expensive (minutes per source), throttled to once per 24 hours, and that force=True bypasses the throttle. This is comprehensive behavioral disclosure.

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

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

The description is front-loaded with the core purpose and cost warning. Each sentence serves a distinct purpose: purpose, cost, usage rules, throttle policy, force guidance. No redundancy or filler.

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

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

Given the tool's complexity (expensive, throttled, force), the description covers all critical aspects. An output schema exists, so return value explanation is unnecessary. The description is fully complete for an agent to use correctly.

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

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

Input schema has 100% coverage, so baseline is 3. The description adds value by explaining that omitting source refreshes all enabled sources and that force bypasses the throttle. It also provides context for when force should be used, exceeding the schema's static descriptions.

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

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

The description clearly states the tool refreshes the local schema metadata cache by querying live databases. This distinguishes it from sibling tools that list or search existing metadata without refreshing. The verb 'refresh' plus resource 'schema metadata cache' is specific and unambiguous.

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

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

The description explicitly states when to call (first-time setup, user-specified schema change) and when NOT to call (not automatically before reads). It also provides guidance on the force parameter and notes the 24-hour throttle, giving clear usage context.

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

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

With no annotations, the description carries full burden. It discloses case-insensitivity and optional schema restriction, but lacks details on side effects, performance, or behavior with missing inputs. Minimal behavioral disclosure.

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

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

The description is extremely concise, using two short sentences that immediately convey the core functionality without extraneous words.

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

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

Given the output schema exists, explanation of return values is not required. However, the description omits explanation of the required source parameter and does not hint at the output structure, making it partially incomplete.

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

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

Schema description coverage is 0%, and the description only explains column_name (substring search, case-insensitive) and schema (optional restriction). The required source parameter is not explained, leaving a gap.

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

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

The description clearly states the tool searches for columns by name (case-insensitive) with optional schema restriction, which is distinct from sibling tools like search_tables or search_stored_procedures.

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

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

The description implies usage for finding columns by name, but does not explicitly state when to use this tool versus alternatives or mention any exclusions or prerequisites.

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

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

With no annotations, the description is the sole source. It mentions case-insensitivity and optional schema restriction, but lacks details on behavior like empty results, performance, or authentication. Adequate but not exhaustive.

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

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

Two sentences, front-loaded with key action, no wasted words. Perfectly 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 search tool with an output schema, the description covers the search logic and optional filter. Missing explanation of 'source' parameter, but overall sufficient for typical 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 0%. The description explains 'keyword' and 'schema' but does not mention 'source', leaving its purpose unclear. Partial value added over raw schema.

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

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

The description clearly states that the tool searches for stored procedures by keyword in name, case-insensitive, with optional schema restriction. This distinguishes it from siblings like 'search_stored_procedure_text' (which searches text) and 'list_stored_procedures' (which lists all).

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

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

The description implies usage: find stored procedures by name pattern, not by text content or without filter. It does not explicitly state when not to use or name alternatives, but the context of sibling tools provides differentiation.

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

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

With no annotations, the description must disclose behavior fully. It mentions case-insensitive matching, excerpt with first line, and optional schema filter. However, it fails to describe the required 'source' parameter, which is critical for the tool's operation.

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

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

Two sentences with no fluff, front-loaded with the action. Could be slightly improved by including the missing source parameter, but overall efficient.

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

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

Output schema exists, so return values are covered. However, missing explanation of the 'source' parameter in the input schema makes it incomplete for a tool with 3 parameters and 2 required ones.

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 explain all parameters. It only partially explains 'keyword' (as *keyword*) and 'schema' (restrict to single schema). The required 'source' parameter is not mentioned at all, which is a significant omission.

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

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

The description clearly states it searches the body of stored procedures for a keyword (case-insensitive), returns an excerpt, and optionally restricts to a schema. This distinguishes it from sibling tools like list_stored_procedures, get_stored_procedure (by name), or search_stored_procedures (likely by name).

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?

Implied usage is for searching stored procedure definitions for text. However, no guidance is given on when to use this tool over siblings like search_stored_procedures or search_columns, nor are there 'when-not' or alternative suggestions.

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

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

No annotations provided. Description implies read-only search but does not explicitly state non-destructiveness or disclose any behavioral traits like result limits or pagination.

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

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

Single sentence, clear and to the point. Could be slightly expanded to add value without losing conciseness.

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

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

Given the presence of an output schema and many sibling tools, the description is minimal. Lacks sibling differentiation and behavioral context, making it somewhat incomplete for confident tool selection.

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%, yet description only mentions 'keyword' and 'source' without further explanation. 'source' is ambiguous and not described beyond being required.

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

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

Description clearly specifies verb 'search', resource 'tables', and filtering condition (name contains keyword case-insensitively). However, it does not differentiate from siblings like list_tables or search_columns.

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?

Indicates when to use (search by keyword in table name) but provides no guidance on when not to use or alternatives among siblings.

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

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

Discloses use of FK graph and heuristic matching, and ordering by confidence, which are behavioral traits. However, no annotations exist, so the description should cover more (e.g., behavior on no results, prerequisites). The existing context is useful but not exhaustive.

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 concise sentences, front-loaded with action, no fluff. Every sentence adds value.

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

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

Adequate for a suggestion tool with an output schema, but lacks parameter details and behavioral completeness given 0% schema coverage and no annotations.

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 only mentions table name format, not explaining 'source', 'max_hops', or parameter purposes. This provides minimal added meaning beyond parameter names.

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

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

Description clearly states the tool suggests join paths using FK graph and heuristic column matching, with results ordered by descending confidence and table names format. This distinguishes it from similar siblings like 'find_direct_joins' by specifying broader methodology.

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

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

The description implies use when needing join path suggestions between two tables, but does not explicitly contrast with alternatives like 'find_direct_joins' or provide when-not-to-use guidance.

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