List Memories

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

Annotations already mark this as read-only, idempotent, and non-destructive. The description goes further by explaining the 'up to limit records with their keys' return behavior, default values, and the non-trivial ordering semantics of `recent`, including persistent vs in-memory keyspace differences and fallback full scans. This is exactly the kind of behavioral context beyond annotations that agents need.

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 well-structured: purpose and routing are front-loaded, the returns behavior is stated immediately, and the Args section is compact with clear labels. The lengthy `recent` explanation is justified because it describes genuinely subtle ordering behavior, not fluff.

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 covers purpose, alternatives, output shape, defaults, and ordering behavior, making it largely complete for a read-only listing tool. However, the complete omission of the schema's `scope` parameter means an agent cannot know what that input controls or whether it is deprecated. For a tool with no output schema and no per-property schema descriptions, that is a meaningful completeness gap.

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?

The description documents keyspace, limit, and recent with defaults and behavioral details, which is valuable given the schema has 0% property descriptions. However, the `scope` parameter appears in the input schema and is never mentioned in the description, leaving its meaning completely unexplained. This is a clear gap in an otherwise strong parameter documentation effort.

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 opens with 'Browse stored memories — enumerate what is remembered, not search by meaning,' giving a specific verb, resource, and scope. It explicitly contrasts itself with montycat_semantic_search and montycat_recall, so the agent can distinguish this tool from its siblings immediately.

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?

'Use this to review or list memory; for meaning-based recall use montycat_semantic_search, and for exact lookups use montycat_recall' is explicit when-to-use guidance with named alternatives. The negative constraint 'not search by meaning' also clarifies when not to use it.

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