@tool stamps a plain return value as status=success: returning a ToolResult that reports the real outcome

[auxiliar-ag]

I spent a while this week reading strands/tools/decorator.py in the Python SDK, and one detail changed how I write tools that call the outside world.

DecoratedFunctionTool._wrap_tool_result has two branches. If the returned object is a dict carrying both status and content, it is treated as a ToolResult and passed through. Everything else — a string, a number, a Pydantic model, and also a dict like {"ok": False, "error": "blocked"} that has neither key — is serialised and stamped with "status": "success". There is no inspection of what came back. A scraper that returns a cookie wall, a search wrapper that returns zero hits, a fetch that returns an empty string: all of them reach the model as a successful tool call. I pinned that against the installed package rather than trusting my reading of it, in tests/test_framework_contract.py:

    @tool
    def naive_fetch(url: str) -> str:
        """Return whatever the page said.

        Args:
            url: Page to fetch.

        Returns:
            The body text.
        """
        return COOKIE_WALL

    result = await run_tool(naive_fetch, {"url": "https://example.test/docs"}, {})

    assert result["status"] == "success"
    assert result["content"] == [{"text": COOKIE_WALL}]

COOKIE_WALL is the string "Just a moment... Enable JavaScript and cookies to continue.". The tool ran, so the framework says success. That is the correct framework behaviour, because @tool cannot know what your task needed. It does mean the judgement has to live in the tool.

Everything below is against strands-agents==1.51.0 (published 2026-08-07, tag python/v1.51.0), on Python 3.11.

The branch that lets a tool speak for itself

The passthrough branch is the way out. A dict carrying both status and content is handed back as the ToolResult essentially unchanged: the framework overwrites toolUseId with the real one and leaves the rest alone. So a tool that wants to report a failed task returns the mapping itself:

    return {
        "status": "success" if ok else "error",
        "content": [{"json": receipt}, {"text": summary}],
    }

ToolResultContent in strands/types/tools.py allows json, text, image and document blocks, so the first block can be structured data rather than prose. That is the whole idea here: block zero is always a machine-readable receipt describing what the tool actually achieved, and block one is the payload or a short failure line.

Keeping the transport out of the model's reach

The tool takes a URL and pass criteria. It does not take providers, clients, keys or timeouts, because anything in the signature becomes part of the JSON schema the model gets to fill in. Providers arrive instead through the agent's invocation state, which @tool(context=True) exposes:

@tool(context=True)
def verified_web_lookup(
    url: str,
    tool_context: ToolContext,
    must_contain: str | None = None,
    min_chars: int = 40,
    max_attempts: int = DEFAULT_MAX_ATTEMPTS,
) -> dict[str, Any]:

    providers = list(tool_context.invocation_state.get(PROVIDERS_KEY, []))
    ceiling = min(max(1, max_attempts), MAX_ATTEMPT_CEILING)
    budget = min(ceiling, len(providers))

Three things about ToolContext that cost me time:

• It is a @dataclass, so it is tool_context.tool_use["toolUseId"], not tool_context["tool_use"]["toolUseId"]. The example in the @tool docstring in 1.51.0 still shows the subscript form, which raises TypeError: 'ToolContext' object is not subscriptable.
• inject_special_parameters reads invocation_state["agent"] with an unguarded subscript. A real Agent sets that key itself, but if you drive a context=True tool directly in a test you have to supply it or you get a confusing KeyError: 'agent' reported as a tool error.
• The injected parameter is excluded from the advertised inputSchema, which is what makes this a safe capability channel rather than just another argument.

On the caller side, pass capabilities as invocation_state=, not as loose keyword arguments. Bare **kwargs on Agent.invoke_async still work in 1.51.0, but they emit a warning that the parameter is deprecating. It is raised with no category, so it arrives as a UserWarning rather than a DeprecationWarning, which matters if you filter warnings by category in CI:

    agent = Agent(
        model=ScriptedModel(_lookup_turns({"url": DOCS_URL, "must_contain": "@tool"})),
        tools=[verified_web_lookup],
    )

    await agent.invoke_async("look up the docs", invocation_state={"web_fetch_providers": providers})

The receipt

The receipt is a TypedDict with a version marker, so a consumer can tell when the shape changes:

    schema: str
    ok: bool
    url: str
    attempts: int
    max_attempts: int
    providers_available: int
    provider_used: str | None
    fallback_used: bool
    failure_reason: str | None
    content_chars: int
    attempts_log: list[AttemptRecord]

Each entry in attempts_log records provider, outcome, http_status and a short detail. outcome is a Literal of ok, transport_error, http_error, unusable_content and malformed_response, which keeps the two failure families distinct: the request never landed, versus the request landed and the body was useless.

One naming caveat, since a receipt is meant to be read by something other than its author: fallback_used means "more than one provider was attempted", not "a fallback rescued the call". After two failed attempts it is true while provider_used is null. provider_used is the field that answers who actually produced the content.

A run where the primary returns HTTP 200 with an interstitial and the fallback returns the real page produces this:

{
  "schema": "verified_web_lookup.receipt/v1",
  "ok": true,
  "url": "https://example.test/strands/tools",
  "attempts": 2,
  "max_attempts": 2,
  "providers_available": 2,
  "provider_used": "backup",
  "fallback_used": true,
  "failure_reason": null,
  "content_chars": 169,
  "attempts_log": [
    {
      "provider": "primary",
      "outcome": "unusable_content",
      "http_status": 200,
      "detail": "interstitial page detected ('just a moment')"
    },
    {
      "provider": "backup",
      "outcome": "ok",
      "http_status": 200,
      "detail": "usable content"
    }
  ]
}

The ToolResult.status for that run is success, and the model can still see that the primary failed and why. When every attempt fails, status is error, ok is false, failure_reason is one of no_providers_configured, all_providers_failed or attempt_budget_exhausted, and no page text is returned at all.

Two details worth stealing regardless of the rest. max_attempts is a model-facing parameter, so it is clamped into a fixed range before use; a model asking for 99 attempts gets the library ceiling. And a provider that returns something other than the declared response type is classified as malformed_response rather than raising, because an AttributeError escaping the tool tells the model nothing useful.

Redaction, because the error path is model-visible

DecoratedFunctionTool.stream catches exceptions and formats them as f"Error: {error_type} - {error_msg}" in the result content. That string goes into the conversation. Provider errors habitually quote the full request URL, and request URLs habitually carry keys, so an uncaught exception is a credential disclosure into model context and then into whatever stores that transcript.

So the tool catches provider exceptions itself and scrubs before recording:

    for provider in providers[:budget]:
        name = str(getattr(provider, "name", type(provider).__name__))
        try:
            response = provider.fetch(url)
        except Exception as exc:
            attempts_log.append(
                AttemptRecord(
                    provider=name,
                    outcome="transport_error",
                    http_status=None,
                    detail=_truncate(redact_text(f"{type(exc).__name__}: {exc}"), MAX_DETAIL_CHARS),
                )
            )
            continue

redact_text and redact_url blank sensitive query-string values and a handful of well-known token shapes, and the same scrubbing runs over the URL echoed in the receipt and over the returned page text. It is a coarse net in both directions. It misses opaque session identifiers, since names such as session, sid, cookie and state are not on the sensitive-key list, and it misses a short all-alphabetic secret, since the value heuristic wants a digit, a separator or real length. It also over-matches, which is why I keep a test asserting that ordinary prose such as Authentication: required. survives untouched: an over-eager redactor quietly corrupts the content you fetched.

Testing it with no model and no network

AgentTool.stream is the interface the event loop uses, and its last event is the ToolResultEvent. Driving a tool through it exercises input validation, context injection and result wrapping without a model:

    state = dict(invocation_state)
    state.setdefault("agent", agent)
    stream = agent_tool.stream(
        {"toolUseId": tool_use_id, "name": agent_tool.tool_name, "input": tool_input},
        state,
    )
    events = [event async for event in stream]
    return events[-1].tool_result  # type: ignore[no-any-return]

For the full loop I use a small Model subclass that replays canned assistant turns as stream events, in the same spirit as the SDK's own strands-py/tests/fixtures/mocked_model_provider.py. That covers tool-spec advertisement, the tool use, and the ToolResult going back into the conversation, still with no credentials and no sockets. The providers are plain objects with a fetch method that return a scripted response, raise a scripted exception, or deliberately return the wrong type.

