Purpose: Return a safe, read-only summary of the Geond Agent Protocol MCP server. When to use: Call this first when an MCP host, Glama browser session, or new agent needs to understand what Geond does before connecting it to PostgreSQL. Inputs: none. Side effects: none; this tool never opens a database connection and does not read local transcripts. Output: server purpose, version, environment variables, tool groups, setup hints, and example workflows. Failure modes: only package metadata lookup fallback is expected, in which case the declared alpha version is returned.

Purpose: Search imported agent transcripts, changesets, and shared development memory for evidence relevant to a question. When to use: use this before editing, reviewing, or explaining repo behavior so the agent can reuse prior context. Inputs: query is the natural-language search text; mode selects keyword, vector, or hybrid retrieval; filters scope the search by workspace or source; rerank can improve ranking. Side effects: records an MCP audit event. Output: compact search hits with snippets, scores, sources, and evidence references. Failure modes: invalid mode raises an error; vector or hybrid search requires an embedding provider and database connectivity.

Purpose: Explain why a file may have changed using stored changesets, code graph entries, snapshots, and related messages. When to use: call during code review, bug triage, or handoff recovery when a file path needs historical context. Inputs: file_path identifies the repo-relative file; limit caps evidence volume; include_narrative adds a deterministic cited summary. Side effects: none beyond database reads. Output: changesets, touched entities, snapshots, related messages, and optional geond.evidence.v1 narrative citations. Failure modes: returns sparse evidence when the file was not indexed or imported.

Purpose: Retrieve full stored detail for one changeset. When to use: call after a search or file explanation returns a changeset id or git commit that needs closer inspection. Inputs: changeset_ref accepts a UUID, full git SHA, or unambiguous SHA prefix; include_narrative controls cited prose. Side effects: none beyond database reads. Output: files, touched code entities, evidence references, ambiguity status, and optional narrative. Failure modes: returns found=false for missing refs or ambiguous=true when a prefix matches multiple changesets.

Purpose: Find known code graph entities that match a symbol name. When to use: call before modifying a function, class, method, or variable so the agent can see definitions and related changesets. Inputs: symbol is the name to match; limit caps returned entities. Side effects: none beyond database reads. Output: matching entities with file locations, workspace data, related changesets, and evidence refs. Failure modes: returns an empty list when the code graph has not indexed the symbol.

Purpose: Link a moved or renamed workspace URI to an existing workspace record. When to use: call when the same repository appears under a new local path, mount point, or machine-specific URI. Inputs: workspace_id_or_uri selects the existing workspace; alias_uri is the new URI; reason and metadata document why it changed. Side effects: writes an alias row. Output: alias record details. Failure modes: fails if the referenced workspace cannot be resolved or the alias conflicts.

Purpose: Inspect workspace alias mappings. When to use: call when an agent is unsure whether two filesystem roots point to the same repository memory. Inputs: workspace_id_or_uri optionally scopes the list. Side effects: none beyond database reads. Output: alias rows including canonical workspace identifiers and reasons. Failure modes: returns an empty list when no aliases exist or the filter matches nothing.

Purpose: Store durable repository identity fingerprints for alias detection. When to use: call after discovering git remotes, first commits, or other stable repo identifiers on a workspace. Inputs: workspace_id_or_uri selects the workspace; fingerprints is a list of typed identity facts. Side effects: writes fingerprint rows. Output: stored fingerprint records. Failure modes: fails when the workspace cannot be resolved or fingerprint payloads are malformed.

Purpose: Suggest existing workspaces that may match a new alias URI based on identity fingerprints. When to use: call before creating a new workspace for a repo that may have moved. Inputs: alias_uri is the new path; fingerprints are observed durable identifiers. Side effects: none beyond database reads. Output: candidate workspace matches with confidence evidence. Failure modes: returns an empty list when no fingerprints overlap.

Purpose: Read reservation and conflict policy for a workspace. When to use: call before reserving files or symbols in a multi-agent workflow. Inputs: workspace_id_or_uri identifies the workspace. Side effects: none beyond database reads. Output: current conflict policy and related coordination settings. Failure modes: fails when the workspace cannot be resolved.

Purpose: Configure how the workspace handles reservation conflicts. When to use: call during setup or team policy changes before multiple agents edit in parallel. Inputs: workspace_id_or_uri identifies the workspace; reservation_conflict_policy chooses advisory, strict, or override-with-reason. Side effects: updates workspace policy. Output: updated policy record. Failure modes: invalid policy names are rejected.

Purpose: Persist a code changeset with files, optional patches, git metadata, and session links. When to use: call after an agent edits or reviews files so future agents can understand what changed and why. Inputs: files contains changed file objects; workspace_id or workspace_uri is required; metadata links commits, branches, intent, and sessions. Side effects: writes changeset and file rows. Output: changeset identifiers and summary fields. Failure modes: raises when no workspace identifier is supplied or payloads are invalid.

Purpose: Log what an agent is doing in a workspace. When to use: call at the start or end of meaningful work so other agents can see active intent and progress. Inputs: workspace_id, agent_name, action_type, summary, optional intent/status/session ids. Side effects: writes an activity row. Output: action_id for future references. Failure modes: fails when the workspace id is invalid.

Purpose: Reserve files so agents can coordinate parallel edits. When to use: call before modifying files that another agent might also touch. Inputs: workspace_id, agent_name, file_paths, purpose, TTL, and optional override reason. Side effects: creates reservation rows and audit events. Output: reservation status and any conflicts. Failure modes: strict policies may reject conflicts unless an override reason is allowed.

