retractFact

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

With no annotations, the description carries the full burden and does most of it well: history is PRESERVED (unlike forget, which deletes the row), the value drops out of current reads, and critically the slot reads as EMPTY with no fallback to an earlier value. It stops short of stating failure/idempotency behavior (e.g. what happens if the slot has no open value, or if the same retraction is issued twice).

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?

Front-loaded with the core action and its counterpart, then consequences, then alternatives — a sensible order. It runs long for what it says and leans on capitalization for emphasis, but no sentence is filler.

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?

An output schema exists, so return values need no explanation, and the description covers side effects, data retention, and read-visibility well. The remaining gap is edge-case behavior — empty slots, repeated retractions, and failure modes — which matters for a mutation with zero annotation coverage.

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 both invocation paths and the oneOf exclusivity are already documented in the schema. The description reinforces the either/or ('Use THIS or a (subject, stateKey) pair, not both') and adds the semantic that the pair closes the slot's single open value, but adds no format or scope guidance beyond what the schema states.

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?

States a specific verb and resource ('Close the current value of a fact slot') and immediately positions it against two siblings: the scalar counterpart to unrelate, and distinct from forget (which deletes). An agent can pick this tool over forget/fact/unrelate without opening any schema.

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?

Explicit when-to-use ('a status that no longer holds, a preference that changed with no replacement') and an explicit when-not/alternative: 'To set a different value instead, just write it with fact().' Both identification paths are named, so the agent also knows the two valid invocation modes.

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