get_fact

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

With no annotations provided, the description carries the behavioral burden, and it does add genuinely useful context by explaining the bitemporal semantics of at and world_at, including an example phrase like 'per what the bank knew on 15 June, what held in May.' However, it does not disclose what happens when at or world_at are omitted (both are nullable with defaults), how missing facts are handled, or any access/error behavior. This is useful but incomplete.

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 output scope and then adds a compact explanation of bitemporality, which is necessary complexity. Every sentence earns its place, though the second paragraph is dense enough that an example input/output pair would have made it clearer without much extra length.

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?

Given there is no output schema and no annotations, the description needs to cover both call semantics and return contract; it covers the return fields and the time-axis model well. It stops short of explaining the default behavior when at and world_at are null, how qname selects the fact uniquely, or what happens when no fact exists, leaving an agent to make reasonable guesses. It is adequate but has clear gaps.

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, and it does so significantly for the two time parameters. It defines at as transaction time over valid_from/valid_to and world_at as world time over world_valid_from/world_valid_to, giving an agent meaning far beyond the bare schema titles. qname is left implicit by its name, and the null-default behavior is not explained, but the parameter semantics provided are strong where schema coverage is weakest.

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 opens with 'A single fact with full provenance,' which clearly identifies the resource returned and its scope. It lacks an explicit verb like 'retrieve' or 'look up,' and it does not differentiate get_fact from siblings such as list_facts or search, but the 'single fact' framing is specific enough for an agent to infer the core purpose.

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?

There is no guidance on when to use get_fact versus list_facts, search, precedents, or check. The bitemporal explanation implies when time parameters matter, but the description never states the selection condition (for example, 'use this when you know the qname and need one fact with provenance'). The agent is left to infer usage from the tool name and sibling names.

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