mimry_reindex

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

No annotations, so the description carries full burden. It discloses that full=true re-parses unchanged files (a meaningful behavioral distinction), and that it rebuilds an index for a specified root (implying write/local effects). However, it doesn't say whether this is destructive, whether the index is unavailable during rebuild, or how it behaves when root is null (defaults to something?). Partial disclosure.

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?

A single tight sentence that front-loads the action and appends the parameter nuance. No waste. Could be slightly more informative without losing concision, but it's efficient.

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 needn't be explained. But for a write-ish index-rebuild tool with no annotations, the description doesn't cover safety, root scoping, or when to prefer it over refresh/init. Given 21 siblings, more routing context is expected.

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 0%, so description must compensate. It explains 'full' ('re-parses unchanged files too'), which is good, but says nothing about 'root' despite it being the scoping parameter with a null default. With 2 undocumented parameters and only half addressed, more 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?

Clear specific verb+resource: 'Rebuild the local MIMRY index for a root.' An agent knows exactly what this does. It distinguishes itself from siblings like mimry_refresh or mimry_init by being the index rebuild operation. Not a 5 because it doesn't explicitly contrast with refresh/init to help selection.

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?

No when-to-use guidance, no mention of alternatives like mimry_refresh (which is a very close sibling by name), no prerequisites or conditions. The agent must infer from sibling names alone whether to reindex or refresh. This is a notable gap given there are 21 siblings with overlapping index-related operations.

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