Last reviewed: August 28, 2026

Direct answer

CometAPI tool result token costs should be controlled at the boundary where an application turns a client-side tool’s response into content for the model’s next request. Measure the exact sanitized and serialized result that will be forwarded—not merely the tool’s raw response—then apply a soft limit, a hard limit, and a declared overflow action before dispatch.

This boundary matters because tool use is usually a loop. A model requests a tool, the application executes it, and the result is returned so the model can continue. For chat and text routes, CometAPI publishes token-based input pricing, so forwarded result content can contribute to the next request’s input cost. The exact accounting still depends on the selected model, protocol, and current rate. Treat a preflight estimate as a gate, then reconcile it against the usage reported for the completed request.

A defensible control therefore uses two measurements: serialized bytes for a fast universal ceiling and a model-appropriate token estimate for cost forecasting. When a result exceeds policy, first remove unneeded fields, duplicates, markup, and low-ranked records. If it remains too large, paginate it, produce a bounded summary with omission metadata, ask for narrower scope, or stop the loop. Never silently forward an unlimited result and hope the model will ignore most of it.

Who this is for

This guide is for AI platform engineers, agent developers, reliability teams, and FinOps operators running client-side tools through CometAPI. It is most useful when search, database, file, ticketing, analytics, or web tools can return unpredictable amounts of text or structured data.

The control is narrower than a total agent-turn budget. It also differs from tool-schema overhead and any separately priced built-in tool. Teams should maintain separate ledger lines for the tool invocation, the schema or definition sent to the model, the result payload returned afterward, and the model output. That separation makes the source of a cost increase visible.

Key takeaways

  • Meter the exact representation sent back to the model after sanitization and serialization.
  • Bind every budget to a model route, pricing unit, price snapshot, and protocol version.
  • Use both byte and token limits; bytes alone are not a reliable estimate of model input cost.
  • Prefer deterministic reduction—field selection, deduplication, ranking, pagination, and clipping—before paying another model to summarize.
  • Reconcile estimates with request-level usage because the total request also includes instructions, history, tool definitions, and other context.
  • Log sizes, counts, actions, and short digests, but not raw tool content, personal data, request headers, or full tool arguments.
  • Preserve provider-specific result ordering and identifiers while applying the cap, or the cost control itself can create rejected requests and retries.

Sources checked

  • The CometAPI pricing page describes token-based billing for chat and text models, separate units for media models, and model-level price rows. It supports the price-binding step, but it does not establish one universal tool-result cap.
  • The OpenAI function-calling guide defines tool calls and tool-call outputs and describes returning output in another model request. That subsequent request is the accounting boundary this control measures.
  • The Anthropic tool-call handling guide documents client-tool result blocks, their required placement, error signaling, supported content types, and the need to treat externally sourced results as untrusted.
  • The Google Gemini function-calling guide documents connecting models to external functions and returning function responses, including multimodal content. It supports separate policies for text and non-text results.

Together, these sources establish the tool loop, the result-return boundary, protocol-specific constraints, and current public pricing units. The soft and hard limits remain an operator policy that should be tested against workload quality and budget targets.

Contract details to verify

Write a tool-result budget contract before setting thresholds. At minimum, bind the following details:

  • Scope: client-side results forwarded in a later model request, server-managed results, or both.
  • Route: the exact CometAPI model identifier and the provider-compatible request protocol in use.
  • Pricing: input unit, current price per unit, source URL, currency, and snapshot date.
  • Serialization boundary: the canonical content after field filtering, normalization, redaction, and encoding.
  • Soft limit: the point at which deterministic reduction begins.
  • Hard limit: the point at which forwarding stops unless an approved exception exists.
  • Overflow action: filter, rank, clip, paginate, summarize, request narrower scope, or return a bounded error.
  • Quality guard: required fields, evidence identifiers, minimum record count, and tests that detect material information loss.
  • Error behavior: the compact structure sent when execution fails or a payload cannot be reduced safely.
  • Ledger fields: raw size, forwarded size, result estimate, total request usage, cap action, and price snapshot.

