ac-agent-tool-design
Deciding what tools an agent gets and shaping each one so the model uses it correctly: which capabilities deserve to be tools at all, writing descriptions the model actually reads, result payloads sized for a context window, the tool menu and its confusion costs, error returns that teach recovery instead of dead ends, and the written tool-surface record. It teaches the craft of the tool interface seen from the model's side; it never recommends a framework and never promises an agent will behave. Use when asking "should this be a tool", "tool description writing", "how many tools is too many", "tool naming", "tool result format", "tool menu design", "agent tool design", "tool error messages", "tool schema design", "when not to give an agent a tool". Not for the client-side agent loop and multi-turn plumbing (ac-llm-api-integration), not for MCP server protocol and transport (ac-mcp-authoring), not for sandboxing what a tool may touch (ac-wasm-and-sandboxes).
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 81
- Forks
- 17
01 前言 Front Matter
- name
- ac-agent-tool-design
- status
- seedling
- license
- MIT
- metadata
- { "domain": "prompt-engineering" }
- description
- Deciding what tools an agent gets and shaping each one so the model uses it correctly: which capabilities deserve to be tools at all, writing descriptions the model actually reads, result payloads sized for a context window, the tool menu and its confusion costs, error returns that teach recovery instead of dead ends, and the written tool-surface record. It teaches the craft of the tool interface seen from the model's side; it never recommends a framework and never promises an agent will behave. Use when asking "should this be a tool", "tool description writing", "how many tools is too many", "tool naming", "tool result format", "tool menu design", "agent tool design", "tool error messages", "tool schema design", "when not to give an agent a tool". Not for the client-side agent loop and multi-turn plumbing (ac-llm-api-integration), not for MCP server protocol and transport (ac-mcp-authoring), not for sandboxing what a tool may touch (ac-wasm-and-sandboxes).
02 资源文件 10
- 许可证LICENSE1.0 KB
- 参考文档SOURCE.md376 B
- 参考文档subskills/choosing-parameters.md3.4 KB
- 参考文档subskills/errors-as-lessons.md3.3 KB
- 参考文档subskills/reading-descriptions.md3.4 KB
- 参考文档subskills/result-payloads.md3.3 KB
- 参考文档subskills/tool-menu-design.md3.3 KB
- 参考文档subskills/tool-surface-record.md3.2 KB
- 参考文档subskills/what-becomes-a-tool.md3.4 KB
- 参考文档TRUST.auto.yaml2.3 KB
03 SKILL.md 正文
Agent tool design
Overview
A tool is an interface read by a model rather than a person, and everything a person would get from layout, help text, and convention must arrive through the description, the name, and the shape of the result. The model chooses from the description alone, decides what to pass from the name and parameters, and interprets the result from its payload shape. Badly shaped tools misfire exactly where a badly designed human interface confuses.
This skill covers the design of the tool surface as seen from the model's side: which capabilities should be tools at all, how descriptions and names work on a model reader, how menu size and near-duplicates create confusion costs, what a result payload should carry and omit, and what an error return owes the caller. The protocol plumbing behind it — the client loop, the MCP transport, the sandbox around execution — belong to three other skills, each named in every leaf.
Primary sources: https://docs.anthropic.com/en/docs/agents-and-tools/tool-use and https://platform.openai.com/docs/guides/function-calling.
When to use
- When deciding whether a capability becomes a tool at all.
- When writing or repairing tool descriptions, names, and parameter schemas.
- When an agent picks the wrong tool, misuses a tool, or calls nothing when it should act.
- When a growing tool menu starts degrading selection accuracy.
When NOT to use
- For the client-side loop, retries, and multi-turn plumbing (use ac-llm-api-integration).
- For the MCP protocol, transports, and server structure (use ac-mcp-authoring).
- For sandboxing and limiting what a tool may touch (use ac-wasm-and-sandboxes).
Subskill Index
| Leaf | Domain segment | Scope (one line) |
|---|---|---|
subskills/what-becomes-a-tool.md |
prompt-engineering/what-becomes-a-tool |
Capabilities that earn tool status, and those that should stay prompt or workflow. |
subskills/reading-descriptions.md |
prompt-engineering/reading-descriptions |
Descriptions and names written for a model reader. |
subskills/tool-menu-design.md |
prompt-engineering/tool-menu-design |
Menu size, near-duplicates, grouping, and the confusion cost of breadth. |
subskills/result-payloads.md |
prompt-engineering/result-payloads |
What a tool returns to a context window, and what it omits. |
subskills/errors-as-lessons.md |
prompt-engineering/errors-as-lessons |
Error returns that tell the model what to do next. |
subskills/choosing-parameters.md |
prompt-engineering/choosing-parameters |
Parameter sets the model can fill correctly from what it knows. |
subskills/tool-surface-record.md |
prompt-engineering/tool-surface-record |
The written record: tool inventory, misfire log, and change history. |
Status and honest limits
Tool selection behaviour varies across models and changes with model updates, so every claim here is a design discipline with a rationale, not a guarantee: misfire rates improve under testing, and the misfire log is the evidence. The protocol skills (MCP, raw API integration) evolve faster than this craft; where a provider adds a mechanism like tool search, this skill stays at the design layer above it. Nothing here recommends a framework — the craft is provider-neutral by design.
04 同仓库更多 Skills
troves
Deposit and withdraw from Troves DeFi yield vault strategies on Starknet. View available strategies, check positions, and manage vault deposits. Use this skill when the user mentions Troves, vault, yield vault, DeFi vault, strategy, yield farming, vault deposit, vault withdraw, earning yield through vaults, passive yield strategies, or wants to deposit into or withdraw from a yield strategy — even if they don't say "Troves" explicitly.
trade
Swap tokens on Starknet via Fibrous DEX aggregator. Supports per-provider selection (avnu, ekubo, or auto to race all). Use this skill when the user wants to swap, exchange, trade, convert, buy, or sell one token for another on Starknet. Also use when the user asks about token prices, exchange rates, DEX routing, best swap route, or wants to check how much they would receive for a given amount — even if they don't explicitly say "swap".
staking
Stake, unstake, claim, and compound rewards for STRK, WBTC, tBTC, SolvBTC, and LBTC on Starknet. View validators, pools, and staking positions. Use this skill when the user mentions staking, delegating, validators, staking pools, rewards, compounding, unstaking, earning yield, passive income on crypto, or wants to earn on their STRK or BTC tokens — even if they don't say "stake" explicitly.
send
Send STRK, ETH, or any ERC-20 token to a Starknet address. Supports simulation (dry-run) before execution. Use this skill when the user wants to send, transfer, pay, tip, or move tokens to another wallet address on Starknet. Also trigger when the user mentions sending funds to someone, making a payment, transferring assets, or moving crypto to a specific address — even if they just say "pay 10 STRK to 0x...".
portfolio
View a comprehensive DeFi portfolio dashboard and optimize portfolio allocation via automated rebalancing. Use this skill when the user wants an overview, summary, dashboard, total value, net worth, portfolio rebalancing, target allocation, or wants to see all their DeFi positions across Starknet at once. Also trigger when the user asks "what do I have", "show me everything", "how much am I worth", "my positions", "my investments", "rebalance my portfolio", "I want 50% ETH", "optimize my holdings", or any request for a holistic view of their Starknet holdings — even if they don't explicitly say "portfolio".
multi-swap
Execute multiple token swaps in a single Starknet transaction via Fibrous (default). Supports per-provider selection (avnu, ekubo, or auto to race all). Supports 2-3 swap pairs bundled into one multicall. Use this skill when the user wants to swap multiple token pairs at once, do batch swaps, execute several trades simultaneously, perform parallel swaps, or do bulk trading in one transaction. Also trigger when the user mentions "two swaps", "three swaps", "swap X and Y at the same time", or wants to convert multiple tokens in a single call.