learn_collect

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

No annotations are provided, so the description carries the full behavioral burden. It discloses key traits: writes a run directory with specific artifacts (sessions, surfaces, usage, phrases, plan.json mapper shards), default scope is all history, and it does not change skills. However, it omits critical mutation details: whether it overwrites existing run directories, permission requirements, and destructive potential. The 'Does not change skills' is a useful safety clarification, but gaps remain for an 11-param write tool.

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?

Three sentences that are front-loaded: the primary action first, then output artifacts, then safety note. Efficient, though the second sentence is slightly dense with artifacts.

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 an 11-parameter write tool with no annotations, no output schema, and 36% schema coverage, the description is significantly incomplete. It lacks details on most parameters, behavioral constraints like overwrite behavior or permissions, and how the estimator mode differs. The basic purpose and output are covered, but much is missing for correct invocation.

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 36%, well below 50%, so the description must compensate. It mentions default scope (all history) which relates to time-based params, and describes the run directory output that out parameter controls, but does not explain semantics for cwd, days, agent, batch, limit, since_last, drop_pattern, include_headless, or include_subagents. The schema provides descriptions for only 4 parameters, leaving many undocumented in both places.

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 states a specific verb+resource: 'Collect compact session records from every local agent for /learn, or estimate the cost of a run.' It distinguishes the dual-mode operation and names the /learn context. No sibling tools overlap this collection behavior, though the description doesn't explicitly contrast with learn_state or session_digest.

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?

It implies usage ('for /learn') and notes the estimate mode, but doesn't specify when to use collection vs. estimation, or how it relates to sibling tools like learn_state or session_digest. The when is only hinted at through the /learn reference.

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