Skip to content

[Bug] Tool schema exposes *args/**kwargs as model-facing parameters (e.g. ClickUpTools.update_task requires kwargs) #11132

Open

Description

@BlueX888

[Bug] Tool schema exposes *args/**kwargs as model-facing parameters (e.g. ClickUpTools.update_task requires kwargs)

Bug

_derive_entrypoint_schema derives a tool's model-facing JSON schema from the entrypoint signature without consulting inspect.Parameter.kind, so *args / **kwargs parameters are advertised to the LLM as ordinary properties — and, since a variadic parameter never has a default, as required properties.

Two shipped tools are affected (verified on main at 6e434823):

Tool Signature Advertised required
ClickUpTools.update_task (libs/agno/agno/tools/clickup.py:222) def update_task(self, task_id: str, **kwargs) -> str ["task_id", "kwargs"]
EmailTools.email_user (libs/agno/agno/tools/email.py:30) def email_user(self, subject: str, body: str, **kwargs) -> str ["subject", "body", "kwargs"]

The advertised kwargs property is an empty schema {} — no type, no description — so the schema demands an argument the model cannot fill meaningfully. The same happens for any user-defined toolkit entrypoint that uses *args or **kwargs.

Why this confuses the model

  • A schema-following model supplies what the schema asks for and nests the real payload inside it: update_task(task_id=..., kwargs={"name": "New title"}). FunctionCall.execute() forwards the model's arguments verbatim to the entrypoint, so the keyword kwargs is captured by the entrypoint's **kwargs under the literal key "kwargs". Verified on main: for def update(task_id, **fields), the schema-following call update(task_id="abc", fields={"name": "New title"}) succeeds but the entrypoint receives fields == {"fields": {"name": "New title"}}. ClickUpTools.update_task forwards that dict as the request body (data=kwargs, clickup.py:232), so ClickUp receives {"kwargs": {"name": "New title"}} — the fields the model meant to set are nested one level too deep and are not applied. No error is raised anywhere; the update is silently wrong.
  • For *args the advertised call cannot be made at all: def collect(label: str, *items: str) advertises items as a property, and passing items=[...] fails with pydantic ValidationError: Unexpected keyword argument — the tool call fails every time the model follows the schema.
  • The call path itself already refuses to bind variadics by name (_build_entrypoint_args, libs/agno/agno/tools/function.py:2329 skips VAR_POSITIONAL / VAR_KEYWORD / POSITIONAL_ONLY), so the schema describes a call the framework never makes.

Root cause

In libs/agno/agno/tools/function.py (_derive_entrypoint_schema, line 586 at 6e434823):

  • line 627 builds excluded_params from framework-injected names only — inspect.Parameter.kind is never consulted;
  • line 656 passes every non-excluded signature name to get_json_schema, so *items / **fields become properties;
  • line 695 (non-strict) marks every parameter without a default as required, and a variadic never has a default.

Minimal repro

Runnable standalone against main (6e434823):

from agno.tools.function import Function

def collect(label: str, *items: str) -> str:
    """Collect items under a label.

    Args:
        label: The label.
        items: The items to collect.
    """
    return f"{label}:{items}"

def update(task_id: str, **fields) -> str:
    """Update a task.

    Args:
        task_id: The task to update.
    """
    return f"{task_id}:{fields}"

for ep in (collect, update):
    func = Function(name=ep.__name__, entrypoint=ep)
    func.process_entrypoint()
    print(ep.__name__, sorted(func.parameters["properties"]), func.parameters["required"])

Output on main:

collect ['items', 'label'] ['label', 'items']
update ['fields', 'task_id'] ['task_id', 'fields']

Expected: a variadic parameter can never be passed as a named argument, so its name must not appear in properties or required (collect ['label'] ['label'], update ['task_id'] ['task_id']).

The same check against the shipped toolkits (no network access needed — only schema derivation runs):

from agno.tools.clickup import ClickUpTools
from agno.tools.email import EmailTools

fn = EmailTools().functions["email_user"]
fn.process_entrypoint()
print(fn.parameters["required"])  # main: ['subject', 'body', 'kwargs']

fn = ClickUpTools(api_key="x", master_space_id="y").functions["update_task"]
fn.process_entrypoint()
print(fn.parameters["required"])  # main: ['task_id', 'kwargs']

Evidence

  • On main (6e434823) the regression test test_variadic_params_are_never_advertised_as_model_arguments fails with AssertionError: assert {'items', 'label'} == {'label'} — the *items name leaks into properties.
  • With the fix the same test passes, and the shipped tools advertise required: ['task_id'] for ClickUpTools.update_task and required: ['subject', 'body'] for EmailTools.email_user, so the model sends the field names directly and update_task PUTs the intended body.

A fix is being prepared in PR #10271, which will link back to this issue.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions