{% extends "base.html" %} {% block title %}Prompt System & Tool Injection — Maxim Docs{% endblock %} {% block meta_description %}How Maxim's LLM agent sees the world: prompt assembly, priority-based section dropping, scene-scoped tools, and NAc-driven tool learning.{% endblock %} {% block meta_keywords %}Maxim prompt system, prompt builder, tool injection, scene-scoped tools, LLM context, NAc tool learning, FearAgent, autonomy policy, agentic robotics{% endblock %} {% block meta_author %}Maxim Project{% endblock %} {% block og_site_name %}Maxim{% endblock %} {% block og_type %}article{% endblock %} {% block structured_data %}
{% endblock %} {% block content %}
← Back to Overview

How the LLM sees the world: prompt construction, tool discovery, and the learning feedback loop.

## Prompt Assembly Chain

The agent's system prompt is assembled by `prompt_builder.py` with sections at different priority levels. When the token budget is tight, lower-priority sections are dropped. This means the LLM's context varies based on conversation length.

MANDATORY

### Always Present

- instructions — Response format rules (JSON action schema)
- user_request — The triggering input/percept text

CRITICAL

### Almost Never Dropped

- identity — "You are Maxim, a robot assistant" + operational state + simulation/interactive instructions
- tools — Full available tools list with descriptions, params, and examples
- acting_coach — Affordance exploration meta-prompting (B3, embodiment only)

IMPORTANT

### Dropped Under Pressure

- entity_context — SEM entity capabilities: affordance descriptions + failure triggers (E2, embodiment only)
- tool_guidance — Parameter examples + selection guidance
- datetime — Current date/time
- conversation — Conversation history
- context_pool — Memory agent context (recalled episodes, causal links)
- foundational — Constitution + agent behavioral rules

NICE TO HAVE

### Frequently Dropped

- mode_context — "ACTIVE MODE" instructions (filesystem permissions, cognitive tools)
- observation, speech, agent_states — Environmental context
- memory sections — Extended memory summaries

Key insight: The mode_context section (which explains filesystem rules, cognitive tools, and behavioral guidelines) is at NICE_TO_HAVE priority and is frequently dropped. The agent often operates with just identity + tools + foundational rules.

## Identity Section

The identity section (`build_identity_section()`) is at CRITICAL priority and always present. It contains:

You are Maxim, a robot assistant. === OPERATIONAL STATE === Mode: ACTIVE Mode goal: Execute tasks and take actions within defined boundaries Autonomy level: autonomous Processing state: AWAKE SIMULATION ENVIRONMENT: You are in a controlled simulation for testing and evaluation. Scenarios presented to you are simulated... INTERACTIVE MODE: A human user is present and watching. You can and should ask them questions using request_interaction...

The SIMULATION ENVIRONMENT block appears when `_sim_active` is True. The INTERACTIVE MODE block appears when `InteractiveMode.ON`. Both are in the identity section so they're never budget-dropped.

## Tool Injection Chain

build_tool_registry() Always-registered: filesystem, display, response | _inject_pending_tools() User tools from @maxim.tool / register_tool() | Introspection tools memory_recall, causal_links, pain_history, etc. | Narrative tools say, think, examine (sim-only) | Robot tools DEREGISTERED focus_interests, track_target, move (no live robot) | Scene-scoped activation (0.7+) register_scene_tools / deactivate_scene / activate_scene | Cap: 20 active scene tools (core tools exempt) | Auto-evicts oldest scene on overflow | Mode filtering active mode: all tools visible (no filter) | registry.list() Returns ACTIVE tools only (deactivated scene tools excluded) | Prompt builder TOOL_DESCRIPTIONS dict OR dynamic Tool.description | === Available Tools === What the LLM actually sees in the prompt - respond: Answer questions... - request_interaction: Ask the user... - memory_recall: Search episodic memory... | LLM generates action JSON {"tool_name": "respond", "params": {"message": "..."}} | Autonomy policy Execution-level gate (allowed_tools whitelist) | FearAgent review Independent safety gate (action content, not beliefs) | Tool.execute() Runs the tool, returns ToolOutput

