Artifact tool for start-of-work preparation: compose implementation brief, verification plan, change plan, and flow map into one typed preflight artifact. Basis is stable — identical inputs produce the same artifactId, so callers may dedupe on it.

Artifact tool for reusable implementation handoff: compose one implementation brief and the current session handoff into a typed handoff artifact. Basis is session-scoped — session_handoff shifts with every tool call, so artifactId moves between calls by design (each call captures the current session state). Do not dedupe on artifactId.

Artifact tool for reviewer-facing change inspection: compose implementation brief, change plan, optional flow map, and optional tenant audit into one typed review bundle. Basis is stable — identical inputs produce the same artifactId, so callers may dedupe on it.

Artifact tool for safe completion and verification: compose verification plan, project-intelligence signals, and optional tenant audit into one typed verification bundle. Basis is stable by default; artifactId shifts across calls only when includeSessionHandoff or includeIssuesNext is set, because those inputs are session-scoped. Dedupe is safe when both flags are off.

Workflow tool for tool-chain recommendations: choose one canonical workflow or a short ordered sequence without executing hidden planner logic.

Workflow tool for bounded read-only investigation: run a short sequential tool chain over shipped workflows and return typed step history.

Graph tool for adjacency questions: traverse outward from one or more start entities with explicit direction, depth, and edge filters.

Graph tool for connection questions: find one shortest typed path between two entities while keeping heuristic edges explicit and opt-in.

Graph tool for end-to-end flow questions: turn one graph path into ordered flow steps, transitions, and major boundary crossings.

Graph tool for bounded change scope: return path-derived direct surfaces, one-hop dependent surfaces, and an explicit dependency order.

Operator tool for tenant-boundary review: audit tenant-keyed tables, RLS posture, and RPC/code touch points without making generic security-score claims.

Operator tool for derived project-state handoff: summarize recent answer traces, active unresolved focus, and recorded follow-up momentum.

Read-only session-recall tool: search prior project answer traces by text, query kind, support level, trust state, and ISO time window. Returns bounded answer summaries, pre-cap matchCount, truncation signal, and optional stored answer markdown. Does not run the answer loop or infer freshness.

Read-only session-recall tool: inspect prior project tool_runs by tool name, outcome, request id, and ISO time window. Returns bounded summaries with runId plus requestId when available; use requestId as agent_feedback.referencedRequestId. Default limit is 50, max 500. Persisted payloads are only included when includePayload is true.

Neighborhood composer for one table: combines db_table_schema/db_rls-equivalent schema snapshot data, schema_usage read/write sites, trace_table RPC-to-table edges, and route_trace handler routes into one bounded typed bundle.

Neighborhood composer for one route: combines route_trace route resolution, file_health handler summary, imports_deps direct imports/dependents, schema_usage touches, trace_rpc downstream table edges, and db_rls policy surfaces.

Neighborhood composer for one RPC: combines db_rpc-equivalent schema snapshot signature/body, schema_usage app-code callers, trace_rpc function-to-table refs, and db_rls policies on touched tables into one bounded bundle.

Append-only feedback tool for rating a prior Mako tool run from the agent perspective. Use sparingly when a result was notably good, notably bad, or wrong; do not emit routine feedback after every call. Requires referencedToolName and referencedRequestId so each row is tied to a specific prior run. Grade semantics: full = helped complete the task, partial = somewhat useful but flawed, no = wrong or wasted the turn. Starter reason codes: full: answer_complete, evidence_sufficient, trust_matches; partial: partial_coverage, noisy, stale_evidence, missing_known_caller, top_not_useful; no: answer_wrong, wasted_turn, tool_did_nothing, schema_missing.

Read-only inspection over agent_feedback rows in mako_usefulness_events: return grade counts by referenced tool plus bounded recent entries, filterable by referencedToolName, grade, and ISO time window. Use to review which tools agents found helpful, noisy, wrong, or incomplete.

Operator tool for project-state trend review: compare a recent trace window against a prior window without fabricating trend lines when history is thin.

Operator tool for queue-oriented recommendations: derive one current issue plus queued follow-on issues from recent unresolved project traces.

Answer tool for route questions: trace a route to the indexed handler, matching files, and nearby evidence.

