twining_archive

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

With no annotations provided, the description carries the full burden. It discloses preservation of decision entries and unresolved needs/warnings, the definition of resolved (#40), optional summary posting, and the potentially dangerous default cutoff of now. This gives the agent a thorough understanding of side effects.

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 three sentences, front-loaded with the core action, and includes an essential WARNING about the default cutoff. Every sentence adds value, no filler or redundancy.

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?

Despite having no annotations or output schema, the description covers purpose, side effects, preservation rules, defaults, and cautionary usage. This is sufficient for a mutation tool with nuanced retention logic.

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 covers all 5 parameters with descriptions, so baseline is 3. The description adds valuable context about defaults (cutoff now, retain N), which entries are exempt, and how resolved status is determined, enhancing understanding beyond raw schema definitions.

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 archives old blackboard entries and explains the mechanism (moves entries older than a cutoff to an archive file). However, it does not explicitly differentiate from sibling tool twining_archive_stale, which may have overlapping functionality.

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?

Provides clear context including the cutoff default of now and advice to pass `before` or `retain` unless a full sweep is intended. It also explains what entries are preserved. It does not mention when to prefer this tool over alternatives or provide explicit when-not-to-use conditions.

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