Start with a decision, not a score
Imagine a tool called process. It accepts an object, returns another object, and has the description “Processes a request.” A person might ask a teammate what it does. An agent has to choose whether to call it using the interface you supplied.
The first question is therefore practical: can a consumer decide when this operation is appropriate, what to send, and what to do with the result? A quality score can point to gaps, but those three decisions are the work.
Name the action and its limits
A name such as get_payment gives more context than process. A description can go further: “Retrieve the status and amount of an existing payment by ID. Does not initiate a payment or refund.” That last sentence helps distinguish a read from a write.
Describe the operation, not the marketing value of your service. Mention a prerequisite when it changes the decision to call. If a tool requires an identifier from another operation, say where that identifier comes from.
Tool: get_payment
Input: payment_id (required string)
Purpose: Retrieve an existing payment.
Side effects: None.This example is intentionally small. A focused operation with a clear boundary is easier to reason about than one tool that tries to handle an entire business process.
Make invalid inputs harder to construct
Use specific parameter types and explain their meaning. An integer named amount still leaves a critical question unanswered: does it represent rupees or paise? Put the unit in the field description and use examples that agree with it.
Required fields should be marked required. Enumerations should include the actual supported values. Distinguish an omitted property from a property that explicitly accepts null. Where you can express a constraint in a schema, do that in addition to writing it in prose.
OpenAPI provides a standard way to describe HTTP API operations and their schemas. That makes it a useful source for reviewing these details before generating other interfaces. See the OpenAPI specification for the format.
Give responses enough context
A successful HTTP status does not explain the business result. Return structured fields that distinguish a pending payment from a settled one. Keep identifiers stable, make amounts unambiguous, and avoid requiring the consumer to parse a human sentence for a critical value.
Errors need the same care. A caller should be able to distinguish a missing record, an invalid input, and a denied operation. Avoid suggesting retries for failures that require a different identifier or permission. For write operations, think through what a retry would do before making it the default recommendation.
Review with a small, real workflow
Pick one safe workflow and walk through it manually. List the available tools. Select one using only its name and description. Construct an input from its schema. Read a success response and an error response. Note every point where you needed knowledge that was not in the interface.
- Can the consumer distinguish reads from writes?
- Are units and identifiers clear?
- Does the response expose unnecessary fields?
- Is the error actionable without revealing sensitive data?
In Sutra, start with the API catalog, inspect quality findings, and then use the playground workflow to try tools. The goal is a consumer that needs fewer guesses, not a score that looks impressive.