reindex_embeddings

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

Goes well beyond the annotations by disclosing batching (64), ordering (newest first), deduplication of identical commands, network destination and default endpoint/model, the remote-endpoint refusal guard requiring TERMINAL_HISTORY_ALLOW_REMOTE_LLM=1, that only already-redacted local text is sent, and that changing the embedding model triggers full re-embedding. It also names the return counters, so cost, data-egress, and idempotency behavior are all visible.

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?

Front-loaded with purpose and consumer tools, then operational constraints and return values; nearly every clause carries information (guard variables, dedup rule, model-change behavior). It is a dense block rather than a scannable list, and the endpoint/env-var detail is heavy for a single-parameter tool, but nothing is clearly expendable.

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 mutating, network-touching, open-world indexing tool this covers preconditions (run `reindex` first), iteration rule, safety guards (non-localhost refusal, redacted-only input), cost/ordering, and result counts. With an output schema present, detailed return-value explanation is not required, so the remaining ground is covered.

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 a single self-documented `limit` parameter, so the schema already carries the meaning and baseline 3 applies. The description adds adjacent context (batch size of 64, newest-first ordering) that helps an agent size calls, but it never maps those facts onto the `limit` parameter explicitly.

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

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

States a specific verb ('Builds the vector index') plus the consuming features ('search_history' semantic/hybrid modes and 'ask_history'), and adds the distinguishing mechanism (distinct command texts, one vector per identical command). An agent can tell this apart from the sibling `reindex` and from the read-only search tools without opening the schema.

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

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

Gives explicit sequencing relative to a sibling: 'Run `reindex` first, then call until `remaining` is 0', which tells the agent both the precondition and the loop-termination condition. It also implicitly excludes use when no new commands exist via 'that have no vector yet', leaving little to infer.

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