fix(tools): support positional-only parameters in beta_tool

[azrabano23]

What was wrong

@beta_tool / @beta_async_tool on a function with a positional-only parameter produced an invalid schema and an uncallable tool, without any error at decoration time:

@beta_tool
def lookup(user_id: int, /, field: str = "name") -> str:
    """Look up a field on a user record."""
    return f"{user_id}:{field}"

lookup.input_schema
# {"maxItems": 2, "minItems": 1, "prefixItems": [...], "type": "array"}
lookup.call({"user_id": 7, "field": "email"})
# ValueError: Invalid arguments for function lookup
#   (2 validation errors: missing_positional_only_argument, unexpected_keyword_argument)

def collect(*values: int) produced {"items": {"type": "integer"}, "type": "array"} the same way. InputSchema requires type: "object", so both schemas are rejected by the API, and the positional-only tool could never be invoked by the tool runner even with a hand-written input_schema=.

Root cause

_create_schema_from_function delegates to pydantic's GenerateJsonSchema.arguments_schema, which renders the positional (array) form whenever a signature has positional-only parameters or *args and no keyword-only ones, so the docstring hook in kw_arguments_schema never runs for those signatures. call() then forwards the input object purely by keyword, which a positional-only parameter cannot accept.

The fix

Tool inputs are JSON objects passed by name, so:

• CustomGenerateJsonSchema.arguments_schema is overridden to render positional-only parameters as ordinary named properties. The schema for lookup above is now identical to the one for def lookup(user_id: int, field: str = "name").
• BetaFunctionTool.call / BetaAsyncFunctionTool.call route positional-only values back into positional slots (_split_input). Missing or unexpected values are still left to validate_call, so the existing ValueError("Invalid arguments for function ...") behaviour is unchanged.
• *args, which a JSON object cannot represent, now raises a TypeError at decoration time. This is the one behavioural change for existing code: such a tool previously constructed successfully but carried an array schema the API cannot accept.

signature() failures (builtins, some callables) fall back to the previous behaviour, and the lazily-entered @asynccontextmanager path is unaffected since its wrapper only takes **kwargs.

Verification

CPU only, no API calls. From the repo root with a uv venv (Python 3.12, pydantic 2.13.5):

python -m pytest tests/lib/tools -q -o addopts="--tb=short -p tests._alias_httpx"
# 431 passed, 1 skipped, 1 xfailed
ruff check src/anthropic/lib/tools/_beta_functions.py tests/lib/tools/test_functions.py   # All checks passed
ruff format --check src/anthropic/lib/tools/_beta_functions.py tests/lib/tools/test_functions.py
pyright src/anthropic/lib/tools/_beta_functions.py tests/lib/tools/test_functions.py     # 0 errors

The four new tests (test_positional_only_parameters, test_positional_only_with_keyword_only_parameters, test_async_positional_only_parameters, test_var_positional_parameter_raises) fail on main and pass with this change.

Fixes #1911

🤖 Generated with Claude Code