Keep adjacent cost categories separate. Use the guide to separate built-in tool-call fees from model tokens for invocation accounting, and control tool-schema tokens for definitions included before a tool runs. This article’s boundary begins with the result produced after execution.

For a text-token route, the preflight estimate is straightforward: estimated result cost equals result tokens sent divided by one million, multiplied by the verified input price per million. Calculate both the raw-result counterfactual and the forwarded-result estimate at the same rate. Their difference is the estimated avoided input cost for that result. Do not present it as invoice truth; the provider’s request-level usage is the reconciliation source.

A concrete operator workflow looks like this:

  1. Inventory the result path. Identify where raw tool output is decoded, sanitized, filtered, serialized, inserted into conversation state, and dispatched through CometAPI. Confirm whether retries reuse the same result.
  2. Freeze the pricing contract. Record the model route, billing unit, public price, and snapshot date. Do not reuse a text-token formula for image, audio, document, or other content unless that route’s metering contract supports it.
  3. Build the canonical envelope. Allowlist fields the model needs, normalize dates and numbers, remove presentation markup, deduplicate records, and retain stable evidence identifiers. Add truncated, omitted_count, and selection_rule fields whenever reduction changes completeness.
  4. Measure before dispatch. Record raw bytes, forwarded bytes, item counts, and a route-appropriate token estimate. Measure the serialized envelope rather than an in-memory object that will be encoded differently later.
  5. Apply the policy. Below the soft limit, forward the envelope. Above the soft limit, apply the declared deterministic reductions and measure again. Above the hard limit, do not send the oversized content.
  6. Happy path: send the bounded result once, preserve the tool-call identifier and required provider ordering, receive the model response, and capture request-level input and output usage. Mark the result as forwarded and compare estimated versus observed usage.
  7. Error path: if safe reduction cannot bring the result below the hard limit, return a compact, protocol-valid error result or ask the user to narrow the request. Include an error class, retryability, and omitted count—not a stack trace or raw upstream body. If the model request is rejected for result formatting, correct the envelope without re-executing the tool unless execution itself failed.
  8. Reconcile and tune. Attribute only the estimated result component to this control while retaining total request usage in the ledger. Review quality failures and cap events together; a cheaper request that omits decisive evidence is not a successful control.

Use sanitized telemetry such as the following. The values illustrate the shape of a record; bind the price to the current route before using it in a ledger.

{
  "event": "tool_result_budget",
  "run_id": "run-042",
  "request_id": "req-104",
  "tool_call_id": "call-009",
  "tool_name": "catalog_search",
  "model_route": "gemini-3.7-flash",
  "result_media_type": "application/json",
  "raw_result_bytes": 48210,
  "forwarded_result_bytes": 7900,
  "raw_item_count": 180,
  "forwarded_item_count": 12,
  "result_token_estimate": 2100,
  "request_input_tokens": 3400,
  "request_output_tokens": 280,
  "input_price_per_million_usd": 0.6,
  "estimated_result_cost_usd": 0.00126,
  "price_snapshot_date": "2026-08-28",
  "cap_action": "field_filter_top_k",
  "cap_reason": "soft_limit",
  "result_digest_12": "a1b2c3d4e5f6",
  "status": "forwarded"
}

The useful logging fields are identifiers, model route, media type, sizes, token estimates, returned usage, item counts, price binding, cap action, error class, and a short digest for matching repeated results. Exclude raw result content, customer identifiers, full URLs with query strings, headers, uploaded documents, and tool arguments. If operational tooling requires a content placeholder, store [REDACTED] rather than the content itself.

