Query and mutate a graph-native code repository: navigate relationships, retrieve source, analyze impact, search semantically, and manage sessions and atomic transactions.
Find references, callers, importers, and dependencies for an entity.
Get token-bounded context packs around one or more entities or a question.
Retrieve exact source for entities and read/list tracked artifacts.
Explore graph neighborhoods, trace data flow, and find paths between entities.
Analyze impact of changes across the repository.
Search declarations by name/kind/language or locate code via natural-language queries.
Check graph status and query provenance/history of an entity.
Start, heartbeat, and end agent sessions.
Stage, commit, abort, or directly mutate graph changes atomically.
Allows importing existing Git repositories and exporting Kin repositories to Git, providing Git interoperability and version control history.
Kin is a graph-native code repository for people and AI agents. It stores source, recorded code relationships, and versioned history as repository state. The graph is the repository model, not a search index maintained beside another repository.
Functions, types, and the relationships between them are data you commit, branch, and merge. Exact source is preserved byte for byte, and filesystem projections let supported tools keep working with ordinary files.
Public beta. Try Kin on a real project you know well. Expect rough edges.
Quickstart · Documentation · Browser demo
A star helps other people find Kin, and Discussions is where to bring a question about it.
Before changing a shared function, what else should you inspect? Kin lets you look up its recorded callers and explore related code. The CLI and MCP server query the same graph, so you and your agent can work from the same record.
Recorded on a prepared ripgrep graph at e89fff89ac9af12e8d4ce9d5fd07beb408ca730f. Raw run artifacts are not public. This illustrates a workflow, not a performance benchmark.
Related MCP server: GraphHub
For Claude Code:
/plugin marketplace add firelock-ai/kin
/plugin install kin@kinFor Codex, add the marketplace and install the plugin, or let kin setup --intent agent write the MCP server into ~/.codex/config.toml for you.
For Cursor, add the MCP server by hand; see plugins/kin-cursor for the exact snippet.
After installing, run kin init . in a fresh clone of a project you know well; the kin-setup skill walks you through the rest.
Kin is not published on crates.io. The kin crate there is an unrelated project.
Start in a fresh, full clone of a project you know well. kin init reads your Git history without changing it or your tracked files. It adds a .kin directory and one line to .git/info/exclude. Import covers every commit your branches and tags reach, so time, memory and disk grow with history rather than with the size of the checkout. Before it starts, kin init checks memory and free disk and stops with the numbers when it can already tell the machine is short. Shallow clones, submodules and Git LFS are not supported, and Git hooks, a sparse checkout or an unfinished merge or rebase also stop the import. kin init names the fix for each, and a fresh clone avoids most of them.
On macOS, Linux and WSL2, one command installs Kin and connects the AI coding tools it finds. It needs Node.js 20 or newer:
npx -y @kinlab/kin setupOn a machine without Node, run the installer instead. get.kinlab.ai and get.kinlab.dev
serve the same script:
curl -fsSL https://get.kinlab.dev/install | shEither way, reload your shell as a separate command, because the install puts kin in
~/.kin/bin and adds that directory to your shell profile for new sessions:
exec "$SHELL" -lOn native Windows x64, install from PowerShell with irm https://get.kinlab.dev/install.ps1 | iex.
It installs the kin CLI and does not connect AI coding tools, because WSL2 remains the
recommended path on Windows. The Windows entry under Beta limits
says what works there. No native Windows ARM64 build is published. On an ARM64 machine, run
that line from x64 PowerShell to install the x86_64 build under emulation, or use WSL2.
The installer adds kin to your user PATH, so open a new PowerShell window in place of
exec "$SHELL" -l before the next step.
For other installers or troubleshooting, see the full quickstart.
At the new prompt, clone a repository with Kin:
kin clone https://github.com/pallets/itsdangerousOr initialize one you already have, replacing the path below:
cd /path/to/your/repository &&
kin init . &&
kin overview &&
kin statusBoth end with the next command to run, a kin refs question about a function in that
repository. They also connect Codex CLI and Grok CLI to it when you allowed that in setup,
because those clients keep one entry that names a repository.
Windows PowerShell 5.1 has no &&, so on native Windows run the same commands one at a
time and stop if one fails:
cd C:\path\to\your\repository
kin init .
kin overview
kin statuskin overview shows the entities Kin imported. kin status shows what was admitted and the working tree's state against it. kin graph status reports the daemon's live query graph and coverage. Uncommitted and untracked changes are not part of the imported Git history; kin init reports what it left out.
Look for something you already know is in the code:
kin locate "<something you already know is in this repository>"Replace ExactEntityName below with a symbol from the result:
kin refs ExactEntityName
kin trace ExactEntityName
kin impact ExactEntityNamerefs returns recorded references, trace brings in nearby context, and impact explores potential effects through the graph. Check the results against the source.
kin setup already asked before connecting the AI coding tools it found, and connected them
if you said yes. There is no separate linking step. After you install another tool, run
kin setup again, and kin setup status shows what is connected. On Windows, connect AI
tools inside WSL2.
Semantic search runs on a local model of about 523 MB, and setup asks before anything
downloads it. If you said no, or kin init says the search index is waiting for the model,
this downloads it and builds the index:
kin embedKin supports Claude Code, Codex, Cursor, Gemini, and other MCP clients. Use kin setup --intent editor for VS Code. Kin also includes kin agent run for local or hosted OpenAI-compatible model endpoints.
Client configuration · MCP tools · Built-in agent
Local imports, storage, and queries run on your machine. Installation and the initial embedding-model download need network access. Before embeddings are ready, kin locate uses lexical and graph signals and reports the missing vector coverage.
After running kin init on the Git branch you want to review, compare explicit commit SHAs against main:
kin review shadow "$(git rev-parse main)..$(git rev-parse HEAD)"The report returns PASS, NEEDS ATTENTION, or WOULD BLOCK, with graph-derived impact and supporting evidence. It is advisory: it does not block a merge or change graph state. Authorship is declared, not independently verified.
Kin has its own commits, branches, merges, diffs, and history, including in repositories with no Git underneath. Existing Git repositories can be imported, and supported workflows can export a new Git repository.
Native version-control walkthrough · Git interoperability and export limits
Coverage is incomplete. Supported languages are parsed into entities and relationships; other files remain available as content and history. An empty result does not prove there are no callers or dependencies. Keep using your compiler, tests, and review. See language support.
Compatibility varies. Release archives do not include the deprecated kin-vfs filesystem projection, so there is no transparent projection to rely on. Check platform notes for what each platform supports.
Back up Kin-only state. Commits, branches, reviews and specs you record with Kin live in .kin, not in Git. Deleting .kin and re-importing from Git does not recover them, so run kin backup create first. Read the import, recovery, and upgrade notes.
Windows. Native Windows x86_64 support is early. Repository admission works: kin init imports a Git repository and publishes graph authority, and graph, lexical, and daemon-backed queries answer natively. The end-to-end install proof also runs agent setup on native Windows and gets graph-backed answers from the installed MCP server. Transparent filesystem projection is not shipped on Windows, and review workflows are not yet tested there, so WSL2 remains the recommended path for the full Kin experience.
I kept watching coding agents piece together parts of a codebase we'd already worked through. Then I'd do a version of that work myself to review their changes. I started wondering why more of that structural understanding wasn't part of the repository itself.
That's what I'm building with Kin.
Troy
CLI reference · Architecture and detailed limits · Contributing · Issues · Security
Kin and its local stack, including kin-db, are Apache-2.0. KinLab is the separate proprietary hosted product. Public repository onboarding is still in development.
Callers, importers and references of one entity. Chains? trace_data_flow.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Name; a section per owner sharing it. | |
| entity_id | No | UUID, or give query. | |
| max_chars | No | Soft cap on reply bytes. | |
| answer_only | No | False adds coverage and candidates. | |
| relation_kinds | No | calls, imports or references. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false). The description adds the 'one entity' scoping constraint and the kinds of references returned, which is useful context beyond annotations, but it says nothing about result structure, completeness, or performance. A 3 reflects annotations doing most of the behavioral work.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short with no wasted words, and the core purpose is front-loaded. The telegraphic 'Chains? trace_data_flow.' phrasing is terse but still readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and five optional parameters, the description should explain return format (e.g., section-per-owner, what answer_only changes) and how to specify the entity when neither query nor entity_id is required. It only gives the broad category of references returned, leaving an agent without enough context to interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all five parameters. The description adds no syntax, format, or interaction details beyond what the schema provides, making the baseline 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific resource and scope: 'Callers, importers and references of one entity.' An agent can tell what is returned, and the reference to trace_data_flow gives partial sibling differentiation. The missing verb is a minor gap, but the purpose is clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The fragment 'Chains? trace_data_flow.' names an alternative and the condition that selects it, which is explicit routing guidance. However, it omits when-not conditions relative to other plausible siblings like get_entity_source or semantic_search, leaving usage only partially covered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Bodies, signatures and routes around entities or a question, in one bundle.
| Name | Required | Description | Default |
|---|---|---|---|
| depth | No | Hops to walk. | |
| entities | No | Several entities, by name or UUID. | |
| question | No | A question to resolve into entities. | |
| entity_id | No | UUID | |
| max_chars | No | Hard cap on reply bytes. | |
| focal_body | No | False: neighbourhood only, no focal body. | |
| token_budget | No | Token budget. | |
| neighbor_bodies | No | True: neighbours' bodies too, not signatures. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds that results come as one bundled payload rather than a graph walk, but says nothing about cost, truncation behavior tied to max_chars/token_budget, or what is omitted when budgets are hit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is a single short sentence with no waste, which is good, but the terseness tips into under-specification for an 8-parameter tool. Nothing is padded, yet the one clause carries too little to orient the agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 8-parameter tool with no output schema, the description should clarify mutual exclusivity of entities/question/entity_id and what the returned bundle looks like. Five input modes (entities, question, entity_id, depth, budget toggles) are left entirely to the schema, so the definition is not complete enough to call this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% across all 8 parameters, so the schema already explains depth, entity_id, max_chars, token_budget and the two boolean toggles. The description only gestures at the entities-vs-question input modes and adds no syntax, default, or interaction detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the payload it returns ("bodies, signatures and routes") and the anchor ("entities or a question"), which is more specific than a tautology. But it gives no verb, and the phrase "around entities" is vague about what the bundle actually is, so an agent cannot cleanly distinguish it from siblings like graph_neighborhood or get_entity_source without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance and no mention of alternatives, despite several plausible siblings (graph_neighborhood, semantic_search, get_entity_source). The agent must infer from the name alone that this is the 'give me a code bundle' entry point.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One entity's exact source, by id.
| Name | Required | Description | Default |
|---|---|---|---|
| entity_id | Yes | UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds no behavioral context beyond that — nothing about what "source" contains, what happens for an unknown id, or the return shape, despite there being no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single tight sentence with no filler, and the key scoping constraint (one entity, by id) is front-loaded. It is arguably too terse rather than bloated, so it earns high marks on conciseness but not perfection.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema and an ambiguous noun ("source"), the description should clarify what is returned. Given the rich set of overlapping siblings, an agent lacks enough to confidently select or interpret this tool's output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the only parameter is documented as a UUID, so the baseline is 3. The description's "by id" merely restates what the schema already makes explicit and adds no format or constraint detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a verb (get) and a resource (entity source) scoped to one entity by id, which is more than a tautology. However, "source" is ambiguous — it could mean source code, provenance, or origin — and the description does nothing to separate this from siblings like kin_provenance_query or get_context_pack.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as kin_provenance_query, get_context_pack, or find_references. The phrase "by id" implies a lookup precondition but no exclusions or routing cues are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What one entity depends on and what depends on it. Paths: trace_data_flow.
| Name | Required | Description | Default |
|---|---|---|---|
| depth | No | Hops. | |
| limit | No | Max entities. | |
| direction | No | `out` deps, `in` dependents, or `both`. | both |
| entity_id | Yes | UUID | |
| max_chars | No | Soft cap on reply bytes. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds nothing behavioral beyond that — it does not mention the reply-byte truncation (max_chars soft cap) or how depth/limit affect the returned subgraph.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short fragments, zero padding, and the core purpose is front-loaded in the first sentence. The second fragment is arguably too compressed, costing a point rather than the whole.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a graph traversal tool with 5 parameters, no output schema, and rich annotations, the description is minimally adequate: it conveys the concept but says nothing about the shape of the result (nodes/edges, depth semantics, truncation behavior) that the schema does not already cover.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all five parameters (depth, limit, direction, entity_id, max_chars) are already documented in the schema. The description adds no semantics on top of that, which puts it at the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence names the resource (one entity's neighborhood) and specifies both directions of the relationship ('depends on' and 'depends on it'), which is specific enough to distinguish it from generic search tools. It falls short of a 5 only because it omits any verb framing of what is returned (a graph/subgraph) and leans on a cryptic sibling reference for differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Paths: trace_data_flow' fragment gestures at an alternative for multi-hop path queries, but it is telegraphic rather than explicit — no 'use this when / use that when' condition is stated. An agent can infer the routing, but must guess at it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Every entity a change could affect, from entity_ids or change_ids.
| Name | Required | Description | Default |
|---|---|---|---|
| base | No | Base change. | |
| head | No | Head change. | |
| files | No | Deprecated; use entity_ids. | |
| max_chars | No | Soft cap on reply bytes. | |
| change_ids | No | Change ids to combine. | |
| entity_ids | No | Entity UUIDs. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds nothing beyond that: it says nothing about scope limits, how base/head interact, or what the max_chars cap implies for output truncation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Very short, but this is under-specification rather than conciseness. The single fragment is front-loaded with the resource but omits the action and any supporting detail an agent needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Six optional parameters, no output schema, and no required inputs mean the description must explain how entity_ids and change_ids combine and what base/head mean. It does not, leaving the agent to infer the tool's behavior entirely from the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description loosely ties entity_ids/change_ids to the operation, but says nothing about base, head, files (deprecated), or max_chars that isn't already in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The fragment 'Every entity a change could affect' identifies the resource (entities impacted by a change) and hints at the analysis operation, but lacks a verb and reads as a sentence fragment. It does not differentiate itself from siblings like trace_data_flow or graph_neighborhood, which could plausibly return similar graph results.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description names the two input sources ('from entity_ids or change_ids') but gives no guidance on when to use this tool versus trace_data_flow, find_references, or graph_neighborhood. No prerequisites, no conditions, no exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Graph and embedding counts. last_settled_selected_graph marks a last settled reading.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, covering the safety profile. The description adds no behavioral context beyond that — it doesn't say whether counts are per-session or global, how fresh they are, or what 'settled reading' means operationally. The cryptic second sentence about last_settled_selected_graph reads more like a fragment of a return-field note than usable guidance.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no filler, and the core purpose is front-loaded. The second sentence is terse to the point of being opaque, but it is not padded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the burden of explaining what comes back, and it only gestures at this ('Graph and embedding counts' plus one oddly named field). An agent knows it gets counts but not the shape, units, or the meaning of 'last settled reading' — adequate but with a real gap for a status/metrics tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so per the rubric baseline is 4. The description cannot and need not explain parameter semantics, and it correctly avoids implying any inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The phrase 'Graph and embedding counts' states the resource being reported but not a clear verb — it implies a read of status metrics without saying 'returns', 'reports', or what the status actually means. It does not distinguish itself from siblings like graph_neighborhood or impact_analysis, which also touch graph data, though the name and annotation title ('Graph status') hint at a lightweight read-only status check.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no indication of when to call this versus the many kin_* siblings (session ops, mutation, provenance queries). No prerequisites, no mention of whether a session must be active first, and no alternatives named. The agent must infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set a folder up as a Kin repository when it is not one.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Default: the workspace folder. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=false, idempotentHint=true, and openWorldHint=false, so the safety profile is covered. The description adds the useful precondition that the folder must not already be a repo, complementing the idempotency hint, but says nothing about what gets written to disk or required permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with zero filler; the precondition follows immediately after the action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter setup tool with no output schema, the description plus annotations cover what an agent needs to call it correctly. Only the destination of the operation's side effects is left unstated, which is minor here.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single optional 'path' parameter is documented with its default in the schema itself. The description adds no parameter detail, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (set up) and resource (a folder as a Kin repository) with a clear precondition. It is distinguishable from siblings like kin_mutate or kin_session_start, though it doesn't explicitly name a sibling to contrast with.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The clause 'when it is not one' gives a usable trigger condition, which is more than nothing. However, it names no alternative tool for the case where the folder IS already a repository, leaving routing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Commit targeted entity changes atomically, in one call.
| Name | Required | Description | Default |
|---|---|---|---|
| summary | No | One sentence for the history. | |
| operations | Yes | Applied atomically. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the safety profile is covered. The description adds the atomicity guarantee ('atomically, in one call'), which is genuinely beyond the annotations, but says nothing about failure behavior, all-or-nothing rollback semantics, or whether a base/session is required.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single short sentence with the action and the atomicity constraint front-loaded; nothing is wasted. It is arguably too terse for a tool of this complexity, but there is no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a multi-verb atomic mutation tool with a large nested payload schema and no output schema, the description omits the crucial operational facts an agent needs: how partial failure is handled, that multiple heterogeneous operations can be mixed, and that base values must come from a prior read. The rich schema compensates for parameters, but the behavioral picture is only partially complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the exceptionally detailed nested schema already documents operations, verbs, payload variants and base fields. The description adds no syntax, format, or constraint detail beyond what the schema provides — baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource — 'Commit targeted entity changes' — plus the atomicity scope, so an agent knows it performs batched graph mutations. However, it does not distinguish itself from its transaction siblings (kin_transaction_stage, kin_transaction_commit), and 'Commit' actively invites confusion with kin_transaction_commit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus the transaction tools or the read-only siblings like get_entity_source. The phrase 'in one call' hints at the contrast with staged multi-call transactions, but the agent must infer that; no prerequisites (e.g. obtaining source_base/repository_base first) are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Who changed an entity, when, and whether it was approved.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Page size. | |
| entity_id | Yes | UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds the useful content signal that results include approval status, but says nothing about ordering, pagination semantics, or result volume — context the annotations cannot supply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single 11-word sentence with zero filler, front-loaded on the core question. It is efficient, though the interrogative phrasing is slightly less actionable than a declarative statement of what it returns.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter read-only tool with no output schema, the description conveys the essential return content. It stops short of covering result ordering, the meaning of the limit cap, or any auth expectations, leaving modest gaps an agent may need to probe.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters (entity_id, limit) are documented in the schema itself, so the baseline is 3. The description adds no format or usage detail beyond implying the entity target; it says nothing about the limit/page-size behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the resource (entity provenance) and the exact questions it answers — who changed it, when, and approval status. That is specific and distinguishes it from siblings like kin_mutate or get_entity_source, though it never explicitly names those siblings as alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use or when-not-to-use guidance and no alternatives referenced. An agent must infer from the name that this is the audit/history lookup, with no indication of prerequisites or how it relates to the mutation tools in the sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Session plumbing for writes. Close an open session.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes | UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare it is mutating (readOnlyHint false), idempotent, non-destructive, and not open-world. The description adds only that it is 'session plumbing for writes,' which contextualizes but does not disclose edge cases like behavior on a non-existent session or interaction with pending transactions. With annotations carrying the safety profile, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Very short and efficient, with no wasted words. However, the actual action is in the second sentence while the vague 'Session plumbing for writes' is front-loaded, which slightly diminishes front-loading of the key instruction.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with no output schema and annotations covering safety, the description is minimally adequate. It does not clarify what happens to uncommitted transactions or staged data when the session closes, which is a notable gap given the sibling transaction tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the single session_id parameter is already fully documented. The description adds no additional meaning about the UUID format, where to obtain it, or its role. Baseline 3 when schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Close an open session.' This clearly distinguishes it from the sibling kin_session_start, and the name reinforces the action. The leading phrase 'Session plumbing for writes' is slightly opaque but does not obscure the core purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Close an open session' implies the condition that a session must already be open, but there is no explicit guidance on when to use this versus transaction commit/abort siblings, or what prerequisites exist. Usage is inferable but not spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Build, test or run this project with its toolchain. Session needs can_execute.
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | App variables; loader and build keys refused. | |
| argv | Yes | Command words; no shell runs them. | |
| summary | No | History message for manifests it keeps. | |
| session_id | Yes | Session that declared can_execute. | |
| timeout_secs | No | Seconds before the command is stopped. | |
| max_output_bytes | No | Bytes kept per stream; the middle is cut. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds one genuinely useful behavioral fact – the can_execute capability requirement on the session – but says nothing about what a destructive run may modify, whether timeout truncation loses work, or what the tool does on failure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with the core action front-loaded and the prerequisite second. No waste, though the prerequisite sentence is telegraphic to the point of being slightly ambiguous about which session must hold the capability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 6-parameter, destructive, open-world execution tool with no output schema, the description is thin: it omits what the command can affect, how output is returned once truncated, and any failure semantics. The can_execute prerequisite and the rich schema keep it at a minimum-viable level rather than inadequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and every parameter carries a description (argv 'no shell runs them', env refusal of loader/build keys, timeout clamping, per-stream truncation), so the schema does the heavy lifting. The description adds no parameter-level meaning beyond what is already documented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific set of verbs (build, test, run) against a concrete resource (this project with its toolchain), which is enough for an agent to distinguish it from the session-lifecycle siblings (kin_session_start/end/heartbeat) and from the mutation tool kin_mutate. It does not explicitly contrast with kin_mutate or the transaction tools, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The only guidance is the precondition 'Session needs can_execute', which tells the agent what must be true before calling but not when to prefer this tool over kin_mutate or the transaction siblings. Usage is implied by the description's verbs rather than stated as when/when-not.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Session plumbing for writes. Keep a session alive.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes | UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=false, and idempotentHint=false, so the safety profile is covered. The description adds the lifecycle behavior 'Keep a session alive' and the write association, but does not explain auth requirements, side effects, or failure behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no wasted words, and the core action is front-loaded. The phrase 'Session plumbing for writes' is slightly vague, but the overall definition is efficiently sized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter heartbeat tool with annotations and no output schema, the description is minimally adequate. It still lacks lifecycle context such as when a session needs heartbeating relative to other session tools, but nothing critical is missing for invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the session_id UUID parameter is already fully documented in the schema. The description adds no additional meaning about the parameter, making the baseline 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a clear action, 'Keep a session alive,' and scopes it with 'Session plumbing for writes,' naming the session resource. It does not distinguish this from sibling session lifecycle tools such as kin_session_start, kin_session_end, or kin_session_exec.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides only implied context ('for writes') and no explicit guidance on when to call heartbeat versus kin_session_start, kin_session_end, or kin_session_exec. No alternatives, prerequisites, or frequency guidance are named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Session plumbing for writes. Open one; get a session_id.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | Yes | Agent's cwd. | |
| pid | No | Agent process id. | |
| vendor | Yes | e.g. claude-code, codex. | |
| transport | No | mcp|cli|wrapper|ui | mcp |
| session_id | No | Optional UUID to register under. | |
| client_name | Yes | Client name. | |
| capabilities | No | Abilities |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the safety profile (not read-only, not destructive, not idempotent, not open-world), so the description's bar is lower. The description adds that it is for writes and returns a session_id, but it does not disclose session lifecycle details, reuse behavior, or what happens if capabilities are omitted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no filler and front-loads its purpose. It is efficient, though its telegraphic style may be overly terse for a tool with seven parameters and a nested capabilities object.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a session-start tool with seven parameters, a nested capabilities object, no output schema, and many session/transaction siblings, the description is too sparse. It does not cover session prerequisites, expiration, capability defaults, or relationship to kin_transaction_begin, leaving key operational context unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all seven parameters, including the nested capabilities object, are already documented in the schema. The description adds no parameter-level meaning, which is acceptable given the high schema coverage baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Open one') and resource ('session'), and notes the return value ('get a session_id'). It also gives scope ('for writes'), though it does not distinguish this tool from siblings like kin_transaction_begin or kin_session_end.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It implies usage for write operations via 'Session plumbing for writes' and the imperative 'Open one; get a session_id.' However, it never explicitly states when to choose this tool over alternatives, such as kin_transaction_begin or kin_session_exec, leaving the agent to infer the sequencing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Transaction plumbing for writes. Discard what is staged and close it.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | No | Owning session UUID. | |
| transaction_id | Yes | UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds real value by specifying what is destroyed ('what is staged') and that the transaction is closed, which the annotations alone do not convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no filler, and the destructive effect is front-loaded. The lead-in phrase 'Transaction plumbing for writes' is slightly oblique but not wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter mutation with rich annotations and no output schema, the description covers the essential effect (staged writes discarded, transaction closed). Minor gaps remain, e.g. behavior if the transaction id is unknown or already closed, but nothing an agent needs to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and both parameters (session_id, transaction_id) are documented in the schema, so the baseline of 3 applies. The description adds no syntax, format, or validity constraints beyond what the schema states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names the resource (transaction) and the action (abort: 'discard what is staged and close it'), which lets an agent distinguish it from kin_transaction_commit without opening the schema. 'Transaction plumbing for writes' is a slightly vague framing sentence, but the second sentence pins down the operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied rather than stated: an agent can infer this is the counterpart to commit when staged writes should be thrown away. However, the description never names kin_transaction_commit as the alternative nor states a condition for choosing abort over it, leaving the routing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Transaction plumbing for writes. Open one; get a transaction_id.
| Name | Required | Description | Default |
|---|---|---|---|
| scope | Yes | Label, never a path. | |
| session_id | Yes | Owning session. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare non-readOnly, non-idempotent, non-destructive, so the write-scoped nature is covered. The description usefully discloses the return (a transaction_id) in the absence of an output schema, but says nothing about lifetime, scope semantics, or what a transaction is good for.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short clauses, zero filler, and the core action is front-loaded. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
It covers the essential call contract (open a transaction, receive an id) for a no-output-schema tool, but omits lifecycle and interaction details with the sibling commit/abort/stage tools and the meaning of scope/session ownership.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and there are only two required parameters, so the schema carries the load; baseline 3 applies. The description adds no parameter-level meaning beyond what is already documented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (open) and resource (transaction), and the phrase 'plumbing for writes' clarifies its role relative to the sibling transaction_abort/commit/stage tools. It stops short of naming which sibling to use next, so it is clear but not maximally differentiating.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Transaction plumbing for writes' implies the context (wrap write operations) but never states when to use this versus kin_transaction_stage/commit or what prerequisites exist. Usage is inferable rather than spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Transaction plumbing for writes. Publish everything staged, atomically.
| Name | Required | Description | Default |
|---|---|---|---|
| message | No | One sentence on what this change does. | |
| operations | No | Operations to stage in this commit. | |
| session_id | No | Owning session UUID. | |
| transaction_id | Yes | UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=true and closed-world, so the safety profile is covered structurally. The description adds one genuine behavioral fact beyond them — publication is atomic (all-or-nothing) — but says nothing about failure handling, validation of stale bases, or what a rejected commit does to staged work.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short front-loaded sentences with no redundancy; the atomicity guarantee is stated immediately. The opening phrase 'Transaction plumbing for writes' is somewhat vague filler relative to the precise second sentence, keeping it just short of a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive, high-stakes commit step in a multi-tool transaction workflow, the description omits the prerequisites (a begun transaction with staged operations), the consequences of failure, and any hint of what is returned or how success is confirmed. Annotations and a rich schema help, but the prose is too thin for the risk profile.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the nested operation variants are documented exhaustively in the schema. The description contributes only the loose phrase 'everything staged' mapping to the operations array and adds no detail on transaction_id, session_id, or message beyond what the schema already provides, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: publish staged operations as a commit. The word 'commit' in the name and 'Publish everything staged, atomically' make it distinguishable from kin_transaction_begin/stage/abort without opening the schema, though it never names those siblings explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Publish everything staged' implies it must follow kin_transaction_stage, but there is no explicit when-to-use, no note that a transaction must be begun first, and no guidance on when to prefer kin_transaction_abort instead. Usage is left to inference from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Transaction plumbing for writes. Stage an update, create, delete or rename.
| Name | Required | Description | Default |
|---|---|---|---|
| operations | Yes | What to stage. | |
| session_id | No | Owning session UUID. | |
| transaction_id | Yes | UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the agent knows this writes and is neither destructive nor idempotent. The description adds almost nothing beyond that: it never states that staging is deferred and unpublished until commit, nor mentions staleness/refusal behavior that the schema repeatedly references. For a write-plumbing tool, the key behavioral fact (nothing is published at stage time) is absent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, front-loaded sentences with no filler. However, the extreme brevity is arguably under-specification for a tool with such a large surface rather than true economy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The schema is enormous, with six distinct operation shapes, stale-base refusal semantics and unit-addressed creation rules, while the description conveys none of this. With no output schema, the description should at least characterize the staging/commit lifecycle and refusal behavior; it does not.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents transaction_id, session_id and the operations structure in depth. The description adds no parameter-level meaning at all, leaving the baseline 3 for a fully-covered schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('stage') and the resource (transaction operations), and enumerates the operation kinds (update, create, delete, rename). It does not distinguish this from kin_mutate or kin_transaction_commit, so an agent cannot tell from the description alone why it should stage here rather than mutate directly. Notably, 'rename' is listed but no rename verb appears in the schema's oneOf variants.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-use guidance, no mention of the begin/stage/commit workflow, and no reference to the sibling tools kin_transaction_begin, kin_transaction_commit or kin_mutate. The phrase 'transaction plumbing for writes' implies a role but leaves the agent to infer the workflow ordering.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Exact literals, punctuation included, in stored graph fields. Lexical evidence only.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | Entity kind; test means test role. | |
| limit | No | Hits per page. | |
| cursor | No | Next page; restart if contents changed. | |
| literal | No | Bare literal; ASCII case-insensitive. | |
| max_chars | No | Soft cap on reply bytes. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds the meaningful behavioral detail that matching is exact (punctuation-sensitive) rather than fuzzy, but says nothing about pagination behavior, result shape, or how the soft byte cap truncates the response.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, purpose and matching semantics front-loaded, with zero filler. It is arguably too terse for a five-parameter tool, but nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With five parameters, no output schema, and no required parameters, the description should say something about what a hit looks like and how limit/cursor/max_chars interact with the returned graph fields. It leaves the entire result contract to inference, which is a notable gap given there is no output schema to fall back on.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all five parameters are already documented, and 3 is the baseline. 'Punctuation included' does sharpen the interpretation of the literal parameter, but the description adds no meaning for kind, limit, cursor, or max_chars.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific matching mode (exact literals, punctuation preserved) against a specific resource (stored graph fields), and 'Lexical evidence only' implicitly separates it from the semantic_* siblings. It stops short of naming the operation verb or the field/entity scope being searched, so it is clear but not fully differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Lexical evidence only' implies the contrast with semantic_search/semantic_locate, giving an implied routing rule. However, it never states when to prefer lexical over semantic retrieval, and no alternative is named explicitly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find code by describing what it does. Know the exact name? semantic_search.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Rows per page. | |
| query | No | What the code does, in plain words. | |
| cursor | No | `next_cursor` from the prior page. | |
| max_chars | No | Soft cap on reply bytes. | |
| granularity | No | Rank entities or files. | entity |
| include_tests | No | Rank test entities too. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without description help. The description adds no behavioral context beyond a routing rule — no mention of ranking behavior, result shape, or how pagination interacts with the cursor. Adequate but thin.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, zero filler, with the primary action front-loaded and the routing caveat second. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a six-parameter read-only search tool with a fully documented schema and no output schema, the description covers the essential decision (semantic vs. exact-name lookup). It omits pagination flow and the max_chars soft-cap semantics, but those are already carried by the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all six parameters (limit, query, cursor, max_chars, granularity, include_tests) are already documented in the schema. The description implies the nature of the query parameter but adds no syntax, default, or interaction detail. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Find') and resource ('code') with the retrieval modality made explicit ('by describing what it does'). It then contrasts itself against a named sibling, so an agent can route between them without opening schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly names the alternative (semantic_search) and the condition that selects it ('Know the exact name?'), which is exactly the when-to-use-other-tool guidance that sibling tools require. Nothing about routing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Declarations by name, kind or language. By meaning? semantic_locate.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | Kind; `command` finds CLI entry points. | |
| limit | No | Max rows. | |
| query | Yes | Name pattern. | |
| language | No | Language filter. | |
| max_chars | No | Soft cap on reply bytes. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds nothing beyond that — no note on what is searched, ranking, truncation (max_chars), or whether results are source-backed; its brevity borders on cryptic rather than informative.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two telegraphic fragments with zero padding and the disambiguation front-loaded, which is efficient. But the fragment style ('By meaning? semantic_locate.') sacrifices clarity for brevity and reads more like a note than a usable definition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 5-parameter read-only search with no output schema, the description should at least sketch what comes back (declarations plus what fields) and how the filters combine. It names the resource but leaves return shape and filter interaction to the schema and inference.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents query, kind, language, limit, and max_chars, making 3 the baseline. The description adds no additional semantics for any parameter, so it earns no uplift.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States the resource (declarations) and the filter axes (name, kind, language), which is more than a restatement of the name, and it explicitly names semantic_locate as the different tool. But the tool is called 'semantic_search' while its own description disclaims meaning-based lookup, and the verb 'search/find' is only implied — an agent can be left unsure how this differs from lexical_lookup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives one explicit routing rule ('By meaning? semantic_locate.'), which is genuine when-to-use guidance. However, lexical_lookup is the nearest sibling and is not addressed, and no prerequisites, exclusions, or ordering guidance are provided, so the routing is only half-complete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The ordered call chain out from one entity. Two endpoints? trace_path.
| Name | Required | Description | Default |
|---|---|---|---|
| depth | No | Hops from the focal (max 8). | |
| focal | Yes | Start entity: UUID or name. | |
| target | No | A symbol to reach; its branch is kept. | |
| compact | No | Alias for include_body: false. | |
| direction | No | `calls`, `callers` or `both`. | both |
| max_chars | No | Soft cap on reply bytes. | |
| include_body | No | Inline sources; false gives the shape. | |
| limit_per_step | No | Edges kept per hop. | |
| max_response_chars | No | Same as `max_chars`. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is fully covered. The description adds only the single-source traversal scope and reveals nothing about output shape, truncation behavior at max_chars, or how depth/limit_per_step pruning affects results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short fragments, zero filler, with the core purpose front-loaded and the disambiguation sentence second. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a 9-parameter traversal tool with no output schema and no description of what is returned (tree structure, ordering guarantee, how truncation is signaled) or what happens when the focal cannot be resolved. Given the complexity, the description is too thin to be complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and all 9 parameters, including the alias pairs (compact/include_body, max_chars/max_response_chars), are documented inline. The description adds no parameter meaning beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('the ordered call chain') and pins the scope ('out from one entity'), which distinguishes it from trace_path's two-endpoint traversal. An agent can pick between the two trace tools without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides an explicit routing rule: 'Two endpoints? trace_path.' That is a real when-to-use-this-vs-alternative signal. It stops short of a full 5 because it gives no exclusions or prerequisites (e.g. graph must be initialized, entity must exist).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
How one entity reaches another, as hops. One endpoint? trace_data_flow.
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | End entity. | |
| from | Yes | Start: UUID, exact name, or name@file. | |
| limit | No | Routes returned, shortest first. | |
| to_file | No | Deprecated; pin with name@file. | |
| direction | No | `forward`, `reverse` or `either`. | either |
| from_file | No | Deprecated; pin with name@file. | |
| max_chars | No | Soft cap on reply bytes. | |
| max_depth | No | Hops between the ends (max 12). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is fully carried by structured data. The description adds only that results are expressed as hops, with nothing on truncation behavior, depth limits, or cost of large traversals – adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two fragments, front-loaded with the core purpose and followed immediately by the routing rule. No filler; every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 8-parameter traversal tool with no output schema, the schema plus annotations cover parameters and safety well, and the description supplies the sibling routing. The only gap is a slightly thin account of what a returned path actually contains.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with 8 documented parameters, so the schema already explains from/to syntax, direction, limit, max_depth, and the deprecated file params. The description adds no parameter meaning beyond that, which is the correct baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific resource (the connection between two entities) and the return shape ('as hops'), and explicitly distinguishes itself from trace_data_flow for the single-endpoint case. It is a noun phrase rather than a verb+resource, but the intent is unambiguous next to its siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'One endpoint? trace_data_flow.' gives an explicit when-not condition and names the alternative tool. It does not distinguish this from other plausible siblings such as find_references or impact_analysis, but the primary routing decision is covered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.7.17find_references5 fields changedInput schema / properties / answer_onlyAdded value: +{
+ "default": true,
+ "description": "False adds coverage and candidates.",
+ "type": "boolean"
+}Input schema / properties / entity_id / descriptionPrevious value: -"Exact entity UUID. Optional if query is provided."New value: +"UUID, or give query."Input schema / properties / max_chars / descriptionPrevious value: -"Serialized characters this response may occupy; what was cut is named in `elisions`."New value: +"Soft cap on reply bytes."Input schema / properties / query / descriptionPrevious value: -"Exact symbol name to resolve. Optional if entity_id is provided."New value: +"Name; a section per owner sharing it."Input schema / properties / relation_kinds / descriptionPrevious value: -"Filter to calls, imports or references. Defaults to all three."New value: +"calls, imports or references."get_context_pack11 fields changedInput schema / anyOfRemoved value: -[
- {
- "required": [
- "entity_id"
- ]
- },
- {
- "required": [
- "entities"
- ]
- },
- {
- "required": [
- "question"
- ]
- }
-]Input schema / properties / depth / descriptionPrevious value: -"Dependency traversal depth"New value: +"Hops to walk."Input schema / properties / entities / descriptionPrevious value: -"Several focal entity names or UUIDs when the question is about how they connect."New value: +"Several entities, by name or UUID."Input schema / properties / entity_id / descriptionPrevious value: -"Focal entity UUID"New value: +"UUID"Input schema / properties / focal_bodyAdded value: +{
+ "default": true,
+ "description": "False: neighbourhood only, no focal body.",
+ "type": "boolean"
+}Input schema / properties / max_chars / defaultPrevious value: -12000New value: +24576Input schema / properties / max_chars / descriptionPrevious value: -"Serialized characters this response may occupy; what was cut is named in `elisions`."New value: +"Hard cap on reply bytes."Input schema / properties / neighbor_bodiesAdded value: +{
+ "default": false,
+ "description": "True: neighbours' bodies too, not signatures.",
+ "type": "boolean"
+}Input schema / properties / question / descriptionPrevious value: -"A plain-language question resolved to one or more focal entities before packing."New value: +"A question to resolve into entities."Input schema / properties / token_budget / defaultPrevious value: -2500New value: +4000Input schema / properties / token_budget / descriptionPrevious value: -"Token budget (8000, 16000, or 32000)"New value: +"Token budget."get_entity_source1 field changedInput schema / properties / entity_id / descriptionPrevious value: -"Entity UUID"New value: +"UUID"graph_neighborhood5 fields changedInput schema / properties / depth / descriptionPrevious value: -"Traversal depth"New value: +"Hops."Input schema / properties / direction / descriptionPrevious value: -"`out` for what the focal depends on, `in` for what depends on it, `both` merges."New value: +"`out` deps, `in` dependents, or `both`."Input schema / properties / entity_id / descriptionPrevious value: -"Entity UUID"New value: +"UUID"Input schema / properties / limit / descriptionPrevious value: -"Max entities to return (default 30)"New value: +"Max entities."Input schema / properties / max_chars / descriptionPrevious value: -"Serialized characters this response may occupy; what was cut is named in `elisions`."New value: +"Soft cap on reply bytes."impact_analysis6 fields changedInput schema / properties / base / descriptionPrevious value: -"Base semantic change ID (hex)"New value: +"Base change."Input schema / properties / change_ids / descriptionPrevious value: -"Change ID hexes to combine and analyze impact"New value: +"Change ids to combine."Input schema / properties / entity_ids / descriptionPrevious value: -"Entity UUIDs to analyze impact for"New value: +"Entity UUIDs."Input schema / properties / files / descriptionPrevious value: -"Deprecated, answered through 0.7.16; use entity_ids. File paths resolved to entities."New value: +"Deprecated; use entity_ids."Input schema / properties / head / descriptionPrevious value: -"Head semantic change ID (hex)"New value: +"Head change."Input schema / properties / max_chars / descriptionPrevious value: -"Serialized characters this response may occupy; what was cut is named in `elisions`."New value: +"Soft cap on reply bytes."kin_artifact_listkin_artifact_readkin_initkin_mutate9 fields changedInput schema / properties / operations / descriptionPrevious value: -"Array of mutation operations to validate and commit atomically"New value: +"Applied atomically."Input schema / properties / operations / items / oneOfRemoved value: -[
- {
- "additionalProperties": false,
- "properties": {
- "description": {
- "description": "Human-readable explanation of this change.",
- "type": "string"
- },
- "target": {
- "description": "Repository-relative path of the file to retire, such as \"src/parser.py\". It must be a path repository authority already tracks; a path the graph has never seen is refused.",
- "minLength": 1,
- "type": "string"
- },
- "verb": {
- "description": "Retire a tracked file. This is the only operation that removes a file, along with every entity derived from it and every edge incident to those entities.",
- "enum": [
- "delete",
- "remove"
- ],
- "type": "string"
- }
- },
- "required": [
- "verb",
- "target",
- "description"
- ],
- "title": "Retired source file",
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "description": {
- "description": "Human-readable explanation of this change.",
- "type": "string"
- },
- "destination": {
- "description": "Repository-relative path the file moves to. It must not be tracked already, and it follows the same path rules as `target`: no leading slash, no \"..\", and no Kin or Git control component.",
- "minLength": 1,
- "type": "string"
- },
- "target": {
- "description": "Repository-relative path the file lives at now. It must be a path repository authority already tracks.",
- "minLength": 1,
- "type": "string"
- },
- "verb": {
- "description": "Relocate a tracked file. Entity identity, history, and incoming edges survive the move, which is what separates this from a delete followed by a create.",
- "enum": [
- "rename",
- "move"
- ],
- "type": "string"
- }
- },
- "required": [
- "verb",
- "target",
- "destination",
- "description"
- ],
- "title": "Renamed source file",
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "body": {
- "description": "The file's complete UTF-8 source text. Kin parses it with the same extractor the ingest path uses, so every entity in it enters the graph, and writes the file into the working directory when the transaction commits. You do not need to write the file yourself first.",
- "minLength": 1,
- "type": "string"
- },
- "description": {
- "description": "Human-readable explanation of this change.",
- "type": "string"
- },
- "target": {
- "description": "Repository-relative path of the new file, such as \"src/parser.py\". No leading slash, no \"..\", and no Kin or Git control component. A path the graph already tracks is refused; rewrite that one with verb 'replace' instead.",
- "minLength": 1,
- "type": "string"
- },
- "verb": {
- "description": "Admit a source file the graph has never seen. This is the only operation that introduces a new file.",
- "enum": [
- "create",
- "add",
- "insert"
- ],
- "type": "string"
- }
- },
- "required": [
- "verb",
- "target",
- "body",
- "description"
- ],
- "title": "New source file",
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "body": {
- "description": "The file's complete new UTF-8 source text, never a fragment or a diff. Kin reparses it with the same extractor the ingest path uses, so entities the new text adds enter the graph, entities it drops leave it, and the rest keep their identity. A body identical to the tracked contents is refused as an empty change.",
- "minLength": 1,
- "type": "string"
- },
- "description": {
- "description": "Human-readable explanation of this change.",
- "type": "string"
- },
- "target": {
- "description": "Repository-relative path of the file to rewrite, such as \"src/parser.py\". It must be a path repository authority already tracks; a path the graph has never seen is refused, and 'create' is the verb for it.",
- "minLength": 1,
- "type": "string"
- },
- "verb": {
- "description": "Rewrite a tracked file from its complete new text. This is the operation to use when you hold a path and the file's new contents, which is what a local edit or write leaves you holding.",
- "enum": [
- "replace",
- "overwrite"
- ],
- "type": "string"
- }
- },
- "required": [
- "verb",
- "target",
- "body",
- "description"
- ],
- "title": "Replaced source file",
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "body": {
- "description": "The entity's complete new UTF-8 source text, including its own leading indentation. Do not submit a truncated retrieval body.",
- "minLength": 1,
- "type": "string"
- },
- "description": {
- "description": "Human-readable explanation of this change.",
- "type": "string"
- },
- "target": {
- "description": "Exact repository entity UUID or unambiguous exact entity name.",
- "minLength": 1,
- "type": "string"
- },
- "verb": {
- "description": "Update an existing source entity.",
- "enum": [
- "update",
- "modify"
- ],
- "type": "string"
- }
- },
- "required": [
- "verb",
- "target",
- "body",
- "description"
- ],
- "title": "Entity source body edit",
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "body": {
- "description": "Full new UTF-8 source text for a source-bound Entity update. Omit for Relation operations.",
- "type": "string"
- },
- "description": {
- "description": "Human-readable explanation of this change.",
- "type": "string"
- },
- "payload": {
- "description": "Exact mutation payload: {\"Entity\": { ...existing entity identity... }} or {\"Relation\": {\"from\": \"...\", \"to\": \"...\", \"kind\": \"...\"}}.",
- "type": "object"
- },
- "target": {
- "description": "Exact repository entity UUID for an Entity payload; empty string for a Relation payload.",
- "type": "string"
- },
- "verb": {
- "description": "Entity or relation mutation verb.",
- "enum": [
- "create",
- "add",
- "upsert",
- "insert",
- "update",
- "modify",
- "delete",
- "remove"
- ],
- "type": "string"
- }
- },
- "required": [
- "verb",
- "target",
- "payload",
- "description"
- ],
- "title": "Structured entity or relation mutation",
- "type": "object"
- }
-]Input schema / properties / operations / items / propertiesAdded value: +{
+ "body": {
+ "description": "Complete new entity source for update.",
+ "type": "string"
+ },
+ "description": {
+ "description": "What this op changes.",
+ "type": "string"
+ },
+ "payload": {
+ "additionalProperties": false,
+ "description": "Required. body only with EntitySourceBase. In an empty repository, create with EntityCreate addressed to a unit.",
+ "oneOf": [
+ {
+ "required": [
+ "EntitySourcePatch"
+ ]
+ },
+ {
+ "required": [
+ "EntitySourceBase"
+ ]
+ },
+ {
+ "required": [
+ "EntityCreate"
+ ]
+ },
+ {
+ "required": [
+ "UnitImports"
+ ]
+ },
+ {
+ "required": [
+ "EntityRemove"
+ ]
+ }
+ ],
+ "properties": {
+ "EntityCreate": {
+ "additionalProperties": false,
+ "description": "Unit form (empty repository, any Go kind): repository_base and unit, target the name. Anchored form (functions): source_base and placement, target the anchor UUID.",
+ "properties": {
+ "body": {
+ "description": "The declaration only: no package clause or imports.",
+ "minLength": 1,
+ "type": "string"
+ },
+ "imports": {
+ "description": "Import paths it needs.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "kind": {
+ "enum": [
+ "function",
+ "method",
+ "struct",
+ "class",
+ "interface",
+ "type",
+ "const",
+ "var"
+ ],
+ "type": "string"
+ },
+ "name": {
+ "description": "Name, or Receiver.Method.",
+ "type": "string"
+ },
+ "placement": {
+ "enum": [
+ "sibling_after",
+ "new_source_unit"
+ ],
+ "type": "string"
+ },
+ "repository_base": {
+ "description": "Unchanged repository_base from session, status or the last mutate.",
+ "type": "object"
+ },
+ "source_base": {
+ "description": "Unchanged source_base from a current get_entity_source read.",
+ "type": "object"
+ },
+ "unit": {
+ "description": "{language:\"go\", package:\".\" or \"internal/store\", name: package name, role:\"source\" or \"test\"}",
+ "type": "object"
+ }
+ },
+ "required": [
+ "name",
+ "kind",
+ "body"
+ ],
+ "type": "object"
+ },
+ "EntityRemove": {
+ "additionalProperties": false,
+ "description": "Remove one source-bound top-level leaf function in Rust, Python or Go, preserving its artifact and siblings. No whole-file removal is admitted.",
+ "properties": {
+ "source_base": {
+ "description": "Unchanged source_base from a current get_entity_source read.",
+ "type": "object"
+ }
+ },
+ "required": [
+ "source_base"
+ ],
+ "type": "object"
+ },
+ "EntitySourceBase": {
+ "description": "Unchanged source_base from a current get_entity_source read; verb update with the complete body.",
+ "type": "object"
+ },
+ "EntitySourcePatch": {
+ "additionalProperties": false,
+ "properties": {
+ "edits": {
+ "description": "Each old_text must occur exactly once. Anchors must not overlap; all address the original entity body.",
+ "items": {
+ "additionalProperties": false,
+ "properties": {
+ "new_text": {
+ "type": "string"
+ },
+ "old_text": {
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "old_text",
+ "new_text"
+ ],
+ "type": "object"
+ },
+ "minItems": 1,
+ "type": "array"
+ },
+ "source_base": {
+ "description": "Unchanged source_base from a current get_entity_source read.",
+ "type": "object"
+ }
+ },
+ "required": [
+ "source_base",
+ "edits"
+ ],
+ "type": "object"
+ },
+ "UnitImports": {
+ "additionalProperties": false,
+ "description": "Add or remove imports on a unit; Kin writes its import block. Target the package name.",
+ "properties": {
+ "add": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "remove": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "repository_base": {
+ "description": "Unchanged repository_base from session, status or the last mutate.",
+ "type": "object"
+ },
+ "unit": {
+ "description": "{language:\"go\", package:\".\" or \"internal/store\", name: package name, role:\"source\" or \"test\"}",
+ "type": "object"
+ }
+ },
+ "required": [
+ "repository_base",
+ "unit"
+ ],
+ "type": "object"
+ }
+ },
+ "type": "object"
+ },
+ "target": {
+ "description": "UUID, or the declared or package name.",
+ "minLength": 1,
+ "type": "string"
+ },
+ "verb": {
+ "description": "Patch, update, create or remove.",
+ "enum": [
+ "patch",
+ "update",
+ "create",
+ "remove"
+ ],
+ "type": "string"
+ }
+}Input schema / properties / operations / items / requiredAdded value: +[
+ "verb",
+ "target",
+ "payload",
+ "description"
+]Input schema / properties / operations / items / typeAdded value: +"object"Input schema / properties / request_idRemoved value: -{
- "description": "Optional client request id, carried into the receipt so you can match the answer to your call; nothing deduplicates on it",
- "type": "string"
-}Input schema / properties / scopeRemoved value: -{
- "description": "Optional target scope or workspace identifier (defaults to 'repository')",
- "type": "string"
-}Input schema / properties / session_idRemoved value: -{
- "description": "Optional owning session UUID",
- "type": "string"
-}Input schema / properties / summary / descriptionPrevious value: -"Optional change message: one sentence in your own words saying what this change does, which becomes the subject a human reads in history. Omit it and the change records only the transaction id, which names the call and not the work."New value: +"One sentence for the history."kin_provenance_query2 fields changedInput schema / properties / entity_id / descriptionPrevious value: -"Entity UUID to query provenance for"New value: +"UUID"Input schema / properties / limit / descriptionPrevious value: -"Max changes per page. Default 20."New value: +"Page size."kin_session_end1 field changedInput schema / properties / session_id / descriptionPrevious value: -"Session UUID"New value: +"UUID"kin_session_execkin_session_heartbeat1 field changedInput schema / properties / session_id / descriptionPrevious value: -"Session UUID"New value: +"UUID"kin_session_start7 fields changedInput schema / properties / capabilities / descriptionPrevious value: -"Agent capabilities"New value: +"Abilities"Input schema / properties / client_name / descriptionPrevious value: -"Human-readable client name"New value: +"Client name."Input schema / properties / cwd / descriptionPrevious value: -"Working directory of the agent"New value: +"Agent's cwd."Input schema / properties / pid / descriptionPrevious value: -"OS process ID of the agent (optional)"New value: +"Agent process id."Input schema / properties / session_idAdded value: +{
+ "description": "Optional UUID to register under.",
+ "type": "string"
+}Input schema / properties / transport / descriptionPrevious value: -"Connection type: mcp, cli, wrapper, or ui"New value: +"mcp|cli|wrapper|ui"Input schema / properties / vendor / descriptionPrevious value: -"Vendor identifier (claude-code, codex, gemini-cli, etc.)"New value: +"e.g. claude-code, codex."kin_transaction_abort2 fields changedInput schema / properties / session_id / descriptionPrevious value: -"Owning session UUID. In enforce mode it must match the authenticated caller."New value: +"Owning session UUID."Input schema / properties / transaction_id / descriptionPrevious value: -"Transaction UUID"New value: +"UUID"kin_transaction_begin2 fields changedInput schema / properties / scope / descriptionPrevious value: -"Target scope (e.g. filename, module, etc.)"New value: +"Label, never a path."Input schema / properties / session_id / descriptionPrevious value: -"Session UUID owning the transaction"New value: +"Owning session."kin_transaction_commit5 fields changedInput schema / properties / message / descriptionPrevious value: -"Optional change message: one sentence in your own words saying what this change does, which becomes the subject a human reads in history. Omit it and the change records only the transaction id, which names the call and not the work."New value: +"One sentence on what this change does."Input schema / properties / operations / descriptionPrevious value: -"Optional exact mutation operations to stage atomically in this commit request"New value: +"Operations to stage in this commit."Input schema / properties / operations / items / oneOfPrevious value: -[
- {
- "additionalProperties": false,
- "properties": {
- "description": {
- "description": "Human-readable explanation of this change.",
- "type": "string"
- },
- "target": {
- "description": "Repository-relative path of the file to retire, such as \"src/parser.py\". It must be a path repository authority already tracks; a path the graph has never seen is refused.",
- "minLength": 1,
- "type": "string"
- },
- "verb": {
- "description": "Retire a tracked file. This is the only operation that removes a file, along with every entity derived from it and every edge incident to those entities.",
- "enum": [
- "delete",
- "remove"
- ],
- "type": "string"
- }
- },
- "required": [
- "verb",
- "target",
- "description"
- ],
- "title": "Retired source file",
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "description": {
- "description": "Human-readable explanation of this change.",
- "type": "string"
- },
- "destination": {
- "description": "Repository-relative path the file moves to. It must not be tracked already, and it follows the same path rules as `target`: no leading slash, no \"..\", and no Kin or Git control component.",
- "minLength": 1,
- "type": "string"
- },
- "target": {
- "description": "Repository-relative path the file lives at now. It must be a path repository authority already tracks.",
- "minLength": 1,
- "type": "string"
- },
- "verb": {
- "description": "Relocate a tracked file. Entity identity, history, and incoming edges survive the move, which is what separates this from a delete followed by a create.",
- "enum": [
- "rename",
- "move"
- ],
- "type": "string"
- }
- },
- "required": [
- "verb",
- "target",
- "destination",
- "description"
- ],
- "title": "Renamed source file",
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "body": {
- "description": "The file's complete UTF-8 source text. Kin parses it with the same extractor the ingest path uses, so every entity in it enters the graph, and writes the file into the working directory when the transaction commits. You do not need to write the file yourself first.",
- "minLength": 1,
- "type": "string"
- },
- "description": {
- "description": "Human-readable explanation of this change.",
- "type": "string"
- },
- "target": {
- "description": "Repository-relative path of the new file, such as \"src/parser.py\". No leading slash, no \"..\", and no Kin or Git control component. A path the graph already tracks is refused; rewrite that one with verb 'replace' instead.",
- "minLength": 1,
- "type": "string"
- },
- "verb": {
- "description": "Admit a source file the graph has never seen. This is the only operation that introduces a new file.",
- "enum": [
- "create",
- "add",
- "insert"
- ],
- "type": "string"
- }
- },
- "required": [
- "verb",
- "target",
- "body",
- "description"
- ],
- "title": "New source file",
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "body": {
- "description": "The file's complete new UTF-8 source text, never a fragment or a diff. Kin reparses it with the same extractor the ingest path uses, so entities the new text adds enter the graph, entities it drops leave it, and the rest keep their identity. A body identical to the tracked contents is refused as an empty change.",
- "minLength": 1,
- "type": "string"
- },
- "description": {
- "description": "Human-readable explanation of this change.",
- "type": "string"
- },
- "target": {
- "description": "Repository-relative path of the file to rewrite, such as \"src/parser.py\". It must be a path repository authority already tracks; a path the graph has never seen is refused, and 'create' is the verb for it.",
- "minLength": 1,
- "type": "string"
- },
- "verb": {
- "description": "Rewrite a tracked file from its complete new text. This is the operation to use when you hold a path and the file's new contents, which is what a local edit or write leaves you holding.",
- "enum": [
- "replace",
- "overwrite"
- ],
- "type": "string"
- }
- },
- "required": [
- "verb",
- "target",
- "body",
- "description"
- ],
- "title": "Replaced source file",
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "body": {
- "description": "The entity's complete new UTF-8 source text, including its own leading indentation. Do not submit a truncated retrieval body.",
- "minLength": 1,
- "type": "string"
- },
- "description": {
- "description": "Human-readable explanation of this change.",
- "type": "string"
- },
- "target": {
- "description": "Exact repository entity UUID or unambiguous exact entity name.",
- "minLength": 1,
- "type": "string"
- },
- "verb": {
- "description": "Update an existing source entity.",
- "enum": [
- "update",
- "modify"
- ],
- "type": "string"
- }
- },
- "required": [
- "verb",
- "target",
- "body",
- "description"
- ],
- "title": "Entity source body edit",
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "body": {
- "description": "Full new UTF-8 source text for a source-bound Entity update. Omit for Relation operations.",
- "type": "string"
- },
- "description": {
- "description": "Human-readable explanation of this change.",
- "type": "string"
- },
- "payload": {
- "description": "Exact mutation payload: {\"Entity\": { ...existing entity identity... }} or {\"Relation\": {\"from\": \"...\", \"to\": \"...\", \"kind\": \"...\"}}.",
- "type": "object"
- },
- "target": {
- "description": "Exact repository entity UUID for an Entity payload; empty string for a Relation payload.",
- "type": "string"
- },
- "verb": {
- "description": "Entity or relation mutation verb.",
- "enum": [
- "create",
- "add",
- "upsert",
- "insert",
- "update",
- "modify",
- "delete",
- "remove"
- ],
- "type": "string"
- }
- },
- "required": [
- "verb",
- "target",
- "payload",
- "description"
- ],
- "title": "Structured entity or relation mutation",
- "type": "object"
- }
-]New value: +[
+ {
+ "additionalProperties": false,
+ "properties": {
+ "description": {
+ "type": "string"
+ },
+ "payload": {
+ "additionalProperties": false,
+ "properties": {
+ "EntitySourcePatch": {
+ "additionalProperties": false,
+ "properties": {
+ "edits": {
+ "description": "Exact unique nonoverlapping anchors in the original entity body. All edits use that same original body, not earlier replacements.",
+ "items": {
+ "additionalProperties": false,
+ "properties": {
+ "new_text": {
+ "type": "string"
+ },
+ "old_text": {
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "old_text",
+ "new_text"
+ ],
+ "type": "object"
+ },
+ "minItems": 1,
+ "type": "array"
+ },
+ "source_base": {
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "additionalProperties": false,
+ "properties": {
+ "artifact_id": {
+ "format": "uuid",
+ "type": "string"
+ },
+ "body_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ },
+ "context": {
+ "additionalProperties": false,
+ "properties": {
+ "repository_id": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "workspace_generation": {
+ "minimum": 0,
+ "type": "integer"
+ },
+ "workspace_head_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ },
+ "workspace_id": {
+ "format": "uuid",
+ "type": "string"
+ },
+ "workspace_tree_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ }
+ },
+ "required": [
+ "repository_id",
+ "workspace_id",
+ "workspace_generation",
+ "workspace_head_hash",
+ "workspace_tree_hash"
+ ],
+ "type": "object"
+ },
+ "end_byte": {
+ "minimum": 1,
+ "type": "integer"
+ },
+ "entity_id": {
+ "format": "uuid",
+ "type": "string"
+ },
+ "schema": {
+ "const": "kin.entity.source_base.v1"
+ },
+ "source_blob_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ },
+ "start_byte": {
+ "minimum": 0,
+ "type": "integer"
+ }
+ },
+ "required": [
+ "schema",
+ "context",
+ "entity_id",
+ "artifact_id",
+ "source_blob_hash",
+ "start_byte",
+ "end_byte",
+ "body_hash"
+ ],
+ "title": "Exact entity source base v1",
+ "type": "object"
+ }
+ },
+ "required": [
+ "source_base",
+ "edits"
+ ],
+ "type": "object"
+ }
+ },
+ "required": [
+ "EntitySourcePatch"
+ ],
+ "type": "object"
+ },
+ "target": {
+ "description": "The exact entity UUID in source_base.",
+ "format": "uuid",
+ "type": "string"
+ },
+ "verb": {
+ "enum": [
+ "patch"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "verb",
+ "target",
+ "payload",
+ "description"
+ ],
+ "title": "Anchored entity source patch",
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "body": {
+ "description": "Complete new entity text, indentation kept, never truncated.",
+ "minLength": 1,
+ "type": "string"
+ },
+ "description": {
+ "description": "What this changes.",
+ "type": "string"
+ },
+ "payload": {
+ "additionalProperties": false,
+ "properties": {
+ "EntitySourceBase": {
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "additionalProperties": false,
+ "properties": {
+ "artifact_id": {
+ "format": "uuid",
+ "type": "string"
+ },
+ "body_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ },
+ "context": {
+ "additionalProperties": false,
+ "properties": {
+ "repository_id": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "workspace_generation": {
+ "minimum": 0,
+ "type": "integer"
+ },
+ "workspace_head_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ },
+ "workspace_id": {
+ "format": "uuid",
+ "type": "string"
+ },
+ "workspace_tree_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ }
+ },
+ "required": [
+ "repository_id",
+ "workspace_id",
+ "workspace_generation",
+ "workspace_head_hash",
+ "workspace_tree_hash"
+ ],
+ "type": "object"
+ },
+ "end_byte": {
+ "minimum": 1,
+ "type": "integer"
+ },
+ "entity_id": {
+ "format": "uuid",
+ "type": "string"
+ },
+ "schema": {
+ "const": "kin.entity.source_base.v1"
+ },
+ "source_blob_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ },
+ "start_byte": {
+ "minimum": 0,
+ "type": "integer"
+ }
+ },
+ "required": [
+ "schema",
+ "context",
+ "entity_id",
+ "artifact_id",
+ "source_blob_hash",
+ "start_byte",
+ "end_byte",
+ "body_hash"
+ ],
+ "title": "Exact entity source base v1",
+ "type": "object"
+ }
+ },
+ "required": [
+ "EntitySourceBase"
+ ],
+ "type": "object"
+ },
+ "target": {
+ "description": "source_base UUID.",
+ "format": "uuid",
+ "type": "string"
+ },
+ "verb": {
+ "description": "Edit an entity.",
+ "enum": [
+ "update",
+ "modify"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "verb",
+ "target",
+ "body",
+ "payload",
+ "description"
+ ],
+ "title": "Guarded entity source body edit",
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "description": {
+ "description": "What this changes.",
+ "type": "string"
+ },
+ "payload": {
+ "description": "{\"Relation\": {from, to, kind}}; create with EntityCreate.",
+ "oneOf": [
+ {
+ "additionalProperties": false,
+ "properties": {
+ "Entity": {
+ "type": "object"
+ }
+ },
+ "required": [
+ "Entity"
+ ]
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "Relation": {
+ "type": "object"
+ }
+ },
+ "required": [
+ "Relation"
+ ]
+ }
+ ],
+ "type": "object"
+ },
+ "target": {
+ "description": "Entity UUID; empty for a Relation payload.",
+ "type": "string"
+ },
+ "verb": {
+ "description": "Mutation verb.",
+ "enum": [
+ "create",
+ "add",
+ "upsert",
+ "insert",
+ "update",
+ "modify",
+ "delete",
+ "remove"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "verb",
+ "target",
+ "payload",
+ "description"
+ ],
+ "title": "Structured entity or relation mutation",
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "description": {
+ "type": "string"
+ },
+ "payload": {
+ "additionalProperties": false,
+ "properties": {
+ "EntityCreate": {
+ "additionalProperties": false,
+ "description": "Create one declaration, in one of two forms, with no path or offset. Addressed to a unit (repository_base and unit): the form for an empty repository and for every Go declaration kind. Kin derives the unit's file, writes its package clause, places the declaration (a method directly after its receiver type or that type's last method, anything else at the end of the unit) and merges imports into the unit's one import block. The operation's target is the declared name. Anchored (source_base and placement): one top-level function in Rust, Python or Go beside a current function, whose UUID is the target. Occupied names, ambiguous placement and stale bases refuse without publication.",
+ "oneOf": [
+ {
+ "required": [
+ "repository_base",
+ "unit"
+ ]
+ },
+ {
+ "required": [
+ "source_base",
+ "placement"
+ ]
+ }
+ ],
+ "properties": {
+ "body": {
+ "description": "Exactly the declaration's source, optionally led by its doc comment: no package clause, imports or sibling declarations.",
+ "minLength": 1,
+ "type": "string"
+ },
+ "imports": {
+ "description": "Unit form: import paths the declaration needs, added to the unit's import block.",
+ "items": {
+ "oneOf": [
+ {
+ "description": "An import path, such as \"fmt\" or \"example.com/app/internal/store\".",
+ "minLength": 1,
+ "type": "string"
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "alias": {
+ "description": "Explicit package name, \"_\" or \".\".",
+ "type": "string"
+ },
+ "path": {
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "path"
+ ],
+ "type": "object"
+ }
+ ]
+ },
+ "type": "array"
+ },
+ "kind": {
+ "description": "Go admits function, method, struct, interface, type, const and var; anchored creation admits function. The graph kinds class, type_alias, constant and static_var are accepted as synonyms.",
+ "enum": [
+ "function",
+ "method",
+ "struct",
+ "class",
+ "interface",
+ "type",
+ "const",
+ "var"
+ ],
+ "type": "string"
+ },
+ "name": {
+ "description": "The declared name as the graph names it: Name, Receiver.Method for a method, the first name of a grouped const or var, or _ for a blank var or const such as var _ Getter = (*Store)(nil), whose entity is named after the assertion (_ Getter = (*Store)(nil)).",
+ "minLength": 1,
+ "type": "string"
+ },
+ "placement": {
+ "enum": [
+ "sibling_after",
+ "new_source_unit"
+ ],
+ "type": "string"
+ },
+ "repository_base": {
+ "additionalProperties": false,
+ "description": "The repository_base Kin returned from session, status or the last mutate, unchanged. Work addressed to a unit is refused as repository_base_conflict when repository authority has moved since.",
+ "properties": {
+ "context": {
+ "additionalProperties": false,
+ "properties": {
+ "repository_id": {
+ "type": "string"
+ },
+ "workspace_generation": {
+ "minimum": 0,
+ "type": "integer"
+ },
+ "workspace_head_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ },
+ "workspace_id": {
+ "type": "string"
+ },
+ "workspace_tree_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ }
+ },
+ "required": [
+ "repository_id",
+ "workspace_id",
+ "workspace_generation",
+ "workspace_head_hash",
+ "workspace_tree_hash"
+ ],
+ "type": "object"
+ },
+ "schema": {
+ "const": "kin.repository.base.v1"
+ }
+ },
+ "required": [
+ "schema",
+ "context"
+ ],
+ "type": "object"
+ },
+ "source_base": {
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "additionalProperties": false,
+ "properties": {
+ "artifact_id": {
+ "format": "uuid",
+ "type": "string"
+ },
+ "body_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ },
+ "context": {
+ "additionalProperties": false,
+ "properties": {
+ "repository_id": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "workspace_generation": {
+ "minimum": 0,
+ "type": "integer"
+ },
+ "workspace_head_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ },
+ "workspace_id": {
+ "format": "uuid",
+ "type": "string"
+ },
+ "workspace_tree_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ }
+ },
+ "required": [
+ "repository_id",
+ "workspace_id",
+ "workspace_generation",
+ "workspace_head_hash",
+ "workspace_tree_hash"
+ ],
+ "type": "object"
+ },
+ "end_byte": {
+ "minimum": 1,
+ "type": "integer"
+ },
+ "entity_id": {
+ "format": "uuid",
+ "type": "string"
+ },
+ "schema": {
+ "const": "kin.entity.source_base.v1"
+ },
+ "source_blob_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ },
+ "start_byte": {
+ "minimum": 0,
+ "type": "integer"
+ }
+ },
+ "required": [
+ "schema",
+ "context",
+ "entity_id",
+ "artifact_id",
+ "source_blob_hash",
+ "start_byte",
+ "end_byte",
+ "body_hash"
+ ],
+ "title": "Exact entity source base v1",
+ "type": "object"
+ },
+ "unit": {
+ "additionalProperties": false,
+ "description": "A source unit named by language identity, never by path. Go: package is the import path relative to the module root (\".\" or \"internal/store\"), name is the package clause, role is source or test (the package's _test unit). Kin derives the file and owns the package clause.",
+ "properties": {
+ "language": {
+ "const": "go"
+ },
+ "name": {
+ "pattern": "^[A-Za-z_][A-Za-z0-9_]*$",
+ "type": "string"
+ },
+ "package": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "role": {
+ "default": "source",
+ "enum": [
+ "source",
+ "test"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "language",
+ "package",
+ "name"
+ ],
+ "type": "object"
+ }
+ },
+ "required": [
+ "name",
+ "kind",
+ "body"
+ ],
+ "type": "object"
+ }
+ },
+ "required": [
+ "EntityCreate"
+ ],
+ "type": "object"
+ },
+ "target": {
+ "description": "The declared name for a unit-addressed creation; the source_base anchor UUID for an anchored one.",
+ "minLength": 1,
+ "type": "string"
+ },
+ "verb": {
+ "enum": [
+ "create"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "verb",
+ "target",
+ "payload",
+ "description"
+ ],
+ "title": "EntityCreate",
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "description": {
+ "type": "string"
+ },
+ "payload": {
+ "additionalProperties": false,
+ "properties": {
+ "UnitImports": {
+ "additionalProperties": false,
+ "description": "Add or remove imports on one source unit. Kin writes the unit's single import block deterministically (standard library first, each group sorted). Adding a held import or removing an absent one is a no-op.",
+ "properties": {
+ "add": {
+ "items": {
+ "oneOf": [
+ {
+ "description": "An import path, such as \"fmt\" or \"example.com/app/internal/store\".",
+ "minLength": 1,
+ "type": "string"
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "alias": {
+ "description": "Explicit package name, \"_\" or \".\".",
+ "type": "string"
+ },
+ "path": {
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "path"
+ ],
+ "type": "object"
+ }
+ ]
+ },
+ "type": "array"
+ },
+ "remove": {
+ "items": {
+ "oneOf": [
+ {
+ "description": "An import path, such as \"fmt\" or \"example.com/app/internal/store\".",
+ "minLength": 1,
+ "type": "string"
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "alias": {
+ "description": "Explicit package name, \"_\" or \".\".",
+ "type": "string"
+ },
+ "path": {
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "path"
+ ],
+ "type": "object"
+ }
+ ]
+ },
+ "type": "array"
+ },
+ "repository_base": {
+ "additionalProperties": false,
+ "description": "The repository_base Kin returned from session, status or the last mutate, unchanged. Work addressed to a unit is refused as repository_base_conflict when repository authority has moved since.",
+ "properties": {
+ "context": {
+ "additionalProperties": false,
+ "properties": {
+ "repository_id": {
+ "type": "string"
+ },
+ "workspace_generation": {
+ "minimum": 0,
+ "type": "integer"
+ },
+ "workspace_head_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ },
+ "workspace_id": {
+ "type": "string"
+ },
+ "workspace_tree_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ }
+ },
+ "required": [
+ "repository_id",
+ "workspace_id",
+ "workspace_generation",
+ "workspace_head_hash",
+ "workspace_tree_hash"
+ ],
+ "type": "object"
+ },
+ "schema": {
+ "const": "kin.repository.base.v1"
+ }
+ },
+ "required": [
+ "schema",
+ "context"
+ ],
+ "type": "object"
+ },
+ "unit": {
+ "additionalProperties": false,
+ "description": "A source unit named by language identity, never by path. Go: package is the import path relative to the module root (\".\" or \"internal/store\"), name is the package clause, role is source or test (the package's _test unit). Kin derives the file and owns the package clause.",
+ "properties": {
+ "language": {
+ "const": "go"
+ },
+ "name": {
+ "pattern": "^[A-Za-z_][A-Za-z0-9_]*$",
+ "type": "string"
+ },
+ "package": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "role": {
+ "default": "source",
+ "enum": [
+ "source",
+ "test"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "language",
+ "package",
+ "name"
+ ],
+ "type": "object"
+ }
+ },
+ "required": [
+ "repository_base",
+ "unit"
+ ],
+ "type": "object"
+ }
+ },
+ "required": [
+ "UnitImports"
+ ],
+ "type": "object"
+ },
+ "target": {
+ "description": "The unit's package name.",
+ "minLength": 1,
+ "type": "string"
+ },
+ "verb": {
+ "enum": [
+ "update"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "verb",
+ "target",
+ "payload",
+ "description"
+ ],
+ "title": "UnitImports",
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "description": {
+ "type": "string"
+ },
+ "payload": {
+ "additionalProperties": false,
+ "properties": {
+ "EntityRemove": {
+ "additionalProperties": false,
+ "description": "Remove one source-bound top-level leaf function in Rust, Python or Go, preserving its artifact and siblings. No whole-file removal is admitted.",
+ "properties": {
+ "source_base": {
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "additionalProperties": false,
+ "properties": {
+ "artifact_id": {
+ "format": "uuid",
+ "type": "string"
+ },
+ "body_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ },
+ "context": {
+ "additionalProperties": false,
+ "properties": {
+ "repository_id": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "workspace_generation": {
+ "minimum": 0,
+ "type": "integer"
+ },
+ "workspace_head_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ },
+ "workspace_id": {
+ "format": "uuid",
+ "type": "string"
+ },
+ "workspace_tree_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ }
+ },
+ "required": [
+ "repository_id",
+ "workspace_id",
+ "workspace_generation",
+ "workspace_head_hash",
+ "workspace_tree_hash"
+ ],
+ "type": "object"
+ },
+ "end_byte": {
+ "minimum": 1,
+ "type": "integer"
+ },
+ "entity_id": {
+ "format": "uuid",
+ "type": "string"
+ },
+ "schema": {
+ "const": "kin.entity.source_base.v1"
+ },
+ "source_blob_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ },
+ "start_byte": {
+ "minimum": 0,
+ "type": "integer"
+ }
+ },
+ "required": [
+ "schema",
+ "context",
+ "entity_id",
+ "artifact_id",
+ "source_blob_hash",
+ "start_byte",
+ "end_byte",
+ "body_hash"
+ ],
+ "title": "Exact entity source base v1",
+ "type": "object"
+ }
+ },
+ "required": [
+ "source_base"
+ ],
+ "type": "object"
+ }
+ },
+ "required": [
+ "EntityRemove"
+ ],
+ "type": "object"
+ },
+ "target": {
+ "description": "Exact source_base anchor/entity UUID.",
+ "format": "uuid",
+ "type": "string"
+ },
+ "verb": {
+ "enum": [
+ "remove"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "verb",
+ "target",
+ "payload",
+ "description"
+ ],
+ "title": "EntityRemove",
+ "type": "object"
+ }
+]Input schema / properties / session_id / descriptionPrevious value: -"Optional owning session UUID mirror; when present in enforce mode it must match the authenticated caller and transaction owner"New value: +"Owning session UUID."Input schema / properties / transaction_id / descriptionPrevious value: -"Transaction UUID"New value: +"UUID"kin_transaction_stage4 fields changedInput schema / properties / operations / descriptionPrevious value: -"Array of mutation operations to stage"New value: +"What to stage."Input schema / properties / operations / items / oneOfPrevious value: -[
- {
- "additionalProperties": false,
- "properties": {
- "description": {
- "description": "Human-readable explanation of this change.",
- "type": "string"
- },
- "target": {
- "description": "Repository-relative path of the file to retire, such as \"src/parser.py\". It must be a path repository authority already tracks; a path the graph has never seen is refused.",
- "minLength": 1,
- "type": "string"
- },
- "verb": {
- "description": "Retire a tracked file. This is the only operation that removes a file, along with every entity derived from it and every edge incident to those entities.",
- "enum": [
- "delete",
- "remove"
- ],
- "type": "string"
- }
- },
- "required": [
- "verb",
- "target",
- "description"
- ],
- "title": "Retired source file",
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "description": {
- "description": "Human-readable explanation of this change.",
- "type": "string"
- },
- "destination": {
- "description": "Repository-relative path the file moves to. It must not be tracked already, and it follows the same path rules as `target`: no leading slash, no \"..\", and no Kin or Git control component.",
- "minLength": 1,
- "type": "string"
- },
- "target": {
- "description": "Repository-relative path the file lives at now. It must be a path repository authority already tracks.",
- "minLength": 1,
- "type": "string"
- },
- "verb": {
- "description": "Relocate a tracked file. Entity identity, history, and incoming edges survive the move, which is what separates this from a delete followed by a create.",
- "enum": [
- "rename",
- "move"
- ],
- "type": "string"
- }
- },
- "required": [
- "verb",
- "target",
- "destination",
- "description"
- ],
- "title": "Renamed source file",
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "body": {
- "description": "The file's complete UTF-8 source text. Kin parses it with the same extractor the ingest path uses, so every entity in it enters the graph, and writes the file into the working directory when the transaction commits. You do not need to write the file yourself first.",
- "minLength": 1,
- "type": "string"
- },
- "description": {
- "description": "Human-readable explanation of this change.",
- "type": "string"
- },
- "target": {
- "description": "Repository-relative path of the new file, such as \"src/parser.py\". No leading slash, no \"..\", and no Kin or Git control component. A path the graph already tracks is refused; rewrite that one with verb 'replace' instead.",
- "minLength": 1,
- "type": "string"
- },
- "verb": {
- "description": "Admit a source file the graph has never seen. This is the only operation that introduces a new file.",
- "enum": [
- "create",
- "add",
- "insert"
- ],
- "type": "string"
- }
- },
- "required": [
- "verb",
- "target",
- "body",
- "description"
- ],
- "title": "New source file",
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "body": {
- "description": "The file's complete new UTF-8 source text, never a fragment or a diff. Kin reparses it with the same extractor the ingest path uses, so entities the new text adds enter the graph, entities it drops leave it, and the rest keep their identity. A body identical to the tracked contents is refused as an empty change.",
- "minLength": 1,
- "type": "string"
- },
- "description": {
- "description": "Human-readable explanation of this change.",
- "type": "string"
- },
- "target": {
- "description": "Repository-relative path of the file to rewrite, such as \"src/parser.py\". It must be a path repository authority already tracks; a path the graph has never seen is refused, and 'create' is the verb for it.",
- "minLength": 1,
- "type": "string"
- },
- "verb": {
- "description": "Rewrite a tracked file from its complete new text. This is the operation to use when you hold a path and the file's new contents, which is what a local edit or write leaves you holding.",
- "enum": [
- "replace",
- "overwrite"
- ],
- "type": "string"
- }
- },
- "required": [
- "verb",
- "target",
- "body",
- "description"
- ],
- "title": "Replaced source file",
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "body": {
- "description": "The entity's complete new UTF-8 source text, including its own leading indentation. Do not submit a truncated retrieval body.",
- "minLength": 1,
- "type": "string"
- },
- "description": {
- "description": "Human-readable explanation of this change.",
- "type": "string"
- },
- "target": {
- "description": "Exact repository entity UUID or unambiguous exact entity name.",
- "minLength": 1,
- "type": "string"
- },
- "verb": {
- "description": "Update an existing source entity.",
- "enum": [
- "update",
- "modify"
- ],
- "type": "string"
- }
- },
- "required": [
- "verb",
- "target",
- "body",
- "description"
- ],
- "title": "Entity source body edit",
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "body": {
- "description": "Full new UTF-8 source text for a source-bound Entity update. Omit for Relation operations.",
- "type": "string"
- },
- "description": {
- "description": "Human-readable explanation of this change.",
- "type": "string"
- },
- "payload": {
- "description": "Exact mutation payload: {\"Entity\": { ...existing entity identity... }} or {\"Relation\": {\"from\": \"...\", \"to\": \"...\", \"kind\": \"...\"}}.",
- "type": "object"
- },
- "target": {
- "description": "Exact repository entity UUID for an Entity payload; empty string for a Relation payload.",
- "type": "string"
- },
- "verb": {
- "description": "Entity or relation mutation verb.",
- "enum": [
- "create",
- "add",
- "upsert",
- "insert",
- "update",
- "modify",
- "delete",
- "remove"
- ],
- "type": "string"
- }
- },
- "required": [
- "verb",
- "target",
- "payload",
- "description"
- ],
- "title": "Structured entity or relation mutation",
- "type": "object"
- }
-]New value: +[
+ {
+ "additionalProperties": false,
+ "properties": {
+ "description": {
+ "type": "string"
+ },
+ "payload": {
+ "additionalProperties": false,
+ "properties": {
+ "EntitySourcePatch": {
+ "additionalProperties": false,
+ "properties": {
+ "edits": {
+ "description": "Exact unique nonoverlapping anchors in the original entity body. All edits use that same original body, not earlier replacements.",
+ "items": {
+ "additionalProperties": false,
+ "properties": {
+ "new_text": {
+ "type": "string"
+ },
+ "old_text": {
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "old_text",
+ "new_text"
+ ],
+ "type": "object"
+ },
+ "minItems": 1,
+ "type": "array"
+ },
+ "source_base": {
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "additionalProperties": false,
+ "properties": {
+ "artifact_id": {
+ "format": "uuid",
+ "type": "string"
+ },
+ "body_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ },
+ "context": {
+ "additionalProperties": false,
+ "properties": {
+ "repository_id": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "workspace_generation": {
+ "minimum": 0,
+ "type": "integer"
+ },
+ "workspace_head_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ },
+ "workspace_id": {
+ "format": "uuid",
+ "type": "string"
+ },
+ "workspace_tree_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ }
+ },
+ "required": [
+ "repository_id",
+ "workspace_id",
+ "workspace_generation",
+ "workspace_head_hash",
+ "workspace_tree_hash"
+ ],
+ "type": "object"
+ },
+ "end_byte": {
+ "minimum": 1,
+ "type": "integer"
+ },
+ "entity_id": {
+ "format": "uuid",
+ "type": "string"
+ },
+ "schema": {
+ "const": "kin.entity.source_base.v1"
+ },
+ "source_blob_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ },
+ "start_byte": {
+ "minimum": 0,
+ "type": "integer"
+ }
+ },
+ "required": [
+ "schema",
+ "context",
+ "entity_id",
+ "artifact_id",
+ "source_blob_hash",
+ "start_byte",
+ "end_byte",
+ "body_hash"
+ ],
+ "title": "Exact entity source base v1",
+ "type": "object"
+ }
+ },
+ "required": [
+ "source_base",
+ "edits"
+ ],
+ "type": "object"
+ }
+ },
+ "required": [
+ "EntitySourcePatch"
+ ],
+ "type": "object"
+ },
+ "target": {
+ "description": "The exact entity UUID in source_base.",
+ "format": "uuid",
+ "type": "string"
+ },
+ "verb": {
+ "enum": [
+ "patch"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "verb",
+ "target",
+ "payload",
+ "description"
+ ],
+ "title": "Anchored entity source patch",
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "body": {
+ "description": "Complete new entity text, indentation kept, never truncated.",
+ "minLength": 1,
+ "type": "string"
+ },
+ "description": {
+ "description": "What this changes.",
+ "type": "string"
+ },
+ "payload": {
+ "additionalProperties": false,
+ "properties": {
+ "EntitySourceBase": {
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "additionalProperties": false,
+ "properties": {
+ "artifact_id": {
+ "format": "uuid",
+ "type": "string"
+ },
+ "body_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ },
+ "context": {
+ "additionalProperties": false,
+ "properties": {
+ "repository_id": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "workspace_generation": {
+ "minimum": 0,
+ "type": "integer"
+ },
+ "workspace_head_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ },
+ "workspace_id": {
+ "format": "uuid",
+ "type": "string"
+ },
+ "workspace_tree_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ }
+ },
+ "required": [
+ "repository_id",
+ "workspace_id",
+ "workspace_generation",
+ "workspace_head_hash",
+ "workspace_tree_hash"
+ ],
+ "type": "object"
+ },
+ "end_byte": {
+ "minimum": 1,
+ "type": "integer"
+ },
+ "entity_id": {
+ "format": "uuid",
+ "type": "string"
+ },
+ "schema": {
+ "const": "kin.entity.source_base.v1"
+ },
+ "source_blob_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ },
+ "start_byte": {
+ "minimum": 0,
+ "type": "integer"
+ }
+ },
+ "required": [
+ "schema",
+ "context",
+ "entity_id",
+ "artifact_id",
+ "source_blob_hash",
+ "start_byte",
+ "end_byte",
+ "body_hash"
+ ],
+ "title": "Exact entity source base v1",
+ "type": "object"
+ }
+ },
+ "required": [
+ "EntitySourceBase"
+ ],
+ "type": "object"
+ },
+ "target": {
+ "description": "source_base UUID.",
+ "format": "uuid",
+ "type": "string"
+ },
+ "verb": {
+ "description": "Edit an entity.",
+ "enum": [
+ "update",
+ "modify"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "verb",
+ "target",
+ "body",
+ "payload",
+ "description"
+ ],
+ "title": "Guarded entity source body edit",
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "description": {
+ "description": "What this changes.",
+ "type": "string"
+ },
+ "payload": {
+ "description": "{\"Relation\": {from, to, kind}}; create with EntityCreate.",
+ "oneOf": [
+ {
+ "additionalProperties": false,
+ "properties": {
+ "Entity": {
+ "type": "object"
+ }
+ },
+ "required": [
+ "Entity"
+ ]
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "Relation": {
+ "type": "object"
+ }
+ },
+ "required": [
+ "Relation"
+ ]
+ }
+ ],
+ "type": "object"
+ },
+ "target": {
+ "description": "Entity UUID; empty for a Relation payload.",
+ "type": "string"
+ },
+ "verb": {
+ "description": "Mutation verb.",
+ "enum": [
+ "create",
+ "add",
+ "upsert",
+ "insert",
+ "update",
+ "modify",
+ "delete",
+ "remove"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "verb",
+ "target",
+ "payload",
+ "description"
+ ],
+ "title": "Structured entity or relation mutation",
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "description": {
+ "type": "string"
+ },
+ "payload": {
+ "additionalProperties": false,
+ "properties": {
+ "EntityCreate": {
+ "additionalProperties": false,
+ "description": "Create one declaration, in one of two forms, with no path or offset. Addressed to a unit (repository_base and unit): the form for an empty repository and for every Go declaration kind. Kin derives the unit's file, writes its package clause, places the declaration (a method directly after its receiver type or that type's last method, anything else at the end of the unit) and merges imports into the unit's one import block. The operation's target is the declared name. Anchored (source_base and placement): one top-level function in Rust, Python or Go beside a current function, whose UUID is the target. Occupied names, ambiguous placement and stale bases refuse without publication.",
+ "oneOf": [
+ {
+ "required": [
+ "repository_base",
+ "unit"
+ ]
+ },
+ {
+ "required": [
+ "source_base",
+ "placement"
+ ]
+ }
+ ],
+ "properties": {
+ "body": {
+ "description": "Exactly the declaration's source, optionally led by its doc comment: no package clause, imports or sibling declarations.",
+ "minLength": 1,
+ "type": "string"
+ },
+ "imports": {
+ "description": "Unit form: import paths the declaration needs, added to the unit's import block.",
+ "items": {
+ "oneOf": [
+ {
+ "description": "An import path, such as \"fmt\" or \"example.com/app/internal/store\".",
+ "minLength": 1,
+ "type": "string"
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "alias": {
+ "description": "Explicit package name, \"_\" or \".\".",
+ "type": "string"
+ },
+ "path": {
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "path"
+ ],
+ "type": "object"
+ }
+ ]
+ },
+ "type": "array"
+ },
+ "kind": {
+ "description": "Go admits function, method, struct, interface, type, const and var; anchored creation admits function. The graph kinds class, type_alias, constant and static_var are accepted as synonyms.",
+ "enum": [
+ "function",
+ "method",
+ "struct",
+ "class",
+ "interface",
+ "type",
+ "const",
+ "var"
+ ],
+ "type": "string"
+ },
+ "name": {
+ "description": "The declared name as the graph names it: Name, Receiver.Method for a method, the first name of a grouped const or var, or _ for a blank var or const such as var _ Getter = (*Store)(nil), whose entity is named after the assertion (_ Getter = (*Store)(nil)).",
+ "minLength": 1,
+ "type": "string"
+ },
+ "placement": {
+ "enum": [
+ "sibling_after",
+ "new_source_unit"
+ ],
+ "type": "string"
+ },
+ "repository_base": {
+ "additionalProperties": false,
+ "description": "The repository_base Kin returned from session, status or the last mutate, unchanged. Work addressed to a unit is refused as repository_base_conflict when repository authority has moved since.",
+ "properties": {
+ "context": {
+ "additionalProperties": false,
+ "properties": {
+ "repository_id": {
+ "type": "string"
+ },
+ "workspace_generation": {
+ "minimum": 0,
+ "type": "integer"
+ },
+ "workspace_head_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ },
+ "workspace_id": {
+ "type": "string"
+ },
+ "workspace_tree_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ }
+ },
+ "required": [
+ "repository_id",
+ "workspace_id",
+ "workspace_generation",
+ "workspace_head_hash",
+ "workspace_tree_hash"
+ ],
+ "type": "object"
+ },
+ "schema": {
+ "const": "kin.repository.base.v1"
+ }
+ },
+ "required": [
+ "schema",
+ "context"
+ ],
+ "type": "object"
+ },
+ "source_base": {
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "additionalProperties": false,
+ "properties": {
+ "artifact_id": {
+ "format": "uuid",
+ "type": "string"
+ },
+ "body_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ },
+ "context": {
+ "additionalProperties": false,
+ "properties": {
+ "repository_id": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "workspace_generation": {
+ "minimum": 0,
+ "type": "integer"
+ },
+ "workspace_head_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ },
+ "workspace_id": {
+ "format": "uuid",
+ "type": "string"
+ },
+ "workspace_tree_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ }
+ },
+ "required": [
+ "repository_id",
+ "workspace_id",
+ "workspace_generation",
+ "workspace_head_hash",
+ "workspace_tree_hash"
+ ],
+ "type": "object"
+ },
+ "end_byte": {
+ "minimum": 1,
+ "type": "integer"
+ },
+ "entity_id": {
+ "format": "uuid",
+ "type": "string"
+ },
+ "schema": {
+ "const": "kin.entity.source_base.v1"
+ },
+ "source_blob_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ },
+ "start_byte": {
+ "minimum": 0,
+ "type": "integer"
+ }
+ },
+ "required": [
+ "schema",
+ "context",
+ "entity_id",
+ "artifact_id",
+ "source_blob_hash",
+ "start_byte",
+ "end_byte",
+ "body_hash"
+ ],
+ "title": "Exact entity source base v1",
+ "type": "object"
+ },
+ "unit": {
+ "additionalProperties": false,
+ "description": "A source unit named by language identity, never by path. Go: package is the import path relative to the module root (\".\" or \"internal/store\"), name is the package clause, role is source or test (the package's _test unit). Kin derives the file and owns the package clause.",
+ "properties": {
+ "language": {
+ "const": "go"
+ },
+ "name": {
+ "pattern": "^[A-Za-z_][A-Za-z0-9_]*$",
+ "type": "string"
+ },
+ "package": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "role": {
+ "default": "source",
+ "enum": [
+ "source",
+ "test"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "language",
+ "package",
+ "name"
+ ],
+ "type": "object"
+ }
+ },
+ "required": [
+ "name",
+ "kind",
+ "body"
+ ],
+ "type": "object"
+ }
+ },
+ "required": [
+ "EntityCreate"
+ ],
+ "type": "object"
+ },
+ "target": {
+ "description": "The declared name for a unit-addressed creation; the source_base anchor UUID for an anchored one.",
+ "minLength": 1,
+ "type": "string"
+ },
+ "verb": {
+ "enum": [
+ "create"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "verb",
+ "target",
+ "payload",
+ "description"
+ ],
+ "title": "EntityCreate",
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "description": {
+ "type": "string"
+ },
+ "payload": {
+ "additionalProperties": false,
+ "properties": {
+ "UnitImports": {
+ "additionalProperties": false,
+ "description": "Add or remove imports on one source unit. Kin writes the unit's single import block deterministically (standard library first, each group sorted). Adding a held import or removing an absent one is a no-op.",
+ "properties": {
+ "add": {
+ "items": {
+ "oneOf": [
+ {
+ "description": "An import path, such as \"fmt\" or \"example.com/app/internal/store\".",
+ "minLength": 1,
+ "type": "string"
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "alias": {
+ "description": "Explicit package name, \"_\" or \".\".",
+ "type": "string"
+ },
+ "path": {
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "path"
+ ],
+ "type": "object"
+ }
+ ]
+ },
+ "type": "array"
+ },
+ "remove": {
+ "items": {
+ "oneOf": [
+ {
+ "description": "An import path, such as \"fmt\" or \"example.com/app/internal/store\".",
+ "minLength": 1,
+ "type": "string"
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "alias": {
+ "description": "Explicit package name, \"_\" or \".\".",
+ "type": "string"
+ },
+ "path": {
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "path"
+ ],
+ "type": "object"
+ }
+ ]
+ },
+ "type": "array"
+ },
+ "repository_base": {
+ "additionalProperties": false,
+ "description": "The repository_base Kin returned from session, status or the last mutate, unchanged. Work addressed to a unit is refused as repository_base_conflict when repository authority has moved since.",
+ "properties": {
+ "context": {
+ "additionalProperties": false,
+ "properties": {
+ "repository_id": {
+ "type": "string"
+ },
+ "workspace_generation": {
+ "minimum": 0,
+ "type": "integer"
+ },
+ "workspace_head_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ },
+ "workspace_id": {
+ "type": "string"
+ },
+ "workspace_tree_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ }
+ },
+ "required": [
+ "repository_id",
+ "workspace_id",
+ "workspace_generation",
+ "workspace_head_hash",
+ "workspace_tree_hash"
+ ],
+ "type": "object"
+ },
+ "schema": {
+ "const": "kin.repository.base.v1"
+ }
+ },
+ "required": [
+ "schema",
+ "context"
+ ],
+ "type": "object"
+ },
+ "unit": {
+ "additionalProperties": false,
+ "description": "A source unit named by language identity, never by path. Go: package is the import path relative to the module root (\".\" or \"internal/store\"), name is the package clause, role is source or test (the package's _test unit). Kin derives the file and owns the package clause.",
+ "properties": {
+ "language": {
+ "const": "go"
+ },
+ "name": {
+ "pattern": "^[A-Za-z_][A-Za-z0-9_]*$",
+ "type": "string"
+ },
+ "package": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "role": {
+ "default": "source",
+ "enum": [
+ "source",
+ "test"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "language",
+ "package",
+ "name"
+ ],
+ "type": "object"
+ }
+ },
+ "required": [
+ "repository_base",
+ "unit"
+ ],
+ "type": "object"
+ }
+ },
+ "required": [
+ "UnitImports"
+ ],
+ "type": "object"
+ },
+ "target": {
+ "description": "The unit's package name.",
+ "minLength": 1,
+ "type": "string"
+ },
+ "verb": {
+ "enum": [
+ "update"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "verb",
+ "target",
+ "payload",
+ "description"
+ ],
+ "title": "UnitImports",
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "description": {
+ "type": "string"
+ },
+ "payload": {
+ "additionalProperties": false,
+ "properties": {
+ "EntityRemove": {
+ "additionalProperties": false,
+ "description": "Remove one source-bound top-level leaf function in Rust, Python or Go, preserving its artifact and siblings. No whole-file removal is admitted.",
+ "properties": {
+ "source_base": {
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "additionalProperties": false,
+ "properties": {
+ "artifact_id": {
+ "format": "uuid",
+ "type": "string"
+ },
+ "body_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ },
+ "context": {
+ "additionalProperties": false,
+ "properties": {
+ "repository_id": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "workspace_generation": {
+ "minimum": 0,
+ "type": "integer"
+ },
+ "workspace_head_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ },
+ "workspace_id": {
+ "format": "uuid",
+ "type": "string"
+ },
+ "workspace_tree_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ }
+ },
+ "required": [
+ "repository_id",
+ "workspace_id",
+ "workspace_generation",
+ "workspace_head_hash",
+ "workspace_tree_hash"
+ ],
+ "type": "object"
+ },
+ "end_byte": {
+ "minimum": 1,
+ "type": "integer"
+ },
+ "entity_id": {
+ "format": "uuid",
+ "type": "string"
+ },
+ "schema": {
+ "const": "kin.entity.source_base.v1"
+ },
+ "source_blob_hash": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ },
+ "start_byte": {
+ "minimum": 0,
+ "type": "integer"
+ }
+ },
+ "required": [
+ "schema",
+ "context",
+ "entity_id",
+ "artifact_id",
+ "source_blob_hash",
+ "start_byte",
+ "end_byte",
+ "body_hash"
+ ],
+ "title": "Exact entity source base v1",
+ "type": "object"
+ }
+ },
+ "required": [
+ "source_base"
+ ],
+ "type": "object"
+ }
+ },
+ "required": [
+ "EntityRemove"
+ ],
+ "type": "object"
+ },
+ "target": {
+ "description": "Exact source_base anchor/entity UUID.",
+ "format": "uuid",
+ "type": "string"
+ },
+ "verb": {
+ "enum": [
+ "remove"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "verb",
+ "target",
+ "payload",
+ "description"
+ ],
+ "title": "EntityRemove",
+ "type": "object"
+ }
+]Input schema / properties / session_id / descriptionPrevious value: -"Optional owning session UUID mirror; when present in enforce mode it must match the authenticated caller and transaction owner"New value: +"Owning session UUID."Input schema / properties / transaction_id / descriptionPrevious value: -"Transaction UUID"New value: +"UUID"lexical_lookuplist_file_entitiessemantic_locate8 fields changedInput schema / anyOfRemoved value: -[
- {
- "required": [
- "query"
- ]
- },
- {
- "required": [
- "cursor"
- ]
- }
-]Input schema / properties / cursor / descriptionPrevious value: -"Opaque token from a prior result's `next_cursor`. Pass it back unedited."New value: +"`next_cursor` from the prior page."Input schema / properties / granularity / descriptionPrevious value: -"Rank entities ('entity', default) or roll up to files ('file')"New value: +"Rank entities or files."Input schema / properties / granularity / enumPrevious value: -[
- "file",
- "entity"
-]New value: +[
+ "entity"
+]Input schema / properties / include_tests / descriptionPrevious value: -"Rank test-role entities alongside source. Off unless your query is about tests."New value: +"Rank test entities too."Input schema / properties / limit / descriptionPrevious value: -"Max ranked rows per page: entities, or files at file granularity. Default 20."New value: +"Rows per page."Input schema / properties / max_chars / descriptionPrevious value: -"Serialized characters this response may occupy; what was cut is named in `elisions`."New value: +"Soft cap on reply bytes."Input schema / properties / query / descriptionPrevious value: -"Natural-language description of the code to find. Optional when paging with `cursor`."New value: +"What the code does, in plain words."semantic_search5 fields changedInput schema / properties / kind / descriptionPrevious value: -"Entity kind filter (function, class, etc.)"New value: +"Kind; `command` finds CLI entry points."Input schema / properties / language / descriptionPrevious value: -"Language filter (rust, typescript, etc.)"New value: +"Language filter."Input schema / properties / limit / descriptionPrevious value: -"Max results to return"New value: +"Max rows."Input schema / properties / max_chars / descriptionPrevious value: -"Serialized characters this response may occupy; what was cut is named in `elisions`."New value: +"Soft cap on reply bytes."Input schema / properties / query / descriptionPrevious value: -"Name pattern to search for"New value: +"Name pattern."trace_data_flow12 fields changedInput schema / properties / compact / descriptionPrevious value: -"Alias for include_body: false. Ignored when include_body is given explicitly."New value: +"Alias for include_body: false."Input schema / properties / depth / descriptionPrevious value: -"Maximum traversal depth from the focal (default 3, capped at 8)"New value: +"Hops from the focal (max 8)."Input schema / properties / direction / descriptionPrevious value: -"Which way to walk: `calls` for callees, `callers` for callers, `both` merges."New value: +"`calls`, `callers` or `both`."Input schema / properties / focal / descriptionPrevious value: -"Focal entity UUID or exact entity name to start tracing from"New value: +"Start entity: UUID or name."Input schema / properties / include_body / descriptionPrevious value: -"Inline each step's source. False gives the chain's shape at a fraction of the size."New value: +"Inline sources; false gives the shape."Input schema / properties / limit_per_step / defaultPrevious value: -5New value: +12Input schema / properties / limit_per_step / descriptionPrevious value: -"Edges kept per hop. Raise it for a node `clipped_steps` reports as cut."New value: +"Edges kept per hop."Input schema / properties / max_chars / defaultPrevious value: -12000New value: +24576Input schema / properties / max_chars / descriptionPrevious value: -"Alias for max_response_chars, the spelling shared with the other retrieval tools."New value: +"Soft cap on reply bytes."Input schema / properties / max_response_chars / defaultPrevious value: -12000New value: +24576Input schema / properties / max_response_chars / descriptionPrevious value: -"Serialized characters this response may occupy; the same parameter as `max_chars`."New value: +"Same as `max_chars`."Input schema / properties / target / descriptionPrevious value: -"A symbol to reach, by exact name or UUID. Its branch survives the per-step cap first."New value: +"A symbol to reach; its branch is kept."trace_path8 fields changedInput schema / properties / direction / descriptionPrevious value: -"`forward`: from reaches to. `reverse`: the other way. `either` (default) tries both."New value: +"`forward`, `reverse` or `either`."Input schema / properties / from / descriptionPrevious value: -"Source end: entity UUID, exact name, or name@file to pin one of two same-named entities."New value: +"Start: UUID, exact name, or name@file."Input schema / properties / from_file / descriptionPrevious value: -"Pin `from` to the entity of that name in this file. Same as the name@file spelling."New value: +"Deprecated; pin with name@file."Input schema / properties / limit / descriptionPrevious value: -"Routes returned, shortest first (default 3, ceiling 25). See `routes_total`."New value: +"Routes returned, shortest first."Input schema / properties / max_chars / descriptionPrevious value: -"Serialized characters this response may occupy; what was cut is named in `elisions`."New value: +"Soft cap on reply bytes."Input schema / properties / max_depth / descriptionPrevious value: -"Hops between the two ends (default 6, ceiling 12). Containment hops are not counted."New value: +"Hops between the ends (max 12)."Input schema / properties / to / descriptionPrevious value: -"Target end, in the same forms."New value: +"End entity."Input schema / properties / to_file / descriptionPrevious value: -"Deprecated, answered through 0.7.16; pass the entity id in `to`. Pins `to` by file."New value: +"Deprecated; pin with name@file."v0.7.16find_referencesget_context_packget_entity_sourcegraph_neighborhoodimpact_analysiskin_artifact_listkin_artifact_readkin_graph_statuskin_mutatekin_provenance_querykin_session_endkin_session_heartbeatkin_session_startkin_transaction_abortkin_transaction_beginkin_transaction_commitkin_transaction_stagelist_file_entitiessemantic_locatesemantic_searchtrace_data_flowtrace_pathScored across 22 tools
Tools cover distinct retrieval modes (lexical, semantic by name vs. meaning, trace flow vs. path, references vs. neighborhood) and descriptions explicitly cross-reference to guide selection. Some overlap remains among graph query tools and between kin_mutate and transaction staging, but boundaries are mostly clear.
All names are snake_case, but prefixes and patterns are mixed: kin_* appears on session/transaction/init/mutate/status/provenance tools, while query tools use bare verb_noun or noun_noun forms. The set is readable but not fully consistent.
22 tools is borderline heavy for a code-graph server. The scope spans read queries, write/session/transaction plumbing, provenance, init, and execution, so most tools earn their place, but the count is on the high side.
The surface covers graph querying, entity mutation with transaction support, sessions, provenance, initialization, execution, and direct source retrieval. Minor gaps like bulk entity listing or file-level operations exist, but core lifecycle appears complete.
Codebase intelligence for AI agents — dead code, blast radius, ownership.
Codebase graphs, caller impact analysis, and recorded project context for AI coding agents.
Code intelligence platform for AI agents. 20 tools for architecture, security & impact analysis.
Persistent knowledge graph for AI-augmented teams. Store decisions, findings, and standing rules across agent sessions with semantic search and typed connections. Includes cross-session memory, audit trail, workspace isolation, and secret detection. Built for teams running agents that need to remember. Free until launch with team tier as default, anon trial available.
