MCP tools reference

This page lists every tool the Vibeless MCP server offers a connected agent. Use it to see what your agent can read and change, and to read the tool calls in an agent's transcript.

How the tools work

MCP (the Model Context Protocol) is the standard way a coding agent calls external tools. When you connect an agent (see Connecting agents), Vibeless adds its MCP server to the agent's configuration. The agent decides when to call each tool. You never call them yourself. You see the calls in the transcript and their effects in the app.

Every tool works on the one project whose token is in the agent's configuration. None of the tools use credits, because none of them calls an LLM.

Some tools format their answer for the agent profile on the Dashboard's Agent Adapter card: Markdown for Claude Code and Codex, compact text for Cursor, JSON for the generic MCP profile.

What agents cannot do: agents never edit a ticket's text, never change a phase, and never write constraints, non-goals, decision forbids, or path globs on an existing project. You change those in the app. The one exception is vibeless_create_project, which may seed starting constraints and non-goals on a brand-new project it creates.

Orientation

vibeless_declare_intent

The agent states what it is about to work on. Vibeless answers with the project map and up to 5 suggested starting points. The map lists the context nodes (rules, specs, and standards) that people maintain in the Context Editor. The map is the authority; the suggestions are ranked guesses.

• Agent passes: a plain-language description of its task, and optionally a flag to include hidden entries.
• Comes back: each entry's name, kind, summary, and approximate size in tokens, the suggestions, and a freshness signal. It writes nothing.

vibeless_get_project_context

The session-start overview. It takes no input.

• Comes back: the project's goal statement, tech stack, and constraints; the current phase; the active hooks; the first 1,500 characters of the architecture document; the active ticket; and enforcement coverage (how many items the drift check can enforce). A stale spec map adds a warning line first. The Claude Code profile also shows the description and non-goals, and the generic MCP profile includes the non-goals.
• In the app: reads the Spec Editor, the Phase Planner, the hooks on the Dashboard's Agents tab, and the coverage badges on the Enforcement tab (Dashboard).

vibeless_get_context

Deprecated, and kept only for older agent setups. Given a scope name such as "auth", it returns pointers to suggested context nodes with no content. Agents should call vibeless_declare_intent instead.

vibeless_get_adapter_info

Returns the agent profile Vibeless uses to format answers for this project. It takes no input.

• Comes back: the profile's name, agent, context size, structured-output support, multi-step reliability rating, and the full list of available profiles.
• In the app: reads the Agent Adapter card on the Dashboard.

vibeless_get_hooks

Returns the hooks that fire on one trigger event, highest priority first. A hook is an instruction that runs on one of the agent's own events, such as session start.

• Agent passes: a trigger event, such as session_start, user_prompt_submit, or pre_tool_use. Claude Code's own names, such as PreToolUse, are accepted too.
• Comes back: each matching hook's name, trigger, purpose, and priority.
• In the app: reads the Hooks card on the Dashboard's Agents tab.

For Claude Code and Codex, vibeless_get_project_context includes the 2 system hooks Vibeless installs (the session-start digest and the governance reminder), labeled as Vibeless system hooks. This tool includes the one that matches the requested event. Cursor and the generic MCP profile get none, because Vibeless installs none for them. There is no separate system-hooks tool.

Spec map and code

vibeless_get_node

Fetches one node and its content. The id can belong to a context node in the spec map or to a node in the code topology.

• Agent passes: a node id. For large spec nodes it can also pass section ids, a request for the full content, or a chunk number.
• Comes back: the node and its content, plus a hint for where to look next. Large spec nodes return an outline first (see Paging and size limits).
• In the app: reads the Context Editor or the Topology graph.

vibeless_search_specs

Keyword search across the project, its phases, its tickets, and its context nodes. This is the same index the app's Search uses.

• Agent passes: a search query.
• Comes back: up to 20 matches, best first, with type, name, and content. Beyond 20, the agent must narrow the query.

vibeless_spec_neighbors

Walks the spec map from one context node. It returns no node content.

• Agent passes: a context node id.
• Comes back: the node's links to other context nodes, plus the code it governs, found live from its file mappings: matching topology nodes and repository files, each with a total.
• In the app: reads the nodes, links, and file mappings in the Context Editor.

vibeless_get_architecture

Returns the full architecture document as Markdown. It takes no input. If the project has no architecture document, the answer says so in a sentence.

• In the app: reads the architecture tab of the Spec Editor.

vibeless_list_constraints

Returns the project's constraints as a list. It takes no input. Each item has the constraint text and, where they exist, its category, rationale, severity, and enforcement pattern.

• In the app: reads the constraints in the Spec Editor, including the machine-enforced rules.

vibeless_check_constraint

The agent describes something it plans to do, and Vibeless returns everything that might apply. Vibeless does not judge compliance; the agent decides.