Failure modes

  • Measuring the wrong representation: Counting the upstream response while forwarding a larger re-serialized object produces a false estimate. Meter the final envelope immediately before dispatch.
  • Using bytes as the only cost proxy: Encoding and content structure affect tokenization, while multimodal routes can use different units. A byte ceiling remains useful for safety, but it is not an invoice calculation.
  • Mixing cost categories: Combining tool invocation fees, schema overhead, result input, and model output into one number prevents diagnosis. Keep separate fields even when they appear on one invoice.
  • Breaking result order: Provider protocols can require the result to follow the corresponding tool call immediately and preserve its identifier. Anthropic also requires result blocks to precede accompanying text in that user message. A wrapper that inserts commentary in the wrong place can trigger a rejected request.
  • Retrying the tool after a formatting rejection: If execution succeeded but the model request was malformed, rerunning the external operation can duplicate side effects and spend. Cache the bounded result for a corrective formatting retry.
  • Forwarding verbose errors: Database traces, HTML error pages, and upstream diagnostic bodies can be larger than successful results. Convert them to a small error class, retryability flag, and safe message.
  • Parallel-result fan-out: Each tool may be below its individual cap while the combined turn exceeds the request budget. Enforce both per-result and aggregate-per-turn limits.
  • Invalid truncation: Cutting serialized JSON at a byte boundary can create malformed content or separate a value from its evidence identifier. Reduce structured fields and items before serialization.
  • Silent evidence loss: A summary can sound complete after removing exceptions or minority records. Mark incompleteness, retain counts and identifiers, and test answer quality against uncapped fixtures.
  • History replay: An orchestrator may resend the same result in later turns. Track result digests and measure whether old tool payloads remain in conversation state; compact or replace them according to the application’s state contract.
  • Untrusted result content: Web pages, email, uploads, and third-party APIs can contain instructions aimed at the model. Keep that content in the designated result structure, sanitize it, and do not promote it into system instructions.
  • Stale price binding: A correct token estimate multiplied by an old rate is still a bad forecast. Store the route and snapshot with every estimate and refresh the contract when routing or pricing changes.

FAQ

Do all tool results create a separate CometAPI charge?

The checked sources do not establish a universal separate tool-result fee. For text routes, the practical control is to treat returned result content as a potential part of the next request’s metered input and verify the actual route’s usage and pricing. Separately priced built-in tools should remain their own ledger category.

Should the hard cap be expressed in bytes or tokens?

Use both. Bytes give a deterministic transport and memory ceiling before provider-specific counting is available. A model-appropriate token estimate gives a better cost forecast for token-priced text routes. For non-text blocks, add the provider’s relevant unit and media-specific restrictions.

Where should the cap run?

Run the per-tool policy in the adapter that creates the canonical result envelope, then run an aggregate turn-level policy in the orchestrator before it calls the model. The second check catches parallel results and other context added after individual tools finish.

Can the application simply summarize every large result?

Not safely by default. Model-generated summarization is another operation with its own cost and possible omissions. Start with deterministic field selection, deduplication, ranking, clipping, and pagination. Use summarization only when the quality contract defines required facts, omission markers, and validation tests.

How should image or document results be handled?

Give them separate media policies. Google documents that function responses can include multimodal content, while CometAPI publishes different billing units across text and media categories. Do not convert a file’s byte count into text tokens without a route-specific metering rule. Cap file count, media size, page or item count, and any extracted text independently.

What should happen when a tool itself fails?

Return a compact, provider-valid error result that identifies the error class and whether retry is safe. Preserve the tool-call identifier, omit raw diagnostics, and prevent automatic retries from exceeding the run budget. A formatting failure after successful execution should not automatically rerun a side-effecting tool.

How can operators prove that the cap saves money?

For a representative sample, retain safe size and usage metadata for the raw-result counterfactual and the forwarded envelope. Apply the same verified input rate to both estimates, then compare request-level usage before and after rollout while monitoring answer quality. Report estimated avoided input cost separately from invoiced total cost.

Does this replace an agent-turn cap?

No. A bounded result can still be repeated across too many turns. Combine this control with a per-run call or turn ceiling and a retry budget so a loop cannot multiply otherwise small payloads.

Reader next step

Choose one high-volume client tool and instrument the boundary immediately before its result is returned to the model. Capture raw and forwarded sizes, item counts, a route-appropriate token estimate, the cap action, total request usage, and outcome quality over a representative window. Then set a provisional soft limit, exercise the happy and error paths, and approve a hard limit only after checking that required evidence survives reduction.

Use Trace CometAPI cost and usage for token budgets to connect these result records to the wider ledger. If repeated calls are the larger risk, pair the policy with agent per-run call budget guardrails .

When the measurement contract and error path are ready, Start with CometAPI and verify the selected model’s current unit price before enabling the cap in production.