match hosted mcp tools to what the server serves

agents/capabilities.mdx

@@ -9,26 +9,27 @@ icon: "map"
 
 import { PromptBlock } from '/snippets/hero-install.jsx';
 
-When your coding agent connects to [Graphify MCP](/platform/graphify-mcp), it gets a set of Graphify tools. This page maps each job you might want done to the tool that does it, with a prompt you can paste. You don't have to name tools in your prompts. Naming them makes it easier to check that the agent used the graph.
+When your coding agent connects to [Graphify MCP](/platform/graphify-mcp), it gets Graphify's tools. Your client shows the current list from `tools/list`. This page maps each job to the tool that does it, with a prompt you can paste. You don't have to name tools in your prompts. Naming them makes it easier to check that the agent used the graph.
 
 ## At a glance
 
 | You want to | Ask your agent to use |
 | --- | --- |
 | See which repositories it can query | `list_repositories` |
-| Find where something is defined | `graphify_find`, `search`, `fetch` |
+| Find where something is defined | `graphify_find`, `search`, then `fetch` |
 | Find the files that matter for a question | `graphify_rank_files` |
 | Understand how a feature works | `query_graph`, `graphify_node` |
-| See who calls a function, and what it calls | `graphify_callers`, `graphify_callees` |
-| Follow a call path from one function to another | `graphify_trace`, `shortest_path` |
-| Find non-call uses of a symbol | `graphify_references` |
+| See who calls a function | `graphify_callers` |
+| See the code directly connected to a function, including what it calls | `graphify_impact` |
+| Follow a call path from one function to another | `graphify_trace` |
 | Map a file's imports and dependents | `graphify_imports_exports`, `graphify_file_neighbors` |
-| Size up a change before making it | `graphify_impact`, `impact_and_risk` |
-| Find the tests linked to code | `graphify_tests_for` |
-| Check that a repository is indexed, and how fresh it is | `graph_stats` |
-| Read or save what the team remembers | `recall`, `memories_about`, `remember` |
+| Size up a change before making it | `graphify_impact` with `include_risk`, `graphify_tests_for` |
+| Check that a repository is indexed, and how large the graph is | `graph_stats` |
+| Read or save what the team remembers | `recall`, `remember` |
 | Read how a pull request review went | `review_status` |
 | Switch between Graphify workspaces | `list_workspaces`, `set_workspace` |
+| Look up setup, which tool to use, or this workspace's plan limits | `graphify_help` |
+| Run a task handed off from a repository page | `run_repository_starter_task` |
 
 ## Find code
 
@@ -40,25 +41,35 @@ When your coding agent connects to [Graphify MCP](/platform/graphify-mcp), it ge
 
 <PromptBlock text="Use Graphify's query_graph to explain how a user signs in, from the login route to the session being stored. Cite file paths and line numbers." />
 
-`query_graph` answers a question with the relevant definitions in full. `graphify_node` returns one symbol's code plus its immediate neighbors. `graphify_expand` turns ids from another tool's results into full code, and `graphify_render_subgraph` returns a small graph you can draw.
+`query_graph` answers a question with the relevant definitions in full. Set `skeleton` when you only need outlines instead of bodies. `graphify_node` returns one symbol's code plus its immediate neighbors. To read one `search` hit, pass its `id` to `fetch` unchanged.
 
 ## Follow calls and dependencies
 
-<PromptBlock text="Use graphify_callers on chargeCard to list everything that calls it, then graphify_trace from the checkout handler to chargeCard. Tell me which paths skip the retry wrapper." />
+<PromptBlock text="Use graphify_callers on chargeCard to list everything that calls it. Tell me the file and line for each caller." />
 
-`graphify_callers` and `graphify_callees` list direct calls. `graphify_trace` returns directed call paths between two symbols, and `shortest_path` returns the most confident connection between them. `graphify_references` finds uses that aren't calls, such as reads and mentions. `graphify_imports_exports` and `graphify_file_neighbors` work at the file level.
+`graphify_callers` lists who calls a symbol. By default it counts only resolved call edges. Set `strict_calls` to false to include weaker, inferred edges. An empty list means no edge was indexed, not that the code has none. If the name matches more than one definition, the tool refuses and lists the candidate ids. Pass an id to pick one.
+
+`graphify_impact` returns the callers and callees directly connected to a symbol. That is a first pass, not every indirect dependency.
+
+`graphify_imports_exports` returns a file's import and export edges. `graphify_file_neighbors` maps what a file imports, what imports it, and the per-file blast radius. Set `symbols_only` to get that file's definitions and signatures without bodies.
+
+## Follow a call path
+
+<PromptBlock text="Use graphify_trace from the checkout handler to chargeCard. Tell me which paths skip the retry wrapper." />
+
+`graphify_trace` returns directed call paths from `src` to `tgt`. If a name does not resolve, it can fall back to a semantically similar node. Check `resolved.src` and `resolved.tgt` (`exact` or `semantic`) and the labels on the result. An empty path means no path was found in the indexed graph.
 
 ## Change code safely
 