• Agent passes: a description of the proposed action.
• Comes back: one list holding the project constraints and every rule in the spec map, and up to 3 earlier decisions that best match by keyword, with a score and the matched words. When the map has more than 150 entries, the list holds only the rules among the suggested starting points.
• In the app: reads the Spec Editor, the spec map, and the decisions in Logs.

vibeless_topology_summary

An overview of the code structure Vibeless extracts from your files. It takes no input.

• Comes back: node and edge counts by kind and extractor, the 10 most-connected nodes, and details of the last extraction run.
• In the app: reads the Topology panel's data.

vibeless_topology_query

Filters the code topology, or lists one node's connections.

• Agent passes: at least one of these filters: node kinds, part of a node name, part of a source file path, or a node id whose connections it wants. It can also set a result limit.
• Comes back: matching nodes (50 by default, 200 at most), their connections, the total, and whether the list was cut. Or, for one node, its incoming and outgoing connections.
• In the app: reads the Topology graph.

Phases and tickets

A phase is a stage of work with its own scope. A ticket is one unit of work inside a phase. In tool names and arguments, a ticket is called a task.

vibeless_get_phase_spec

Returns one phase with all its tickets and its boundary.

• Agent passes: a phase id, or the word "current".
• Comes back: the phase's description, status, acceptance criteria, deliverables, dependencies, boundary, and every ticket in it. "Current" picks the lowest-numbered active phase and names any other active phases. If none is active, the call fails.
• In the app: reads the Phase Planner and the Tickets board.

vibeless_list_open_tasks

Lists tickets that still need work: everything except done.

• Agent passes: optionally a phase id, a single open status (or "all" for every status, including done), a page size, a page offset, and a request for full rows.
• Comes back: one page of summary rows (name, status, phase, assignee, first 200 characters of the spec). Full rows add the whole spec and acceptance criteria.
• In the app: reads the Tickets board.

vibeless_get_task_spec

Returns one ticket in full.

• Agent passes: a ticket id.
• Comes back: the ticket's spec, status, constraints, acceptance criteria, and assignee; merged constraints (ticket, project, and phase boundary); and its comments, oldest first.
• In the app: reads a ticket on the Tickets board.

vibeless_create_task

Creates a ticket. The new ticket always lands at the bottom of Backlog in the chosen phase. After that, the agent can only move it and comment on it. It can never edit or delete it.

• Agent passes: the phase id, a name (up to 255 characters), and optionally a spec and acceptance criteria (up to 50,000 characters each).
• Comes back: the new ticket's id, name, status, and position.
• In the app: the ticket appears on the Tickets board.

vibeless_update_task_status

Moves a ticket to a new status. This is the only change an agent can make to an existing ticket.

• Agent passes: the ticket id, the new status (backlog, pending, in_progress, review, or done), and optional notes. Older agents may send blocked, complete, or skipped. Vibeless stores these as pending, done, and backlog.
• Comes back: the updated ticket and a suggested next ticket in the same phase, preferring tickets assigned to you, then unassigned ones, then the rest, and pending before backlog within each group.
• The notes are echoed back and never saved. When the ticket moves to review and Enable semi-formal certificates on Review is on, the notes also carry the report prompt for vibeless_attach_report.
• In the app: moves the card on the Tickets board.

vibeless_get_active_ticket

Returns the active ticket, the one ticket pinned as current for the project, in the same form as vibeless_get_task_spec. It takes no input.

If the ticket has sat in review or done for more than 7 days, the answer ends with a "Stale active ticket" note. The generic MCP profile gets a stale field instead. Vibeless never clears the pin on its own. If nothing is pinned, the call fails with not_found.

• In the app: reads the pinned ticket on the Tickets board.

vibeless_set_active_ticket

Pins a ticket as the active ticket.

• Agent passes: a ticket id from this project.
• Comes back: the new and previous pinned ids, and whether the pin changed.
• In the app: changes the same pin you set by hand on the Tickets board.

vibeless_add_task_comment

Adds a comment to a ticket's thread. Comments are permanent. Nobody can edit or delete them.

• Agent passes: the ticket id, the comment text (up to 10,000 bytes), and optionally a label for its session.
• Comes back: the comment id and its time.
• In the app: the comment appears on the ticket in Tickets, marked as written by an agent.

vibeless_attach_report

Attaches a structured report, called a semi-formal certificate, to a ticket. Agents use it after moving a ticket to review when the Reports option on the Dashboard's Agents tab is on.

• Agent passes: the ticket id and the report (definitions, premises, analysis, optional edge cases, a counterexample search, a formal conclusion, and an answer of YES, NO, or PARTIAL).
• Comes back: the report id.
• In the app: the report is stored with the ticket in Tickets.

Decisions and drift

A decision is a recorded choice with its rationale and the alternatives considered. Drift is a gap between what the record says and what the code does.

vibeless_log_decision

Records a decision made by the agent.

