Tool decision matrix
Use this matrix to pick a tool from an intent. Every tool name resolves
to mcp__opencodehub__<name> in the agent’s tool namespace. The
anti-pattern column says what not to reach for first.
Single-repo intents
Section titled “Single-repo intents”| Intent | Tool | Why this one | Don’t use |
|---|---|---|---|
| ”What does this function do?” | context | Returns the symbol’s signature, callers, callees, and the processes it participates in — one call. | query (returns search hits, not the 360° view); Read (you’ll miss the call graph). |
| ”If I change this, what breaks?” | impact | Computes upstream/downstream blast radius up to depth N, with a risk tier. | Grep (misses re-exports and dynamic dispatch). |
| ”Find me code about X” | query | Hybrid BM25 + vector search, results grouped by execution flow. | Embeddings-only search; Grep for concepts. |
| ”Plan a rename / refactor across files” | context + impact | Read-only. context lists every inbound/outbound ref, impact gives the dependent edit list and risk tier; you apply the edits in your editor, then verify with detect_changes. Catches dynamic dispatch, re-exports, and shadowed locals an editor’s textual rename misses. | Expecting an MCP tool to write the edits — the surface is read-only. |
| ”Bundle the codebase for an LLM” | pack_codebase | Deterministic 9-item BOM (manifest, skeleton, file-tree, deps, AST chunks, xrefs, optional embeddings, findings, licenses + readme) — byte-identical for the same (commit, tokenizer, budget). | Hand-rolled cat **/*.ts blob. |
| ”Who owns this file?” | owners | Top contributors with commit counts, last-touched dates, lines changed. | git blame parsing. |
| ”What’s the repo’s overall shape?” | project_profile | One call: language mix, top processes, hotspots, dependencies summary. | Multiple query calls. |
| ”What external packages do I depend on?” | dependencies | Returns the full external-dep list, scoped per package. | Reading package.json files manually. |
| ”What changed since this commit?” | detect_changes | Maps an uncommitted or committed diff to affected symbols and processes. | git diff (no graph context). |
| ”Run scanners now” | scan | Spawns the 20 Priority-1 scanners and writes SARIF. openWorld — only when the user explicitly asks. | Calling scan to “see if anything’s wrong” without consent. |
| ”Are there security findings on this branch?” | list_findings_delta | Diffs the latest scan against the frozen baseline (new / fixed / unchanged / updated). | list_findings if you only need the delta. |
| ”Show all current findings” | list_findings | Filterable by severity, scanner, file. | Re-running scan if a recent scan exists. |
| ”Is this PR safe to merge?” | verdict | 5-tier merge decision: auto_merge / single_review / dual_review / expert_review / block. Exit codes 0/1/2 from CLI. | Stitching impact + list_findings_delta by hand. |
| ”What HTTP routes does this service expose?” | route_map | Method, path, handler, file:line. Works across Express, Fastify, Hono, FastAPI, Flask, Spring, etc. | Grep for app.get(. |
| ”What’s the structural shape of this payload?” | shape_check | Detects payload/type drift across handlers and clients. | Manual diff of TypeScript interfaces. |
| ”What CLI/MCP tools does this codebase ship?” | tool_map | Surfaces commander/yargs/click handlers and MCP tool registrations. | Reading every entry-point manually. |
| ”What’s been deprecated or dead?” | list_dead_code | Read-only listing of unreferenced exports, dead functions, orphan files. Review the candidates, then delete them yourself — no MCP tool edits source. | tsc --noUnusedLocals (catches different things). |
| ”What’s the license tier of my deps?” | license_audit | Tiers each transitive dep: permissive / weak-copyleft / strong-copyleft / proprietary / unknown. | license-checker raw output. |
| ”Which areas are getting riskier?” | risk_trends | Per-community trend lines + 30-day projection from temporal data. | One-off risk snapshots. |
| ”Who is changing what most, and where” | risk_trends + owners | Trends point to communities; owners names the people. | Either alone. |
| ”Bespoke temporal query (cochanges / summaries)“ | sql | Read-only SQL against the temporal store (cochanges + symbol_summaries), 5s timeout. NOT the node/edge graph. | A typed tool covers it; or you need the graph — use Cypher (MCP sql cypher arg). |
Cross-repo group intents
Section titled “Cross-repo group intents”group_* tools require an indexed group. Run codehub group sync to
register one. See Cross-repo groups.
| Intent | Tool | Why this one | Don’t use |
|---|---|---|---|
| ”Which repos are in my group, and are they fresh?” | group_list + group_status | Inventory + per-repo staleness. | list_repos (single-repo scope). |
| ”Search across the whole group” | group_query | Fans out BM25 across the group. Returns { group, query, results[] }. | Calling query per repo. |
| ”Which services consume this API?” | api_impact (group) | Edges from API surface to downstream consumers across repos. | Grep across cloned repos. |
| ”Map the HTTP contract surface across services” | group_contracts | Producer/consumer matrix derived from route_map + client calls. | Hand-merged Postman collections. |
| ”Where does the group share types or DB schemas?” | group_cross_repo_links | Cross-repo references — typed shared models, schema imports, etc. | Searching every repo manually. |
When to chain
Section titled “When to chain”Some questions decompose:
- PR review without
verdict: chaindetect_changes→impact→list_findings_delta→ summarize.verdictdoes this in one call with a tier; use the chain when you need bespoke shaping. - Pre-rename safety:
context→impact→ review the edit list → apply edits in your editor →detect_changesto verify scope. The MCP surface is read-only; it plans and verifies, you make the edits. - New-engineer onboarding:
project_profile→ top processes fromquery→ entry points fromroute_mapandtool_map→ownersper area. Thecodehub-onboardingskill orchestrates this for Claude Code.
Idiomatic prompts Five worked examples — prompt, tools called, output shape.