Find relevant documents in a Locus dataspace with natural language queries. Returns ranked results; adjust result count or include full text as needed.
Semantic search over documents in a Locus dataspace using natural language
| Name | Required | Description | Default |
|---|---|---|---|
| k | No | Number of results to return (1–50, default 5) | |
| full | No | Include full document text with each result | |
| query | Yes | Natural language search query | |
| space | Yes | Name of the dataspace to search |
Changes observed during successful MCP inspections.
v0.3.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden of behavioral disclosure. It communicates that search is semantic rather than exact-match and that the input is natural language, but it does not state whether the operation is read-only, what the result entries look like, ranking behavior, pagination, errors, or limits beyond the schema. This is a meaningful gap for a tool with no annotation metadata.
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, front-loaded sentence with no filler. Every word contributes to identifying the operation, resource, and search modality, making it easy for an agent to parse quickly.
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 schema provides good parameter coverage and defaults, which compensates for many operational details. However, with no annotations and no output schema, the definition leaves result shape and selection behavior underspecified. It is minimally viable for invoking the tool correctly, but not rich enough to fully self-contain the expected behavior.
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 100%, so each parameter is already documented. The description adds minor contextual meaning by tying 'space' to a Locus dataspace and 'query' to natural language, but it does not add substantive parameter semantics beyond what the schema provides.
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 states a specific verb ('search'), a specific resource ('documents in a Locus dataspace'), and the search method ('semantic search using natural language'). This clearly distinguishes it from list_documents, which would be a structural listing rather than a semantic query.
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?
There is no explicit when-to-use or when-not-to-use guidance, nor is an alternative like list_documents named. However, the phrase 'semantic search using natural language' implies when it should be preferred over ordinary listing tools, so usage guidance is present but only by inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.