indexing_status

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it does so thoroughly. It explains the behavior of pending notes (still found by text search), notes with previous embeddings (remain in semantic search with last vector), and never-embedded notes (excluded until processed). It also discloses the default semantic cutoff behavior, the meaning of semantic_profile values, and the non-comparability of raw cosines across models. This is exemplary transparency.

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 long but information-dense, covering multiple important behaviors and caveats. It is front-loaded with the core status semantics, then expands into edge cases and configuration details. While it could be tightened, every sentence adds meaningful context that an agent would need to correctly interpret the tool's output. The length is justified by the complexity of the semantic search behavior it explains.

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 zero-parameter status tool with no output schema, the description is remarkably complete. It explains what the tool reports, how to interpret each piece of information, what the default behavior is, why the model name is included, and what to do if the count appears stuck. An agent has everything it needs to call this tool and correctly interpret its results.

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 tool has zero parameters, so the schema is trivially complete. The description adds substantial context about what the tool reports (total/indexed/pending counts, completion flag, model name, cutoff status), which is more than enough for an agent to understand what the tool will return. A 4 is appropriate because while there are no parameters to document, the description goes beyond the schema in explaining the tool's output semantics.

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 opens with a precise summary: 'Semantic-index progress: total/indexed/pending notes, complete=true when pending=0.' This states the tool's function (reporting indexing status) and its key output semantics. It clearly distinguishes itself from sibling tools like search_notes or get_note by focusing on index progress and embedding model information.

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 description explicitly tells the agent when to use this tool: to check indexing progress, to understand why pending notes may be stuck (check Ollama/server logs), and to determine the active embedding model and any semantic cutoff. It also explains when not to rely on it: it doesn't filter search results, and it clarifies that automatic abstention is not part of the default retrieval contract. This is strong usage guidance.

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