Opt-in tool_call_id injection into tool execution

[ypicard]

A tool that indexes documents needs to know which tool call it is serving, so a UI can show which search found which papers. Aviary knows that ID but never hands it to the tool. Environments work around this by scanning the whole corpus after every step and diffing it against the previous one.

A tool function can now declare tool_call_id: str and get the ID of the call it is running:

async def paper_search(query: str, state: MyEnvState, tool_call_id: str) -> str:
    """Search for papers.

    Args:
        query: Search query.
    """
    state.candidates[tool_call_id] = await index(query)

This works like state. Declare the parameter to opt in. Leave it out and nothing changes.

Tool.from_function skips it when building the JSON schema, right next to the state skip, so the model never sees it and cannot send it. If a model sends one anyway, the injected ID wins.

_exec_tool_call already runs once per call, so concurrent calls each get their own ID. No globals. argref_by_name passes the value through instead of treating it as a reference key.

Pairs with #349, which made the ID settable on ToolCall.from_name.

[Copilot]

Pull request overview

This PR adds an opt-in mechanism for tool functions to receive the current ToolCall.id via a tool_call_id: str parameter, enabling tools (e.g., indexing/search tools) to key work/results to the specific tool call that produced them while keeping the parameter hidden from the LLM-facing schema.

Changes:

• Add tool_call_id injection in Environment.exec_tool_calls() when the tool function declares it.
• Hide tool_call_id from Tool.from_function JSON schema generation and skip it in argref_by_name reference handling.
• Add tests and documentation describing the new injected parameter behavior.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/test_tools.py	Adds coverage for schema hiding, injection into async/sync/state/method tools, concurrency behavior, and spoofing override.
src/aviary/tools/base.py	Updates Tool.from_function to exclude tool_call_id from the LLM-facing schema (like state).
src/aviary/tools/argref.py	Ensures tool_call_id is not treated as an argref key when using argref_by_name.
src/aviary/env.py	Injects the tool call ID into tool execution when the signature declares tool_call_id.
README.md	Documents the new optional tool_call_id: str injected parameter for tools.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[sidnarayanan]

Not sure I appreciate the difference: state is dropped but tool call id is injected? Do they not behave the same?