list_memories

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

Even with readOnlyHint=true, the description goes far beyond that annotation to explain the honored content budget, newest-first ordering, row-degradation mechanics, preview cap, suffix fields, ref expansion behavior, and budget_chars presence. It also covers edge cases like all-agent listings and preview-cap-0 disabling trimming. This is exemplary behavioral disclosure — the agent is fully informed about response size limits, truncation, and associated fields without having to guess.

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 long and dense, but it front-loads the core purpose in the first sentence, then structures the rest around the bug-255 behavior and its consequences. The detail is necessary for a tool with no output schema, and the organization (budget → degradation → edge cases) makes it navigable. It could arguably be trimmed, but the density is justified by the complexity of the response contract.

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, this description carries the full burden of explaining the response shape — and it does so thoroughly: rows, degradation conditions, truncation fields, ref expansion, budget_chars, and the scaling ceiling. It also covers the all-agents pairing nuance and the preview-cap edge case. The description is complete enough for an agent to correctly interpret and invoke the tool, including handling the 'ref' expansion via get_contents.

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 input schema already provides 100% coverage for all three parameters (limit, agent_id, project_id), each with descriptive text — project_id's is especially detailed. The tool description adds zero parameter-level information; it focuses entirely on response behavior. Per the rubric, with schema coverage >80%, a baseline of 3 is appropriate, and no extra value is added here.

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 a clear verb-object pair — 'List recent memories for an agent' — and adds the dashboard-display context, making the tool's primary function unmistakable. While it doesn't name sibling tools, the distinction from recall/store/get_contents is evident from 'list recent' versus retrieval/storage actions. The purpose is specific and unambiguous.

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 states a clear use case: 'for dashboard display,' which implicitly signals this is for lightweight listing rather than full recall. It does not explicitly name alternatives or exclusionary conditions (e.g., 'use recall for full content'), but the dashboard-display context implies a preference for this tool over more memory-heavy operations. The guidance is adequate but could be stronger with an explicit 'use this when…' statement.

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