Skip to main content
Glama

save_fact

Records a datasheet value with its source, page, and model ID for later retrieval, so a new session can find facts already read instead of saving duplicates.

Instructions

Save a value that you read from the original, with its source and your model ID, so that a later session finds it with find_facts. Before you read a value, look for it with find_facts: do not save a value two times. A new fact has the state unchecked. Gives the fact number.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "document": "<document>",
      "page": "<page>",
      "subject": "<subject>",
      "value": "<value>"
    },
    "name": "save_fact"
  }
}

Input Schema

NameRequiredDescriptionDefault
bboxNoOr the region that holds the value: [x0, y0, x1, y1] in pt.
noteNoA note, for example a footnote of the table.
pageYesThe page number, from 1, as get_index and search_text give it.
partNoThe part that the value is for, when the document covers more parts: a part that the store has (list_parts), else an error.
unitNoThe unit, for example V, mA, °C.
modelNoYour model ID, for example claude-opus-5-5.
valueYesThe value as the original shows it, for example "3.6". One value: for MIN, TYP and MAX, save one fact for each column. A range with no columns: "1 to 22".
columnNoThe table column of the value: MIN, TYP or MAX.
elementNoThe element ID that holds the value, for example p7.T1.
subjectYesWhat the value is, for example "VDD maximum" or "CTRL register reset value".
documentYesThe document: its reference from list_documents, project_status or add_document (the first 12 characters of its SHA-256). A longer SHA-256 prefix or the numeric document ID also works.
conditionsNoThe conditions of the value, for example "TA = 25 °C, VDD = 3.3 V".

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.5.0
    • changedInput schema / properties / part / description
      Previous value: -"The part that the value is for, when the document covers more parts."New value: +"The part that the value is for, when the document covers more parts: a part that the store has (list_parts), else an error."
  2. First observedv0.1.0

TDQS

A4.3/5.0
Behavior4/5

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

With no annotations, the description carries the full disclosure burden, and it delivers real behavior: the resulting state is 'unchecked', the call returns the fact number, and the dedupe rule implies saving is NOT idempotent — duplicates are the caller's responsibility, not something the server silently collapses. It stops short of saying what happens on an existing fact, what validation is applied to 'value', or whether the write is reversible.

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

Conciseness4/5

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

Four short sentences, all front-loaded: purpose, then the dedupe workflow, then result state, then return value. Slight awkwardness in 'Before you read a value, look for it with find_facts' — the ordering is a little tangled — but nothing is redundant or padded.

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

Completeness4/5

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

For a 12-parameter mutation tool with no annotations, the description covers purpose, the dedupe workflow, resulting state, and return value; the output schema handles return shape and the input schema handles field meanings. The remaining gap is error/conflict semantics (existing duplicate, unknown part, bbox vs element disagreement), which the description does not address.

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

Parameters3/5

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

Schema description coverage is 100%, including nuanced fields (bbox vs element, part must exist in list_parts, document ID formats), so the schema already does the heavy lifting and a 3 is the baseline. The description adds only framing ('with its source and your model ID') and does not clarify interplay among document/page/element/bbox beyond what the schema states.

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?

The first sentence states a specific verb and resource ('Save a value that you read from the original') plus the provenance payload (source, model ID), and it names the payoff ('a later session finds it with find_facts'). That routes the agent away from the read-side sibling find_facts without opening either schema.

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?

Explicit lifecycle guidance: pre-check with find_facts before reading, an explicit prohibition ('do not save a value two times'), and the post-condition (new fact is 'unchecked', use set_fact_status territory). The alternative tool is named and the condition that selects it is stated, which is exactly what usage guidance should do.

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