-<PromptBlock text="Before you change parseConfig, call graphify_impact and impact_and_risk on it, then graphify_tests_for. List the files most at risk and the tests I should run." />
+<PromptBlock text="Before you change parseConfig, call graphify_impact on it with include_risk, then graphify_tests_for. List the hotspot files and the tests I should run." />
 
-`graphify_impact` lists the code directly connected to a symbol. It's a first pass, not every indirect dependency. `impact_and_risk` ranks the riskiest files by combining that with linked test coverage. `graphify_tests_for` lists tests linked through the graph. All three read the graph. They don't run tests or prove that a change is safe.
+`graphify_impact` lists the callers and callees directly connected to a symbol. It's a first pass, not every indirect dependency. Set `include_risk` to also rank hotspot files by linked-test coverage. That ranking is a signal from the graph, not a verdict that the change is safe. `graphify_tests_for` lists tests linked through the graph to a symbol or a file. Both read the graph. They don't run tests.
 
 ## Use what your team remembers
 
-<PromptBlock text="Before you edit src/billing/retry.ts, call memories_about on that path and tell me any decisions or gotchas recorded for it." />
+<PromptBlock text="Before you edit src/billing/retry.ts, call recall with a question about that file and pass the path in paths. Tell me any decisions or gotchas that come back." />
 
-`memories_about` returns what's remembered about one file or symbol. `recall` searches memory with a question. `remember` saves one fact. Have your agent ask you before it saves anything. Saved facts wait for review before they're published. See [Memory](/platform/memory).
+`recall` searches what the workspace remembers. Pass repo-relative paths in `paths`, and function or class names in `symbols`, so notes tied to that code can rank first. Those are hints, not a filter. `remember` saves one fact. Have your agent ask you before it saves anything. Saving records intake, not publication, until someone keeps it in **Memory**. See [Memory](/platform/memory).
 
 ## Search your documents
 
