FileForge

Overview Schema Source Related Servers Discussions Admin

fileforge_browser_action

Destructive

Manage browser tabs and read browser state: navigate, switch, reload, close, move through history, wait for pages, and query context. Dry-run bulk closes to prevent lost work.

Instructions

Manage tabs and read browser state: go to a URL, switch, reload and close tabs, move through history, wait for a page, and list open tabs. Use query_context to see what's open, and fileforge_page_interaction to act inside a page. Closing tabs can lose unsaved work, and close_tabs_matching can close many at once, so try dryRun first. Sensitive tab URLs are redacted. Needs the extension.

Input Schema

Name	Required	Description	Default
`url`	No	URL for navigate or open_url_with_capture.
`query`	No	Fine-grained projection for query_context. Sections: activeTab, tabs, windows, summary, privacy. Merged on top of preset.
`store`	No	Save the result in ~/.fileforge and return a ref.
`tabId`	No	Tab ID or "active". Omit in navigate for smart URL-reuse behaviour.
`until`	No	Condition to wait for.	load
`action`	Yes	What to do. Required parameters are in brackets. navigate (url): Go to a URL in a tab, or in a new tab with newTab. open_url_with_capture (url): Open a URL with capture on and return what it loaded. Closes the tab afterwards unless keepOpen is set, and stores the result by default. activate_tab (tabId): Switch to a tab. close_tab (tabId): Close a tab. Unsaved work in it is lost. reload_tab: Reload a tab, optionally bypassing the cache. history: Go back or forward in a tab. Goes back unless direction says otherwise. wait: Wait until a tab reaches until: load (the default), idle, or url, which also needs urlIncludes. query_context: Read open tabs, windows and the active tab, using a preset or a query. Changes nothing. close_tabs_matching: Close tabs matching urlIncludes or titleIncludes. Use dryRun to preview; keepActiveTab is on by default.
`active`	No	Focus the tab after navigate / open.
`dryRun`	No	Simulate without closing.
`idleMs`	No	Quiet period before considering tab idle.
`newTab`	No	Force a new tab in navigate even if an existing tab has the same URL.
`preset`	No	Preset for query_context. "snapshot" is the automation sweet spot (active tab + nav + compact tabs). "basic" is cheaper (no nav fields).
`project`	No	Project name that groups stored results.	default
`keepOpen`	No	Leave tab open after capture.
`settleMs`	No	Milliseconds to wait after load before capturing.
`direction`	No	Direction for history action.	back
`timeoutMs`	No	Time limit in milliseconds.
`includeHar`	No	Include a HAR capture.
`bypassCache`	No	Reload without the browser cache.
`urlIncludes`	No	URL substring — required for wait(until="url") and close_tabs_matching.
`keepActiveTab`	No	Protect active tab from close_tabs_matching.
`networkIdleMs`	No	Quiet network period that counts as idle, in milliseconds.
`titleIncludes`	No	Title substring for close_tabs_matching.
`includeApiBodies`	No	Include API response bodies.
`includeScreenshot`	No	Include a screenshot.
`includePerformance`	No	Include performance metrics.
`networkIdleTimeoutMs`	No	Longest wait for network idle, in milliseconds.

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.

Changed13 schema fields changedv0.3.0Nov 5, 2026

changedInput schema / properties / action / description

Previous value: -"The browser action to perform."New value: +"What to do. Required parameters are in brackets. navigate (url): Go to a URL in a tab, or in a new tab with newTab. open_url_with_capture (url): Open a URL with capture on and return what it loaded. Closes the tab afterwards unless keepOpen is set, and stores the result by default. activate_tab (tabId): Switch to a tab. close_tab (tabId): Close a tab. Unsaved work in it is lost. reload_tab: Reload a tab, optionally bypassing the cache. history: Go back or forward in a tab. Goes back unless direction says otherwise. wait: Wait until a tab reaches until: load (the default), idle, or url, which also needs urlIncludes. query_context: Read open tabs, windows and the active tab, using a preset or a query. Changes nothing. close_tabs_matching: Close tabs matching urlIncludes or titleIncludes. Use dryRun to preview; keepActiveTab is on by default."

addedInput schema / properties / bypassCache / description
```
Added value: +"Reload without the browser cache."
```
addedInput schema / properties / includeApiBodies / description
```
Added value: +"Include API response bodies."
```
addedInput schema / properties / includeHar / description
```
Added value: +"Include a HAR capture."
```
addedInput schema / properties / includePerformance / description
```
Added value: +"Include performance metrics."
```
addedInput schema / properties / includeScreenshot / description
```
Added value: +"Include a screenshot."
```

addedInput schema / properties / networkIdleMs / description

Added value: +"Quiet network period that counts as idle, in milliseconds."

addedInput schema / properties / networkIdleTimeoutMs / description
```
Added value: +"Longest wait for network idle, in milliseconds."
```

addedInput schema / properties / project / description

Added value: +"Project name that groups stored results."

addedInput schema / properties / settleMs / description

Added value: +"Milliseconds to wait after load before capturing."

addedInput schema / properties / store / description

Added value: +"Save the result in ~/.fileforge and return a ref."

addedInput schema / properties / timeoutMs / description
```
Added value: +"Time limit in milliseconds."
```

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

Behavior5/5

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the bar is lower, yet the description still adds real context: irreversible loss of unsaved work on close, bulk-close blast radius with a dryRun mitigation, URL redaction for sensitive tabs, and the extension dependency. These are exactly the facts an agent cannot infer from the structured fields.

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 sentences, front-loaded with purpose, then routing, then risk mitigation, then prerequisite — no filler. Slightly dense as an action list, and the risk warning could precede the enumeration to surface the destructive caveat even earlier, but nothing is redundant.

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 26-parameter, nine-action tool with an output schema and full annotation coverage, the description covers purpose, alternatives, destructive caveats, and environment requirements. It does not mention the store/project persistence behavior or the capture-output options, but those are documented in the schema and return contract.

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 baseline would be 3, but the description adds cross-parameter meaning the schema cannot express per-property: which params are required per action (navigate needs url, wait with until=url needs urlIncludes, close_tabs_matching needs urlIncludes or titleIncludes) and which are gated (newTab, keepOpen, dryRun, keepActiveTab). Still leaves the capture/HAR/idle tuning params entirely to the schema.

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 opening sentence names a specific resource (tabs / browser state) and enumerates concrete verbs: go to a URL, switch, reload, close, history, wait, list open tabs. It also distinguishes itself from fileforge_page_interaction by scope (tab/state management vs. acting inside a page), so an agent can route without opening the 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 routing guidance is given: use query_context to see what's open, and fileforge_page_interaction to act inside a page. It also states a when-not/caution path for the destructive subset — closing tabs loses unsaved work and close_tabs_matching can close many at once, so try dryRun first — plus the runtime prerequisite that the extension is required.

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