• Agent passes: the decision, the rationale, the alternatives considered, and optionally the ticket it belongs to.
• Comes back: the saved decision and any earlier decisions that share 2 or more longer words with it. The agent decides whether to raise an overlap with you.
• In the app: the decision appears on the Decisions tab in Logs, marked as made by an agent. The agent cannot add forbids. You add those through enforcement proposals on the Dashboard.

vibeless_list_decisions

Lists the project's decisions, newest first.

• Agent passes: optionally a page size, a page offset, and a request for full rows.
• Comes back: one page of summary rows (first 200 characters, who made it, when, its ticket, whether it has forbids). Full rows add the whole text, rationale, alternatives, and forbids.
• In the app: reads the Decisions tab in Logs.

vibeless_run_drift_check

Runs the drift engine against the repository and returns the report. It takes no input. The engine has 5 detectors: tech stack, constraints, scope, phase boundary (the lowest-numbered active phase), and decision forbids. The scope and phase checks look at files changed since the drift baseline.

• Comes back: a header line with the number of findings and of detectors that could run, then the report. "No detectors applicable" means nothing in the record is enforceable yet, not that the code is clean. Phase or non-goal path globs, constraint patterns, decision forbids, or pinned tech-stack versions give the detectors something to check.
• Vibeless saves each report and keeps the latest 100 per project. The agent sees only findings at or above the project's drift threshold. Agents should not run the check in a loop.
• In the app: reads the enforcement fields described in Phase Planner, Spec Editor, and Dashboard. It is separate from the Drift Log in Logs.

vibeless_get_version_history

Returns recent change events for one item in the record.

• Agent passes: the item type (such as project, phase, task, decision, or context_node), its id, and optionally a maximum number of events.
• Comes back: each event's time, type, field changed, old and new values, and who made the change.
• In the app: reads the Version History tab in Logs.

Workspaces

A workspace groups related projects. The app cannot add a project to a workspace, and a new project never joins one. These 5 tools appear only when the agent's project belongs to a workspace. See Workspaces and linked projects.

vibeless_get_workspace_context

Returns the workspace, its member projects, the links between them, and the workspace-level context nodes. It takes no input. A locked member project appears by name only.

vibeless_get_linked_project_context

Reads another project through a link. The coupling level on the link sets how much the agent sees:

• Agent passes: the id of the linked project.
• Without a link between the 2 projects, the call fails with forbidden. A locked target project fails with locked.

vibeless_create_project

Creates a new project.

• Agent passes: a name and goal statement, and optionally a description, tech stack, constraints, and non-goals for the new project.
• Comes back: the new project.
• This is the one exception to the rule on enforcement fields: the agent may seed starting constraints and non-goals on the brand-new project it creates. It cannot change them afterward.
• The new project counts toward your plan's project limit. At the limit, the call fails and the agent is told to ask you to upgrade or delete a project. See Account, plans, and projects.

vibeless_link_projects

Links the agent's own project to another project in the same workspace.

• Agent passes: the source and target project ids, a coupling level (awareness, dependency, read, or governance), and optionally a direction (one-way or both ways; both ways is the default).
• The source must be the agent's own project. The target must belong to the same workspace and must not be locked.

vibeless_check_cross_project_constraint

Works like vibeless_check_constraint and adds the workspace view. As with that tool, the agent decides compliance.

• Agent passes: a description of the proposed action.
• Comes back: everything vibeless_check_constraint returns, plus the workspace-level rules and references to governance nodes shared through governance links.

Error messages

When a tool fails, the agent receives a short error with 3 parts: a code, a message, and a suggested next step. The codes come from a fixed list.

One failure does not use this format. If an argument has the wrong type or a value outside the allowed list, the call is rejected before the tool runs, with plain text starting MCP error -32602: Input validation error. The agent fixes the arguments and calls again.

Paging and size limits

Several tools keep answers small so a large project does not fill the agent's context.

• List tools return summaries. vibeless_list_open_tasks and vibeless_list_decisions return 20 summary rows per page by default, up to 100, and the agent asks for full rows when needed. Each page says where the next one starts. Each list reads at most 500 rows from the app and flags when more exist.
• Large nodes return an outline first. A spec node larger than 8 KB comes back as a list of its headings plus the text before the first heading. The agent then asks for the sections it needs, or for the full content. A large node with no headings is read in numbered chunks.
• The project map hides noise. vibeless_declare_intent leaves out config and entry files, such as lockfiles, tsconfig files, and index files, and says how many it hid. The agent can ask to include them. When more than 150 entries remain, the map comes back as counts grouped by kind and scope instead of one row per node.
• The map reports its own freshness. vibeless_declare_intent and vibeless_get_project_context warn that the map may be stale when changes are waiting in the Drift Log, when no context node has changed in 7 days or more, or when the map is empty. The warning tells the agent to treat suggestions as hints and check them against the code. To clear it, review the Drift Log and update the spec map in the app.