Agent Constraint Triangle Scorer

Agent Constraint Triangle Scorer

Overview

Ch1 names a fundamental challenge in building agents: the agent constraint triangle, "three interconnected constraints that create an inherently difficult operational problem":

1. Complexity management — multistep planning and reasoning. "As tasks

require more steps and deeper analysis, cognitive load increases exponentially," producing "compounding errors as the step count increases."

1. Tool orchestration — translating natural language into precisely

structured API calls. The named failure mode is "bloated tool sets that cover too much functionality or lead to ambiguous decision points about which tool to use." Anthropic's principle: "If a human engineer can't definitively say which tool should be used in a given situation, an AI agent can't be expected to do better."

1. Context utilization — organizing a fixed context window, "the model's

attention budget." Chroma's needle-in-a-haystack research names context rot: "as the number of tokens in the context window increases, the model's ability to accurately recall information from that context decreases" — "a performance gradient," not "a hard cliff."

The chapter's key point is that these "don't exist in isolation but form a system of competing trade-offs. When improving performance along one dimension, you typically create additional pressure on the others." It names three cyclic pressures:

• complexity → tools → context
• tools → context → complexity
• context → complexity → tools

The governing principle: "the smallest possible set of high-signal tokens that maximizes the likelihood of some desired outcome" — minimal-but-sufficient complexity decomposition, minimal-but-complete tool coverage, and minimal-but-adequate context retention.

This skill scores a configuration against that triangle. The scoring curves are transparent heuristics that embody the chapter's qualitative claims (exponential complexity load, ambiguity-dominated tool pressure, context-rot gradient); they are not chapter-cited benchmarks, and the production seam is documented at each lib function.

When to Use

• Deciding whether to add tools, lengthen reasoning chains, or grow context on

an existing agent — and wanting to see which corner breaks first

• Diagnosing an agent that degrades as you scale it up
• Comparing two agent configurations (batch mode) to pick the less constrained
• Teaching why "add more tools / more steps / more context" is not free

Phrases: "which constraint will break", "is my agent overloaded", "constraint triangle", "too many tools", "context is full", "score this agent config".

When NOT to Use

• Model-quality complaints (hallucination, refusals) — Ch1 is explicit that

the triangle is an architectural operational problem, not model quality.

• Small agents (under ~10 tools, short chains, low context fill) — no

corner is under pressure; the score will read BALANCED and buys you nothing.

• As a tool selector. This scores the tool-orchestration pressure; use

rag-mcp-tool-selection (Ch6) to actually filter the registry.

Process

| Step | Input | Action | Output | Verification | |------|-------|--------|--------|--------------| | 1 | steps / tools / disambiguity / window / used | lib.score(config) | per-constraint pressure + band | each pressure in 0-100; dominant_constraint is the max | | 2 | complexity input | lib.score_complexity(steps) | complexity pressure | monotonic increasing in steps (exponential load) | | 3 | tool input | lib.score_tool_orchestration(count, disambiguable) | tool pressure | ambiguous set scores higher than disambiguable at equal count | | 4 | context input | lib.score_context_utilization(window, used) | context pressure | monotonic increasing in fill ratio (rot gradient) | | 5 | full report | read active_pressure_cycles | Ch1 trade-off cycles fired by any high (>60) constraint | each cycle names a source constraint + edge + cascade | | 6 | full report | read recommendations + overall_band | minimal-but-sufficient action per stressed constraint | OVERCONSTRAINED only when all three >60 or any >85 | | 7 | list of configs | lib.score_batch(configs) | configs ranked by peak pressure | most-constrained config ranked first |

Rationalizations

| Agent rationalization | Documented rebuttal | |------------------------|--------------------| | "Context windows are huge now — I'll just add every tool and all context." | Ch1: the three constraints "form a system of competing trade-offs." Adding tools consumes context for their definitions and adds selection ambiguity (tools→context→complexity). Bigger windows do not exempt you from the cycle. | | "More reasoning steps make the agent smarter." | Ch1: "cognitive load increases exponentially ... compounding errors as the step count increases." Past a point, more steps lower reliability. Score complexity before lengthening the chain. | | "The tool set is fine — the model just needs a better prompt." | Anthropic's principle (Ch1): if a human engineer can't say which tool to use, the agent can't either. That is tool-orchestration pressure from ambiguity, not a prompt problem. Set --ambiguous and see the score jump. | | "Compact aggressively to free context — no downside." | Ch1's context→complexity→tools cycle: aggressive compaction "can inadvertently discard subtle but critical context whose importance only becomes apparent later," forcing more tool calls to reconstruct it. | | "One corner is high but the others are fine, so we're OK." | The triangle is coupled. A single high corner fires a pressure cycle onto the other two; active_pressure_cycles shows which. Relieve the source, don't just watch the symptom. |

Red Flags

• All three corners critical (OVERCONSTRAINED). You are past minimal-but-

sufficient on every axis. Cut steps, filter tools, and retrieve selectively together — fixing one corner in isolation pushes pressure to the next.

• Tool pressure high while tools_disambiguable=true. The catalog is

simply too large; filter it (RAG-MCP) rather than rewriting descriptions.

• Context pressure high with short chains and few tools. The task is

stuffing raw data into the prompt; move to selective retrieval before it hits the rot gradient.

• Score reads BALANCED but the agent still fails. The failure is likely

outside the triangle (model quality, a retrieval failure) — use context-failure-classifier or enterprise-readiness-scorer instead.

Non-Negotiable Verification

1. Run the benchmark battery. python cli.py benchmark must report 8/8:

• complexity/tool/context pressures are monotonic in their drivers
• the bloated-MCP config is OVERCONSTRAINED and fires a pressure cycle
• the balanced config is BALANCED with the dominant corner correct
• batch ranks the most-constrained config first

1. Verify CLI help. python cli.py --help exits 0 and prints the SKILL.md

description.

1. Inspect one scenario. python cli.py scenario latency-spike should show

the bloated agent OVERCONSTRAINED and the balanced agent BALANCED on the same DevOps investigation.

Security Posture

• Prompt injection. This skill consumes only numeric/boolean configuration

(step counts, tool counts, token counts) — no free-text tool descriptions or documents enter it, so there is no injection surface in lib.py.

• Data exfiltration. No network calls, no file writes outside the explicit

--configs path. --json output goes to stdout; the caller owns downstream piping.

• Privilege escalation. No shell invocation, no eval, no dynamic import.

The only file read is the config JSON path the caller supplies (default: the bundled sample).

• Misuse boundary. The pressure scores are an operational planning aid, not

an authorization control. Do not gate real permissions on this score; use capability-authorization-gate (Ch3) for authority decisions.

Source Attribution

Distilled from Agentic GraphRAG (O'Reilly, by Anthony Alcaraz and Sam Julien), Chapter 1 — Defining Agentic AI, "The Agent Constraint Triangle" section. The three constraints, the three cyclic trade-offs, and the minimal-high-signal-tokens principle are the chapter's; the tool-disambiguation principle and the attention-budget framing are anchored in Anthropic's "Effective Context Engineering for Agents," and context rot in Chroma's needle-in-a-haystack research, both named in the chapter.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: AnthonyAlcaraz
• Source: AnthonyAlcaraz/agentic-graph-rag-skills
• License: MIT
• Homepage: https://www.oreilly.com/library/view/agentic-graphrag/9798341623163/

Install and usage instructions live in the source repository linked above.