Agent Tool Contract Review

Agent Tool Contract Review

Use this skill to make a tool easier and safer for agents to call.

Use When

• designing or reviewing MCP tools, CLI wrappers, GitHub Actions inputs, or SET planner outputs;
• changing AGENTS.md generator templates that tell agents which commands or tools to use;
• a tool has ambiguous parameters, hidden side effects, noisy output, or weak error messages;
• agent runs repeatedly misuse a command or need human intervention after avoidable failures.
• adapting an external skill, contract, or workflow into the local skill network.

Adaptation Delta

Before writing an adapted external skill, classify each material source fragment in templates/adaptation-delta.yaml:

• KEEP: retain source mechanics or schema without semantic change;
• ADAPT: change paths, tools, authority, terminology, or environment assumptions;
• ADD: introduce local guardrails, routing, verification, or project boundaries;
• REJECT: exclude a fragment and record the reason plus source reference.

Every entry requires a stable ID and source fragment reference. Present the complete delta to the owner before writing. Record APPROVED, REVISE, or REJECTED; silence is not approval. Preserve attribution and license constraints independently of the classification.

Review Dimensions

• purpose: what job the tool owns and what it does not own;
• schema: required fields, optional fields, enums, defaults, and validation;
• authority: read-only, proposal-only, write, destructive, external side effect;
• output: compact, structured, parseable, and stable enough for downstream agents;
• errors: actionable messages with the smallest useful recovery step;
• idempotency: safe retries, duplicate handling, and idempotency keys when needed;
• auditability: logs, dry-run mode, preview mode, and human approval boundary.

Workflow

1. Identify the agent-facing tool surface and its intended caller.
2. Classify the authority level: read, plan, proposal, write, or destructive.
3. Check whether the name, description, schema, and examples make the safe path obvious.
4. Check whether the output can be consumed without reading a large log.
5. Check error paths and retry semantics.
6. Recommend the smallest contract change: rename, tighter schema, dry-run, better error, structured output, or approval gate.

Output Shape

Use:

• verdict: CONTRACT_OK, CONTRACT_AMBIGUOUS, or CONTRACT_UNSAFE;
• tool surface reviewed;
• authority level;
• contract findings;
• smallest contract changes;
• tests or smoke checks.

Guardrails

• Do not redesign the whole tool when a schema or description change is enough.
• Do not hide write or destructive behavior behind friendly wording.
• Do not require agents to infer defaults that can be encoded in schema.
• Do not make logs the primary machine interface when structured output is feasible.
• Do not silently omit or rewrite upstream behavior during adaptation.

Provenance

Adapted from tool-design patterns in muratcankoylan/Agent-Skills-for-Context-Engineering, plus MakerSkills' explicit keep/adapt/add porting report. Narrowed for SET, AGENTS.md generator, MCP, CLI, and provider-neutral skill adaptation, with an added REJECT disposition and owner gate.