langchain-ai/deepagents · error · ValueError

Context tool names conflict with rubric-grader tools: {names

Error message

Context tool names conflict with rubric-grader tools: {names}.

What it means

`_with_context_tools` merges caller-supplied context tools into the rubric grader's tool list, but tool names must be unique in an agent's tool registry. It reserves `GraderResponse` plus the grader's own tool names (e.g. the prefixed `read_file`) and raises ValueError if any context tool shares one of those names (or duplicates another context tool).

Source

Thrown at libs/code/deepagents_code/agent.py:661

                runtime=runtime,
                offset=offset,
                limit=clamped["limit"],
            ),
        )

    normalized_context_tools = _normalize_rubric_grader_context_tools(context_tools)

    def _with_context_tools(grader_tools: list[BaseTool]) -> list[BaseTool]:
        reserved_names = {"GraderResponse", *(tool.name for tool in grader_tools)}
        conflicts: list[str] = []
        for context_tool in normalized_context_tools:
            if context_tool.name in reserved_names:
                conflicts.append(context_tool.name)
            reserved_names.add(context_tool.name)
        if conflicts:
            names = ", ".join(sorted(set(conflicts)))
            msg = f"Context tool names conflict with rubric-grader tools: {names}."
            raise ValueError(msg)
        return [*grader_tools, *normalized_context_tools]

    grader_tools: list[BaseTool] = [read_file]
    if bounds is None:
        return _with_context_tools(grader_tools)

    # `bounds` is available: expose whichever working-directory search tools the
    # parent allowlist permits. `read_file`'s working-directory branch is gated
    # separately (above) on the allowlist including `read_file`, so `ls`,
    # `glob`, and `grep` remain available even when `read_file` is excluded.
    active_bounds = bounds

    repository_wrapper_tools: list[BaseTool] = []

    if "ls" in repository_tools:
        fs_ls = cast("StructuredTool", repository_tools["ls"])
        fs_ls_func = _fs_func(repository_tools, "ls")

View on GitHub (pinned to a1af029e6e)

Solutions

  1. Rename the conflicting context tool so its `.name` differs from `GraderResponse` and all grader tool names.
  2. Remove the context tool that duplicates a grader tool — the grader already exposes its own read_file.
  3. If a tool's name is auto-derived from its schema, rename the schema/model instead of the tool instance.

Example fix

// before
class GraderResponse(BaseModel):
    ...
context_tools = [my_read_file_tool]  # name collides
// after
class RubricContextResponse(BaseModel):
    ...
context_tools = [build_tool(RubricContextResponse, name="rubric_context")]
Defensive patterns

Strategy: validation

Validate before calling

RESERVED = {"GraderResponse", "read_file"}
names = [t.name for t in context_tools]
dupes = RESERVED & set(names)
assert not dupes, f"Rename context tools colliding with grader tools: {sorted(dupes)}"
assert len(names) == len(set(names)), "Context tools contain duplicate names"

Try / catch

try:
    agent = create_cli_agent(..., context_tools=context_tools)
except ValueError as e:
    if "Context tool names conflict" in str(e):
        print(f"Rename these tools: {e}")
    raise

Prevention

When it happens

Trigger: Calling `create_cli_agent` (or the rubric-grader builder) with context tools whose `.name` equals `GraderResponse`, the grader's read_file tool name (e.g. under a `read_file_prefix`), or duplicates another context tool — e.g. passing a custom tool named `read_file` or `GraderResponse` in `context_tools`.

Common situations: Wrapping an SDK filesystem tool and passing it back as a context tool; defining a pydantic tool whose schema name collides with `GraderResponse`; copying tool lists between agents without renaming.

Related errors

AI-assisted analysis of langchain-ai/deepagents@a1af029e6e (2026-08-29). Data as JSON: /api/errors/6d14b428ad2f1335. Report an issue: GitHub.