| name | operational-guardrails |
| description | Shared operational contract for all MedSci agents: sequential execution, planning phase, retry limits, evidence standards. |
Operational Guardrails
These rules apply to every MedSci agent session. They override any conflicting behavior.
1. Planning Phase (Before Any Tool Call)
Before your first tool call, produce a brief plan:
- Classify the task type (lookup, analysis, synthesis, code execution).
- Identify which toolchains are needed and in what order.
- List data dependencies between steps.
- State stop conditions — what constitutes "done" and what would trigger an abort.
- Estimate evidence depth — is one tool call enough, or is multi-step synthesis required?
Only then begin executing. If the plan changes mid-task, state the revised plan before the next tool call.
2. Sequential Execution (No Exceptions)
Execute all MCP tool calls one at a time. Wait for each result before calling the next tool.
Why: MedGemma and TxGemma run locally inside MCP tools. Parallel calls queue on the same local model, causing MCP timeouts (error -32001).
Prohibited language in plans: Never write "I can run these in parallel", "these steps are independent", "simultaneously", or "at the same time" for tool calls. Every step executes sequentially — perceived independence is irrelevant. Write your plan as a numbered sequence and execute step 1 immediately after the plan.
3. Retry and Stop Policy
- Per-tool retry limit: 1 retry on transient failure (timeout, rate limit). If it fails twice, skip it.
- Session retry limit: No more than 3 total retries across all tools in one session.
- Continue with partial data when a non-critical tool fails. Note the gap explicitly.
- Halt and ask the user when a critical-path tool fails twice (e.g., the only data source for the query).
- Never retry on permanent errors:
CLI_UNAVAILABLE, ARTIFACT_PATH_FORBIDDEN, MODEL_NOT_FOUND.
4. Model Interpretation Fallback
When a tool returns model_used: false (MedGemma/TxGemma unavailable):
- Return the raw data — it still has value.
- Provide your own interpretation clearly labeled as "LLM interpretation (not domain model)."
- Do not silently omit the raw data in favor of your interpretation.
5. Sandbox Execution Truth
sandbox_run_job exit code is the source of truth for execution outcome.sandbox_status is advisory — it reflects container state, not job state. Allow 1–2s retry/backoff before concluding a sandbox is missing or stopped.- Default interpreter for inline scripts:
python3 (not python).
- Default network policy:
deny. Only allow hosts when the task explicitly requires network access.
6. Evidence and Confidence Standards
- Ground every claim in retrieved data. If a claim cannot be traced to a tool result, flag it as inference.
- State confidence for each finding: high (direct data support), medium (indirect/partial data), low (inference or limited data).
- State limitations for every analysis: what data was unavailable, what tools were skipped, what assumptions were made.
- Use hedged language for scientific findings: "consistent with," "suggests," "associated with" — never "proves" or "confirms."
- Never provide: definitive medical diagnoses, treatment recommendations as clinical advice, or absolute certainty about scientific findings.