@@ -72,7 +83,11 @@ See [Connect Google Drive](/platform/connectors#connect-google-drive).
 
 <PromptBlock text="Call list_workspaces and list_repositories and tell me which Graphify workspace is active and which repositories you can query." />
 
-Most tools take a `repository_id`, either an id or a name like `acme/web-app`. `graph_stats` shows whether a repository is indexed and when. `set_workspace` switches the workspace for the current session. Your agent can also start a task handed off from a repository page with `run_repository_starter_task`.
+Most tools take a `repository_id`, either an id or a name like `acme/web-app`. `graph_stats` shows whether a repository is indexed and how large the graph is: node and edge counts, and languages. `set_workspace` switches the workspace for the current session. `graphify_help` answers questions about Graphify itself. `topic` is `setup`, `plan`, `repositories`, `tools`, or `troubleshooting`. `plan` is this workspace's plan and usage.
+
+## Run a handed-off task
+
+`run_repository_starter_task` runs a task handed off from a repository page. Pass its `task_id` unchanged. It returns source context for that task and records that the context was delivered. It does not record that your agent finished the answer.
 
 ## What the tools don't do
 

agents/overview.mdx

@@ -19,51 +19,54 @@ Default to the hosted server. Use open-source Graphify only when the user asks f
 | --- | --- | --- |
 | Hosted MCP server | Default. The user's repositories are indexed at [app.graphify.com](https://app.graphify.com?utm_source=docs&utm_medium=link&utm_campaign=agents-overview). | Add `https://api.graphify.com/mcp` as a remote Streamable HTTP server. Sign-in is OAuth in the browser; there is no API key. Commands per agent: [Setup for AI agents](/for-agents#setup-for-ai-agents), step 2. |
 | One-click installs and plugins | The user prefers to click instead of editing config. | [Install in Cursor](/integrations/cursor), the [VS Code extension](/integrations/vscode), and the [Graphify plugin for ChatGPT and Codex](/integrations/chatgpt). All three connect to the same hosted server. |
-| Graphify CLI | The user asks for an offline or on-machine graph. | `uv tool install graphifyy`, then `graphify install`. See the [Graphify CLI quickstart](/open-source/quickstart). Its MCP server has [ten tools](/open-source/features/mcp-tools) with different names from the hosted ones. |
+| Graphify CLI | The user asks for an offline or on-machine graph. | `uv tool install graphifyy`, then `graphify install`. See the [Graphify CLI quickstart](/open-source/quickstart). Its MCP tools are in the [MCP tool reference](/open-source/features/mcp-tools), and the names differ from the hosted ones. |
 
 Before you change a config file, tell the user what you will change and wait for a yes. After you connect, check the connection with `list_repositories`. If anything fails, use [Check your agent is using Graphify](/platform/verify-connection).
 
 ## Pick the tool
 
-The hosted server sends instructions on connect that map question types to tools, and it lists 27 tools. Your client builds its tool list from the server, so trust the live tool list and its input schemas over this table.
+The hosted server sends instructions on connect that map question types to tools. Your client builds its tool list from the server's `tools/list` response, so trust that live list and its input schemas over this table.
 
 | The user asks | Call |
 | --- | --- |
 | Which repositories or workspaces can I query? | `list_repositories`, `list_workspaces` |
 | How does X work? | `query_graph` |
 | Where is X defined? | `graphify_find`, or `graphify_node` for the body and its neighbors |
 | Find a definition by part of its name, then read it | `search`, then `fetch` with a result's `id` |
-| Who calls X? What does X call? | `graphify_callers`, `graphify_callees` |
-| How does A reach B? | `graphify_trace` for a directed call path, `shortest_path` for any connection |
-| What could break if I change X? | `graphify_impact` for the directly connected callers and callees, then `impact_and_risk` to rank the files by linked tests |
-| Where is X used, other than calls? | `graphify_references` |
+| Who calls X? | `graphify_callers` |
+| What is directly connected to X, including what it calls? | `graphify_impact` |
+| How does A reach B? | `graphify_trace` |
+| What could break if I change X? | `graphify_impact`. Set `include_risk` to rank hotspot files by linked-test coverage. `graphify_tests_for` lists linked tests. |
 | Which tests cover X? | `graphify_tests_for` |
 | What does this file import, and what imports it? | `graphify_file_neighbors`, or `graphify_imports_exports` for its import and export edges |
-| Is the repository indexed, and how fresh is it? | `graph_stats` |
+| Is the repository indexed, and how large is the graph? | `graph_stats` |
 | Which files matter for this task? | `graphify_rank_files` |
-| What did the team decide about X? | `recall`, `memories_about` |
+| What did the team decide about X? | `recall`. Pass `paths` and `symbols` for the code you are about to change so those notes can rank first. |
+| How do I set Graphify up, or which tool fits? | `graphify_help` |
+| What did a pull request review find? | `review_status` |
+| Run the task handed off from a repository page | `run_repository_starter_task`, with its `task_id` unchanged |
 
 Rules for the results:
 
 - Use a `repository_id` from `list_repositories`: the UUID or the `owner/name`. Never invent an ID or silently pick a different repository.
-- Check the returned symbol and file before you cite them. If a name matches several symbols, the result lists them under `ambiguous`. Say which one you used. If a name doesn't resolve, you get an error with similar `candidates`, or a `semantic` match instead of an `exact` one. Say so and don't treat it as the symbol the user asked about.
-- Results carry `freshness`: the indexed commit and its age. Mention it when the age matters.
-- An empty caller list means the index returned no callers. It does not prove the symbol is unused.
+- Check the returned symbol and file before you cite them. If a name matches several definitions, `graphify_callers` and `graphify_node` refuse and list the candidate ids. Pass an id to pick one, and say which one you used. If a name does not resolve, `graphify_node` can return a semantic match. The `resolved` field is `exact` or `semantic`. A semantic result is a suggestion, not proof the symbol exists.
+- `graphify_trace` can also return a semantic match for `src` or `tgt`. Check `resolved.src` and `resolved.tgt`. An empty path means no directed call path was found in the indexed graph. Dynamic calls can hide a real path, so don't say A never reaches B from an empty path alone.
+- An empty caller list means no call edge was indexed. It does not prove the symbol is unused.
 - `search` and `graphify_find` match part of a symbol's name, like `ReaSource` or `webhook`, not a question. If a fragment returns nothing, try another name or ask `query_graph` in a full sentence.
-- If `graphify_trace` finds no directed call path, it says so and returns the `frontier` it reached. Dynamic calls can hide a real path, so check the callees from there before you say A never reaches B.
-- An empty `recall` result means nothing is remembered for that repository yet.
-- Impact and test tools read the graph. They don't run tests or prove runtime behavior.
+- An empty `recall` result means nothing relevant is remembered yet.
+- `graphify_impact` and `graphify_tests_for` read the graph. They don't run tests or prove runtime behavior. `include_risk` ranks hotspot files by linked-test coverage. That ranking is a signal from the graph, not a verdict.
 - Use grep for exact strings, such as error messages or config keys.
 - If a Graphify tool fails or the repository isn't indexed, say so, then fall back to reading files. Don't guess.
 
 ## Ask before you change state
 
-The tools don't edit source files, but two of them change stored state on purpose. Ask the user first:
+The tools don't edit source files. Ask the user before you call a tool that changes stored state:
 
-- `remember` saves a note to the workspace's shared [Memory](/platform/memory). Save only what the user asked you to save.
+- `remember` saves a note to the workspace's shared [Memory](/platform/memory). Save only what the user asked you to save. Saving records intake, not publication, until someone keeps it.
 - `set_workspace` changes which workspace, and so which repositories, the session reads. With `make_default`, it also changes the user's default. See [Graphify MCP](/platform/graphify-mcp#workspaces-and-mcp-sessions).
+- `run_repository_starter_task` runs a task handed off from a repository page and records that it delivered source context. Call it only for that task, and pass `task_id` unchanged.
 
-In workspaces with trail capture turned on, `search`, `query_graph`, `graphify_find`, `graphify_trace`, `graphify_rank_files` and an unscoped `recall` can also save the question you asked to workspace memory. They never change source code.
+The hosted server does not capture tool calls as memory. `recall` reads notes the workspace already has, such as ones saved with `remember`, created through the API, or recorded from a workspace event such as a merged pull request.
 
 ## Keep answers fresh