Tools your AI agent can use.

Which tool to reach for

Start with semantic_locate to find something by meaning, get_context_pack for a bundle around an entity or a question, and find_references for recorded references. Every response carries a freshness and coverage envelope, so read that before acting on an absence: a tool that found nothing and a graph that has not finished answer in the same shape.

The tools

• find_references

  Find who depends on one entity: direct callers, importers and references, one row each with id, name, kind, file and the lines it references from. Call it for one hop. For a whole chain, use trace_data_flow.

  View inputs for find_references

  arguments: entity_id, max_chars, query, relation_kinds

• get_context_pack

  Assemble a token-bounded bundle from one entity, several entities, or a plain-language question: focal bodies plus dependency signatures and connecting routes. Call it instead of several get_entity_source and traversal reads.

  View inputs for get_context_pack

  arguments: depth, entities, entity_id, max_chars, question, token_budget

• get_entity_source

  Return one entity's exact graph-owned body by id. Call it when you hold an id and need the real source text, not a snippet.

  View inputs for get_entity_source

  arguments: entity_id | required: entity_id

• graph_neighborhood

  Get what one entity depends on and what depends on it, to a depth you choose, as summaries with ids. Call it to orient in unfamiliar code. Use find_references for callers only, trace_data_flow for an ordered path.

  View inputs for graph_neighborhood

  arguments: depth, direction, entity_id, limit, max_chars | required: entity_id

• impact_analysis

  Walk the graph from a change to every entity it could affect. Target it one way at a time: entity_ids, file paths, base and head change ids, or change_ids. Call it before editing, across the whole repository.

  View inputs for impact_analysis

  arguments: base, change_ids, entity_ids, files, head, max_chars

• kin_artifact_list

  List the repository's tracked files at one semantic change, code and non-code alike: Dockerfiles, lockfiles, configuration, assets, symlinks. Call it for what the repository contains, not what the parsers turned into entities.

  View inputs for kin_artifact_list

  arguments: limit, offset, source_change_id

• kin_artifact_read

  Read one tracked file's exact bytes by artifact_id or repo-relative path, as base64 and, when valid UTF-8, as text. Call it for a file the parsers made no entities for, which a locate hit's artifact_path means.

  View inputs for kin_artifact_read

  arguments: artifact_id, path, source_change_id

• kin_graph_status

  The graph this call is answered from: entity and relation counts, and how many are embedded, pending or unindexed. Call it when a search returns less than you expect. `sampling=last_settled_selected_graph` means the last settled reading, aged in `stale`.

• kin_provenance_query

  Answer who changed an entity and whether it was approved: change count, latest change, approvals on it, a page of changes newest first, and recent audit events. Call it before relying on code whose history matters.

  View inputs for kin_provenance_query

  arguments: entity_id, limit | required: entity_id

• kin_session_end

  Close this session and release what it holds. Call it when your work is done.

  View inputs for kin_session_end

  arguments: session_id | required: session_id

• kin_session_heartbeat

  Keep this session alive. Call it periodically during long work so the session does not lapse at its idle TTL.

  View inputs for kin_session_heartbeat

  arguments: session_id | required: session_id

• kin_session_start

  Register this agent with Kin and get a session_id: who you are, your transport, working directory and capabilities. Call it once at the start of your work, before any transaction, so activity is attributed.

  View inputs for kin_session_start

  arguments: capabilities, client_name, cwd, pid, transport, vendor | required: vendor, client_name, cwd

• kin_transaction_abort

  Abandon an open transaction and discard everything staged on it. Call it when you decide against a change, or to start clean after a refusal. Refused once kin_transaction_commit has fenced it.

  View inputs for kin_transaction_abort

  arguments: session_id, transaction_id | required: transaction_id

• kin_transaction_begin

  Open a transaction to stage mutations onto. Returns a transaction_id; nothing lands until kin_transaction_commit.

  View inputs for kin_transaction_begin

  arguments: scope, session_id | required: session_id, scope

• kin_transaction_commit

  Publish every staged mutation atomically: the daemon reparses the final bytes and journals the semantic change, the workspace tree and the ref together. All of it lands or none does. Re-sending a fenced commit is safe.

  View inputs for kin_transaction_commit

  arguments: operations, session_id, transaction_id | required: transaction_id

• kin_transaction_stage

  Stage mutations onto an open transaction. Four verbs: 'create' admits a file the graph has never seen, 'update' changes an entity, 'delete' retires one, 'rename' moves one. An 'update' replaces the whole body; read it first with get_entity_source.

  View inputs for kin_transaction_stage

  arguments: operations, session_id, transaction_id | required: transaction_id, operations

• list_file_entities

  List every entity the graph holds for one file, by repo-relative path. The only retrieval tool that says what it left out: it returns the whole set and reports whether it is complete. Call it before concluding a file holds nothing.

  View inputs for list_file_entities

  arguments: cursor, page_size, path

• semantic_locate

  Find code by a plain-language question, ranked from the graph. Call it when you know what the code does but not its name. Returns id, name, kind, file, line, signature, score. Read `ranked_by`. Know the exact name? Use semantic_search.

  View inputs for semantic_locate

  arguments: cursor, granularity, include_tests, limit, max_chars, query

• semantic_search

  Filter declarations by name, kind or language: functions, methods, classes, structs, traits, enums, types, constants. Call it when you know what the thing is called. It matches names, not meaning. For a description, use semantic_locate.

  View inputs for semantic_search

  arguments: kind, language, limit, max_chars, query | required: query

• trace_data_flow

  Walk the call chain out from ONE entity and get the whole path back, as ordered steps. Give a focal, a direction and a depth. It walks call and import edges, not values through variables. Naming TWO things? Use trace_path.

  View inputs for trace_data_flow

  arguments: compact, depth, direction, focal, include_body, limit_per_step, max_chars, max_response_chars, target | required: focal

• trace_path

  Find how one entity reaches another, as ordered hops. Call it when your question names TWO things. `from` and `to` take a name, an id, or name@file. Read `found` and `gap` before concluding A never reaches B. One endpoint? Use trace_data_flow.

  View inputs for trace_path

  arguments: direction, from, from_file, limit, max_chars, max_depth, to, to_file | required: from, to