Purpose: Release active file reservations after work is done or abandoned. When to use: call at handoff, task completion, or when a stale reservation should be cleared. Inputs: workspace_id plus reservation_id or file_path, optionally scoped by agent_name. Side effects: updates reservation state and audit events. Output: count of released reservations. Failure modes: returns zero when no matching active reservation exists.

Purpose: Extend active file reservations while work continues. When to use: call before TTL expiry if an agent still owns the edit. Inputs: workspace_id plus reservation_id or file_path, optional agent_name, and new TTL. Side effects: updates reservation expiry and audit rows. Output: count of renewed reservations. Failure modes: returns zero when no matching active reservation exists.

Purpose: Read current file reservations for a workspace. When to use: call before editing or reviewing files to detect coordination conflicts. Inputs: workspace_id and optional file_paths filter. Side effects: none beyond database reads. Output: active reservations with agents, purpose, TTL, and file paths. Failure modes: returns an empty list when no active reservations match.

Purpose: Reserve functions, classes, or other symbols for finer-grained parallel coordination. When to use: call before editing shared APIs where file-level reservation is too broad. Inputs: workspace_id, agent_name, symbols, purpose, TTL, and optional override reason. Side effects: creates symbol reservation and audit rows. Output: reservation status and conflicts. Failure modes: strict policy may reject conflicting symbols.

Purpose: Release active symbol reservations. When to use: call after finishing work on a function, class, API, or other reserved symbol. Inputs: workspace_id plus reservation_id or symbol, optionally scoped by agent_name. Side effects: updates reservation state and audit rows. Output: count of released symbol reservations. Failure modes: returns zero when no matching reservation exists.

Purpose: Extend active symbol reservations while an agent is still editing. When to use: call before TTL expiry for ongoing API or function work. Inputs: workspace_id plus reservation_id or symbol, optional agent_name, and TTL. Side effects: updates reservation expiry and audit rows. Output: count of renewed symbol reservations. Failure modes: returns zero when no matching active reservation exists.

Purpose: Read active symbol reservations that could conflict with planned work. When to use: call before changing shared APIs or named entities. Inputs: workspace_id and optional symbols filter. Side effects: none beyond database reads. Output: active symbol reservations with owners, purposes, and expiry. Failure modes: returns an empty list when there are no active conflicts.

Purpose: Import language-server reference edges into the code graph. When to use: call after collecting definitions or references from an external LSP client. Inputs: workspace_id, reference payloads, and replace flag. Side effects: writes or replaces code graph reference rows. Output: import counts and status. Failure modes: malformed reference payloads or invalid workspace ids are rejected.

Purpose: Summarize relevant reservations, handoffs, lineage, and recent activity before work starts. When to use: call at the beginning of a task to avoid duplicating or conflicting with other agents. Inputs: workspace, intent, optional file paths, symbols, agent name, and limit. Side effects: records an MCP audit event. Output: compact review context with risks, reservations, handoffs, and lineage. Failure modes: returns limited context when workspace history is sparse.

Purpose: Store a structured handoff packet for the next agent or human reviewer. When to use: call when pausing, finishing, or transferring a task. Inputs: workspace_id, from/to agents, summary, next steps, blockers, tested commands, remaining risks, next action, and template. Side effects: writes a handoff row. Output: handoff_id for future retrieval. Failure modes: invalid workspace or malformed list fields are rejected.

Purpose: Retrieve handoff packets for a workspace or across workspaces. When to use: call when resuming a task, auditing pending work, or preparing context for another agent. Inputs: optional workspace filter, status filter, and limit. Side effects: none beyond database reads. Output: handoff summaries with status, agents, next steps, blockers, and risks. Failure modes: returns an empty list when no handoffs match.

Purpose: Inspect audit history for reservation lifecycle events. When to use: call during conflict analysis, stale reservation cleanup, or team coordination review. Inputs: optional workspace, reservation kind, action filter, and limit. Side effects: none beyond database reads. Output: created, renewed, released, and expired reservation events. Failure modes: returns an empty list when no events match.

Purpose: Mark a handoff as consumed or no longer active. When to use: call after the receiving agent has acted on the handoff or a human has reviewed it. Inputs: handoff_id and final status. Side effects: updates handoff status. Output: count of closed records. Failure modes: returns zero when the handoff id does not match an active row.

Purpose: Return a graph of major collaboration artifacts for a workspace. When to use: call when an agent needs a high-level map of sessions, changesets, handoffs, reservations, and activity. Inputs: workspace_id and limit. Side effects: none beyond database reads. Output: nodes and edges suitable for dashboard or orchestration analysis. Failure modes: returns a sparse graph for new or unindexed workspaces.

Purpose: Return normalized activity events for dashboards and orchestrators. When to use: call to inspect recent agent runs, reservations, handoffs, changesets, or status transitions. Inputs: workspace_id plus optional limit, kind, agent, and status filters. Side effects: none beyond database reads. Output: event records normalized for UI or agent consumption. Failure modes: returns an empty event list when no activity matches.

Purpose: Return a compact read-only dashboard summary for one workspace. When to use: call when a human reviewer, PM agent, or orchestrator needs current state without reading raw transcripts. Inputs: workspace_id and limit. Side effects: none beyond database reads. Output: summary cards, recent activity, handoffs, reservations, and risk signals. Failure modes: returns sparse sections for a new workspace.