> ## Documentation Index
> Fetch the complete documentation index at: https://docs.platform.nora.my/llms.txt
> Use this file to discover all available pages before exploring further.

# Which lever to tune

> Prompt, tool, retrieval, memory, rules — which change makes sense for this failure?

Every improvement targets one lever — a specific part of the system. Picking the right lever matters: the wrong one wastes effort and often introduces regressions.

## The levers

### 1. Prompt

Change the Agent's role or system prompt. Effective for:

* Missing behaviors ("always cite sources").
* Wrong tone or format.
* Handling of edge cases the current prompt doesn't mention.

Fast to test, cheap to iterate. Risk: rewording too much causes drift in other behaviors.

### 2. Tool description

Refine what tools promise. Effective when:

* Agent picks the wrong tool.
* Agent picks the right tool with wrong arguments.
* Agent doesn't call a tool it should.

Very effective per unit of effort — the LLM decides tool use from the description.

### 3. Tool implementation

Change what a tool actually does or how it returns data. Effective when:

* Tool response is misleading (returns success on partial data).
* Tool doesn't include a field the Agent needs.
* Tool is too permissive (allows an operation that should be gated).

Slower to iterate (code change) but sometimes unavoidable.

### 4. Retrieval preset

Change the retrieval config (weights, filters, top-K, boosts). Effective when:

* Right chunks are indexed but not retrieved.
* Chunks retrieved but in wrong order.
* Too many low-relevance chunks flooding context.

### 5. Data source

Add, tag, supersede, or restructure knowledge. Effective when:

* The answer isn't in the knowledge at all (add).
* The answer is there but outdated (supersede).
* The answer is there but wrongly tagged (retag).

Doesn't require touching the Flow — pure data change.

### 6. Memory rules

Add a procedural rule. Effective when:

* The Agent needs a standing behavior ("always X before Y").
* A specific correction should apply to all future runs.

Fast to add, easy to remove, doesn't require publishing (rules take effect immediately).

### 7. Causal graph

Add/adjust an edge or variable. Effective when:

* Verification is misfiring (graph is wrong).
* Verification isn't catching real errors (graph is missing edges).

### 8. Routing

Add a Router to send different intents to different Agents. Effective when:

* A single Agent tries to do too many things and does none well.
* Cost profile differs sharply by intent (route cheap intents to cheap model).

Restructures the Flow, so simulation is essential.

### 9. Guardrail / approval

Add a guardrail or approval gate for a specific action. Effective when:

* The Agent is making decisions that should have human review.
* Certain outputs need to be blocked outright.

Doesn't fix quality — it prevents damage while quality improves.

### 10. Model swap

Change the model used by an Agent (or use a fallback). Effective when:

* Consistent failures indicate the model can't handle the domain.
* Cost/quality tradeoffs point to a different model on the Pareto frontier.

Biggest lever, biggest cost/latency impact. Simulate extensively.

## Nora's lever choice

For each root cause category, Nora prefers certain levers:

* **Retrieval issue** → retrieval preset > data source > prompt.
* **Prompt issue** → prompt > memory rule > tool description.
* **Tool issue** → tool description > tool implementation > prompt.
* **Data issue** → data source (add/tag/supersede) > nothing else fixes it.
* **Memory issue** → memory rule > scope config > new memory space.
* **Grounding issue** → causal graph > data source.
* **Model issue** → model swap > prompt tightening.

Ordering reflects "cheapest to try first that plausibly addresses this class."

## Manual lever choice

You can override Nora's default. **Proposals → Change lever** — pick a different lever and Nora regenerates proposals targeting that lever.

Useful when you know your domain better than the auto-diagnosis. E.g., Nora suggests a retrieval fix but you know a rule would be simpler.

## When multiple levers apply

Complex clusters have multiple root causes and multiple sensible levers. Nora generates proposals per lever and lets you pick which combination to ship (usually one is enough — over-fixing invites regressions).

If you ship two levers at once, simulation is essential to isolate which one actually helped.