Gemini Web MCP
Use this Skill to complete the user's task with Gemini, not to tour the Gemini tool surface.
The product priority is:
1. Agent assistance and multimodal understanding
2. Generated artifacts
3. Explicit Gemini account management
Choose one lane for the current task. Do not expose or load account-management tools merely because they exist.
Choose the Capability Lane
| User intent | Preferred current route | What success means |
|---|---|---|
| Second opinion, critique, code/design review | low-token chat; primary gemini_chat when exact controls are needed |
useful Gemini result incorporated into the agent's work |
| Quick current-web lookup | chat or gemini_chat with an explicit request for current sources |
answer plus observed source URLs; otherwise label it ungrounded or escalate to Research |
| Understand one image or screenshot | low-token chat(image_path=...); primary gemini_chat(image_paths=[...]) |
analysis returned to the agent and used in the surrounding task |
| Understand files, URLs, or mixed evidence | primary gemini_upload_file, gemini_analyze_url, and image chat as needed |
source identity preserved and conclusions synthesized |
| Deep, multi-source research | primary gemini_deep_research(wait_for_completion=false, retain_chat=true) |
an opaque operation/chat handle is preserved immediately; a later result yields a report |
| Generate or edit images | low-token create(type="image") / edit; primary media tools when exact controls are needed |
a usable image Artifact, preferably a verified local file |
| Generate video or music | low-token `create(type="video" | "music")` or primary media tools |
| History, Notebook, Scheduled, Gem, Prompt, usage, or cleanup | low-token account facades or narrow primary profiles | only the explicitly requested account operation is performed |
Load workflows.md for detailed task routes.
Default Server Choice
Use gemini-mcp-skill-server for the smallest current tool surface when it can complete the task.
Use the primary server only for a narrow profile:
GEMINI_TOOLS=modelfor text/session work;GEMINI_TOOLS=corefor files, URLs, media, and Deep Research;GEMINI_TOOLS=historyorhistory-organizefor explicit history work;GEMINI_TOOLS=account-readfor explicit account inventory;GEMINI_TOOLS=scheduled-adminonly for requested scheduled mutations.
Do not use GEMINI_TOOLS=all as a general-agent default.
The repository is migrating toward three dedicated products. gemini-assist is now implemented as the dedicated gemini-mcp-assist server (gemini_ask, gemini_search, gemini_understand_image, gemini_understand, gemini_research) with its own gemini-assist Skill; gemini-create and gemini-account are not implemented yet. This Skill remains the compatibility router until they land.
Standard Workflow
- Identify the user's intended outcome.
- Choose exactly one capability lane.
- Call the narrowest current tool that can complete it.
- Read the structured result before trusting compatibility prose.
- Continue the user's actual task with the result or Artifact.
- Use manifest or diagnostics only when discovery or recovery is needed.
Do not call the manifest before every known workflow. Use gemini_get_tool_manifest or account(action="manifest") when:
- the expected tool is unavailable;
- a schema or profile appears different;
- the user asks what is supported;
- upstream drift is suspected.
Information Versus Artifacts
Search and understanding normally return information to the calling agent. The agent should synthesize it and continue working rather than dumping raw Gemini output.
Generation normally returns an Artifact. The agent should pass that file or URI to the next relevant tool:
- add the image to the document, website, slide, or app;
- use the edited image instead of merely reporting its path;
- attach the video or audio to the requested project;
- read and cite the research report.
A path, URI, or success sentence alone is not completion. Load artifacts.md for acceptance and handoff rules.
Long Operations
Deep Research, video, and music are long operations. Start them asynchronously by default.
Preserve every returned operation_id, upstream_operation_id, upstream_chat_id, and Artifact identity. Do not start a duplicate operation merely because one MCP call timed out.
Until the shared local operation registry lands, use start-only/current typed states and retain the upstream IDs. The target contract is an opaque, restart-safe handle stored in local SQLite with no prompt, chat, Cookie, or raw-response content.
Load operations.md before running or recovering a long operation.
Account Workflows
Only load or use account operations when the user explicitly asks to work with Gemini account data.
Start with list/search/read actions, identify the exact object, then mutate or delete it. A remote request being accepted is not proof that the target state changed; require positive read-back before claiming success.
For browser Cookie export, obtain explicit user approval because it can create sensitive account-authentication material in a local cache. Session reset changes only MCP/Gemini conversation state; it never changes agent memory or agent instructions.
Load tool_surface.md only when detailed account, privacy, destructive, or profile information is needed.
Recovery
Load recovery.md when a tool is missing, authentication fails, an entitlement is unavailable, a long operation times out, an Artifact is incomplete, or Gemini Web behavior appears to have drifted.
Do not convert an unavailable entitlement, an ungrounded answer, a queued operation, or an accepted-but-unverified mutation into a success claim.