memo_ask

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false; the description reinforces read-only behavior and adds context: synthesis runs on the calling model when client sampling is enabled, and source attributes consult logging. No contradictions; all details align with and extend annotations.

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 concise (three sentences) and front-loaded with the main purpose. It efficiently conveys core functionality and usage hints. However, it could be more structured (e.g., separating parameter explanations) to improve readability, but it remains relatively tight.

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?

Given the complexity (7 parameters, many siblings) and lack of schema descriptions, the description should provide more complete context. It covers the main idea but leaves significant gaps for parameters like session_id and include_repos. The presence of an output schema does not excuse missing parameter guidance. A more thorough explanation of retrieval tuning and optional features is needed.

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?

With 0% schema description coverage, the description is expected to explain parameters. It mentions k, type, snippet_chars for tuning retrieval, and source for logging, but omits session_id and include_repos entirely. It does not detail default values or allowed types. The coverage is insufficient for a 7-parameter tool.

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's purpose: 'Answer a question using memo retrieval and citations.' The verb 'answer' and resource 'memos' are specific, and it distinguishes itself from siblings by emphasizing 'synthesized answer grounded in durable memories instead of raw hit lists.' The read-only nature is explicitly noted, matching annotations.

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 explicitly states when to use: 'Use when you want a synthesized answer grounded in durable memories instead of raw hit lists.' It mentions parameters that tune retrieval (k, type, snippet_chars) and source for logging. While it doesn't explicitly name sibling alternatives, the context implies using memo_search for raw lists. It could be more direct about exclusions, but the guidance is clear.

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