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

With no annotations provided, the description carries the full burden of behavioral disclosure, but it only states that the tool creates an index. It fails to mention important details like potential table locking, the need for the column to have the vector type, or that this is an DDL operation that modifies the schema. The description adds no context beyond the bare action.

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 that is front-loaded with the core purpose, containing no filler or redundant information. It is appropriately sized for a high-level tool overview, though other dimensions suffer from lack of detail.

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

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

The tool is a DDL operation with 8 parameters, no annotations, and no schema descriptions, yet the description provides only a one-line overview. It fails to mention prerequisites, side effects, or index selection guidance, making it insufficient for agents to understand the full operational context. Even though an output schema exists, the tool's complexity demands a more complete description.

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 by explaining parameters. It only mentions 'HNSW or IVFFlat', which maps to the 'method' parameter, but leaves parameters like hnsw_m, metric, schema, and ivfflat_lists unexplained. The description adds minimal semantic value beyond what the schema already exposes through names and defaults.

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

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

The description clearly states the action ('Create'), the specific resource ('vector index'), and the index methods ('HNSW or IVFFlat'), making the tool's purpose unmistakable. It distinguishes itself from sibling tools like list_vector_tables and similarity_search, which perform different operations on vector data.

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

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

The description implies when to use the tool (when you need an approximate-nearest-neighbor index on a vector column), but it does not provide explicit when/when-not guidance or mention prerequisites such as the pgvector extension or the column already containing vector data. No alternatives are discussed because the siblings are for different operations, but the lack of exclusion criteria leaves room for 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?

With no annotations, the description carries the full burden. It does disclose that the row count is 'approximate,' which is a useful behavioral detail. However, it does not explicitly state non-destructive nature or any requirements, though 'Get' implies read-only. Some behavioral context is present but incomplete.

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

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

The description is a single sentence of 11 words, front-loaded with the action and object. Every word earns its place with 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 metadata-description tool with an output schema available, the description adequately covers what the tool returns and hints at the approximate nature of the row count. It lacks explicit parameter clarifications, but the overall simplicity and presence of output schema make it nearly complete.

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

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

Schema description coverage is 0%, so the description must compensate for lack of parameter documentation. It does not explain the 'schema' parameter or its default behavior, and only indirectly references 'table.' The parameter names are self-explanatory, but the description adds no meaning beyond the raw schema fields.

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 ('Get') and clearly identifies the resource ('columns, indexes, and an approximate row count') and target ('a table'). It is immediately distinguishable from sibling tools such as list_vector_tables and hybrid_search, which serve different purposes.

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

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

The description implies usage when one needs table metadata, but it does not explicitly state when to use this tool versus alternatives. No exclusions or alternative tool references are provided, so guidance is only implicit.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the key behavior (running EXPLAIN ANALYZE), but does not disclose potential side effects such as the query actually being executed, performance implications, required privileges, or the format of the output. This is a minimal but not misleading 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 a single, front-loaded sentence with no filler. It efficiently communicates the tool's purpose without wasting 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?

Despite having six parameters, no annotations, and an output schema, the description is extremely minimal. It does not explain how the similarity query is constructed, the role of metric or k, or what the EXPLAIN ANALYZE output will contain. This leaves significant gaps for an AI agent trying 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?

The description provides no explanation of the six parameters. Schema description coverage is 0%, and the tool description does not compensate by explaining the role of table, embedding_column, query_embedding, k, metric, or schema. Relying on parameter names alone is insufficient.

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

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

The description clearly states the tool's function: 'Run EXPLAIN ANALYZE on a similarity query to confirm an ANN index is used.' It uses a specific verb ('Run EXPLAIN ANALYZE') and a resource ('similarity query'), and the intent is explicit. This differentiates it from sibling tools like similarity_search (runs the query) and create_vector_index (creates an index).

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

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

The description implies usage when one needs to confirm ANN index utilization, but it does not explicitly state when to use this tool versus alternatives, nor does it mention exclusions or prerequisites. Sibling tools such as similarity_search or hybrid_search are not referenced, leaving the decision contextual rather than explicit.

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

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

Since no annotations are provided, the description must carry the full burden of behavioral disclosure. It does explain the core mechanism ('weighted blend of vector similarity and full-text search') and the ranking behavior. However, it does not disclose potential edge cases, performance implications, or how the weighting affects results. This is a moderate level of transparency, similar to the update_drive example but with less risk (read-only operation implied by 'search').

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-structured sentence that immediately communicates the tool's primary function. There is no redundant or filler content. The key terms 'weighted blend', 'vector similarity', and 'full-text search' are all high-signal and front-loaded.

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

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

