ddflow_session_note

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

With no annotations provided, the description carries the behavioral disclosure burden. It does disclose that the content 'goes into the reconstruction alongside the prompts,' giving a useful side-effect hintokus, but it does not mention whether the record is append-only, editable, or how it affects later reconstruction. The second sentence adds motivational framing but no concrete behavioral detail.

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?

Two sentences, with the core action and boundary conditions in the first sentence and a reinforcing rationale in the second. Every clause earns its place and no space is wasted on repetition of the schema.

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 simple create-note tool with three parameters and no output schema, the description covers the purpose, content guidance, and the relationship to the reconstruction. It could have explicitly noted whether the note is immediately persisted or appended, but the essential invocation context is present.

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%, so the baseline is 3 ate. The description adds meaning beyond the schema by clarifying that 'text' should contain surprises, dead ends, or rationale for changes – content guidance not present in 'The note.' It provides some help for 'session' implicitly via the session start context but adds little for 'item.'

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 'Record something that happened during a session' – a specific verb and resource – then sharpens the scope by explicitly excluding operator prompts and decisions. It gives concrete examples (surprise, dead end, changed approach) and the mention of 'reconstruction alongside the prompts' distinguishes it from sibling note-taking flows.

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 clearly indicates when to use this tool: for unexpected events, dead ends, and strategy changes. It also says what it is not for ('neither an operator prompt nor a decision'), which indirectly routes an agent away from ddflow_session_prompt and ddflow_decision_add, though it does not name those siblings directly.

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