Torus

Overview Schema Source Related Servers Discussions Admin

record_claim

Save one sourced finding about one or more entities in the knowledge graph. Use it to store facts, metrics, inferences, forecasts or opinions with supporting evidence, so theses and relations can cite them.

Instructions

Save one finding about one or more entities, tied to its sources.

    Record the source first with `record_evidence` and pass its id. A fact or
    metric without supporting evidence_ids is rejected, as is an inference with
    neither evidence nor derived_from. Returns the new claim with its id, which
    theses (`record_thesis`) and relations (`record_relation`) can cite. To fix
    an existing claim use `supersede_claim`, not a second record_claim.

Input Schema

Name	Required	Description
`text`	Yes	One atomic, self-contained statement, e.g. 'TSMC supplies over 90% of NVIDIA's data-center GPU wafers'
`entities`	No	Entities the claim is about (ticker, name or id); they are resolved
`valid_to`	No	When it stopped being true; omit if it still holds
`mentioned`	No	Entities only mentioned in passing
`claim_type`	Yes	fact or metric (must cite evidence_ids), inference (evidence or derived_from), forecast, or opinion
`confidence`	Yes	0 = guess, 1 = certain
`valid_from`	No	When the statement became true (UTC if no zone); omit if unknown
`derived_from`	No	Claim ids an inference builds on
`evidence_ids`	No	Supporting source ids from record_evidence
`contradicting_evidence_ids`	No	Source ids from record_evidence that cut against it

Output Schema

Name	Required	Description	Default
`id`	Yes
`text`	Yes
`status`	Yes
`entities`	Yes
`evidence`	Yes
`valid_to`	Yes
`claim_type`	Yes
`confidence`	Yes
`lineage_id`	Yes
`session_id`	Yes
`valid_from`	Yes
`recorded_at`	Yes
`derived_from`	Yes
`change_reason`	Yes
`superseded_at`	Yes
`supersedes_id`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed7 schema fields changedv0.1.1Oct 24, 2026

addedInput schema / properties / claim_type / description

Added value: +"fact or metric (must cite evidence_ids), inference (evidence or derived_from), forecast, or opinion"

addedInput schema / properties / contradicting_evidence_ids / description
```
Added value: +"Source ids from record_evidence that cut against it"
```

changedInput schema / properties / entities / description

Previous value: -"Entities the claim is about"New value: +"Entities the claim is about (ticker, name or id); they are resolved"

addedInput schema / properties / evidence_ids / description

Added value: +"Supporting source ids from record_evidence"

changedInput schema / properties / text / description

Previous value: -"One atomic, self-contained statement"New value: +"One atomic, self-contained statement, e.g. 'TSMC supplies over 90% of NVIDIA's data-center GPU wafers'"

addedInput schema / properties / valid_from / description

Added value: +"When the statement became true (UTC if no zone); omit if unknown"

addedInput schema / properties / valid_to / description

Added value: +"When it stopped being true; omit if it still holds"

First observedv0.1.0Oct 24, 2026

TDQS

A4.7/5.0

Behavior4/5

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

Annotations only declare the generic write profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), and the description adds real behavioral detail: validation rules that cause rejection, the returned id used for downstream citation, and the non-destructive correction path via supersede_claim. It stops short of describing the response shape or duplicate handling, so not a full 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four short sentences, each carrying distinct information: purpose, prerequisite, validation rule, return/citation contract, and the alternative for edits. The core purpose is front-loaded in sentence one.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-parameter write tool with an output schema, the description covers the prerequisite ordering, validation constraints, and the sibling that handles corrections, which are exactly the gaps structured fields cannot fill.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3; the description earns above that by adding cross-parameter business rules the schema only hints at, namely that fact/metric require evidence_ids and inference requires evidence_ids or derived_from, mapping directly onto claim_type plus the evidence/derived_from fields.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Save one finding') with its scoping constraint ('about one or more entities, tied to its sources'), which cleanly separates it from siblings like record_evidence, record_thesis, and record_relation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly names the prerequisite flow (call record_evidence first and pass its id), states rejection conditions per claim type, and names the alternative for corrections ('use supersede_claim, not a second record_claim'). Nothing about when to pick this tool is left to inference.

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