semantic_searchSearch the user's document vault semantically. Returns only the most relevant chunks (minimal tokens).
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | ||
| query | Yes | Natural language search query | |
| top_k | No | Number of chunks (default 5, max 20) | |
| document_ids | No |
Changes observed during successful MCP inspections. Dates show when Glama detected each change.
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the operation read-only and non-destructive. The description adds valuable behavioral context by stating it returns only the most relevant chunks and minimizes token usage, which informs the agent that output is distilled rather than full documents. This goes beyond annotation data without contradicting it.
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 a single, tight sentence followed by a short, informative clause. Every word earns its place, and the core action is front-loaded. No filler or redundant restatement of the tool name is present.
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 is adequate for a simple semantic-search tool, especially given the annotations, but it omits key contextual details such as how filtering parameters affect the search and what the returned chunk structure looks like. Since there is no output schema, a bit more detail about the return format or behavior with no matches would improve completeness.
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 only 50%, and the description does not compensate for the undocumented tags and document_ids parameters. It does not explain that tags can filter results or that document_ids restrict the search scope; it only references the query concept implicitly. With half the parameters left unexplained, the description fails to add meaning beyond 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 names a specific verb ('Search'), a specific resource ('the user's document vault'), and the search method ('semantically'), which clearly distinguishes it from sibling tools like semantic_search_media or find_documents_by_name. The added detail about returning relevant chunks further clarifies its role as a chunk-level retrieval tool.
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 implies a semantic-search use case but gives no explicit guidance on when to choose this tool over siblings such as find_documents_by_name or semantic_search_media. There is no mention of exclusions, preferred scenarios, or alternatives, leaving the agent to infer routing from the tool name and context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
Most tools have clearly distinct resource-action pairs, but the media tools overlap somewhat: get_relevant_frames, get_media_description, and semantic_search_media can all return frame or transcript content. The descriptions clarify scope, but an agent could briefly hesitate before choosing between them.
The set mostly follows a verb_noun pattern like list_user_documents, get_chunk, and summarize_document. However, semantic_search and semantic_search_media break the pattern by leading with an adjective, and list_user_documents uses a redundant 'user_' prefix that list_media does not.
Ten tools is well-scoped for a document and media vault assistant. Each tool addresses a distinct retrieval or summarization need without excessive redundancy or padding.
Search, list, summarize, compare, and media description workflows are well covered. However, get_chunk requires both document_id and chunk_id, and no tool enumerates chunk IDs or retrieves a full document's text, creating a potential dead end for agents that need complete document contents.