install_dense_ann

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

With no annotations at all, the description still carries the most important behavioral fact: rebuild=true drops and recreates the existing index, a destructive side effect the agent would otherwise not know. It also states the supported algorithm/quantization pairing matrix and the product_num_subvectors divisibility constraint. It stops short of covering cost/duration, idempotency, or what happens when an incompatible pair is requested.

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 short sentences, front-loaded with the action and its scope, followed by defaults, the validity matrix, and the destructive-rebuild warning. The compact "hnsw×{dense,binary_sign,product}" notation encodes a large constraint set with almost no tokens.

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 16-parameter, annotation-free install tool this is only partially adequate: it nails the algorithm/quantization interplay but leaves nine or so tuning and plumbing parameters (diskann_l/r, ivf tuning, provider_id, backfill_limit, embedding/source columns) undescribed. Without an output schema, the description also says nothing about what the install returns or how progress is reported.

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 only 44%, so the description must compensate, and it does for the highest-risk parameters: it supplies defaults (hnsw, dense), defines the cross-parameter validity matrix across algorithm and quantization, and explains that product requires product_num_subvectors evenly dividing dimension — a constraint the schema can only hint at. Roughly half the parameters (diskann_l/r, ivf_nlist/nprobe, provider_id, backfill_limit, diskann_beam_width, source_text_column) receive no guidance in either place.

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?

"Install ANN on a table" is a specific verb plus resource, and it adds a scope qualifier ("direct/local only") that tells the agent this is a local-index build rather than a remote/managed operation. It never names a sibling such as reindex or semantic_search, so the boundary with those tools is left to inference.

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 "direct/local only" parenthetical and the rebuild=true note imply some usage context, but there is no explicit statement of when to call this versus reindex, or what prerequisites exist (existing embedding column, provider availability). The reader must infer the call conditions.

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