index

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

With no annotations, the description carries the full burden, and it discloses the key behaviors: status reads cache metadata, build warms the cache, and clear is destructive ('drops it'). It also signals low risk by stating every other tool works with the index off. Return values and build-overwrite behavior are left implicit, but the core operation semantics are honestly described.

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 and front-loaded with the resource and optionality, then lists the three actions. The final action list is slightly redundant with the earlier sentence, but overall every sentence contributes useful information.

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 covers all three actions and the cache's optional nature, but there is no output schema and it does not explain what each action returns. It also leaves 'the second question' vague and only states args for index_build, so an agent must infer the arg behavior for status and clear.

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 covers both parameters with 100% description coverage, so the baseline is 3. The description adds that index_build takes filepath and with_transcript, which helps because the schema's args object is generic, but it does not explain what with_transcript means or whether status/clear accept args. This is only a modest improvement over 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 identifies the resource (~/.fcp-mcp/index.db) and enumerates three concrete operations (index_status, index_build, index_clear), so an agent can tell this is the index-management tool. It is specific and not a tautology, though it does not explicitly contrast itself with a sibling alternative.

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 sentence 'Every other tool works with the index off... this only makes the second question fast' gives an explicit selection signal: the index is optional and purely for performance. It does not spell out when to prefer one sub-action over another in detailed scenarios, but the contextual guidance is clear.

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