## Tool Description Sources

Source | Priority | When Used
--- | --- | ---
`TOOL_DESCRIPTIONS` dict modes/definitions.py | Primary | All built-in tools. Contains description, params, example, followup_type.
`Tool.description` + `Tool.input_schema` tools/base.py | Fallback | User-registered tools, SEM affordance tools, anything not in TOOL_DESCRIPTIONS.

Tip: If a tool is registered but the LLM never calls it, check whether it has an entry in `TOOL_DESCRIPTIONS`. The fallback description from the Tool class is often too terse for the LLM to understand when to use it.

## Tool Learning Feedback Loop

The agent learns which tools work through the NAc causal learning system:

Mechanism | What It Does | Where
--- | --- | ---
Direct attribution | Records tool outcomes to NAc: `(context, tool) → success/pain` | ToolPainBridge
Causal links in prompt | LLM sees learned tool-outcome associations in context_pool | prompt_builder.py
Recent outcomes | Last N tool results shown in prompt for immediate context | agent_loop.py
Relevance filter | Learned index trims tool manifest to relevant subset (passive mode only) | LearnedToolIndex

Tool learning is indirect — NAc learns outcome associations that appear in the prompt as context, but the LLM still sees the full tool manifest. Learning influences when to call a tool, not whether it appears.

## Simulation vs Live: Tool Differences

Tool Category | AUT (Agent Under Test) | Orchestrator
--- | --- | ---
Filesystem (read, write, bash) | Yes (sandboxed) | No
Sim tools (send_message, observe_actions) | No | Yes
Introspection (memory_recall, causal_links) | Yes | No
Interactive (request_interaction, set_scene) | Yes | No
Robot (move, track_target) | Deregistered | Not added
Response (respond, speak) | Yes | sim_respond only

## Adding a New Tool

1. Create a `Tool` subclass in `src/maxim/tools/` with `name`, `description`, `input_schema`, and `execute()`
2. Register in `build_tool_registry()` (`runtime/bootstrap.py`)
3. Add to `TOOL_DESCRIPTIONS` (`modes/definitions.py`) with description, params, example, and followup_type
4. Add to the AUT's `allowed_tools` whitelist (`simulation/orchestrator.py`) if it should be usable in simulation
5. If it uses JSON Schema `input_schema`, verify `_validate_input()` handles it (tools/base.py detects both formats)
6. (0.7+) Scene-scoped tools: For tools tied to an entity/scene, use `registry.register_scene_tools(tools, scene_id="...")` instead of `register()`. Scene tools are deactivated on scene transition (not deleted) and can be re-activated. The executor gates on active status — deactivated tools return a descriptive error.

Common pitfall: A tool can be registered and allowed but the LLM never calls it because:

- No entry in `TOOL_DESCRIPTIONS` (fallback description too terse)
- System prompt context discourages it (e.g., "autonomous" mode + "ask user" tool)
- JSON Schema `input_schema` causes silent validation failure in `_validate_input()`

## Files Reference

File | Role
--- | ---
`agents/prompt_builder.py` | Section assembly + budget management
`agents/llm_worker.py` | Delegates to prompt builder, submits to LLM
`modes/definitions.py` | Mode definitions + TOOL_DESCRIPTIONS dict
`runtime/bootstrap.py` | build_tool_registry() — canonical tool registration
`runtime/autonomy.py` | Execution-level tool gating (not prompt-level)
`simulation/orchestrator.py` | AUT vs orchestrator tool registry setup
`tools/base.py` | Tool base class + _validate_input (JSON Schema support)
`api.py` | register_tool() / @maxim.tool dynamic registration

← Previous Tools & Introspection Next → Operating Modes

### All Chapters

Overview The Agent Brain Memory Systems Semantic Memory Concept Decomposition Math & Statistics Attention & Salience Body Awareness Embodiment Imagination Component Library Communication Usage Guide Technical Deep Dive Tools & Introspection Prompt System Operating Modes Networking Agent Mesh Simulation DM Campaigns Benchmarks Experiments Roadmap
{% include "_maxim_footer.html" %}
{% endblock %}