From f7f4797d457b118915d6cf37e003f14661fbb915 Mon Sep 17 00:00:00 2001
From: bradAGI <46579244+bradAGI@users.noreply.github.com>
Date: Mon, 24 Aug 2026 15:15:09 -0400
Subject: [PATCH] feat(pydantic_ai): add PYD-013, ambiguous tool name

Ports the ambiguous-name check to pydantic_ai. Claude SDK (CSDK-007), OpenAI
(OAI-007), ADK (ADK-007), and MCP (MCP-003) all ship it; the five newer
packs had none.

The tool name sits directly beside the description in what the model sees,
so it is half the selection signal, and a generic verb like process or
handle spends that half on nothing.
---
 pydantic_ai/tool_definition.yaml | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

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.