Getting it into your agent
One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.
npx skills add Koredotcom/agents-mcp-tools --skill arch-tool-designgit clone --depth 1 https://github.com/Koredotcom/agents-mcp-toolsWrote this? Show the measurements
A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.
[](https://agentmods.dev/skills/koredotcom/agents-mcp-tools/arch-tool-design)<a href="https://agentmods.dev/skills/koredotcom/agents-mcp-tools/arch-tool-design"><img src="https://agentmods.dev/badge/skills/koredotcom/agents-mcp-tools/arch-tool-design/github.svg" alt="Measured on agentmods" height="20"></a>Or the 80×15 button, for a site that already has a row of RSS and ATOM ones. Only the verdict fits; the numbers stay here.
<a href="https://agentmods.dev/skills/koredotcom/agents-mcp-tools/arch-tool-design"><img src="https://agentmods.dev/badge/skills/koredotcom/agents-mcp-tools/arch-tool-design.svg" alt="Reviewed on agentmods" width="80" height="20"></a>What it costs to keep this loaded
Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.
| Model | Per session | Once invoked |
|---|---|---|
| Fable 5.1 | $0.00112 | $0.01662 |
| Opus 5.5 | $0.00045 | $0.00665 |
| Sonnet 5.5 | $0.00022 | $0.00332 |
| Haiku 4.5 | $0.00011 | $0.00166 |
Grade A, and why
arch-tool-design scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 1mo ago.
A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.
Nothing flagged
None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.
How it starts
The opening of the file, as written. The whole thing — 91 lines — stays where its author put it; the contents beside it link to each section on GitHub.
Tool design
A tool is a contract between the model and your backend. Most tool bugs come from a contract that leaves something to the model: an ordering, a hidden ID, a confirmation, an error message. Make the contract structural and keep the model's job small.
Where each setting lives
- The agent's
TOOLS:entry: the signature, description, parameter rules and behavior keys (effect,confirm,MODEL_CONTEXT,on_result,on_error,process). - The project tool: endpoint, method, auth, headers, timeout and retry. Implementation keys
written in an agent
TOOLS:entry are dropped with a warning. - Tool kinds you can create: HTTP, MCP, workflow, integration, knowledge base (SearchAI), table and
sandbox code. Knowledge-base tools: see
arch-knowledge-search. Workflow tools: seearch-workflow-design.
The contract, key by key
| Concern | Key | Rule |
|---|---|---|
| What it is for | description |
One or two sentences: what it does and when to use it. Without one it defaults to "Execute " |
| Hidden inputs | params: with default_source: runtime, visibility_model: false, context_access.read: [field] |
Use for IDs, tokens and anything the model should not fill or see; a missing value fails the call closed |
| Effect | effect: read_only | state_write | side_effect |
Declare it on every tool. Undeclared HTTP tools are judged by method (GET, HEAD, OPTIONS read-only), knowledge-base tools are read-only, table tools by their operations; workflow, MCP, integration and sandbox tools are treated as side-effecting |
| Facts it publishes | provides with on_result set |
Allow-list what a successful result may write to the session |
| Confirmation | confirm: always | never | when_side_effects, immutable |
Confirm irreversible writes, freeze amounts and IDs with immutable. confirm: yes means no confirmation |
| Preconditions | process.before with require and on_fail (reask, block, warn, use_original, fallback) |
Reject missing or invalid inputs before the API call; reask is the default on interactive channels |
| Result shape | MODEL_CONTEXT with FIELDS (or TEMPLATE) |
Pass only the fields the model needs; up to 64 paths, 1,000 items, 16,000 characters, otherwise the view fails closed |
| Remove sensitive output | process.after with OMIT (beta) |
Drop echoed tokens and personal data before the model sees them |
| Keep values for later turns | on_result set |
Results are replaced by a placeholder on the next turn; store_result turns off once set is used unless you set it back on |
| Reply without a model call | on_result do with RESPOND |
RESPOND must sit under do:, or it is ignored |
| Errors | on_error with canonical types (tool_error subtypes rate_limit, auth_failure, network_error, tool_timeout) |
Write what the caller hears; do not retry auth_failure |
| Timeouts and retries | Project tool timeout (milliseconds), retry, idempotency_header |
Default 30 s, cap 300 s. Write milliseconds; "30s" is rejected by one parser and misread as 30 ms by another. Retry only idempotent reads unless the provider honors an idempotency key |
| Credentials | Auth profiles | Never secret config in prompts or tool parameters |
What ships with it
1 file beside SKILL.md in the same directory: the scripts, references and assets a skill reads on demand. Not counted in the per-session cost; read them before you install if any of them is executable.
What this file has done since we first saw it
Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.
- 1mo ago First seen · 91 lines · 112 tokens per session scan A 8af013b6b139
arch-tool-design is a skill published in the GitHub repository Koredotcom/agents-mcp-tools (4 stars, last pushed 1mo ago), licensed MIT. It adds 112 tokens to every session and 1,662 once invoked, about $0.0004 per session on Opus 5.5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-10-09.
arch-tool-design compared with skills from other repositories
| Mod | Type | Stars | Last push | Licence | Scan | Tokens | Works with |
|---|---|---|---|---|---|---|---|
| arch-tool-designKoredotcom/agents-mcp-tools | Skill | 4 | 1mo ago | MIT | A | 112 | Codex |
| mcp-tool-developersickn33/agentic-awesome-skills | Skill | 50k | today | MIT | A | 38 | Claude Code |
| mem0-oss-to-platformmem0ai/mem0 | Skill | 69k | 6d ago | Apache-2.0 | A | 217 | Claude Code, Codex |
| azure-mgmt-botservice-dotnetmicrosoft/skills | Skill | 3.2k | today | MIT | A | 78 | Claude Code |
| fastapi-router-pymicrosoft/skills | Skill | 3.2k | today | MIT | A | 46 | Claude Code |
| dev-runtimelangwatch/langwatch | Skill | 5.0k | today | Apache-2.0 | A | 172 | Claude Code |
| api-designericrisco/rsc-harness | Skill | 598 | today | MIT | A | 105 | Claude Code, Codex |