Answer tool for schema questions: find where an indexed schema object is defined and directly referenced in app code. RPC-mediated touches are intentionally excluded; use trace_rpc, route_context, table_neighborhood, or flow_map for transitive schema paths.

Answer tool for file questions: summarize a file's role, dependents, and notable risks with evidence.

Answer tool for auth questions: trace likely auth boundaries for a route, file, or feature without overclaiming. When no exact route/file/feature match exists, returns matched:false with suggestedNext:{ tool:"cross_search", args:{...} } instead of throwing, so batches and agent workflows can continue.

Imports tool for direct dependencies: list a file's indexed imports and flag unresolved internal edges.

Imports tool for downstream impact: trace which indexed files depend on a file through the import graph.

Imports tool for graph hotspots: rank the most connected files in the indexed internal import graph.

Imports tool for cycle detection: detect circular dependencies in the indexed internal import graph.

Symbols tool for declarations: list the indexed symbols declared in a file.

Symbols tool for exports: list only the indexed symbols that a file exports.

Orientation tool for coding agents: given a natural-language task, return the recommended Mako workflow recipe as an ordered tool sequence with pre-filled suggestedArgs, batchable follow-ups, and notes. Use before reading long AGENTS/CLAUDE docs when deciding whether to start with context_packet, cross_search, file_preflight, lint_files, verification_state, or DB/Reef tools. Read-only and does not execute the returned steps.

Router tool: map one natural-language engineering question to one canonical named tool, or conservatively fall back to free_form.

Workflow tool: generate a typed workflow packet from a project-scoped query answer and expose watch/surface metadata.

