# Agent Constraint Triangle Scorer

> |

- **Type:** Skill
- **Install:** `agentstack add skill-anthonyalcaraz-agentic-graph-rag-skills-agent-constraint-triangle-scorer`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [AnthonyAlcaraz](https://agentstack.voostack.com/s/anthonyalcaraz)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [AnthonyAlcaraz](https://github.com/AnthonyAlcaraz)
- **Source:** https://github.com/AnthonyAlcaraz/agentic-graph-rag-skills/tree/main/skills/crisis/agent-constraint-triangle-scorer
- **Website:** https://www.oreilly.com/library/view/agentic-graphrag/9798341623163/

## Install

```sh
agentstack add skill-anthonyalcaraz-agentic-graph-rag-skills-agent-constraint-triangle-scorer
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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."
2. **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."
3. **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
2. **Verify CLI help.** `python cli.py --help` exits 0 and prints the SKILL.md
   description.
3. **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](https://github.com/AnthonyAlcaraz)
- **Source:** [AnthonyAlcaraz/agentic-graph-rag-skills](https://github.com/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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-anthonyalcaraz-agentic-graph-rag-skills-agent-constraint-triangle-scorer
- Seller: https://agentstack.voostack.com/s/anthonyalcaraz
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.