Decision Architecture

The qualitative leap: from Python routing on model output to the model picking what happens next. This changes everything about how agents behave.

The before and after

Traditional agent design: the model produces text, Python reads it, a router function calls the next node. The model is a component. The routing is code. In this architecture, the model is the router. It reads tool docstrings and decides. No if-statements. No hard-coded paths. The model owns the decision.

Old Architecture

Python Routes on Model Output

Model generates text. Python function parses it. If "search" in text → route to search node. If "stop" in text → route to stop node. The model suggests; Python decides. The model can't change the menu. The routing logic lives in code, frozen at deploy time.

New Architecture

Model Picks What Happens Next

The model receives tool definitions with docstrings. It reads them. It picks one. The chosen tool IS the next action. No parsing. No routing function. The model's output directly determines execution. Add a tool to the menu and the model can use it immediately.

The choose_next_action Node

This is where the architecture shift happens. The model receives a menu and decides.

Analysis completes

The agent has finished classifying the article, recalling past briefs, and producing the BriefResult. It now holds a complete understanding of the article.

The tool menu is presented

The model receives a list of available tools. Each tool has a name, a description, and — critically — a docstring that explains when to use it and when not to use it.

The model reads the docstrings

This is the key interaction. The model doesn't just see tool names. It reads the full description of what each tool does, when it's appropriate, and what edge cases to watch for. The docstrings ARE the prompt.

The model chooses

Based on the article analysis and the tool descriptions, the model selects one tool. It also provides a rationale — a human-readable explanation of why it chose this tool. This rationale becomes part of the audit trail.

Execution follows the choice

Python executes whatever the model chose. If search_web → the web search node runs. If stop_here → the run ends. No if-else. No routing logic. The model's choice is the control flow.

The Tool Menu

Two tools. Both first-class. Both documented. The model reads both before choosing.

Available tools → choose_next_action

search_web

Search the web for external sources to verify or contextualize claims from the article. Use when: the article makes empirical claims that need corroboration, the article is opinion-heavy and needs grounding, or the author's claims seem questionable. Do not use: for well-established practitioner viewpoints, when the article itself is the primary source, or when the search results would likely surface the article itself or generic discourse.

stop_here

Stop the pipeline. The analysis is sufficient as-is. Use when: the article's claims are self-contained, the thesis is a well-established viewpoint, the article is the primary source for its own claims, or additional search would add no marginal value. This is a first-class choice, not a fallback.

The action bias problem: Early versions of the agent almost always chose search_web — even when the article was the primary source for its own claims. The model defaulted to "do something." The fix wasn't a routing rule. It was better docstrings. When stop_here was documented as a first-class choice with clear "use when" criteria, the model started choosing it appropriately. The docstrings ARE the design.

Real Decision from the Trace

search_web path

The agent could have searched the web to verify IBM's claims about enterprise readiness. It didn't. The article is its own primary source — IBM's own analysis. Searching would surface the article itself or generic AI hype commentary.

→ stop_here (CHOSEN) ←

The agent chose to stop. The thesis — AI agents are overhyped, enterprises aren't ready — is a well-established practitioner viewpoint captured fully in the brief.

Rationale: "Although the article is classified as analysis with a critic stance rather than pure opinion, the reading_depth is skim and the core thesis is a well-established practitioner viewpoint that the brief already captures fully. The key insight about enterprise readiness (APIs, data, governance) being the real bottleneck is the article's own framing, not an empirical claim requiring external corroboration."

Why this matters for agent design

When the model chooses, you design tools differently. Every tool needs a clear contract. Every docstring is a prompt. Add a tool and the model can use it tomorrow. Remove a tool and the model adapts. The architecture is extensible by documentation, not by code changes to a routing function. That's the qualitative leap.