fact_set

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

With zero annotations the description carries the full burden, and it delivers the non-obvious traits: the previous value is closed at exactly that instant and never deleted (append-only, reversible by writing a new interval). It also discloses a hard validation rule (canon subjects need evidence) and an authorization rule (owner-only predicates are refused). It omits failure behavior on conflicting or duplicate writes and never mentions the agent/api_key parameters.

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?

Dense but every clause carries information, and the core assertion is front-loaded ahead of the temporal and evidence caveats. The parenthetical canon list and the trailing record_decision pointer are compact; 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?

For an unannotated mutation tool with no output schema, the description covers the semantics an agent needs to call it correctly (interval closing, evidence requirement, refused predicates, valid_from default). The missing pieces are the unexplained agent/api_key parameters and the response shape, which are secondary but not negligible.

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% across 8 parameters, so the description must compensate, and it covers only about half: subject, predicate, value, valid_from default, evidence via the canon rule, and project via 'whatever the project'. agent and api_key are left entirely unexplained, which for an unannotated 8-param tool is a real gap.

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 precise verb-and-resource pair, 'Assert subject.predicate = value from valid_from', and pins down the temporal write semantics rather than just naming the operation. It is trivially distinguishable from siblings fact_get (point read) and fact_history (timeline read) because it says the write closes the prior interval.

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 routes the agent by consequence: open a new interval here so fact_get(as_of=...) can answer 'what was true then', and it names record_decision(sets=...) as the required path for owner-only predicates. That is concrete when-to-use and one explicit exclusion, though it doesn't say when a read or fact_history is preferable to writing at all.

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