APOLLO VISION LABS

AI4 min read

Writing good tools: a clear action and a precise contract

Removing a jacket from one store’s catalog: turn a business intent into a precise, testable tool.

A store manager asks her assistant: “Delete this jacket from the Lyon catalog.” She wants to stop selling it at that store while keeping existing orders.

The agent has three tools: hide a product, delete a catalog entry and delete a product record shared by all stores. The name “delete a product” is not enough to select the right action.

The problem: one clear intention, several possible effects

The scope is obvious to the manager. The agent still needs to know which store is involved, which identifier to use and which data will change.

A vague description can lead to a technically valid call that does not match the request. The contract must explain business effects as well as parameters.

The solution: describe six essentials

For our delete_catalog_item tool, we would specify:

  • Action and object: delete an entry from the product catalog.
  • Scope: only the specified store.
  • Inputs: store and item identifiers, types and required fields.
  • Output: affected identifier, deletion confirmation or an explicit error.
  • Effect: stop new orders for this item in this catalog; keep historical orders.
  • Difference: hiding is temporary; deleting the shared product record would affect a different scope.

These commitments describe our illustrative example. They must match the service’s actual behavior.

From intent to the right tool

Selection starts with the requested effect and scope. If either is missing, the agent should ask for clarification. In our scenario, local deletion is the appropriate branch.

Clarify the effect and scope, then choose temporary hiding, local catalog entry deletion or shared record deletion. Check identifiers, permissions and applicable confirmation before calling the tool.
Tool names are illustrative. The center branch removes the Lyon catalog entry; the application and service must still enforce execution checks. Open the full-size diagram.

How it works technically: from worksheet to call

A drafting worksheet can help validate the requirement with the business team. This YAML example is not an executable MCP definition.

name: delete_catalog_item
action: Delete a product catalog entry
scope: The specified store’s catalog
inputs:
  store_id: string, required
  item_id: string, required
output:
  item_id: Affected identifier
  deleted: true if deletion succeeded
effect: >
  Stops new orders in this catalog.
  Preserves historical orders.
difference: >
  Deletes the entry, unlike temporary hiding.
  Preserves the shared product record and other stores.
errors:
  - store_inaccessible
  - item_not_found

The team then turns this worksheet into an actionable contract: tool description, input and output schemas, and error handling. A field described as required in prose must also be required in the schema.

If an HTTP API exists, OpenAPI can hold descriptions, parameters and responses. A Markdown worksheet is an optional drafting aid, not a storage requirement. OpenAPI specification

In our scenario, the application obtains both identifiers, checks access, applies its confirmation policy and calls the service. It reports deletion after actual success. A repeated call after deletion returns item_not_found here: that is a contract choice to document.

Benefits of a precise contract

  • The agent can distinguish related actions. Hiding, removing a catalog entry and deleting a shared product record are explicitly different.

  • The team can review consequences before coding. Preserving orders becomes a verifiable commitment.

  • Tests have expected outcomes. “Hide this jacket,” “remove it from Lyon” and “delete it everywhere” should lead to different decisions.

A single source of truth also enables generating the required representations without maintaining several descriptions by hand.

Limits: the description is not enough

  • The service must enforce the rules. A sentence about permissions does not block unauthorized access. The implementation must guarantee preservation of orders.

  • Errors must guide recovery. After a timeout, the deletion state may be unknown. Plan a status check or suitable recovery mechanism before repeating the call.

  • The right tool must remain discoverable. A good worksheet is useless if catalog search cannot find it. Test selection with similar wording and missing identifiers.

  • The contract must track changes. For a CLI, flags, exit codes and structured output also belong to the contract. CLI design guidelines

Continue with an introduction to MCP and MCP, API and CLI compared.

← Back to journal