Tools
The evidence tools search, read, and cite your documents. The task and decision tools record and read an agent's work. The built-in agent and the MCP server expose both groups under the names below, and Python exposes the evidence operations as functions in agrag.evidence.
Tool names
The Python functions, the built-in agent, and the MCP server use the same name for each tool. The methods of TaskMemory and DecisionMemory have the names of the task and decision tools. A parameter has the same name on every surface, except where the agent or the server supplies the value itself.
Evidence tools
| Operation | Python function | Tool name |
|---|---|---|
| Passage search | search_evidence | search_evidence |
| Fetch exact text | fetch_evidence | fetch_evidence |
| Document tree navigation | navigate_document_tree | navigate_document_tree |
| Entity search | entity_search | entity_search |
| Relationship exploration | explore_relationships | explore_relationships |
| Citation check | check_citations | check_citations |
| Numbered references | render_citations | none. The agent formats its own answer, and fetch_evidence on the MCP server returns citation_markdown. |
| Source status | source_status | none |
Task and decision tools
| Operation | Tool name | Offered by |
|---|---|---|
| Read a task | get_task | Agent and MCP server |
| List task events | list_events | Agent and MCP server |
| Read one event | fetch_event | Agent and MCP server |
| List task steps | list_steps | Agent and MCP server |
| Search decisions | search_decisions | Agent and MCP server |
| List conflicting decisions | list_conflicts | MCP server only |
| Read a decision | get_decision | Agent and MCP server |
| List a decision's support history | list_support_history | Agent and MCP server |
| List a task's decisions | list_decisions | Agent and MCP server |
| List decisions that need review | list_decisions_for_review | Agent and MCP server |
| Create a task | create_task | MCP server only. A run creates its task. |
| Record an event | record_event | MCP server only. The run records events. |
| Set a step | set_step | Agent and MCP server |
| Record a decision | record_decision | Agent and MCP server |
| Supersede a decision | supersede_decision | Agent and MCP server |
| Reaffirm a decision | reaffirm_decision | Agent and MCP server |
| Continue review propagation | continue_decision_review | Agent and MCP server |
| Reject a decision | reject_decision | MCP server only. The agent cannot reject a human decision. |
The agent works on one task in one project, and the caller fixes both. Its task tools therefore take no task_name, and its write tools take no request_id. On the MCP server, fetch_evidence takes max_chars, and set_step takes result_event_seq, the sequence number of an event that the client recorded. The agent passes result, the text of the result, to set_step and the run records the event.
Settings that turn tools on
| Tool group | Built-in agent | MCP server |
|---|---|---|
| Evidence tools | On. The scope argument of build_agent sets the readable documents. | On. MCP_SCOPE_DOCUMENT_KEYS sets the readable documents. |
| Task and decision read tools | On. build_agent sets the project and the agent. | On when both MCP_PROJECT_ID and MCP_AGENT_ID are set. |
| Task and decision write tools | On. | On when the read conditions hold and MCP_READ_ONLY is false. |
reject_decision | Not offered. | On when the write conditions hold and MCP_ALLOW_REJECT is true. |
The MCP server starts read-only. It refuses to start when write access is on and the project or the agent is missing. A tool call cannot widen the document scope or change the project.
Evidence tools
Every evidence tool applies the document scope inside its queries. Retrieval lists the rules that all of them share.
Passage search
Searches the text of current document versions in scope and returns ranked passages with evidence ids. Passage search describes the modes and the result.
| Parameter | Type | Default | Range and notes |
|---|---|---|---|
query | string | required | Plain words. Query syntax has no effect. |
mode | lexical, semantic, or hybrid | hybrid | hybrid runs both searches and fuses them. |
limit | integer | agent 8, MCP MCP_MAX_HITS | Agent 1 to 50. MCP at least 1, capped at MCP_MAX_HITS. Python any positive integer. |
Returns an EvidenceSearchResult with status, hits, truncated, index_state, and failures. A hit has evidence_id, document_key, title, content_hash, location, snippet, score, and legs.
Fetch
Returns the exact stored text for evidence ids. Only a complete fetch makes an id citable. Fetch evidence describes the outcome and the statuses.
| Parameter | Type | Default | Range and notes |
|---|---|---|---|
evidence_ids | list of strings | required | At most 20 ids per call on the agent. On MCP, at most MCP_MAX_FETCH_IDS, default 20. |
max_chars | integer | agent max_result_characters, MCP MCP_MAX_FETCH_CHARS | The agent setting defaults to 12000. MCP accepts the argument and caps it at MCP_MAX_FETCH_CHARS, default 4000. Python requires the argument. |
Returns one outcome for each id, in order. An outcome has status, text, title, uri, location, content_hash, status_of_version, partial, and citation_markdown.
Document tree navigation
Returns passages near a known passage, in the same document version. Document tree navigation describes the six relations.
| Parameter | Type | Default | Range and notes |
|---|---|---|---|
evidence_id | string | required | A chunk id or a span id. |
relation | parent, children, siblings, previous, next, or table_context | required | |
limit | integer | 10 | 1 to 50. The agent caps larger values at 50. |
max_chars | integer | 12000 | 1 to 20000. The agent caps larger values at 20000. |
Returns a NavigationResult with status, items, truncated, truncation_reason, version_status, and multi_section.
Entity search
Finds entities by name or meaning, each with up to three mentioning passages. Entity search describes the search and the result.
| Parameter | Type | Default | Range and notes |
|---|---|---|---|
query | string | required | MCP accepts 1 to 1000 characters. |
labels | list of strings | all entity labels | MCP accepts up to 20 labels. |
mode | lexical, semantic, or hybrid | hybrid | As in passage search. |
limit | integer | 10 | 1 to 50. MCP also caps it at MCP_MAX_HITS. |
Python adds support_limit, the most passages listed for each entity, with a default of 3. Returns an EntityResult with status, hits, truncated, index_state, and failures. A hit has entity_id, label, name, properties, kind, score, legs, and support.
Relationship exploration
Follows the relations around one entity. Explore relationships describes assertions, paths, and bounds.
| Parameter | Type | Default | Range and notes |
|---|---|---|---|
entity_id | string | required | A canonical lowercase UUID from entity_search. |
depth | integer | 1 | 1 or 2. |
relation_types | list of strings | all schema relation types | MCP accepts up to 20 types. |
max_nodes | integer | 25 | 1 to 200. |
max_edges | integer | 50 | 1 to 200. |
Returns an ExplorationResult with status, nodes, edges, truncated, truncated_by, and detail. An edge has source_id, target_id, relation_type, kind, and evidence.
Citation check
Checks that cited evidence ids trace to text fetched in scope. Check citations describes the verdicts.
| Parameter | Type | Default | Range and notes |
|---|---|---|---|
evidence_ids | list of strings | required | The MCP server accepts at most MCP_MAX_FETCH_IDS ids. |
Python takes the cited ids, the fetched ids, and the scope. It returns one verdict for each cited id. On MCP the check compares against the ids this server session fetched.
Task and decision tools
The task and decision tools act on the configured project, and the document scope does not apply to them. Record decisions and review them describes the workflow, and Agent loop describes how the built-in agent uses them.
Read tools
| Tool | Returns | Use it when |
|---|---|---|
get_task | The bounded resume view of a task, without event bodies. | You resume a task or need its goal and progress. |
list_events | One bounded page of a task's events after a sequence number. | You need the order of messages, tool calls, and results. |
fetch_event | One event by task name and sequence number. | You need the full body of one event. |
list_steps | One bounded page of steps in a given state, with a cursor. | You need the completed, in-progress, or failed steps. |
search_decisions | Current decisions in the project that can serve as precedents. The agent version leaves out decisions that need review or have non-current supports. | A choice may already be covered by an earlier decision. |
list_conflicts | Active decisions of the same choice that reached different conclusions. MCP only. | You look for disagreement across tasks. |
get_decision | One decision with its typed supports. | You need one decision in full. |
list_support_history | One page of a decision's original and refreshed supports. | You need to see why a decision was flagged. |
list_decisions | A task's decisions, including superseded history. | You review everything a task decided. |
list_decisions_for_review | Decisions flagged for review. The MCP tool can limit the list to one task. | A source changed and you need the decisions that depend on it. |
Write tools
| Tool | Effect | Use it when |
|---|---|---|
create_task | Creates a task, or returns the existing record. A name with another goal returns task_exists. MCP only. | A client starts work it wants to resume later. |
record_event | Appends a bounded raw event. MCP only. | A client keeps its own log in the task. |
set_step | Creates or updates a named step. A completed step needs result text. | You mark progress that a later run can reuse. |
record_decision | Records a decision with explicit support references. The same run or session must have fetched document evidence. | A conclusion matters beyond the current answer. |
supersede_decision | Replaces a decision with a new conclusion and keeps the history. | New evidence changes a conclusion. |
reaffirm_decision | Reaffirms an active decision using current fetched document evidence. | A flagged decision still holds after you read the current text. |
continue_decision_review | Advances queued review propagation by a bounded amount. The MCP tool takes limit from 1 to 100, default 20. | Review flags are still reaching dependent decisions. |
reject_decision | Rejects a decision and keeps the history. The MCP server offers it only when MCP_ALLOW_REJECT is true. | A human reviewer overturns a decision. |
The request-based MCP writes take a request_id, and a retry with the same id returns the saved result. The agent cannot rely on a decision marked needs_review or unknown.
Other limits
| Limit | Built-in agent | MCP server |
|---|---|---|
| Preview length of a hit | 240 characters | MCP_MAX_SNIPPET_CHARS, default 240 |
| Size of one result | none | MCP_MAX_RESPONSE_CHARS, default 60000 |
| Time for each store read | none | MCP_REQUEST_DEADLINE_SECONDS, default 30 |
| Tool calls in one run | max_tool_calls, default 20 | none |
| Steps in one run | recursion_limit, default 50 | none |
An MCP result sets truncated when it left items out. Agent loop describes the agent settings, and the configuration reference lists the MCP variables.