Skip to main content
Glama
Sign In
folio

folio

by jakubro
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Find what elsewhere in the folder says the same

folio_related
Read-onlyIdempotent

Find passages in other documents that restate a decision or cover the same ground as a page block or a question, using local embeddings and only where a related section declares them.

Instructions

Find the blocks of other documents closest in meaning to one block of a page, or to a question in your own words - passages that restate a decision or cover the same ground, whether or not anything links them. Folio works this out with a small embedding model on the reader's machine, only for documents below a FOLIO.md whose related section asks for it. Take the block's id from folio_document; a short structural line or a block repeated word for word across documents answers no blocks. For links between documents use folio_query over folio.links. Answers {asked: false} where no declaration asks; else {asked: true, state: {status: installing, downloading, indexing, ready or failed, done, total, message}, related: [{path, block, lines: [first, last], title, text: the block's words, closeness: the cosine of the two vectors, higher is closer}], version}; only status ready answers blocks, so while indexing ask again shortly. 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
pathNoThe page's path, relative to the served folder or absolute under it, such as notes/plan.md; omit with question
blockNoThe 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; omit for the page's own blocks
questionNoWords to find the closest blocks to instead of a block

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Annotations only declare read-only/idempotent/local; the description adds far more: local embedding model, per-document opt-in via FOLIO.md, the full status lifecycle (installing, downloading, indexing, ready, failed), the {asked: false} case, and the rule that only 'ready' answers blocks. It also discloses truncation behavior (omitted, narrow) and that closeness is a cosine similarity where higher is closer.

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?

Front-loaded with the core purpose followed by prerequisites, alternatives, and response shape; nearly every clause carries operational information. It is dense and the response-shape sentence is long, but with no output schema that detail is justified rather than padding.

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 tool with no output schema, the description supplies the complete return contract (asked/state/related fields including lines, text, closeness, version) and the follow-up protocol for non-ready states. Combined with the FOLIO.md prerequisite, an agent has everything needed to call it and interpret the result.

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 the baseline is 3; the description adds mode-selection meaning beyond the schema by framing path/block/source as the block-identity route versus question as the alternate free-text route, and by noting source matters only when an include brings text onto the page. It doesn't add format detail for the 8-hex block id, but the schema already carries that.

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: 'find the blocks of other documents closest in meaning' to either a given block or a free-text question. It names the mechanism (a local embedding model) and explicitly contrasts with sibling folio_query ('For links between documents use folio_query'), so an agent can pick it apart from folio_document and folio_query without opening a 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?

Gives explicit when-to-use routing: take the block id from folio_document, use question instead of a block for free-form search, and use folio_query for links. It also states the precondition (only documents under a FOLIO.md whose related section asks for it) and what to do mid-index ('while indexing ask again shortly'), plus when the tool is a no-op (structural lines, duplicated blocks).

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

Deploy Server

Other Tools