The description is concise but under-specified for a tool with 10 parameters and no schema-level descriptions. Given the existence of an output schema, the return format is covered, but the description does not explain how to configure weights, metrics, or filtering. It also fails to differentiate from sibling tools. This makes it adequate but with clear gaps in a complex 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 description coverage is 0%, meaning the description adds no parameter-level detail. With 10 parameters, including k, metric, vector_weight, and return_columns, the description only mentions the core inputs (query_embedding, text_column, etc.) implicitly. It does not explain what any parameter means or how to use them, leaving the agent to rely solely on parameter names, which is insufficient.

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 this tool ranks rows using a weighted blend of vector similarity and full-text search. This distinguishes it from sibling tools like similarity_search, which likely only handles vector similarity. The verb 'Rank' and the resources 'rows' and 'Postgres full-text search' are specific and informative.

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 for hybrid retrieval scenarios but does not explicitly state when to use this tool over a pure vector search (similarity_search) or full-text search alone. No exclusions or alternative recommendation is provided. This is acceptable but not explicit, matching 'implied usage' rather than clear guidance.

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

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

With no annotations, the description carries the full burden. It specifies that it lists 'every column' and includes table and dimensionality, which provides concrete behavioral expectations. It doesn't mention permissions or performance, but for a read-only listing tool this is acceptable.

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?

A single, front-loaded sentence conveys the purpose and key details without waste. Every word earns its place.

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

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

For a simple listing tool with one optional parameter and an output schema, the description provides enough context. It clearly states what is listed and what fields are included, so the agent can 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?

The schema already fully documents the single parameter with a good description, so the tool description adds no additional parameter semantics. Baseline 3 is appropriate given 100% schema coverage.

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

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

The description uses the specific verb 'List' and identifies the exact resource: columns of type `vector`. It also states what is returned (table and dimensionality), clearly distinguishing it from sibling tools like `describe_vector_table` or `hybrid_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?

The description implies use for discovering all vector columns in the database, and the optional schema parameter clarifies scope. It doesn't explicitly name exclusions or alternatives, but the intent is clear enough given the sibling set.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does add a valuable security guarantee: 'filters' is a structured allowlist, not raw SQL, and is injection-safe. However, it does not disclose other behavioral traits such as the return format, any potential side effects (though likely read-only), or error/performance characteristics, leaving significant gaps.

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

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

The description is exceptionally concise: two sentences, front-loaded with the main purpose and a contextually relevant security note. Every sentence earns its place without redundancy, making it easy to parse and quick to understand.

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

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

Despite having an output schema, the tool is complex with 8 parameters and no annotations. The description only addresses the filters safety aspect, leaving out crucial context about metric selection, k behavior, return_columns, and the critical distinction from hybrid_search. It is not complete enough for an agent to confidently select and invoke this tool.

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

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

Schema description coverage is 0%, meaning the description adds no parameter names or explanations beyond the schema. The only parameter it touches is 'filters', explaining its structure and safety. For the remaining seven parameters (table, embedding_column, query_embedding, k, metric, schema, return_columns), the description provides no added meaning, which is insufficient given the low coverage and the tool's complexity.

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 and clear action: 'Find the k nearest neighbors to a query embedding.' This effectively conveys the tool's core function with a concrete resource and operation. However, it does not explicitly differentiate it from closely related siblings like hybrid_search or explain_similarity_query, so it misses the top score for distinctiveness.

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 the available alternatives. It doesn't mention suitable scenarios, exclusions, or relationships to sibling tools. The existence of hybrid_search and explain_similarity_query suggests meaningful distinctions, but the description leaves them unaddressed.

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

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

The description discloses the core upsert behavior (insert or update in place). However, it does not explain whether the update is partial (only provided columns) or full, nor does it disclose any side effects on unspecified columns. With no annotations, the description carries the full burden but only conveys the basic write operation.

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

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

The description is a single, front-loaded sentence with no filler. It immediately states the operation and the key condition, earning its place efficiently.

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

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

For a 7-parameter mutation tool with no annotations, this description is too thin. It omits operational context like how `schema` defaults to 'public', how metadata interacts with the row update, and what the output schema contains. The presence of an output schema does not compensate for the missing parameter and behavior 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 only 14% (only `metadata` has a description). The description adds meaning for `id_value` (the existence check) but does not clarify the roles of `table`, `id_column`, `embedding`, `embedding_column`, `schema`, or the metadata object, leaving most parameters under-specified.

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 ('Insert a row or update it in place') with a clear resource (row) and condition (`id_value` already exists). This clearly distinguishes it from sibling read/query tools like similarity_search or describe_vector_table.

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

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

No guidance is provided on when to use this tool versus alternatives. It does not mention that it is for writing/updating embedding rows or that search tools should be used for querying, despite the sibling tool names making this somewhat implicit.

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