Skip to main content
Glama

Trace where a block came from

folio_provenance
Read-onlyIdempotent

Trace a block to its source file, lines, last change, embedded data files, queries, and claim checks. Explain why a number or table reads as it does or if a figure still matches its data.

Instructions

Trace one block of a page to its origin: the file and lines it comes from, when it last changed, the data files and queries behind its embedded tables and values with when each changed, and each figure in it checked against its data. Use it to explain why a number or table reads as it does, or whether a figure still matches its data; take the block's id - and, for a block an include brings, its source - from folio_document's page. For every problem in the folder at once use folio_health. An id not on the page is an error. Answers {source, kind, lines: [first, last], changed: ISO time, included: {section} for an included block, data: [{reference, files: [{path, changed}], query, error}], claims: [{figure, reference, state: matching, contradicted or unchecked, live: the data's value, reason, deliberate: true when left unchecked by choice, as a range is}], conventions}. A list cut to fit one answer adds omitted, the entries each list left out, and narrow, how to ask for less.

Input Schema

NameRequiredDescriptionDefault
pathYesThe page's path, relative to the served folder or absolute under it, such as notes/plan.md
blockYesThe block's id, 8 hex characters, as folio_document lists it
sourceNoThe file the block's text comes from when an include brings it onto the page, as folio_document's page names it; omit for the page's own blocks

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description adds substantial behavior: the exact answer fields, the three claim states including "deliberate" for intentionally unchecked figures like ranges, and the truncation contract ("omitted" plus "narrow" telling the agent how to ask for less). The error condition for an id not on the page is also disclosed.

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?

Purpose is front-loaded and every sentence carries information; the return-shape sentence is long and comma-dense, but it is doing necessary work since no output schema exists. Slight density cost rather than waste.

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?

With no output schema and a rich multi-part response, the description fully specifies the returned structure (source, kind, lines, changed, included, data, claims, conventions) and the pagination/truncation markers. An agent has everything needed to call it and interpret the answer.

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 coverage is 100%, so all three parameters are already documented in structured form; the description's statements about block id and source largely restate the schema. It adds little beyond the schema except the constraint that an id absent from the page is an error.

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?

Opens with a specific verb+resource ("Trace one block of a page to its origin") and enumerates exactly what is traced: source file and lines, last-change time, backing data files and queries, and per-figure claim checks. This is clearly distinguishable from folio_health (folder-wide problems) and from folio_document (page listing).

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?

Gives concrete when-to-use cases ("explain why a number or table reads as it does, or whether a figure still matches its data"), states where the required argument comes from ("take the block's id ... from folio_document's page"), names the alternative for the folder-wide case (folio_health), and flags the failure mode ("An id not on the page is an error").

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