scout_note

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 reveals that notes are dated, attributed to the acting role, and deduplicated, and that the file is human-readable and correctable. It also states that it stores understanding so every run starts smarter, implying persistence across sessions. No contradictions with annotations (none exist), and the description fully explains the tool's behavior.

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 densely informative yet well-organized. It front-loads the core purpose and file path, then explains actions with examples, lists the sections inline, and closes with a clear exclusion rule. Every sentence earns its place; there is no fluff or repetition. The use of parentheses and examples makes it scannable without losing depth.

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 tool has 4 parameters, 2 enums, and no output schema, the description covers all necessary aspects: what it does, when to use it, how to use each parameter, what content to store, and what to avoid. It even explains the file location and the distinction from memory.json. An agent could confidently call this tool correctly after reading the description alone.

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 coverage is 100% (all parameters have descriptions), but the description adds significant meaning beyond the schema. It explains the action enum (read/add) and how to combine with section and note, gives concrete examples of section values, and clarifies the session parameter's concurrency behavior. This enriches the agent's understanding of how to construct valid calls, far exceeding the bare schema descriptions.

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: it stores cumulative WRITTEN knowledge about the tested app in ASSUMPTIONS.md, and supports reading and adding durable learnings. It distinguishes itself from memory.json (coverage) and from sibling tools like scout_finding by focusing on durable understanding rather than session-specific events. The verb 'read' and 'add' are explicit, and the resource (knowledge store) is named.

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 instructs to READ at the start of every session and to ADD durable learnings as you go, with concrete examples of what to record (app-model, roles, conventions, constraints, risks, glossary) and what NOT to record (session-specific facts like ids and counts). This gives clear when-to-use guidance and even defines the exact action pattern. It implicitly differentiates from other scout tools by focusing on knowledge accumulation rather than immediate actions.

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