diff --git a/pydantic_ai/tool_definition.yaml b/pydantic_ai/tool_definition.yaml index 2fb6011..91e0ee4 100644 --- a/pydantic_ai/tool_definition.yaml +++ b/pydantic_ai/tool_definition.yaml @@ -62,3 +62,34 @@ rules: list[str], a Pydantic model, etc.). Pydantic AI propagates these annotations into the schema the model sees, so the model emits correctly-shaped arguments and validation stops rejecting them. + + - id: PYD-013 + title: Ambiguous Pydantic AI tool name + severity: low + confidence: 0.9 + language: python + applies_to: + - pydantic_ai_tool + scope: tool + match: + name_in: + - process + - handle + - run + - do + - execute + - perform + - work + - go + - thing + - stuff + explanation: > + The tool name is a generic verb that says nothing about what the tool + acts on. The name sits directly beside the description in what the model + sees, so it is half the selection signal, and a name like process or + handle spends that half on nothing — the model either calls the tool for + the wrong job or passes over it entirely. Pydantic AI derives the tool name from the function name unless one is passed explicitly, so a generically named function silently becomes a generically named tool. + fix: > + Rename to a verb-object form that names the thing acted on: + summarize_invoice, refund_charge, fetch_order_status. Keep the + description for the detail and let the name carry the subject.