Tool Invocation

Tool invocation fails when agents pass wrong arguments, use wrong ID or key formats, misunderstand tool semantics, fail to page results, or retry non-idempotent operations without side-effect awareness. The 12 invocation patterns documented here cover the challenge of calling tools correctly — from parameter validation through pagination, query scoping, timezone handling, and understanding when operations are idempotent. Invocation failures are particularly common because agents must understand and respect tool contracts (what parameters it accepts, what they mean, what side effects occur), and misunderstanding any part of that contract leads to failed or incorrect tool calls.

Key Takeaways

• 12 patterns documented: parameter validation, ID/key usage, query scoping, pagination, timezone, idempotency, side effects, rate-limiting, result handling, and format errors.
• Missing Required Parameter and Wrong Argument Format are most severe: missing required parameters cause tool failures, wrong format (string vs integer) causes parsing errors.
• Over Broad Query and Over Narrow Query are second-order: agents don’t scope queries correctly, returning too much (inefficient, expensive) or too little (missing relevant results) data.
• Idempotency Failure and Side Effect Misunderstanding are architectural failures: agents don’t know whether operations are idempotent or what side effects they cause, leading to unwanted retries or cascading effects.

Scope

• Parameter and Format Correctness — Missing Required Parameter, Wrong Argument Format, Wrong ID/Key Usage. Arguments must be provided, formatted correctly, and reference correct IDs; missing or malformed arguments cause failures.
• Scoping and Boundaries — Over Broad Query, Over Narrow Query. Queries must be scoped correctly; too broad returns expensive results, too narrow misses relevant data.
• Temporal and Measurement — Wrong Date Range/Timezone, Wrong Units/Currency. Date ranges, timezones, units must be correct; timezone mismatch returns data from wrong time period, unit mismatch causes wrong calculations.
• Result Handling — Pagination Failure, Partial Result Misuse. Results may be paginated; agents must handle pagination or may miss results; agents must not use partial results as if they were complete.
• Safety and Semantics — Idempotency Failure, Side Effect Misunderstanding, Rate Limit/Timeout Mishandling. Agents must understand idempotency and side effects; retrying non-idempotent operations causes duplicates, misunderstanding side effects causes cascading failures.

When Tool Invocation Matters

• Agents invoke tools with complex parameters where correct formatting and scope matter.
• Tools have side effects or state changes; retrying without idempotency awareness causes duplicate writes.
• Tools return paginated results; agents must navigate pagination to get complete data.

Cross-Pattern Insight

The 12 invocation patterns describe systems where tool semantics are implicit: agents guess what parameters mean, whether operations are idempotent, whether queries are scoped correctly, without explicit validation or documentation. Tool documentation exists but is incomplete, and agents must infer semantics from example usage or error messages. Most teams discover invocation failures only after agents start calling tools incorrectly and cascading failures reveal the misunderstandings. The mitigation that recurs across nearly every pattern is explicit contract validation: use API contracts to specify required parameters and their formats, document idempotency and side effects explicitly, test tool invocation with correct and incorrect parameters, and add agent-level validation before calling tools.

Frequently Asked Questions

How do you prevent wrong-argument-format errors?

Per Wrong Argument Format, validate argument types and formats before calling tools: check that IDs are strings not integers, dates are ISO 8601 not user-locale format, amounts are in correct currency. Use API contracts (OpenAPI, schema) to specify expected formats and validate against them.

What should an agent do if pagination is required?

Per Pagination Failure, agents should check for pagination metadata (e.g., has_next, next_token), and iterate through all pages rather than assuming first page is complete. Test pagination by requesting large result sets and verifying all results are retrieved.

How do you understand tool idempotency?

Per Idempotency Failure, ask the tool documentation: is calling this operation twice with same parameters safe? If yes, idempotent; if no, non-idempotent. Never retry non-idempotent operations automatically — log the failure and require manual intervention or explicit retry logic that accounts for side effects.

Can over-broad queries be optimized after the fact?

Partially — per Over Broad Query, agents should scope queries before calling (filter by date range, category, etc.) rather than retrieving everything and filtering client-side. Over-broad queries waste resources and cost; filter server-side first.

Patterns

Total: 12 patterns

Related Goals

• Tool Reliability — invocation correctness affects tool reliability
• Tool Selection — selecting the right tool complements correct invocation
• Observability Monitoring — invocation errors should be logged and analyzed