Code-intelligence tool for structural pattern search: run one ast-grep pattern against every fresh indexed TypeScript / TSX / JavaScript / JSX file and return typed matches (file, line range, column range, matched text, captured metavariables). Ambiguous TSX/JSX snippets that start with {, [, or < retry with an auto-anchored const _ = ... parser context when the original pattern returns zero matches, and patternAttempts / match patternVariant report which form matched. Reef-backed freshness guard skips stale/deleted/unknown indexed files so old AST rows do not become phantom matches; set MAKO_REEF_BACKED=legacy for the one-release rollback path. Read-only; never edits files. Use when text/FTS search is too noisy for structural queries (e.g. console.log($X), await supabase.rpc($NAME), useEffect($FN, [])).

Code-intelligence tool for live filesystem text search: run ripgrep over the attached project root and return bounded file/line matches. Defaults to fixed-string matching; pass fixedStrings: false to use ripgrep regex syntax. Read-only and explicitly live, so use it when the indexed snapshot may be stale or when exact text search is the right primitive.

Code-intelligence tool for diagnostics on an indexed file set: run rule-packs, including canonicalHelper producer/consumer checks, plus TS-aware and structural alignment diagnostics; persist indexed Reef findings/run metadata under source lint_files; and return typed AnswerSurfaceIssue findings. Same engine that powers the answer loop and review_bundle, so findings stay consistent across surfaces.

Explicit Reef ingestion tool for semantic TypeScript compiler diagnostics: read tsconfig, run the TypeScript program with no emit, persist working-tree ProjectFinding rows under source typescript, and return bounded findings. This may run a broad typecheck; use diagnostic_refresh with typescript_syntax for syntax-only refresh.

Explicit Reef ingestion tool for ESLint diagnostics: run the project's local ESLint executable on the requested project-relative files with JSON output, persist working-tree ProjectFinding rows under source eslint, and record unavailable/error/succeeded run status. File-mode only; does not run broad project lint.

Explicit Reef ingestion tool for Oxlint diagnostics: run the project's local Oxlint executable or JSON package script on requested project-relative files with --format json, persist working-tree ProjectFinding rows under source oxlint, and record unavailable/error/succeeded run status. File-mode only; does not run broad project lint.

Explicit Reef ingestion tool for Biome diagnostics: run the project's local Biome executable or GitLab-reporter package script on requested project-relative files with check --reporter=gitlab, persist working-tree ProjectFinding rows under source biome, and record unavailable/error/succeeded run status. File-mode only; deliberately avoids Biome's experimental JSON reporter.

Git pre-commit guard for staged TS/TSX files: reads staged blobs, checks API route auth guards and Next.js server/client boundary mistakes, persists staged Reef findings unless MAKO_REEF_BACKED disables the migration, and returns hook-friendly continue/stopReason output. Uses discovered project-profile auth guards/server-only modules plus optional .mako/git-guard.json/input allowlists. Never edits the index or worktree.

Explicit Reef diagnostic ingestion runner: invoke selected diagnostic sources (lint_files, programmatic_findings, typescript_syntax, TypeScript, ESLint, Oxlint, Biome, or git_precommit_check), persist their Reef diagnostic runs/findings through the underlying tools, and return a compact per-source summary. File-mode sources are skipped unless files are supplied; this is a mutation tool because it refreshes Reef state.

Explicit Reef DB ingestion tool: replace indexed Reef facts for the current schema snapshot, including schemas, tables, columns, indexes, foreign keys, RLS policies, triggers, enums, RPCs, RPC-to-table refs, and indexed schema usages. Uses the existing schema snapshot/read-model indexes; run project_index_refresh first if the snapshot is stale or missing.

Append-only DB review note tool: leave a short AI/operator comment on a database object such as a table, column, policy, trigger, publication, replication slot, or general replication topic. Writes only to Mako's local project store; it never mutates the live database.

Read DB review comments from Mako's local append-only ledger, filterable by database object, category, tag, free-text query, or target fingerprint. Use during schema/table/RLS/replication review to recover prior AI/operator notes.

Code-intelligence tool for repo orientation: emit a token-budgeted aider-style outline of the indexed project (ranked files + key symbols) as first-turn context for agents meeting an unfamiliar codebase. Ranking approximates centrality via fanIn * 2 + fanOut + 0.1; symbol selection prefers exported declarations. Read-only; default budget 1024 tokens (char/4 approximation), cap 16384.

Context scout for coding agents: turn a messy request into ranked, source-labeled, readable context using deterministic providers first (files, routes, symbols, schema, import graph, centrality, hot hints). Reef-backed enrichments add working-tree overlay metadata and active findings; use risksMinConfidence to suppress low-confidence risk speculation. Set MAKO_REEF_BACKED=legacy for the one-release rollback path. Read-only; does not refresh the index. Use as the first-mile packet before normal harness read/search/edit loops.

Read-only batching wrapper for independent Mako lookups. The input schema only accepts batchable read-only tools; runtime also rejects mutation tools and recursive tool_batch calls defensively. Returns labeled sub-results with per-op duration. Use verbosity: "compact" or per-op resultMode: "summary" to return compact summaries instead of full payloads; per-op resultMode: "full" keeps the full output. Each sub-op's projectId is overridden with the parent batch's resolved project, so all ops run against one project. Use to reduce round-trips after a context_packet recommends several expansions.

Project tool for index freshness: compare indexed file rows against live disk metadata, report Reef working-tree fact freshness, watch state, latest index run, unindexedScan status, and a suggested next action. By default this checks indexed rows only and reports that the new-file scan was skipped; pass includeUnindexed: true to pay the repo walk cost and get an exact count/details for files not yet in the index. Trust/stability is not freshness; this tool answers whether the index snapshot is current.

Mutation tool for index freshness: run the project indexer through the current project-store cache when the snapshot is stale, unknown, deleted, or has unindexed files, then return before/after freshness summaries and the new index run. In if_stale mode, unknown freshness refreshes defensively and unindexed files count as stale work.

Read-only inspection over mako_usefulness_events (Phase 8.1): return aggregate counts (by decisionKind, by family, by grade) and a bounded list of recent events, filterable by decisionKind, family, requestId, and ISO time window. Use to verify usefulness capture is flowing or to triage why a decision site emitted the grade it did. Never writes to the event table.

Mutation tool for verified-safe markers: append one row to the finding_acks ledger so subsequent ast_find_pattern / lint_files callers that opt into the same category filter the match out. Category is caller-owned (for lint findings, finding.code is the recommended default). For ast_find_pattern matches, pass match.ackableFingerprint; for lint_files findings, pass finding.identity.matchBasedId. Append-only; duplicate (projectId, category, fingerprint) inserts persist as separate rows and dedupe at query time. Emits one RuntimeUsefulnessEvent per successful call.

Mutation batch for reviewed finding acknowledgements: append many finding_acks rows in one call while sharing batch-level defaults for category, subjectKind, status, reason, acknowledgedBy, sourceToolName, and sourceRuleId. Use when a scan returns many reviewed false positives or accepted tradeoffs. Emits one finding_ack telemetry event per successful row.

Read-only inspection over the finding_acks ledger: return aggregate counts (by category, status, subjectKind, filePath) and a bounded reverse-chronological list of acks, filterable by category, subjectKind, filePath, status, and ISO time window. Use to see what operators have suppressed and which categories carry the most weight. Never writes to the ledger.

Reef read tool for active project findings: query the durable Reef findings view by overlay, source, status, and resolved inclusion. The source filter accepts a producer source, bare rule ID, or rule_pack:. Acknowledged status is derived from the existing finding_ack ledger, so this is the canonical read path for Reef-native lint/rule findings.

Reef read tool for one project-relative file: return durable Reef findings attached to that file, with the same overlay/source/status filters as project_findings, including source aliases for bare rule IDs and rule_pack:. Use this before editing a file when a shell or agent needs known active diagnostics without rerunning broad lint.

Reef pre-edit composer for one file: returns durable findings, file-scoped diagnostic freshness, source-filtered recent runs, watcher diagnostic state, applicable conventions, and finding acknowledgement history in one read-only packet. Use before editing a file when an agent needs the operational gate without separate file_findings, verification_state, project_conventions, and finding_acks_report calls.

Reef read tool for durable project facts: query facts by overlay, source, kind, and subject fingerprint. Use this when an agent or shell needs the calculated substrate behind findings without rerunning analysis.

Reef read tool for one file's durable facts: computes the file subject fingerprint and returns facts such as working_tree_overlay file_snapshot rows. Use this to inspect what Reef currently knows about a file across overlays.

Advisory Reef mutation: snapshot working-tree file facts for explicit files, watcher-dirty paths, or non-fresh indexed paths. Persists file_snapshot facts with size, mtime, line count, sha256, or deleted state; it does not reparse AST, imports, routes, or schema.

Reef read tool for overlay comparison: diff durable facts between two overlays, defaulting indexed vs working_tree, with optional filePath/kind/source filters. Use after working_tree_overlay or before edits to see exactly what Reef believes changed without rerunning diagnostics.

Reef mid-edit impact composer: for changed working-tree files, return affected import callers, active caller findings that may need re-checking, and conventions the diff or impacted callers may violate. Reads existing working_tree_overlay facts and import graph state; it does not refresh or mutate Reef.

Reef read tool for scoped project instructions: load .mako/instructions.md and applicable AGENTS.md files for requested project-relative files, returning structured instruction items plus derived Reef fact shapes. Reads only inside the project root and does not persist facts.

Reef read tool for rule metadata: list durable rule descriptors, optionally filtered by source namespace or enabled-by-default status. Descriptors explain which facts a finding source consumes and what rule ids mean.

Read-only Reef rule-pack authoring tool: validate .mako/rules YAML packs, including canonicalHelper cross-file declarations; return pack/rule counts, schema errors, and optional ReefRuleDescriptor previews without running diagnostics or writing Reef state.

Read-only Reef rule-pack mining tool: inspect a local git fix diff and propose .mako/rules YAML templates from removed TS/JS anti-pattern shapes, with related durable findings when available. Does not write files or mutate Reef state.

Reef read tool for diagnostic source runs: list recent lint/type adapter runs by source and status, including unavailable/error/succeeded state, duration, counts, command, config, cwd, metadata, and derived cache freshness/age. Use this to distinguish no findings from a diagnostic source that did not run or ran too long ago.

Reef 7 model-facing scout view: turn a messy request into intent-weighted, explainable candidates from durable Reef facts, findings, rules, and diagnostic runs. App-flow queries prefer files/routes/findings; RLS/schema queries prefer database evidence. This is a context scout, not an editing agent; use normal harness read/search after the packet.

Reef 7 inspection view: explain one file or subject fingerprint by returning its durable facts, findings, and relevant diagnostic runs. Use after reef_scout when the model needs the evidence trail and freshness details before editing.

Reef maintained structural query: answer where a symbol, component, route, file, or indexed pattern is defined and used from maintained symbols/imports/routes first, then supplement symbol/component answers with indexed identifier-text references and related durable findings. Does not run grep; coverage explains import-graph/text/finding limits and returns fallback tool args when maintained state has no answer.

Reef 8 open-loop view: list unresolved active findings, stale or unknown facts, and stale or failed diagnostic runs so an agent can see what still needs attention without rerunning broad checks.

Reef 8 verification state view: summarize whether cached diagnostic runs still cover the current working-tree overlay, including file-scoped recent runs, watcher diagnostic state, files modified after successful checks, and suggested verification actions. With files, runs only count when project-wide or scoped to those files.

Reef 9 convention view: surface explicit convention facts plus profile/index/rule-derived convention candidates such as auth guards, runtime boundaries, generated paths, route patterns, and schema usage conventions.

Reef 9 rule-memory view: aggregate Reef rule descriptors and finding history so agents can see which rules are active, acknowledged, resolved, or suppressed before making changes.

Reef 10 evidence-confidence view: label facts and findings as verified_live, fresh_indexed, stale_indexed, fuzzy_semantic, historical, contradicted, or unknown so model-facing tools can prefer trustworthy evidence.

Reef 10 conflict view: surface stale indexed evidence, explicit conflict facts, and findings that report incorrect or contradictory evidence, with suggested cross-check actions.

Reef warm issue query: answer "have any errors?" from maintained Reef findings and diagnostic readiness state without launching broad lint or typecheck commands.

Reef agent-loop status summary: report maintained known issues, changed files needing verification, stale diagnostic sources, schema freshness, watcher degradation, and background queue state. Never edits files.

Read-only database tool: verify connectivity and surface platform, version, schemas, and transaction state.

Read-only database tool for column questions: inspect only columns and primary-key details for a table via pg_catalog.

Read-only database tool for relationship questions: inspect inbound and outbound foreign-key references for a table via pg_catalog.

Read-only database tool for security questions: inspect row-level security state and policies for a table via pg_catalog.

Read-only database tool for function questions: inspect one stored procedure or function signature, args, return shape, language, and security.

Read-only database tool for full table shape: inspect columns, indexes, constraints, foreign keys, RLS, and triggers.

Trace a file end-to-end from the snapshot: declared symbols, outbound imports, inbound dependents, routes contributed, and related evidence. Read-only.

Return the full preflight surface for a table: columns, primary key, indexes, foreign keys, RLS state + policies, triggers, related routes, and zod schemas whose surrounding file references the table. Snapshot-strict.

Search a term across code chunks, schema objects, RPC/trigger bodies, routes, and stored memories in one call. Returns grouped indexed evidence with freshness details per source. Snapshot-strict; use live_text_search when you need a live disk fallback for recently edited or unindexed files.

Trace a handler / edge function: its own route, app-code callers (ast-grep on fetch('/functions/v1/$NAME') and supabase.functions.invoke('$NAME')), tables and RPCs the handler touches, and DB triggers whose body references the name. Snapshot-strict.

Trace an error term across throw sites (ast-grep throw new Error($MSG), throw new $ERR($MSG)), catch handlers (ast-grep try/catch), and PL/pgSQL bodies that reference the term. FTS narrows the ast-grep pass. Snapshot-strict.

Trace a table end-to-end: columns, indexes, foreign keys, RLS, triggers (via getSchemaTableSnapshot), schema-scoped RPC → table edges (via listFunctionTableRefs), and app-code .from('$TABLE') call sites (FTS-retrieval + ast-grep proof). Snapshot-strict.

Trace an RPC end-to-end: the RPC definition (searchSchemaObjects filtered to rpc), other PL/pgSQL bodies whose body text references it (searchSchemaBodies), overload-aware table refs (listFunctionTableRefs), and app-code .rpc('$FN') call sites (FTS-retrieval + ast-grep proof). Snapshot-strict.

Search the MCP-visible tool catalog, including deferred and blocked tools. Use when you are unsure which tool fits a task or why a tool is unavailable over MCP.

Create or overwrite a file at a project-relative path. Returns a snapshot id for undo.

Replace a substring in an existing file. The substring must occur exactly once unless replaceAll is true.

Create a new file at a project-relative path. Errors if the file already exists; use file_write to overwrite.

Delete a file at a project-relative path. Snapshot captures the bytes for undo.

Apply a multi-file unified diff. Hunks must apply cleanly with exact context.

Run a shell command with arguments as a list (never concatenated). cwd is locked to the project root or a subdirectory; env keys must be allowlisted.