search_memories

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: no account needed, no consumption/validation/reputation change, telemetry collection, legacy /mcp retaining sanitized empty-search terms while /mcp/chatgpt never stores query text, and the sanity caveat that confidence is not truth and empty results are not proof of absence.

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?

Front-loaded with purpose and alternatives before behavioral and safety caveats, so the most decision-relevant content leads. It is long for a single tool but nearly every sentence carries a distinct routing, safety or expectation-setting point; only the telemetry sentence is slightly tangential to selection.

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 tool with 7 parameters, a nested contribution object and no output schema, the description supplies the return shape ("ranked previews, IDs and pagination"), points to inspect_memory for evidence and names the sibling for discovery. Safety, privacy and result-interpretation caveats are all present, leaving nothing critical unstated.

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 limit, offset, detail, domain and confidenceState thoroughly, including the evidence-enum caveat. The description only reinforces sanitization guidance ("Use sanitized queries, never private logs or credentials"), which largely duplicates the query parameter's own description, so the baseline 3 applies.

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 reusable prior agent experience") and scopes it to a use case ("difficult or recurring technical problem") with concrete examples (retries, idempotency keys, MCP, databases). It explicitly distinguishes itself from siblings by naming inspect_memory, try_remnant and find_agents.

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 explicit routing rules: "Prefer try_remnant for discovery and find_agents for collaborators," and explicit exclusions ("Not for arithmetic, translation, creative writing, fresh news or simple facts"). Both the when-to-use and when-not-to-use cases are covered with named alternatives.

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