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

The description adds useful behavioral context beyond the annotations: 'one call is one commit' and the vector-index embedding fallback with a local model and no API key. It does not cover response format or failure behavior, but the most important behavioral traits are 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 three sentences with no filler. The main action and data format are front-loaded, followed by the commit/embedding behavior and batching alternative. 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 two-parameter write tool, the description covers the key invocation details: required parameters, document format, batch sizing, commit semantics, and vector embedding behavior. It omits output/response expectations, but since there is no output schema and this is an append operation, that 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 coverage is 100%, so the baseline is 3. The description adds meaningful extra semantics by explaining that omitting the vector field triggers server-side embedding from the text column, and by advising row counts per call. This goes beyond the schema's simple 'Rows to append' phrasing.

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 ('Append documents'), a clear resource ('to a table'), and the data shape ('rows, as JSON objects keyed by column name'). This clearly distinguishes the tool from the update/delete siblings by framing the operation as append-only.

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 explicit batching guidance ('Send tens of rows per call') and an explicit alternative for larger volumes ('for a whole corpus use the infino CLI or an SDK'). It does not explicitly contrast with infino_update_documents or infino_delete_documents, but 'append' makes that distinction reasonably 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?

Beyond the readOnly/idempotent annotations, the description adds non-obvious behavioral context: it is a 'fast tally... without fetching or ranking' and is cheaper than the search sibling. It does not detail the exact result shape, but 'HOW MANY rows' makes the count-only output 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 two tight sentences with the core use case front-loaded. Every clause earns its place: the count-only purpose, the non-fetch behavior, the cost comparison, and the sibling routing.

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 count tool with strong annotations and fully described schema, the description covers use case, intended result, cost/performance characteristics, and alternative tools. The absence of an output schema is mitigated by the explicit 'HOW MANY rows' statement.

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 schema already explains all parameters including mode, query token matching, table, and inferred column. The free-text description adds little parameter-specific meaning, so the baseline score applies.

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 names the operation and return intent: 'HOW MANY rows match a keyword query' over a text column. It explicitly distinguishes itself from infino_keyword_search and infino_token_match, so an agent can identify what this tool alone provides.

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 states when to use the tool ('Use when you only need HOW MANY rows... not the rows themselves') and names the alternatives for retrieving matching rows. It also adds a cost rationale ('Cheaper than infino_keyword_search'), 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 idempotentHint=true, but the description adds valuable behavioral nuance: existing databases are reported as created:false, and behavior differs by storage backend. This goes beyond the structured annotations. 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?

Three concise sentences with no filler. The first sentence states the core purpose, the second clarifies environment-specific behavior, and the third covers idempotency and when to call. Every sentence adds distinct 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?

For a parameterless, low-complexity tool, the description is remarkably complete. It covers the operation, environment differences, idempotency behavior, and the explicit error context that should trigger the call. No output schema exists, but the description gives the key response field (created:false) for the relevant edge case.

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

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

The tool has zero parameters, so the baseline is 4. The description correctly explains that the database is derived from the connection rather than provided as an argument, which eliminates any expectation of a parameter. No parameter documentation 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 clearly states the action with a specific verb and resource: 'Provision the database named in the connection.' It also clarifies the meaning in different environments (Cloud vs. local/bucket), which removes ambiguity. There is no sibling tool that creates a database, so this stands alone distinctly.

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

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

The description gives an explicit trigger condition: 'Call it when a hosted connection answers 404.' It also explains when the operation is a no-op on local paths or buckets. It does not name alternative tools for the same job, but no direct sibling alternative exists.

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 a write operation (readOnlyHint=false). The description adds valuable behavioral detail: fts indexes are created on large_utf8 columns by default, vector:true adds an embedding column and cosine index, rows without a vector are embedded from text, and every declared column is required in all rows. It does not state behavior if the table already exists, but 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?

Four dense sentences, each earning its place: the first states the core action, the second explains fts, the third explains vector behavior, and the fourth gives schema design guidance. It is front-loaded and contains no filler.

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

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

For a table-creation tool with no output schema, the description covers defaults, side effects, required-column policy, and search implications. It even explains how column type choices affect later searches. The only omitted detail is behavior on duplicate table names, but the idempotentHint=false annotation already signals that, so the description is complete 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%, so the baseline is 3. The description adds meaningful semantics beyond the schema: fts defaults and type requirements, vector column creation behavior, column type guidance (utf8 vs large_utf8), and the purpose of a stable key column. This enriches the agent's understanding of how to set each parameter.

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

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

The description opens with a specific verb and resource: 'Create a table from a {column: type} descriptor.' It clearly distinguishes this tool from siblings like infino_create_database, infino_describe_table, and infino_drop_table, and it conveys the core schema-definition responsibility without ambiguity.

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

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

