This server provides a full browser-automation and persona-management backend (Navvi) for agents: it drives real browsers via OS-level input, manages persistent personas/accounts/knowledge, automates logins and flows, and records sessions.
Persona management: create, list, get, update, delete personas with locale, timezone, stealth, viewport, purpose, and writing profile; state persisted in Docker volumes.
Account tracking: add, list, update, delete accounts per persona with service, email, credential references (e.g. gopass://), and status.
Milestone timeline: record, list, export, and delete persona milestones with evidence, tags, timestamps, and screenshots; generate persona briefs for consistent roleplay.
Context/knowledge store: add, search, update, remove, digest, and save digested knowledge entries per persona, separating "what they did" from "what they know".
Browser container lifecycle: start/stop Navvi browser containers (Firefox + Xvfb), check status, and list available Codespaces for remote mode.
Atomic browser actions: open URLs, find elements and get screen coordinates, click, fill, press keys, drag, hold, mouse down/up/move, scroll, screenshot, get current URL, and manage tabs.
VNC handoff: get a noVNC URL for human intervention on CAPTCHAs, OAuth consent, or 2FA.
Credential management: list/get/generate/import/autofill credentials via gopass inside the container, keeping passwords out of model responses.
Session recording: start/stop browser recording, assemble MP4, and convert to optimized GIF.
Flow recipes: save, list, show, delete reusable browser workflows per domain; high-confidence flows execute automatically.
High-level browsing: navvi_browse takes natural-language instructions and handles navigation, clicking, typing, cookies, login detection, and CAPTCHA escalation.
Automated login: navvi_login uses stored credentials to log into services and verifies success, with 2FA support via VNC.
Allows searching DuckDuckGo via browser automation, with persistent sessions and anti-detection.
Supports interacting with GitHub, including starring repositories, searching, and attaching screenshots to pull requests.
Enables logging into Tutanota (Tuta) with stored credentials, handling forms and CAPTCHAs automatically.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Navvi Log into Tutanota using stored credentials"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Your agent asks in plain words. navvi "extract the title, price and availability" <url>.
Navvi compiles a scraper, fast and accurately. Code finds the candidates on the page; a model only picks among them. With Jev those picks are typed, cheap and several times faster than Haiku.
Re-runs make zero LLM calls. The compiled scraper is a JSON file of selectors and fingerprints. Run it in cron, in CI, on Apify.
It heals itself when the site changes. A field that moved is found again and the scraper is updated; a redesign is reported, never guessed.
A scraper compiler makes a lot of small decisions: which element is the price, which control to click next, is the search done. Navvi never asks a model to write a selector or code; it enumerates the options and asks for a pick. That is exactly the shape Jev is built for.
The same 19 questions navvi asked while compiling a Hacker News search, asked again of each backend, one after another, median of three runs:
Who decides | Time for 19 decisions | Jev is | Matched the reference |
Jev (TypeSafe API) | 3.5 s | — | 19/19 |
Claude Haiku 4.5 over the API (AI Gateway) | 12.6 s | 3.6× faster | 19/19 |
Claude Haiku through Claude Code — navvi's default without a key | 31–38 s | 8–11× faster | 19/19 |
Same answers, a fraction of the wait. The Claude Code row is already the fast version: navvi now runs it without extended thinking, which took it from 91.6 s to 31–38 s with the same 19/19 (two sets of runs the same day; Claude Code's time varies).
Method, every batch's
latency and the captured questions:
decisions-race-provenance.json (the video, an earlier set of runs: 3.2 s against 11.0 s)
and decisions-race-claude-code.json (the
table). One task and one network location: a measurement, not a benchmark.
Turning it on is one environment variable. With TYPESAFE_API_KEY (or
AI_GATEWAY_API_KEY) set, navvi picks Jev by itself and says so:
chooser: jev (TYPESAFE_API_KEY found — fast typed decisions; text questions go to claude)Jev picks; it does not write. The one or two free-text questions in a run (reading
your prompt, the words to type into a search box) go to a signed-in Claude Code or
Codex on your subscription, or to ANTHROPIC_API_KEY. Get a key at
typesafe.ai.
Related MCP server: puppeteer-real-browser-mcp-server
Node 22+.
npm install -g navvi
npx playwright install chromium
navvi "Extract the book title, price and availability" \
https://books.toscrape.com/catalogue/a-light-in-the-attic_1000/index.html --browser chromium --out books.jsonRun the same command again, or point it at another page of the same kind
(…/sharp-objects_997/index.html): the saved scraper answers with zero model calls.
No key and no signed-in CLI? --decider agent makes your coding agent answer the
questions itself — see Give it to your agent.
Until 3.1.0 is on npm,
npm install -g navvigives 3.0.0, which predates the single compiler and--work. From source:git clone https://github.com/fellowship-dev/navvi.git && cd navvi && NAVVI_SKIP_BROWSER_DOWNLOAD=1 npm ci && npx playwright install chromium && npm run build, thennode dist/bin/cli.js ….
Records on stdout or --out data.json|data.csv, one object per item with a _source URL.
A scraper you can commit: storage/key_value_stores/scraper-cache/<key>.json.
The rest of storage/ holds browser profiles with live sessions; keep it private.
A summary on stderr saying who answered what:
navvi: status succeeded
items 2 pages 2 templates 1 cache hit no
decider jev: 3 decisions, 10115 input tokens, 7.3s waiting, $0.0004
writer claude: 1 text question, 18709 input tokens, 7.7s waiting, $0.0000Typed values when you ask: --fields name,price:money,stock:boolean reads
$ 6.990 as 6990 and Agotado as false; a value that does not coerce is null.
A URL list as input: --from-url <url> fetches the pages to scrape from an
endpoint (newline text or JSON), so a backend can feed the daily list.
One compiler, cheapest evidence first. For each kind of page (a URL template):
flowchart LR
A[declared data<br/>JSON-LD, meta] --> B[the page's own<br/>JSON payloads]
B --> C[DOM candidates<br/>a model picks]
C --> D[gate + determinism]
D --> E[scraper.json]Tier 1 — what the page declares. JSON-LD and meta tags, read with one plain request. No browser, no model.
Tier 2 — what the page fetches. The JSON payloads the page loads for itself, bound only when a payload is provably about this page, and never two fields to one path.
Tier 3 — the DOM. Code enumerates candidate elements; the chooser picks one per field. Only the fields tiers 1–2 could not cover are asked.
Close calls are questions, not guesses. When two readings compete, the
chooser is asked once, with your rules (--rubric) in the question, and the
answer is recorded with who gave it.
Replay makes no model calls. Each field carries fingerprints; when one stops matching, only that field is re-decided and the scraper is updated.
--workAdd --work <dir> and the compile writes every step as a file you can read, edit
and re-run from — the spec, the sample, what each tier found, why each field was
bound (rationale.md), and a scorecard:
navvi "Extract the book title, price and availability" <url> <url> --work work/booksnavvi make "<brief>" <url...> --work <dir> is the same pipeline as a resumable
driver: each stage re-runs only when the bytes it read changed, a hand-edited
artifact is never overwritten without --force, and open questions stop the run
with exit 3 until you --answer them. Both write the same scraper.json for a
record page.
Copy SKILL.md into your agent's skills (for Claude Code:
.claude/skills/navvi/SKILL.md). It tells the agent when to reach for navvi
instead of writing Playwright, the one command, how to answer questions itself
with no key (--decider agent, over stdio or with --agent-mode file and
--resume), and what each exit code means. llms.txt indexes the rest.
Navvi asks two kinds of question. The decider answers the picks (which candidate, yes/no, a score); the writer answers free text.
| Who answers | Needs | Writes text |
| Jev by TypeSafe |
| no — hands text to the writer |
| Claude Code on your subscription |
| yes |
| Codex on your subscription |
| yes |
| Any AI SDK model |
| yes |
| Your coding agent, over stdio | nothing | yes |
Default order: a Jev key → Jev; else ANTHROPIC_API_KEY → model; else a
signed-in Claude Code, then Codex; else agent. The choice and its reason print
on stderr.
Jev's writer is, in order: a signed-in claude, then codex, then a metered
key (ANTHROPIC_API_KEY, then the Gateway). A CLI that is signed out or times out
hands over to the next CLI; it never quietly starts spending on an API.
--writer pins it.
Jev's transport: with both keys set it goes over the Gateway and falls back to
the TypeSafe API if the Gateway is unavailable, saying so in the summary.
--decider-transport gateway|typesafe pins it and turns the fallback off.
--chooser <name> still works and means --decider <name>.
NAVVI_CLAUDE_MODEL (default haiku) and NAVVI_CODEX_MODEL pick the CLI model;
NAVVI_CLI_TIMEOUT_MS raises the CLI wait on a slow machine.
Exit | Status | What to do |
0 |
| Use the data |
1 |
| Read stderr; a redesign needs a new prompt, a login needs |
1 |
| Rows were written, but a requested field was never bound and is null on every row; the status line names it ( |
2 | configuration error | Fix the flag; the message names what is missing |
3 |
| Answer the parked questions and |
4 |
| Retry later, raise the cap, or switch chooser |
Heals a moved field or a renamed button; reports a redesign as drift rather
than guessing.
No captcha solving. --headed hands a challenge to the person at the keyboard.
Logins use --profile local; secrets come from NAVVI_SECRET_<NAME>,
--secrets-file or a TTY prompt — never the command line, a question, a log or
the scraper JSON.
The run stays on the start URLs' domains (--allow-domain widens it); private
hosts need --allow-private-host; destructive-looking clicks need --allow-mutation.
Defaults: 10 pages, 1000 items, or the limit the prompt states ("up to 10",
"the first 3 pages"); --max-pages and --max-items win over both.
Validate what you extract, not just that it is non-empty: a filled form is not always a finished search.
Running on Apify — the actor, residential proxies, pay-per-event.
navvi spec and navvi heuristics — the
brief as a spec with its open questions, and the rules that decide what a model is asked.
Architecture — every module and import, generated from the code and checked in CI.
npm ci && npx playwright install chromium
npm run typecheck && npm test && npm run buildCI runs the offline suite with Chromium and recorded answers; it needs no key. Report a failing URL with a redacted summary in an issue — never include browser profiles, cookies or API keys.
MIT.
Manage accounts linked to a persona. Actions: add, list, update, delete.
Add: navvi_account(action="add", persona="mybot", service="github", email="bot@x.com", creds_ref="gopass://navvi/mybot/github") List: navvi_account(action="list", persona="mybot") Update: navvi_account(action="update", account_id=1, status="blocked", notes="captcha") Delete: navvi_account(action="delete", account_id=1)
Accounts track which services a persona has registered on, with credential references (gopass://) and status.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | ||
| persona | No | default | |
| service | No | ||
| No | |||
| creds_ref | No | ||
| status | No | active | |
| notes | No | ||
| account_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description discloses the CRUD behavior via examples but does not elaborate on side effects, such as whether delete is permanent or if updates require specific permissions. Without annotations, more explicit behavior details would be beneficial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a summary, followed by examples, then a conceptual note. It is efficient, though the examples could be slightly condensed without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and 0% schema coverage, the description adequately explains the tool's purpose, actions, and parameter semantics. The presence of an output schema compensates for missing return value details, making the description complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description adds value by showing parameter usage in context (e.g., creds_ref='gopass://...', status='blocked'). This clarifies format and purpose beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Manage accounts linked to a persona' and enumerates actions (add, list, update, delete). This specific verb+resource combination distinguishes it from sibling tools like navvi_creds or navvi_persona, which handle different concerns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Examples for each action provide clear when-to-use guidance (e.g., adding an account requires persona, service, email, creds_ref). However, no explicit 'when not to use' or comparison to alternatives like navvi_creds for credential management.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Quick reference for atomic browser tools (navvi_click, navvi_find, navvi_fill, etc.).
Atomic tools are always available. Call this for a summary of tools and workflow.
Example: navvi_atomic() → lists all atomic tools with parameters
| Name | Required | Description | Default |
|---|---|---|---|
| enable | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It declares the tool is a reference (lists tools) and implies non-destructive, read-only behavior. Sufficient for a meta-tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences plus an example. Front-loaded with purpose. No waste; each part contributes meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description adequately explains the tool's role as a reference. The presence of an output schema covers return values, but the missing parameter description creates a gap, making it slightly incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one boolean parameter 'enable' with zero description coverage. The description does not mention it, leaving its purpose unclear. Agents may not know what 'enable' does.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is a 'quick reference' that lists atomic browser tools, distinguishing it from sibling tools like navvi_click, navvi_find, etc., which are the actual action tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It says 'Call this for a summary of tools and workflow,' providing clear usage context. However, no explicit exclusions or when-not-to-use guidance, though not critical for a reference tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PRIMARY BROWSING TOOL — use this for ANY web interaction instead of manually calling navvi_open, navvi_find, navvi_click, navvi_fill. Give a natural language instruction and optional URL; it handles navigation, element finding, clicking, typing, and screenshots internally.
Examples:
navvi_browse(instruction="search for 'Python FastMCP'", url="https://duckduckgo.com")
navvi_browse(instruction="click the first link in the results")
navvi_browse(instruction="accept cookie banners and screenshot the clean page", url="https://example.com")
navvi_browse(instruction="read the inbox and list unread emails", url="https://app.tuta.com")
Handles cookie banners, login detection, CAPTCHAs (escalates to VNC), and multi-step flows automatically. Returns screenshots and a step-by-step log.
If a stored flow recipe exists for the target domain, it will be used to guide or fast-track execution depending on confidence level. After completion, you'll be prompted to save new flows for reuse.
Only fall back to atomic tools (navvi_open, navvi_find, navvi_click) if this tool explicitly asks for guidance.
| Name | Required | Description | Default |
|---|---|---|---|
| instruction | Yes | ||
| url | No | ||
| max_steps | No | ||
| persona | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses internal handling of navigation, clicking, typing, screenshots, cookie banners, login detection, CAPTCHAs (escalation to VNC), multi-step flows, and flow recipes. However, it lacks details on side effects like saving flows or specific permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is relatively long but each sentence adds value. It is front-loaded with the primary purpose and structured logically with examples and behaviors. Minor redundancy could be trimmed, but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 parameters, 1 required, no annotations, and an output schema (not shown), the description is fairly complete. It covers purpose, usage, behavior, and return values. However, it lacks explicit documentation for 'max_steps' and 'persona', leaving some gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description only partially clarifies 'instruction' and 'url' through examples, but does not explain 'max_steps' or 'persona'. The meaning of these parameters remains unclear, and the description does not fully compensate for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states this is the PRIMARY BROWSING TOOL for ANY web interaction, and explicitly names specific sibling tools (navvi_open, navvi_find, navvi_click, navvi_fill) to distinguish itself. It uses a specific verb-resource combination and describes the integrated capabilities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to use this tool instead of manually calling atomic tools, and only fall back to those if this tool asks for guidance. It provides clear context on when to use it and when not to, including handling of cookies, login, and CAPTCHAs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Click at (x, y) screen coordinates using OS-level xdotool input (isTrusted: true). IMPORTANT: Use navvi_find to get coordinates -- it returns screen-ready (x, y) values. Do NOT use raw JS getBoundingClientRect() -- those are viewport coords that miss the browser chrome offset.
| Name | Required | Description | Default |
|---|---|---|---|
| x | Yes | ||
| y | Yes | ||
| persona | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description carries burden. Discloses OS-level xdotool input with isTrusted: true, implying real user simulation. Does not detail environment prerequisites like screen focus, but sufficient for a click action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no fluff. Front-loaded with action and method, followed by critical usage instruction. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has output schema so return values need not be explained. Description covers purpose, coordinate sourcing, and key behavioral trait (isTrusted). Minor gap: no mention of click type (left) or boundary handling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%. Description adds context that x and y should be screen-ready values from navvi_find, but does not explain persona parameter. Partial compensation for missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Click at (x, y) screen coordinates using OS-level xdotool input (isTrusted: true)'. It specifies the action, resource, and method, distinguishing from siblings like navvi_find and navvi_drag.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to use navvi_find for coordinates and warns against using getBoundingClientRect(). Provides clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Persistent knowledge store for a persona — what they know. Actions: add, list, search, update, remove, digest, save_digest.
Add: navvi_context(action="add", persona="chet", summary="InboxGuard: email deliverability scanner with SPF/DMARC checks", source="https://inboxguard.me/", tags="competitor,inbox-angel") List: navvi_context(action="list", persona="chet") or navvi_context(action="list", persona="chet", tags="competitor") Search: navvi_context(action="search", persona="chet", query="email deliverability", tags="competitor") Update: navvi_context(action="update", context_id=3, summary="Updated finding", tags="competitor,updated") Remove: navvi_context(action="remove", context_id=3) — soft-deletes, included in next digest Digest: navvi_context(action="digest", persona="chet") — returns current summary + undigested entries for LLM synthesis Save digest: navvi_context(action="save_digest", persona="chet", summary="Synthesized knowledge summary...") — stores digest, marks entries processed
Milestones = what a persona did. Context = what a persona knows.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | ||
| persona | No | default | |
| summary | No | ||
| source | No | ||
| tags | No | ||
| query | No | ||
| context_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description thoroughly explains the behavior of each action, including that remove is a soft-delete and included in the next digest, and that digest returns a current summary plus undigested entries. However, it lacks details on limits, authentication, or idempotency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is relatively long but well-structured with bullet-style action listings and examples. Each sentence provides valuable information, justifying its length. It could be slightly more concise but remains efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters and 7 actions, the description covers most behavioral aspects. It mentions return values for digest (current summary + undigested) and save_digest (stores and marks processed), but does not specify output for other actions. Overall, it is fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description compensates by illustrating each parameter through examples (action, persona, summary, source, tags, query, context_id). While not formal parameter descriptions, the examples effectively convey semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it's a persistent knowledge store for a persona, listing 7 actions with examples. It distinguishes from sibling tool navvi_milestone by explaining that milestones are actions done while context is knowledge. The verb-resource structure is explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides example invocations for each action, which serve as usage patterns. It differentiates context from milestones, but does not explicitly state when to use this tool over other sibling tools like navvi_account or navvi_persona. The examples indirectly guide selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage credentials stored in gopass inside the container. Five actions:
"list": show available entries (no secrets)
"get": retrieve a non-secret field (username, url, email — refuses password)
"generate": create a new credential with a random password that NEVER leaves the container. Requires entry + username. Optional length (default 24). Use this for signups.
"import": bulk-import credentials from a JSON file on the host. Requires file_path pointing to a JSON array of {entry, username, password} objects. File is read and deleted after import.
"autofill": fill a login form from gopass — password goes gopass → xdotool → browser, NEVER in this response.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | ||
| entry | No | ||
| field | No | ||
| username | No | ||
| length | No | ||
| file_path | No | ||
| username_selector | No | ||
| password_selector | No | ||
| persona | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses key behaviors: passwords never leave the container, get refuses password, import file is deleted after, autofill uses xdotool. This exceeds the burden of transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is somewhat long but well-structured with bullet points for each action. Front-loads the main purpose. Every sentence adds value, though minor redundancy exists (e.g., 'NEVER' emphasis repeated).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a credential tool with 9 parameters and no schema descriptions, the description covers the main actions and key parameter semantics. It does not discuss return values or error handling, but the output schema likely handles return structure. Overall quite complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. It maps actions to relevant parameters (e.g., generate requires entry and username, length defaults to 24; import requires file_path). However, parameters like username_selector, password_selector, and persona are not explained, leaving gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool manages credentials in gopass and enumerates five distinct actions (list, get, generate, import, autofill) with specific verbs. It distinguishes itself from sibling browser automation tools by focusing on credential management.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Each action's purpose and recommended use are described: list for showing entries, get for non-secret fields, generate for creating new credentials with password never leaving container, import for bulk, autofill for filling forms. It implies when to use each but does not explicitly state when not to use or name alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Drag from (x1,y1) to (x2,y2) with interpolated mouse moves. Uses OS-level input -- works on CAPTCHAs and canvases. Get coordinates from navvi_find.
| Name | Required | Description | Default |
|---|---|---|---|
| x1 | Yes | ||
| y1 | Yes | ||
| x2 | Yes | ||
| y2 | Yes | ||
| steps | No | ||
| duration | No | ||
| persona | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description partially discloses behavior (OS-level input, interpolation) but omits details like blocking behavior, failure modes, and output format. Some transparency is present but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief (two sentences), front-loaded with the action, and free of unnecessary words. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters, 0% schema coverage, and no output schema explanation, the description is incomplete. It fails to specify how steps, duration, and persona affect behavior or what the tool returns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description explains x1, y1, x2, y2 but does not clarify steps, duration, or persona, leaving 3 parameters semantically undefined.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (drag from (x1,y1) to (x2,y2) with interpolation) and distinguishes it from siblings like navvi_click and navvi_mousedown by emphasizing interpolation and OS-level input.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context for when to use (CAPTCHAs, canvases) and suggests obtaining coordinates from navvi_find, but does not explicitly exclude alternatives or specify when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Click at (x, y) to focus an input field, then type text using OS-level xdotool. Selects existing text before typing to replace any current value.
Uses triple-click to select all text in the field (works in all input contexts), then types the new value which replaces the selection.
| Name | Required | Description | Default |
|---|---|---|---|
| x | Yes | ||
| y | Yes | ||
| value | Yes | ||
| delay | No | ||
| persona | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behaviors: OS-level xdotool usage, triple-click for selection, and replacement typing. However, it does not explain the effect of the delay parameter, the role of persona, or potential side effects like mouse position changes or field focus behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tightly written with no extraneous content. It front-loads the action and provides the key mechanism (triple-click) in a single sentence. Every sentence adds essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters with 0% schema coverage and no annotations, the description covers the core workflow but omits parameter details for delay and persona. The presence of an output schema may compensate, but without its content, completeness is moderate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains x, y (coordinates) and value (text to type), but fails to describe delay (likely inter-step timing) and persona (possibly user profile). This leaves two parameters undocumented, reducing semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool clicks at coordinates to focus an input field, selects all text via triple-click, and types a replacement value. It differentiates from siblings like navvi_click (which only clicks) and navvi_press (which types without selection).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for filling input fields by replacing text, but does not explicitly state when not to use (e.g., for non-input elements) or compare with alternatives like combining navvi_click and navvi_press. No guidance on prerequisites or edge cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find element(s) by CSS selector and return screen-ready (x, y) coordinates. THIS IS THE PRIMARY WAY TO GET COORDINATES -- use before navvi_click, navvi_fill, navvi_drag, navvi_mousedown. Automatically corrects for browser chrome offset. Workflow: navvi_find -> get (x, y) -> navvi_click/navvi_fill at those coords -> navvi_screenshot to verify. For dropdowns: navvi_find the button -> navvi_click to open -> navvi_find the options (selector="[role=option]", all=true) -> navvi_click the desired option.
| Name | Required | Description | Default |
|---|---|---|---|
| selector | Yes | ||
| all | No | ||
| persona | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses automatic browser chrome offset correction, which is a key behavioral trait. With no annotations provided, this adds value, though it could mention error handling or timeout behavior for completeness.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections: purpose, primary usage indicator, workflow, and special case. Some redundancy in emphasizing its primary role, but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers primary use case, workflow, and dropdown handling. Given the presence of an output schema (implied) and the tool's moderate complexity, the description provides sufficient context for an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains the 'selector' parameter contextually and hints at 'all' through the dropdown example, but the 'persona' parameter is unmentioned. With 0% schema description coverage, the description partially compensates but leaves a gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool finds elements by CSS selector and returns screen-ready coordinates, explicitly distinguishing it from sibling tools like navvi_click and navvi_fill by positioning it as the primary coordinate getter.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit workflow instructions (navvi_find -> coordinates -> navvi_click/navvi_fill -> navvi_screenshot) and specific guidance for dropdowns, including alternative selector strategies and use of the 'all' parameter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage flow recipes — reusable browser workflows that improve over time.
Actions: list — list all flows, or filter by domain navvi_flow(action="list") navvi_flow(action="list", domain="outlook.live.com")
show — show full detail for a specific flow navvi_flow(action="show", flow="outlook.live.com/read-email")
save — store a verified flow recipe (call after navvi_browse prompts you) navvi_flow(action="save", flow="outlook.live.com/read-email", description="Read emails from inbox", steps='[{"action":"navigate","url":"https://outlook.live.com"}, ...]', caveats='["Login required first"]', refs='["outlook.live.com/login"]')
delete — remove a flow recipe navvi_flow(action="delete", flow="outlook.live.com/read-email")
The flow parameter uses the format "domain/action-name".
Steps, caveats, and refs are JSON strings (arrays).
Flows are automatically loaded by navvi_browse when it visits a matching domain. High-confidence flows execute via fast path (no screenshots); low-confidence flows serve as guidance while still using visual analysis.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | ||
| flow | No | ||
| domain | No | ||
| description | No | ||
| steps | No | ||
| caveats | No | ||
| refs | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses behavioral traits: save requires prior navvi_browse prompt, steps/caveats/refs are JSON strings, flows auto-load on domain match, and high/low confidence flows affect execution path. This is comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-organized with clear sections for each action and example calls. It is detailed but not verbose; every sentence adds value. The structure aids readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters, 1 required, and no output schema concerns (has output schema, so return values not needed), the description covers all actions and parameter usage completely. It provides sufficient information for an AI agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so description must compensate. It does so by specifying parameter formats (e.g., flow uses 'domain/action-name') and stating that steps, caveats, refs are JSON string arrays. Examples show exact usage, adding significant meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool manages flow recipes (reusable browser workflows) and enumerates four distinct actions (list, show, save, delete) with examples. This differentiates it from sibling tools that are single-purpose (e.g., navvi_click, navvi_fill).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context for when to use each action, including example calls and parameter format. It mentions that flows are automatically loaded by navvi_browse, but does not explicitly exclude use cases or describe when not to use this tool vs. alternatives. Slightly lacking in exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Press and hold at (x, y) for duration_ms milliseconds. Use for press-and-hold CAPTCHAs. Get coordinates from navvi_find.
| Name | Required | Description | Default |
|---|---|---|---|
| x | Yes | ||
| y | Yes | ||
| duration_ms | No | ||
| persona | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description is minimal. It does not disclose side effects, blocking behavior, or return value despite having an output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. Purpose, inputs, and use case are front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers main use case and coordinate sourcing, but leaves duration_ms and persona unexplained. Output schema exists but not mentioned.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds meaning for x and y via reference to navvi_find, but duration_ms and persona lack explanation. Schema coverage is 0% so description partially compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action (press and hold), inputs (x,y,duration_ms), and use case (press-and-hold CAPTCHAs). It distinguishes from siblings like navvi_click and navvi_press.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly specifies when to use (CAPTCHAs) and where to get coordinates (navvi_find). Lacks explicit exclusions but provides clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List available Codespaces for Navvi (remote mode).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It merely states the action without disclosing behavioral traits such as side effects, authentication needs, or rate limits. Additional context is missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is front-loaded and contains no extraneous information. Every word serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is minimal. While it clearly states the purpose, it does not explain what 'remote mode' means or the context of codespaces. An output schema exists, which alleviates the need to describe return values, but additional context would be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% schema coverage. With no parameters, the description does not need to add parameter semantics. Baseline 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' and identifies the resource 'available Codespaces for Navvi (remote mode)'. This clearly distinguishes it from sibling tools like navvi_browse or navvi_account, which perform different actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly suggests that this tool is used to list codespaces, but it does not provide explicit guidance on when to use it versus alternatives, nor does it mention when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Log into a service using stored credentials — use this instead of manually navigating to a login page and calling navvi_creds autofill.
Give it a service name (e.g. "tuta.com", "github.com") and it reads gopass credentials, navigates to the login page, fills the form, submits, and verifies login success. Handles 2FA by providing a VNC URL for human intervention.
Example: navvi_login(service="tuta.com", persona="default")
Requires: an account registered via navvi_account with a creds_ref pointing to a gopass entry.
| Name | Required | Description | Default |
|---|---|---|---|
| service | Yes | ||
| persona | No | default |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description fully discloses behavior: navigates to page, fills credentials, submits, verifies, and handles 2FA with VNC. It is transparent about the autofill and submission steps, though it could mention potential state changes (e.g., page navigation).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two core sentences, an example, and prerequisites. No redundant information, and the key action is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema and low parameter count, the description covers input, behavior, prerequisites, and 2FA handling. It is complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description adds meaning by explaining 'service' as a service name with examples like 'tuta.com', and notes 'persona' defaults to 'default'. This compensates for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool logs into a service using stored credentials, explaining the automated process of navigating, filling, submitting, and verifying login. It distinguishes from sibling navvi_creds by emphasizing the complete login flow rather than just autofill.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides usage context (instead of manual navigation and navvi_creds), a concrete example, and prerequisites (account with creds_ref). It mentions 2FA handling via VNC, but lacks explicit when-not-to-use or alternative tools for different scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Curated lifetime timeline for a persona — milestones with evidence. Actions: add, list, export, delete.
Add: navvi_milestone(action="add", persona="chet", event="Signed up for Reddit", detail="Username: chestertownwilliams. Subscribed to r/selfhosted.", url="https://reddit.com/user/chestertownwilliams", tags="first,reddit,signup", screenshot=true) Import (retroactive): navvi_milestone(action="add", persona="chet", event="Created Outlook account", detail="Email: chester.town.williams@outlook.com", ts="2026-03-27T11:00:00", screenshot_file="/path/to/old-screenshot.png", source="import") List: navvi_milestone(action="list", persona="chet") or navvi_milestone(action="list", persona="chet", tag="reddit", limit=10) Export: navvi_milestone(action="export", persona="chet") — generates full markdown timeline Brief: navvi_milestone(action="brief", persona="chet") — generates persona brief (who am I, my accounts, my email, my history, my writing style). READ THIS BEFORE ACTING AS A PERSONA. Delete: navvi_milestone(action="delete", milestone_id=3)
Tags: comma-separated string. Use 'first' tag for firsts (first post, first signup, etc.). Screenshot: if true, captures current browser screen and attaches it. For retroactive imports, use screenshot_file to attach an existing image. Detail: include FULL content — exact post text, comment body, form values. This builds the persona's voice and style for consistency.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | ||
| persona | No | default | |
| event | No | ||
| detail | No | ||
| url | No | ||
| tags | No | ||
| screenshot | No | ||
| source | No | manual | |
| ts | No | ||
| screenshot_file | No | ||
| tag | No | ||
| milestone_id | No | ||
| limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It explains that add creates a milestone (optionally capturing a screenshot), list retrieves, export generates markdown, brief generates a persona profile, and delete removes a milestone. It mentions retroactive imports using screenshot_file and ts, which are behavioral traits beyond basic CRUD.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with a clear header, bullet-like examples for each action, and additional notes on tags and details. While it is long, it avoids verbosity and every line adds value. A slightly more compact format could improve it.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 13 parameters, 0% schema description coverage, and no annotations, this description covers all necessary aspects: all actions, parameter usage, and behavioral details. An output schema exists, so return values are not required. The description is fully adequate for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It thoroughly explains all 13 parameters through examples and notes: tags as comma-separated, screenshot=true captures screen, detail must include full content, etc. Each parameter's role is made clear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Curated lifetime timeline for a persona — milestones with evidence' and lists actions (add, list, export, delete). This clearly identifies the tool's purpose and resource, distinguishing it from sibling tools like navvi_context or navvi_browse which handle browser automation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides concrete usage examples for each action (add, list, export, brief, delete), including parameter values. It tells when to use 'brief' ('Read this before acting as a persona'). However, it doesn't explicitly state when not to use this tool or compare it to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Press mouse button at (x, y). Pair with navvi_mouseup for manual hold control. For simple press-and-hold, use navvi_hold instead.
| Name | Required | Description | Default |
|---|---|---|---|
| x | Yes | ||
| y | Yes | ||
| persona | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the primary action of pressing the mouse button. Without annotations, it carries the full burden and does well but lacks details on side effects like whether the press is atomic or if it can be used without a corresponding mouseup. Still, it is clear enough for a simple action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences, no redundant words, and information is front-loaded. Every sentence provides value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for a simple tool with an output schema, but it fails to explain the optional 'persona' parameter. Given the low parameter coverage, more detail about the parameters is needed for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must explain the parameters. It only mentions '(x, y)' in context but does not describe the 'persona' parameter or the meaning of x and y beyond coordinates. This is a significant gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it presses the mouse button at a given coordinate using a specific verb and resource. It distinguishes from sibling tools 'navvi_mouseup' and 'navvi_hold' by explaining when to use each, preventing confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool (for manual hold control in pair with navvi_mouseup) and when to use an alternative (navvi_hold for simple press-and-hold). This clearly differentiates usage scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move mouse to (x, y) without clicking. Useful for hover effects.
| Name | Required | Description | Default |
|---|---|---|---|
| x | Yes | ||
| y | Yes | ||
| persona | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description discloses that the tool moves the mouse without clicking, but does not detail other behavioral traits such as whether it triggers hover effects, waits for UI updates, or coordinates system (viewport vs. page).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence efficiently conveys purpose and a key usage scenario (hover effects), with no extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and presence of an output schema, the description is minimal. It covers the core action but omits details like return values, error handling, and whether it triggers side effects (e.g., hover events). Adequate for a simple tool but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% parameter description coverage; description adds no meaning to x, y (e.g., units, coordinate system) or persona, leaving ambiguity. Only the phrase 'Move mouse to (x, y)' hints at their role but insufficiently.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states action ('Move mouse'), target (x, y), and key modifier ('without clicking'), distinguishing it from click-related siblings like navvi_click.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Mentions 'Useful for hover effects' which implies usage context, but lacks explicit guidance on when to use this vs. alternatives like navvi_drag or navvi_find, and no when-not-to-use conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Release mouse button at (x, y). Pair with navvi_mousedown.
| Name | Required | Description | Default |
|---|---|---|---|
| x | Yes | ||
| y | Yes | ||
| persona | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description only states the basic action, lacking details on coordinate system, event effects, or behavior if called without prior mousedown.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with key information, zero waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lacks context on coordinate system, behavior for invalid coordinates, and persona usage; despite simplicity, description is incomplete for reliable agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%; description adds meaning only for x and y (coordinates) but omits explanation of coordinate system and does not mention persona parameter at all.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Explicitly states 'Release mouse button at (x, y)' and pairs with navvi_mousedown, clearly differentiating from siblings like navvi_click.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Directs agent to pair with navvi_mousedown, providing clear context for sequence usage, though no alternatives or when-not are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Navigate to a URL in the active browser. After navigating, use navvi_find to locate elements on the page, then navvi_click/navvi_fill to interact.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | ||
| persona | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states 'navigate to a URL' without disclosing whether it waits for page load, handles errors, requires authentication, or changes the browser state. This is insufficient for a operation that affects shared browser state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences front-load the core action and provide a useful workflow hint. No redundant or irrelevant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists, the description could omit return details, but it still lacks guidance on what happens after navigation (e.g., page loaded event, error scenarios). It is adequate for simple cases but incomplete for robust agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, and the description adds no explanation for either parameter. The required 'url' parameter is not specified as full/relative URL or accepted protocols, and the optional 'persona' parameter is not described at all.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool navigates to a URL in the active browser, and distinguishes itself from interaction siblings like navvi_click and navvi_fill. However, it does not differentiate from similar navigation tools like navvi_browse or navvi_url, and the optional persona parameter is not explained.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear workflow: use navvi_open first, then navvi_find to locate elements, then navvi_click/navvi_fill to interact. This gives good sequential guidance, but it does not mention when not to use the tool or any prerequisites/context requirements.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage browser personas. Actions: create, get, update, list, delete.
Create: navvi_persona(action="create", name="mybot", description="GitHub admin", stealth="high") List: navvi_persona(action="list") Get: navvi_persona(action="get", name="mybot") Update: navvi_persona(action="update", name="mybot", purpose="new purpose", profile="Casual tone, uses emoji") Delete: navvi_persona(action="delete", name="mybot")
The profile field stores voice, phrases, and writing style notes for the persona.
This gets injected into generate_brief() so sessions adopt the right tone.
Personas store config (locale, timezone, stealth, purpose) and track accounts + action history. Each persona maps to a persistent Docker volume (navvi-profile-). Read persona state via resource: persona:///state
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | ||
| name | No | ||
| description | No | ||
| purpose | No | ||
| stealth | No | ||
| locale | No | ||
| timezone | No | ||
| viewport | No | ||
| profile | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that personas map to Docker volumes and store config, but does not detail mutation effects (e.g., irreversible deletion), auth requirements, or rate limits. Some behavioral context is present but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear hierarchy of actions and examples. It front-loads the purpose and uses bullet-like formatting. Each section adds value, though the inclusion of raw code examples could be slightly streamlined.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (context signal), the description does not need to detail return values. It covers persona creation, retrieval, update, deletion, and mentions resource URLs for state access. It handles the complexity of 9 parameters reasonably well, though error handling is omitted.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains the 'profile' parameter and shows usage patterns via examples, but does not define allowable values for parameters like 'stealth', 'locale', or 'timezone'. Some parameters remain ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it manages browser personas with specific CRUD operations (create, get, update, list, delete). Examples for each action make the purpose unambiguous and distinguish it from sibling tools like navvi_account or navvi_browse.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides examples for each action, showing when to use which combination of parameters. It also explains the role of the 'profile' field in tone injection. However, it does not explicitly state when not to use this tool or compare it to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Press a keyboard key (Enter, Tab, Escape, Backspace, ArrowDown, etc.). Sends to currently focused element.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | ||
| persona | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description only states basic behaviour without disclosing side effects, error handling, or prerequisites like focus.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with action and examples, no wasted words, efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple tool with output schema, but could improve by listing all valid keys and explaining persona; overall sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds meaning to 'key' via examples, but 'persona' parameter is left unexplained; schema coverage is 0%, so description partially compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verb 'Press' and resource 'keyboard key', listing common examples (Enter, Tab, etc.), clearly distinguishing from sibling tools like navvi_click.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
States action applies to 'currently focused element', implying context, but provides no explicit when-to-use or when-not-to-use guidance compared to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Convert a recorded video to an optimized GIF (1600px wide, 8fps, palette-optimized).
| Name | Required | Description | Default |
|---|---|---|---|
| input | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose all behavioral traits. It mentions optimization settings but omits details like side effects (e.g., deletion of original video), required input format, limitations, or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that efficiently conveys the core function. However, it lacks structural elements like sections or bullet points that could improve readability without adding much length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the tool having a single parameter and an output schema, the description fails to explain the input parameter or any prerequisites. It is incomplete for an agent to reliably invoke the tool without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'input' has no description in the schema (0% coverage) and the description provides no clarification on its purpose, expected format, or use. The description adds zero value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Convert a recorded video to an optimized GIF') with specific output parameters (1600px wide, 8fps, palette-optimized). It effectively distinguishes itself from sibling tools like navvi_record_start and navvi_record_stop.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, such as prerequisites (e.g., a recorded video must exist) or when not to use it. The context of sibling tools implies usage after recording, but it is not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start recording the browser via screenshot polling. Captures frames in background, assembles to MP4 on stop.
| Name | Required | Description | Default |
|---|---|---|---|
| duration | No | ||
| persona | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It reveals that recording uses screenshot polling, runs in background, and assembles MP4 on stop. However, it lacks details on destructive effects, rate limits, or required permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (two sentences), but it sacrifices parameter explanation. For a simple tool, this is acceptable, but additional detail on parameters would improve it without harming conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is insufficient for a tool with two undocumented parameters and no annotations. It does not explain return values (though output schema exists), nor does it clarify important context like what 'duration' means or what 'persona' does.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description does not mention the 'duration' or 'persona' parameters, leaving their meaning and usage entirely unclear. This is a major gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool starts recording via screenshot polling and mentions MP4 output. However, it doesn't explicitly differentiate from the sibling 'navvi_record_gif', though the output format (MP4 vs GIF) is implied.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (to start recording) but provides no explicit guidance on when not to use or alternatives like 'navvi_record_gif'. No criteria for duration or persona are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stop recording and assemble frames into MP4. Optionally trims dead time between actions.
| Name | Required | Description | Default |
|---|---|---|---|
| trim | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must cover behavioral traits. It mentions assembling frames and optional trimming, but omits details like whether the recorder is closed, what happens if no recording is active, or file location.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no redundant words. Front-loaded with the primary action, followed by the optional feature.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one optional param and an output schema (not shown), the description is adequate. It explains core functionality and the parameter. Could mention what the output contains, but schema covers that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single boolean parameter 'trim' is described as 'Optionally trims dead time', adding clear meaning beyond the schema (which has 0% description coverage). Default value is also stated.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Stop recording and assemble frames into MP4') and distinguishes from siblings like navvi_record_start and navvi_record_gif by specifying the output format and optional trim feature.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use or alternatives. It is implied for stopping a recording, but doesn't mention prerequisites or contrast with navvi_record_gif or other stop tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Take a screenshot of the virtual display. Returns file path to a PNG image -- use Read tool to view it. Use for VISUAL VERIFICATION only (confirming what happened). To get clickable coordinates, use navvi_find instead -- screenshot pixel positions include browser chrome and are not reliable for targeting elements.
| Name | Required | Description | Default |
|---|---|---|---|
| persona | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses that pixel positions include browser chrome and are unreliable for targeting. Could mention whether the screenshot is read-only or has side effects, but the disclosure is substantial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three efficient sentences, front-loaded with the key action, no redundant words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers return format and use case adequately given output schema exists, but missing parameter explanation reduces completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has one parameter 'persona' with 0% description coverage, and the description does not explain its purpose. Agent has no guidance on what 'persona' does.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool takes a screenshot of the virtual display and returns a file path. Distinguishes from sibling tool navvi_find for coordinate retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly limits use to visual verification only and advises against using for clickable coordinates, pointing to navvi_find as an alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scroll the page in a given direction (up, down, left, right).
| Name | Required | Description | Default |
|---|---|---|---|
| direction | No | down | |
| amount | No | ||
| persona | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should fully disclose behavioral traits (e.g., scroll type, speed, overscroll behavior), but it only states the basic action, leaving significant gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with clear front-loading, but it lacks any structural elements like sections that could improve readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the tool's simplicity, the description fails to explain key parameters and usage context (e.g., amount unit, persona purpose), leaving the agent to guess, even with an output schema present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain what 'amount' (pixels? lines?) or 'persona' means, adding no value beyond the parameter names and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool scrolls the page and specifies valid directions (up, down, left, right), making the purpose unambiguous and distinct from siblings like navvi_click or navvi_drag.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool over alternatives (e.g., navvi_browse, navvi_drag), nor are there any when-not-to-use conditions mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start a Navvi browser container (Firefox + Xvfb + xdotool). Local=Docker, Remote=Codespace. Workflow: navvi_open(url) -> navvi_find(selector) -> navvi_click/navvi_fill -> navvi_screenshot to verify. All input is OS-level (isTrusted:true). If you hit a CAPTCHA you cannot solve (Arkose/FunCaptcha, image puzzles, reCAPTCHA), call navvi_vnc and send the user the noVNC URL so they can solve it manually.
| Name | Required | Description | Default |
|---|---|---|---|
| persona | No | default | |
| mode | No | local | |
| name | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that 'All input is OS-level (isTrusted:true)' and provides a CAPTCHA handling strategy. It does not elaborate on container lifecycle or persistence, but the workflow and behavioral notes are fairly comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately concise and well-structured: it starts with the primary purpose, then environment, then a workflow, then a note on CAPTCHA. While it could be slightly trimmed, each sentence adds value and the flow is logical.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers workflow, environment, and a special case (CAPTCHA). However, it does not explain output semantics (despite an output schema likely existing) and leaves parameters undocumented. For a start tool, it provides adequate but not complete context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has three parameters (persona, mode, name) with defaults, but the description provides no explanation of their meaning or usage. Schema description coverage is 0%, and the description fails to compensate, leaving the agent without guidance on how to use these parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Start a Navvi browser container' and specifies the components (Firefox + Xvfb + xdotool). It differentiates between local and remote environments. However, it does not explicitly contrast with sibling tools, though 'start' is intuitively the initializer among many interaction tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides an explicit workflow: 'navvi_open(url) -> navvi_find(selector) -> navvi_click/navvi_fill -> navvi_screenshot to verify.' It also offers a fallback for CAPTCHA by calling navvi_vnc. This clearly indicates when to use this tool (at the start) and when to use an alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show current Navvi state -- running containers, API health, active persona.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description explicitly indicates a read operation showing state. Could mention safety (e.g., no side effects) but adequately transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words. Front-loaded with action and scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With zero parameters and output schema present, description is sufficient. Could elaborate on output format slightly but overall complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters, so baseline is 4. Description doesn't need param details; output schema covers return values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool shows current Navvi state, listing specific components (running containers, API health, active persona). It effectively distinguishes from sibling action tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Purpose is clear but no guidance on when to use vs alternatives. No mention of when not to use or preferred context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stop a Navvi container. Stops all if no persona specified. Firefox profile is preserved in the Docker volume.
| Name | Required | Description | Default |
|---|---|---|---|
| persona | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description discloses an important behavioral trait: 'Firefox profile is preserved in the Docker volume.' This indicates that stopping does not destroy data, which is valuable beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no waste. The core action and key behavior are front-loaded. Every sentence adds information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple one-optional-parameter tool and the presence of an output schema (not shown), the description covers the main action, default behavior, and a side effect. Some might want warnings about ongoing operations, but it's fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, but the description adds meaning to the 'persona' parameter by explaining that omitting it stops all containers. This adds significant value beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Stop a Navvi container') and the resource ('container'). It distinguishes from siblings by specifying that it stops all containers if no persona is specified, making the scope clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides a clear usage hint: stop a specific container by persona, or all if no persona. However, it does not explicitly mention when not to use this tool or suggest alternatives among the many sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage browser tabs within a persona. Four actions:
"list": list all open tabs with handle, url, and title
"new": open a new tab (optionally navigate to url). Switches to the new tab.
"switch": switch to a tab by handle
"close": close a tab by handle (cannot close the last tab)
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | ||
| handle | No | ||
| url | No | ||
| persona | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that 'new' switches to the new tab and that closing the last tab is forbidden, but it does not describe behavior for invalid handles, error handling, or the structure of the output (beyond listing 'handle, url, and title' for list action).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and uses a list format for readability. However, it could be slightly more organized (e.g., grouping parameters per action). It front-loads the verb 'Manage' and then lists actions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool manages four actions with four parameters, the description covers the main use cases and key constraints (no last tab close, new tab switches). An output schema exists but is not described; return values for list are hinted. The description is sufficient for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% (no parameter descriptions in schema), so description must compensate. It explains that 'action' is one of four values, 'handle' is for switch/close, 'url' is for new, and 'persona' is likely a context parameter. This adds meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Manage browser tabs within a persona' and enumerates four specific actions (list, new, switch, close) with brief explanations. This distinguishes it from sibling tools like navvi_browse or navvi_open.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly tells when to use each action (e.g., 'list all open tabs', 'open a new tab (optionally navigate to url)', 'switch to a tab by handle', 'close a tab by handle'). It also provides a constraint: 'cannot close the last tab'. However, it does not explicitly contrast with alternatives or state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current page URL.
| Name | Required | Description | Default |
|---|---|---|---|
| persona | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only restates the tool's name without disclosing behavioral traits like prerequisites, side effects, or error states.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The single-sentence description is concise but lacks necessary detail about usage and parameters, making it minimally acceptable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description fails to explain the parameter or provide context for when and how to use the tool, leaving significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description ignores the 'persona' parameter entirely, leaving its purpose unexplained despite 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get the current page URL' clearly states the tool's action and resource, distinguishing it from siblings that perform different operations like clicking or browsing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as navvi_context, which might also provide URL information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the noVNC URL for live browser view. Share with the user when human intervention is needed: visual CAPTCHAs that require image recognition, OAuth consent screens, or 2FA code entry. The user opens this URL in their real browser to interact directly.
| Name | Required | Description | Default |
|---|---|---|---|
| persona | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description clearly discloses that the tool returns a URL for the user to open in their real browser. However, it does not mention potential side effects, rate limits, or prerequisites like an active VNC session.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two efficient sentences: first states purpose, second provides usage guidance. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool and presence of an output schema, the description is adequate but could mention prerequisites (e.g., browser must be started) or output format details for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'persona' is not explained in the description, and schema coverage is 0%. The description adds no meaning to the parameter beyond the schema's type and default.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets a noVNC URL for live browser view and specifies the exact scenarios for human intervention (visual CAPTCHAs, OAuth, 2FA). This distinguishes it from sibling tools like navvi_screenshot or navvi_browse.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool (human intervention needed) and implies when not to use it (automated browsing). It provides clear context relative to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v3.21.0navvi_accountnavvi_atomicnavvi_browsenavvi_clicknavvi_contextnavvi_credsnavvi_dragnavvi_fillnavvi_findnavvi_flownavvi_holdnavvi_listnavvi_loginnavvi_milestonenavvi_mousedownnavvi_mousemovenavvi_mouseupnavvi_opennavvi_personanavvi_pressnavvi_record_gifnavvi_record_startnavvi_record_stopnavvi_screenshotnavvi_scrollnavvi_startnavvi_statusnavvi_stopnavvi_tabnavvi_urlnavvi_vncScored across 31 tools
Each tool has a clearly distinct purpose: high-level browsing (navvi_browse), low-level actions (navvi_click, navvi_fill), credential management (navvi_creds), persona lifecycle (navvi_persona, navvi_account, navvi_milestone), etc. Even related tools like mouse actions are differentiated by action type. No overlapping ambiguity.
All tools follow the consistent snake_case pattern 'navvi_<verb_or_noun>'. The naming is predictable: verbs for actions (browse, click, find) and nouns for entities (context, flow, persona). No mixed conventions or irregular patterns.
31 tools is higher than typical (3-15) but well-justified given the comprehensive scope: browser automation (atomic & high-level), credential management, persona profiles, knowledge context, recording, and infrastructure. Each tool has a defined role without redundancy.
The tool set covers the full lifecycle of persona-driven web automation: browser control (open, find, click, type, scroll), credential handling, knowledge storage, flow recipes, and recording. Minor gaps exist (e.g., file uploads, extension management) but do not hinder primary workflows.
Undetectable cloud browser sessions for AI agents and scrapers. Navigate, extract, click, captcha.
Stealth web automation for AI agents. Login, signup, navigate, screenshot.
Stealth web automation for AI agents. Login, signup, navigate, screenshot.
AI-powered browser automation — navigate, click, fill forms, and extract data from any website.
