AIYINGFrom AI Awareness to Accomplishment
Showing posts with label C27 Before-and-After. Show all posts
Showing posts with label C27 Before-and-After. Show all posts

Tuesday, November 17, 2026

AI Agent Tool Calling: Fix Unclear Parameters Before Changing Models

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?

By Ravindra Dastikop


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:

After: a clearer contract for the same implementation
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

  1. Select a real failure where the tool was appropriate but its arguments were wrong. Remove sensitive log contents.
  2. Clarify the relevant description and parameter documentation. Keep tool name, schema structure, backend, model, main prompt, and fixture fixed.
  3. 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.
  4. Repeat trials from fresh context. Record argument-validation failures, correct retrieval against the fixture, pagination handling, and final-answer accuracy separately.
  5. 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.

AIYING · Ravindra Dastikop
See differently. Generate possibilities. Accomplish what matters.

Accomplish with AI

Powered by Blogger.

Featured post

How do I AI my first attempt? A Practical Guide to Getting Started

AIYING · HOW TO AI · EPISODE 001 How do I AI my first attempt? Turn an unfinished idea into one small version you can exa...

Search This Blog

List of blogs

Search This Blog

About

Translate

Instant Stories

Read in Your Language

Test

share this

ShareThis

Popular Posts