Reference

MCP tools

The plugin serves these tools to your agent. They are what your agent rates advice, switches principles and writes principles with.

Using principles#

Tool	Inputs	What it does
`show`	`principle`: `expert/principle`, a bare principle id, or its link	Reads a principle's advice, with its author, tags, visibility and link. Follows a link that one principle's advice makes to another. A private principle reads only for those it is shared with.
`rate_principle`	`id`, `rating`: `up`, `down` or `not_applicable`	Tells the expert how the advice went, after it was shown. Sends only the principle, the rating, and the agent and model as the agent reports them.
`disable_principle`	`id`, `scope`: `project` or `global`, `dir`	Switches a principle off, when you ask for it.
`enable_principle`	`id`, `scope`, `dir`	Switches it on again, in the scope it was switched off in.
`set_stats`	`on`: `true` or `false`, left out to report the current setting	Switches off, or on again, what this machine reports: the daily counts and the ratings. Only when you ask.

A bare principle id is one of yours first, then one on your advisory board. @3 after an id, or ?v=3 on a link, reads an earlier revision. The agent is asked to rate once per principle and task, when it knows how the advice went. It is told not to switch advice off on its own, but to say that it does not fit and rate it not_applicable.

Writing principles#

These need esbuild to build a principle. It comes with the SDK in the repository that holds your principles:

bash

npm install --save-dev github:passsy/wellactually#sdk vitest

Write with an agent shows how they fit together.

Tool	Inputs	What it does
`scaffold`	`slug`, `parent`	Creates a principle folder that already passes `run_tests`.
`run_tests`	`dir`	Builds the principle and runs its tests in the isolate, with the publish checks and the warnings about the advice.
`try`	`dir`, one of `file`, `prompt` or `command`, and `read` or `output`	Shows one input to the detector and returns the findings and the text the agent would read.
`probe`	`dir`, `repo`	Runs the detector over a repository and reports how often it fires, with timings and samples.
`pull`	`id`, `dir`, `force`	Downloads a principle's files: the current draft, or the newest release. `@3` for a revision.
`history`	`id`	The principle's revisions, newest first, including an unreleased draft.
`publish_draft`	`dir`, `visibility`	Uploads the principle and releases it as its next revision. A package licence that needs your approval keeps it a draft. `visibility` is `public` or `private`, and left out keeps it as it is.
`release`	`id`	Releases a principle's waiting draft.
`set_visibility`	`id`, `visibility`	Makes one of your principles `public` or `private`.

All paths are absolute. The server also hands the agent a guide to how a principle is built, so it needs no docs to start.