Spot the bug in this LangChain `@tool` definition that uses a free-form docstring with no type hints

**The bug.** The function `lookup_user(query)` has no type annotation on `query` and no `Args:` section in the docstring describing what `query` should be. **What `@tool` does under the hood.** It introspects the function's signature and docstring to build a JSON Schema that's sent to the LLM as part of the tool definition. The schema becomes the model's instructions for how to call the tool. With no annotation, LangChain infers `query` as an untyped slot (effectively `any` or a permissive string). The docstring becomes the tool's overall description, but there is no per-parameter description because the docstring isn't formatted as an `Args:` block. **Why this breaks at runtime.** The model sees a tool called `lookup_user` whose description says "by name, email, or id" but whose schema gives no type or per-arg guidance. It guesses. Sometimes it passes a string `"jane@acme.io"` and the call works. Other times it passes a structured object `{"email": "jane@acme.io"}` because the description suggested multiple fields. Your function receives the wrong shape and either errors or silently misbehaves. **The fix.** ```python @tool def lookup_user(query: str) -> dict: """Look up a user by name, email, or id and return their profile. Args: query: The user's name, email address, or numeric id. """ return user_service.search(query) ``` Now the schema has `query: string` with a description. The model passes a string every time.

**The bug.** `@tool` infers its JSON Schema from the function signature and docstring. With `query` untyped and no `Args:` section, the generated schema has an untyped parameter and no per-arg description. The model gets a tool definition like `{ name: "lookup_user", description: "...", parameters: { query: any } }` and has to guess what `query` should be. **Concrete failure modes.** The model often passes a structured object instead of a plain string because the description ("by name, email, or id") suggests multiple distinct fields. Your function gets `{"email": "jane@acme.io"}` instead of `"jane@acme.io"` and silently misbehaves (`user_service.search` receives a dict and returns nothing, or errors). With newer models you might get lucky and consistently see strings, but the schema is still wrong and the next prompt phrasing or model upgrade can break it. **Two fixes.** **Fix 1: proper annotations + Google-style docstring.** ```python @tool def lookup_user(query: str) -> dict: """Look up a user by name, email, or id and return their profile. Args: query: The user's name, email address, or numeric id. """ return user_service.search(query) ``` Now the schema has `query: string` with a description, and the model has clear guidance. **Fix 2: explicit `args_schema` for richer constraints.** ```python from pydantic import BaseModel, Field class LookupUserArgs(BaseModel): query: str = Field(description="The user's name, email, or numeric id.") @tool(args_schema=LookupUserArgs) def lookup_user(query: str) -> dict: """Look up a user by name, email, or id.""" return user_service.search(query) ``` This lets you add Pydantic validators, enums, regex patterns, and richer per-field guidance. **The lesson.** `@tool` is only as good as the type information it can introspect. Treat the function signature and docstring as the model's API contract, not as developer documentation.