The description gives clear context for when to use this tool and how to shape input: it explains fts defaults, vector behavior, required columns, and the recommendation to add a stable utf8 key column. It does not explicitly name alternatives or state when not to use it, but the guidance is strong enough for an agent to select it 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?

Annotations already mark the tool as destructive and non-read-only. The description adds valuable behavior: it returns the number of rows matched and removed, and it requires durable storage rather than memory://. This goes beyond the structured annotations without contradicting 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?

Three sentences, each earning its place: the action and example, the return value, and the safety prerequisite. The most important information is front-loaded, and there is no filler or redundancy.

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

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

For a simple two-parameter destructive tool with no output schema, the description covers the essential context: what it deletes, what it returns, and the storage precondition. The safety hint to verify with count/sql rounds out the picture, making it complete for an agent to call 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%, with both 'table' and 'predicate' already described. The tool description repeats the predicate example but adds no new parameter-level meaning beyond what the schema 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 clearly states a specific action ('Delete the rows matching a SQL predicate') and identifies the resource (rows in an Infino table). It also distinguishes itself from siblings like infino_drop_table by targeting rows rather than the whole table, and from query tools by emphasizing deletion.

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 pre-use guidance: 'Check the predicate first with infino_count or infino_sql.' This tells the agent when to use related tools before invoking deletion. It does not explicitly contrast with infino_drop_table or infino_update_documents, 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the practical context of using it before searching, but does not disclose output format, error behavior, or other behavioral details beyond what annotations provide.

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 front-loads the core function ('Return a table's column names and types') and then adds a concise, high-value usage note. Every word earns its place with no redundancy.

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

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

For a simple one-parameter read-only tool, the description covers what it returns and when to call it. There is no output schema, but the description adequately explains the return value; it could be more complete by mentioning what happens for a non-existent table, but that 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 only parameter, 'table', is already described as 'Table name (from infino_list_tables).' The tool description adds no additional parameter-level meaning, so it stays at the baseline for full 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 a specific verb ('Return') and resource ('a table's column names and types'), making the tool's function immediately clear. It also distinguishes itself from search and table-management siblings by framing its role as a pre-search introspection step.

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 call this tool ('call before searching') and why, which is strong usage guidance. It does not name alternative tools or state when not to use it, but the context is clear enough for correct selection 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?

Beyond the destructiveHint annotation, the description discloses the default deletion of storage objects, the purge: false escape hatch, and the irreversible nature of the operation. This is valuable behavioral context an agent needs before invoking a destructive tool.

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

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

The description is three short sentences, front-loading the core action and default behavior, then explaining the optional parameter, then warning about irreversibility. No sentence is wasted.

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 destructive tool with no output schema, the description covers the action, default behavior, the parameter that changes behavior, and the key risk. 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 both parameters. The description restates the purge behavior but adds no new parameter-level meaning beyond what the schema 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 a specific verb and resource: 'Drop a table from the catalog.' It also clarifies the default storage-deletion behavior, which distinguishes it from simple catalog removal and from sibling tools like list or describe.

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

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

The description gives clear context for when to use the tool: to drop a table and optionally delete its storage. It does not explicitly name alternatives or exclusions, but the purge: false option provides a clear conditional behavior within the tool.

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 read-only, idempotent, and non-destructive behavior. The description adds important behavioral context beyond that: the operation is 'unranked' and relies on an 'indexed column,' which sets expectations about ordering and prerequisites. It also clarifies that this is exact equality, not fuzzy or ranked matching.

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

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

The description is three tight sentences with no filler. It front-loads the operation, adds a key behavioral qualifier, and then names alternatives in a compact final sentence. 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 read-only exact-filter tool, the description covers operation, value semantics, indexing expectations, and sibling differentiation. The schema fills in parameter details, including limit behavior and column inference, so nothing essential is missing for an agent to select and use 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 100%, so the baseline is 3. The description adds extra meaning by giving expected value examples ('tag, status, or id string') and by framing column as an indexed column, which supplements the schema's generic definitions. Limit and table parameters are already well documented in the schema.

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

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

The description uses a specific verb and resource: 'fetch rows whose column exactly equals a value' and gives concrete value examples like tag, status, or id. It clearly distinguishes this tool from infino_keyword_search and infino_sql by calling it an 'unranked exact-equality filter.'

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 the primary use case up front and explicitly routes the agent to infino_keyword_search for ranked text relevance and infino_sql for multi-column analytical filtering. This gives clear when-to-use and when-not-to-use guidance relative to the most relevant sibling tools.

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

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

Beyond the readOnly/idempotent annotations, it discloses that the query is embedded locally with no API key, that scoring is a fused rank where higher is better, and that projection is passed straight to the engine with no truncation. These are behavioral details 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?

The description is a tight four-sentence paragraph that front-loads the usage trigger, then explains mechanism, scoring, and sibling placement. Every sentence contributes distinct information with no filler.

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

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

Despite having no output schema, the description covers what the result contains (fused rank score plus projected columns, with _id and score always included per the schema). Combined with the rich parameter schema and safety annotations, an agent has everything needed to select and call 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 coverage is 100%, so the baseline is 3, but the description adds value by explaining the fused-rank score semantics and the default projection to the full text column. Most parameter-level detail already lives in the schema, so this is a solid enhancement rather than a complete re-documentation.

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

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

The description opens with a concrete use case and names the exact mechanism: fusing BM25 keyword matching with vector similarity in one ranking pass. It also positions itself between infino_keyword_search and infino_semantic_search, so an agent can distinguish it from sibling tools 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?

It explicitly says 'Use when' a query has both specific terms and intent, and names the two alternatives with their limitations ('literal only' vs 'meaning only'). This gives clear selection criteria without needing to inspect sibling schemas.

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 read-only, idempotent, and non-destructive, so the description adds valuable behavioral context beyond that: it matches exact tokens and stems, returns relevance scores where higher is better, and never truncates projected values. This helps the agent predict output size and semantics without overstepping the annotation safety profile.

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 key use condition, then explains the ranking behavior, then routes to alternatives, and then details parameter nuances. Every sentence adds value, and the structure makes it easy for an agent to quickly decide whether to use this 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 7-parameter tool with no output schema, the description covers the essential return shape by stating that results include a relevance score and projected columns, with '_id' and 'score' always included. It also addresses result-size concerns through the 'k' parameter and the 'columns' projection guidance, making the tool fully usable without additional inference.

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 baseline is 3, but the description adds meaningful guidance beyond the schema, especially for 'columns' with concrete examples like ['id'] for compact hits and ['id', 'text'] for citing, plus the caveat that nothing is truncated. It also clarifies the practical effect of the 'stats' scope, which the schema describes but does not motivate.

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

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

The description clearly states a specific verb and resource: 'BM25 full-text search over a text column' that ranks rows by token/stem relevance. It also distinguishes itself from siblings by noting it matches exact tokens, not synonyms or paraphrases, and explicitly contrasts with infino_semantic_search and infino_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?

It opens with an explicit when-to-use condition: 'Use when the query is literal terms — identifiers, error codes, product names, exact phrases.' It also gives direct routing guidance: 'Prefer this over SQL LIKE for known literal terms' and names the exact alternatives for meaning-based and combined search.

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, idempotentHint, and non-destructive behavior. The description adds the contextual detail of a connected catalog and discovery intent, which is useful but not a substantial behavioral disclosure 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?

Two short sentences efficiently convey what the tool does and when to use it. The core action is front-loaded, and there is no redundant or filler content.

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

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

For a parameterless listing tool with strong safety annotations, the description fully covers the agent's needs: what it lists, where it lists from, and when to call it. No output schema is present, but the description implies the result is a set of available tables, which is sufficient for this simple operation.

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

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

The input schema has zero parameters, so there is no parameter burden for the description to carry. The baseline of 4 applies, and no additional parameter explanation 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 clearly states the tool's action ('List the tables') and the resource scope ('connected catalog'). It also signals its role as a discovery entry point, distinguishing it from table-specific or query operations among the 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?

'Call this first to discover what is available to search or query' gives explicit when-to-use guidance, placing it before search/query operations. It does not explicitly name alternatives or exclusions, but the instruction is clear enough for initial orientation.

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?

Even though annotations already mark this as read-only, idempotent, and non-destructive, the description adds valuable behavioral details: it uses a local model with no API key, returns a distance score where lower is closer, and applies filters as a pushdown pre-filter rather than a post-filter. These details materially affect how an agent interprets results.

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 dense but every sentence earns its place. It front-loads the primary use case, then covers score semantics, filters, projections, and alternatives without repetition or filler. The structure is logical 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?

Despite having no output schema, the description explains what each hit contains, how scores behave, what defaults are used, and how nested filters work. The required parameters and common optional parameters are all contextualized. An agent has enough information to call this tool correctly and interpret its 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?

The schema has 100% description coverage, but the description goes further by explaining practical parameter behavior: how 'columns' can be used for compact vs. full projection, that '_id' and 'score' are always included, that 'filter' is a pushdown pre-filter, and that the default text column is used. This is exactly the kind of parameter guidance that helps an agent invoke the tool correctly.

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 use case ('searching for a concept by meaning'), identifies the resource ('a table's embedding column'), and immediately contrasts itself with sibling tools. The distinction from exact-match and hybrid search is explicit, so an agent can select it without ambiguity.

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

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

The description opens with 'Use when...' and later names the two relevant alternatives with their conditions: 'For exact terms use infino_keyword_search; when the query has both literal terms and an intent use infino_hybrid_search.' This explicitly tells an agent when to choose this tool and when to choose a sibling.

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 annotation already marks the operation as destructive, and the description reinforces this by stating 'Any single statement is allowed, DDL/DML included.' It also discloses the server-side embedding behavior and placeholder substitution. It stops short of warning about potential destructive consequences or side effects, but the annotation covers the core safety signal.

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 almost every sentence carries necessary information for correctly invoking this complex SQL tool. It is front-loaded with the purpose, then explains TVFs, embedding, gives an example, and closes with the important DDL/DML caveat. It could be tightened slightly, but it is structured and not padded.

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 adequately explains return value as 'result rows,' but the exact response shape for DDL/DML statements is left implicit. The coverage of query construction, embedding syntax, and search functions is strong and sufficient for an agent to call the tool correctly. Minor gaps remain around output format and error 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 coverage is 100% and both parameters are documented in the schema, so the baseline is 3. The description adds value by explaining the {{name}} placeholder mechanism, the embed:{"name":"query text"} pattern, and concrete search function signatures such as bm25_search and hybrid_search. The example further clarifies how to combine query and embed.

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 tool is for structural or analytical questions and enumerates concrete operations: counts, GROUP BY, joins, aggregates, and column filtering. It also distinguishes this SQL gateway from the specialized sibling search/count tools by explaining that search functions are callable as table-valued relations within SQL.

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

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

The first sentence clearly scopes appropriate use cases, and the TVF explanation shows when this tool is uniquely useful: a single query can both rank and aggregate. It also gives concrete syntax for embedding vectors. However, it does not explicitly say when to prefer a sibling tool instead, such as infino_keyword_search for simple searches.

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 readOnly, idempotent, and non-destructive behavior, so the description's job is lighter. It adds meaningful behavioral context beyond annotations: the operation is fast, unranked, matches indexed tokens and their stems, and returns a set of rows. This gives the agent a clear model of what the tool does without contradicting 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?

Three sentences, each earning its place: the first states the use case and core behavior, the second defines the return semantics, and the third routes to alternatives. The most decision-relevant 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 read-only filtering tool with a fully documented schema and explicit sibling routing, the description is complete. It covers purpose, behavior, return semantics, and alternatives; the schema covers parameter details. No output schema exists, but the description's statement that it returns rows containing the tokens is sufficient for this tool's complexity.

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

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

Schema description coverage is 100%, so the input schema already documents all five parameters, including defaults, enums, and inference behavior. The description adds no parameter-level detail beyond what the schema 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 clearly states the tool returns rows whose text column contains the token(s), and explicitly frames it as an unranked keyword filter producing a set rather than a ranked order. It distinguishes itself from infino_keyword_search and infino_sql, 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 opens with a precise when-to-use condition: when you need the set of rows containing a keyword, not ranked results. It also names explicit alternatives and the conditions that select them: infino_keyword_search for ranked results and infino_sql for analytical filtering across 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?

Annotations only state destructiveHint=true, which the description confirms and expands upon. It adds meaningful behavioral details: the operation is strictly 1:1, embeddings are generated locally when omitted, and memory:// storage is unsupported. This goes beyond the annotation hints and gives an agent important operational expectations.

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

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

The description is compact and front-loaded, starting with the core operation and the key constraint. Each sentence delivers distinct operational information without 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?

For a destructive tool with no output schema, the description covers the operation, cardinality constraint, embedding behavior, and storage requirement. It does not specify what happens on count mismatch, but the 'must equal' phrasing implies an error condition, so the definition is still largely complete.

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

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

The schema already describes each parameter, but the description adds the crucial relationship between predicate and documents—that the number of matched rows must equal the number of replacement documents. It also explains how vector omission in documents is handled, which is not apparent from the 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 uses the specific verb 'replace' and identifies the resource as 'rows matching a SQL predicate', with a clear 1:1 mapping to new documents. This distinguishes it from sibling operations like add or delete, even without naming them.

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

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

The description provides clear context for when to use the tool: replacing existing rows selected by a predicate, with a count equality requirement. It also gives a necessary precondition ('Requires durable storage'). However, it does not explicitly contrast this with alternatives like delete-then-add or SQL updates.

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