Search shared AI-agent context by keyword to find prior checkpoints, failures, and task handoffs; returns short excerpts with IDs for follow-up retrieval.
Search shared context by keyword. Returns short excerpts with ids; use get_audit_trail or load_context detail "full" for more.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Most results to return (default 8) | |
| query | Yes | Search query |
Changes observed during successful MCP inspections.
v3.1.1Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already declares this a safe read, and the description adds genuinely new behavior: results are excerpts, not full documents, and each carries an id for follow-up. It does not mention result caps or pagination behavior, though the limit parameter partly covers that.
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?
Two compact sentences, with the core action front-loaded and the alternative-tool guidance immediately after. No filler or duplication.
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?
With no output schema, the description supplies the essential return contract (short excerpts with ids) and a next step for full content. Given a 2-parameter tool with 100% schema coverage and a readOnly annotation, nothing critical is missing.
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 both query and limit are already documented, including the default of 8 and max of 25. The description only restates that the search is keyword-based, adding no syntax, matching, or format guidance 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?
States a specific verb and resource ('Search shared context') plus the retrieval unit ('by keyword') and return shape ('short excerpts with ids'). It names sibling tools (get_audit_trail, load_context) but only as fallbacks for depth, not as a clear differentiation of scope.
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 a clear use case (keyword search over shared context) and an explicit routing rule to alternatives when fuller detail is needed. It stops short of saying when NOT to use it or how it differs from a full context dump beyond the 'detail full' hint.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.