FileForge

Overview Schema Source Related Servers Discussions Admin

fileforge_result_action

Read-onlyIdempotent

Retrieve, list, search, or slice stored results from ~/.fileforge when a tool returns a ref instead of full data, so you can inspect saved output without the extension.

Instructions

Read results other tools stored in ~/.fileforge: fetch one by ref, list them, search them, or slice a large one. Use this when a tool returns a ref instead of full data. Use fileforge_sql_action to query across results and fileforge_export_action to write one to a file. Works without the extension.

Input Schema

Name	Required	Description
`ref`	No	The result ref (e.g. scrape_page_20260509_abc123)
`limit`	No	Maximum items to return.
`query`	No	Text to search stored results for.
`action`	Yes	What to do. Required parameters are in brackets. get (ref): Retrieve a stored result by its ref. list: List stored results, newest first. Optionally filter by project. search (query): Search stored results by keyword across URL, tool name, and data. slice (ref): Get a paginated slice of a stored result.
`offset`	No	Items to skip, for paging.
`project`	No	Filter by project name.

Output Schema

Name	Required	Description
`ok`	Yes	False if the action failed or a check did not pass.
`ref`	No	Stored result ID, for fileforge_result_action.
`data`	No	The result. Its shape depends on the action.
`meta`	No	Tool, action and context.
`error`	No	Failure code and message.
`warnings`	No	Notes about a call that still ran.

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedv0.3.0Nov 5, 2026

changedInput schema / properties / action / description

Previous value: -"The action to perform. Available actions: get: Retrieve a stored result by its ref. list: List stored results, newest first. Optionally filter by project. search: Search stored results by keyword across URL, tool name, and data. slice: Get a paginated slice of a stored result."New value: +"What to do. Required parameters are in brackets. get (ref): Retrieve a stored result by its ref. list: List stored results, newest first. Optionally filter by project. search (query): Search stored results by keyword across URL, tool name, and data. slice (ref): Get a paginated slice of a stored result."

addedInput schema / properties / limit / description
```
Added value: +"Maximum items to return."
```
addedInput schema / properties / offset / description
```
Added value: +"Items to skip, for paging."
```

addedInput schema / properties / query / description

Added value: +"Text to search stored results for."

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "description": "query_* actions return their modules as extra top-level fields.",
+  "properties": {
+    "data": {
+      "description": "The result. Its shape depends on the action."
+    },
+    "error": {
+      "description": "Failure code and message."
+    },
+    "meta": {
+      "description": "Tool, action and context."
+    },
+    "ok": {
+      "description": "False if the action failed or a check did not pass.",
+      "type": "boolean"
+    },
+    "ref": {
+      "description": "Stored result ID, for fileforge_result_action."
+    },
+    "warnings": {
+      "description": "Notes about a call that still ran."
+    }
+  },
+  "required": [
+    "ok"
+  ],
+  "type": "object"
+}

First observedv0.2.1Nov 5, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile is fully covered. The description adds genuinely new behavioral context: where results are persisted (~/.fileforge), that it operates on prior tool output rather than live data, and that it 'works without the extension' — a meaningful availability note given the fileforge_extension_action sibling. It stops short of disclosing retention/lifetime of stored refs or behavior on a missing ref, which keeps it out of the top band.

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, front-loaded with the core purpose before the conditional guidance and the alternative routing. Every sentence carries distinct information — none restates the name or the schema.

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?

With an output schema present, return-value explanation is correctly omitted, and the description covers purpose, trigger, storage location, and sibling routing for a six-parameter tool. The only real omission relevant to correct invocation is the lifecycle of stored refs (do they expire, are they session-scoped), which would help an agent decide whether a ref is still usable.

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% and the action enum already documents required parameters in brackets per action, so the schema does the heavy lifting. The description reinforces the action-to-parameter mapping ('fetch one by ref', 'slice a large one') but adds no syntax, format, or constraint detail beyond it. Baseline 3 is appropriate.

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 ('read results other tools stored in ~/.fileforge') and enumerates the four operations (fetch by ref, list, search, slice). It also names the two adjacent siblings it is not — fileforge_sql_action and fileforge_export_action — so the agent can distinguish it without opening schemas.

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 an explicit trigger condition ('when a tool returns a ref instead of full data') plus explicit alternatives with their selection criteria: sql_action for cross-result queries, export_action for writing to a file. This is when-to-use plus when-to-use-something-else, not just implied context.

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