Search Memory

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. It does well by specifying the return format ('compact index ~50-100 tokens/result') and scope ('searches across all observations stored from any IDE session'). However, it doesn't mention important behavioral aspects like whether this is a read-only operation, potential rate limits, authentication requirements, or error conditions. The description adds useful context but leaves gaps in behavioral 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 efficiently structured in three sentences: first states the core purpose and return format, second provides explicit sibling tool differentiation, third clarifies the search scope. Every sentence earns its place by adding distinct value - no wasted words, and the most important information (what it does and when to use alternatives) is front-loaded.

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 search tool with 8 parameters and 100% schema coverage but no annotations or output schema, the description provides good contextual completeness. It explains the return format (compact index), distinguishes from siblings, and clarifies the cross-session search capability. However, without an output schema, it could benefit from more detail about the structure of returned results. The description is mostly complete but has minor gaps in output specification.

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 the schema already documents all 8 parameters thoroughly with descriptions and enums. The description doesn't add any parameter-specific information beyond what's in the schema. It mentions the tool searches memory but doesn't elaborate on how parameters like 'type', 'scope', or 'status' affect the search behavior. The baseline 3 is appropriate when the schema does the heavy lifting.

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 clearly states the tool searches project memory with a specific verb ('Search') and resource ('project memory'), distinguishing it from siblings like memorix_detail (fetches full content) and memorix_timeline (shows chronological context). It explicitly mentions searching across all observations from IDE sessions, which clarifies its scope beyond basic search functionality.

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 provides explicit guidance on when to use alternatives: 'Use memorix_detail to fetch full content for specific IDs' and 'Use memorix_timeline to see chronological context.' This clearly differentiates this tool's role (compact index search) from sibling tools, helping the agent choose appropriately based on the need for full content vs. search results vs. timeline views.

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