capture_session

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

With no annotations, the description carries the behavioral burden and does it well: it reveals that the tool only files the summary, creates a note marked undistilled, and drops a pointer into today's log. It also warns against transcript-style content, giving the agent a clear boundary on what the persisted artifact should be. It does not cover deeper concerns like authentication or reversibility, but the disclosed side effects are the key ones here.

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 front-loaded with the core purpose, then gives actionable guidance in compact, high-density sentences. Each sentence earns its place: purpose, division of labor, content expectations, and side effects. There is no filler or 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 tool with 8 parameters, no annotations, and no output schema, this description is unusually complete. It tells the agent what to prepare, what content the summary must contain, and what physical effects to expect in the vault. A small gap is the lack of guidance on how the optional session_id, tags, and project parameters relate to the overall capture workflow.

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 description coverage is 0%, so the description must compensate; it does for the most important parameters. It tells the agent that the summary should contain what was being done and why, and it explicitly maps the content categories to decisions, open questions, and artifacts. Tags, project, and session_id remain only schema-explained by name and type, which is a minor gap for optional fields.

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 action: 'Persist the current session into the vault -- the `/compact` step.' It goes further by explaining the concrete result: a note in the sessions folder marked undistilled and a pointer in today's log. This distinguishes it from generic note-creation siblings like create_note.

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 gives explicit when-to-use context ('the /compact step') and detailed before-calling instructions: the agent must compact the session into durable facts covering what/why, decisions, open questions, and artifacts. It does not explicitly name alternatives or say when not to use the tool, so it stops short of a 5.

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