FileForge

Overview Schema Source Related Servers Discussions Admin

fileforge_note_action

Create, list, and search local notes to save debugging findings across sessions; notes persist in ~/.fileforge for later reference.

Instructions

Keep local notes: create, list and search them. Use this to save findings across sessions. Use fileforge_memory_action to save page content and fileforge_report_action for shareable evidence. Notes stay in ~/.fileforge, and there's no update or delete action.

Input Schema

Name	Required	Description
`tag`	No	Tag to filter by.
`url`	No	Associated URL, if any
`body`	No	Note text.
`tags`	No	Tags to attach.
`limit`	No	Maximum items to return.
`query`	No	Text to search notes for.
`title`	No	Note title.
`action`	Yes	What to do. Required parameters are in brackets. create (title, body): Create a local note. list: List saved notes. search (query): Search notes by text.
`offset`	No	Items to skip, for paging.

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.

Changed9 schema fields changedv0.3.0Nov 5, 2026

changedInput schema / properties / action / description

Previous value: -"The action to perform. Available actions: create: Create a local note. list: List saved notes. search: Search notes by text."New value: +"What to do. Required parameters are in brackets. create (title, body): Create a local note. list: List saved notes. search (query): Search notes by text."

addedInput schema / properties / body / description
```
Added value: +"Note text."
```
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 notes for."
```
addedInput schema / properties / tag / description
```
Added value: +"Tag to filter by."
```
addedInput schema / properties / tags / description
```
Added value: +"Tags to attach."
```
addedInput schema / properties / title / description
```
Added value: +"Note title."
```

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.3/5.0

Behavior4/5

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

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), and the description adds real context beyond them: notes persist only in ~/.fileforge and there is no update or delete action, which tells the agent writes are effectively append-only and irreversible in scope. What is missing is anything about search matching behavior (substring vs. tag semantics) or how tags/URLs relate to a note.

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?

Three tight sentences, capability and storage location front-loaded, alternatives second, the no-update/delete constraint last. Every sentence earns its place; slight compression of the trailing constraint into the first sentence would be marginally tighter.

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 the description needn't explain return values, and annotations carry the safety profile, so coverage of purpose, alternatives, storage location, and lifecycle limits is nearly complete for a 9-param tool. The only real gap is how filtering/search inputs interact with the returned note fields.

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% and the action enum itself documents required parameters per action, so the schema does the heavy lifting. The description adds no additional parameter meaning (e.g., how tag differs from tags, or whether limit/offset apply to search as well as list), so baseline 3 applies.

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 set and resource ('Keep local notes: create, list and search them') and immediately distinguishes the tool from sibling note-adjacent tools by naming fileforge_memory_action and fileforge_report_action. An agent can route between them 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?

Explicit when-to-use ('save findings across sessions') plus explicit alternatives and the condition that selects each ('fileforge_memory_action to save page content', 'fileforge_report_action for shareable evidence'). Nothing 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.