What this is and is not

This is a pattern, not a package. There is no NativePort integration for Strands and nothing here is an official Strands component; it is ordinary application code you would paste into your own repository and adapt. The code blocks above are excerpts from the modules I run locally, quoted inline in this post; they are not attached to it, and a fence on its own is not a runnable file. verified_web_lookup alone needs four neighbours to run — providers, receipt, redaction and validation — and the test excerpts need the harness and fakes as well.

Known limits: the usability check is deliberately crude (length, interstitial markers, one required substring) and belongs to the calling application, not the framework; redaction is pattern-based, with the specific gaps above; and the fallback ordering is static rather than health-aware.

Disclosures

I work on NativePort, which routes agents to 32 provider-native APIs behind one key and one credit balance and passes per-call provider prices through without a per-request markup. That is the only reason multi-provider fallback is on my mind at all, and it is why the receipt tracks which provider answered. How we measure providers is written up at our measurement methodology. Nothing in this post requires NativePort, and the fakes in the tests are the only providers involved.

I used an AI assistant while reading the SDK source and drafting both the code and this write-up. Every claim in this post about how Strands behaves is asserted in a test against strands-agents==1.51.0, because that is the only way I would trust either of us on it. That includes the small ones it would be easy to assert from memory: the docstring text, the ToolResultContent key set, the Bedrock request formatter and the tool-call span all have their own assertions. Exactly one claim is source-reading rather than execution: the Anthropic model's is_error mapping, because the anthropic extra is not installed in my environment. It is marked inline where it appears.

Getting that sentence right took three attempts, so here is how it is now checked rather than asserted. A test holds a table mapping every SDK claim in this post to the test functions that execute it, and a second table holds the read-only ones; the suite fails if a named test does not exist, or if the number of read-only claims stops matching the number of inline markers in this text. The suite is also hermetic by construction: a fail-closed guard raises on any outbound socket, and a second guard raises if anything asks botocore to resolve credentials, so the Bedrock tests cannot quietly reach the EC2 metadata service the way an earlier draft of them did.

One question

For the failure case I return status="error" with the receipt in a json block and no page text, on the theory that a model reasons better from an explicit failure than from a plausible-looking empty payload.

Working out what that choice actually costs took longer than writing the tool. As far as I can tell in 1.51.0, ToolResult.status is not a control-flow signal: after tool execution the loop calls recurse_event_loop unconditionally, and ModelRetryStrategy.is_retryable matches ModelThrottledException only, which concerns model calls rather than tool results.

Where it does land is three places, and the first surprised me. Reaching the model is conditional on Bedrock: _format_request_message_content forwards status only when _should_include_tool_result_status() is true, and the default "auto" setting resolves against _MODELS_INCLUDE_STATUS, which contains the single prefix anthropic.claude. So on Bedrock the status survives to Claude and is dropped for Nova, Llama, Mistral and DeepSeek unless you set include_tool_result_status=True. I ran the formatter across those model ids to check, with a boto session holding fake static credentials so nothing is resolved and no socket is opened — worth spelling out, because constructing BedrockModel without explicit credentials makes botocore walk the AWS credential chain and call the EC2 metadata service, which is how my first version of that test accidentally started talking to 169.254.169.254. The Anthropic model, by contrast, maps status to a tool-result is_error flag unconditionally — that line is the one claim in this post I read rather than ran. Second, status increments ToolMetrics.success_count or error_count. Third, it becomes gen_ai.tool.status on the tool-call span, and an error status ends that span with the first text block as its error message.

So the choice looks like a reporting decision rather than a loop-behaviour one, and a partly provider-dependent reporting decision at that. For a partially useful outcome — a page that came back genuinely thin rather than blocked — is the intended idiom in Strands to return status="success" and let the receipt carry the nuance, keeping the error counters for real failures? Or to return status="error", accept that it marks the result as an error in your metrics and traces and, on the models that forward it, to the model as well, and treat "thin" as a failure? I could not find guidance on where that line is meant to sit, and it changes both what a dashboard of tool error rates means and what some models are told.