Rebuild Team Vector Index

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

Annotations already declare this is a mutating, non-idempotent, non-destructive operation, so the safety bar is partly covered. The description adds real context beyond annotations: the required TEAM_DB_PATH environment variable and the admin scope requirement. It does not say whether the existing team index is replaced or merged, or whether the operation is expensive/blocking for large entry sets.

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, no filler; the action and its data source come first and the invocation constraints follow. Nothing repeats the title or wastes 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?

An output schema exists, so return values need not be described. However, for an index rebuild the agent still lacks whether the old index is discarded, expected cost on large teams, and how it relates to the other vector-index siblings — gaps that matter more than usual for a mutating, non-idempotent 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 single parameter use_test_db has 0% schema description coverage and the description never mentions it. With one undocumented parameter, the agent must guess whether the rebuild targets the test database, which is a consequential ambiguity for a mutation.

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?

Specific verb ("Rebuild") plus specific resource ("team semantic search vector index") and the source of truth ("all existing team entries"). This implicitly separates it from the local rebuild_vector_index and from the incremental team_add_to_vector_index, though neither sibling is named.

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?

Prerequisites are stated (TEAM_DB_PATH, admin scope), which is genuinely useful for invocation gating. But it never says when to rebuild versus using team_add_to_vector_index for incremental updates, nor what conditions make a full rebuild the wrong choice.

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