Semantic Search

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds genuinely new context: entries are auto-indexed on creation and the index can drift and be rebuilt, plus how threshold values change result breadth. Pagination and limit behavior remain unstated.

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?

Four sentences, front-loaded with purpose, then modes, then the tuning advice, then the index-maintenance escape hatch. Every sentence carries information an agent would otherwise have to guess at.

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 17-parameter, zero-required tool with an output schema and rich annotations, the description covers the key modes, the tunable that matters most, and the failure/recovery path. The remaining gap is routing: nothing tells the agent when to prefer this over search_entries, cross_team_search, or team_semantic_search.

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 76%, so most parameters are documented structurally, but the description adds the one thing the schema omits entirely: what similarity_threshold actually does and how to tune it. It also clarifies the entry_id mode ('find-related-by-ID'). However, several of the 17 parameters (is_personal, include_archived, include_team, limit) get no prose attention.

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 and resource ('Perform semantic/vector search on journal entries using AI embeddings') and names the two operating modes (find-related-by-ID vs. metadata filtering). It implicitly distinguishes itself from keyword siblings like search_entries via the word 'semantic', but never names an actual sibling, so it stops short of a 5.

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 concrete tuning guidance for the threshold (0.25 default, 0.15-0.2 for broader, 0.4+ for strict) and explicitly routes to rebuild_vector_index when the index has drifted — a real alternative-selection rule. It lacks guidance on when to choose this over search_entries or team_semantic_search, which keeps it below a 5.

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