AIYING · ALL OF AI FOR ALL OF US · AI ENGINEERING · C27 — BEFORE-AND-AFTER #001
Your Agent Calls the Right Tool with the Wrong Arguments. What Should You Fix?
Inspect the tool contract before rewriting the agent’s main prompt
A tool name tells an agent where it might act. Its description and parameter definitions explain how. If those definitions leave units, accepted values, or search behaviour unclear, the agent has to infer them.
Anthropic’s Writing effective tools for agents — with agents recommends refining tool descriptions and specifications, examining invalid-parameter errors, and evaluating changes. It also recommends filtering and pagination for large responses.
Start with one inspectable improvement: clarify an existing tool’s contract while leaving its implementation unchanged. This is a proposed engineering exercise, not a claim that documentation explains every tool failure.
Before-and-after: a log-search tool
Consider this fictional request:
Find checkout-service logs with HTTP status 500–599 between 09:00 and 09:15 UTC on 17 November 2026. Report matching records and whether more pages remain.
The existing tool exposes this illustrative interface:
search_logs(service, start, end, query, limit, cursor)
Its description says: “Search logs. Supply a service, time range, and query.”
That leaves important questions unanswered: Are times seconds or strings? Is the query plain text or a search language? Does the end time count?
Suppose the backend already expects the following behaviour. Document it explicitly:
| Field | Definition |
|---|---|
| service | Exact service ID from the environment’s service catalogue. |
| start / end | UTC timestamps such as 2026-11-17T09:00:00Z. Start inclusive; end exclusive. |
| query | Backend filter syntax. For HTTP 5xx records: status_code >= 500 AND status_code < 600. |
| limit | Integer from 1 to 100; maximum records returned per page. |
| cursor | Null for the first page. For subsequent pages, use next_cursor exactly as returned. |
Add a response definition: records contains matches; next_cursor is null only when no further page remains. Empty records mean no matches only when the search succeeded and pagination is complete. A failed search returns an explicit error.
These names and conventions are fictional, not an Anthropic or MCP API. Documentation must describe your actual backend. Timestamp formats, filter syntax, and pagination rules differ between systems.
Test one documentation change
- Select a real failure where the tool was appropriate but its arguments were wrong. Remove sensitive log contents.
- Clarify the relevant description and parameter documentation. Keep tool name, schema structure, backend, model, main prompt, and fixture fixed.
- Compare both versions on a small task set: a normal search, a zero-match search, a multi-page result, and an ambiguous service request requiring clarification or lookup.
- Repeat trials from fresh context. Record argument-validation failures, correct retrieval against the fixture, pagination handling, and final-answer accuracy separately.
- Inspect failed traces. If both versions fail, investigate schema design, implementation, available context, and task ambiguity rather than assuming a larger model is required.
Use task variants you did not tune the wording against before accepting an improvement. Better wording can guide calls; backend validation must still enforce the contract.
Your turn: Which parameter in your tool would a new developer have to ask you to explain?
Source and scope: Anthropic, Writing effective tools for agents — with agents, 11 September 2025; checked 17 November 2026. The log-search interface and exercise are AIYING adaptations. No comparative results are claimed.

