feat(claude_sdk): add tool description quality rules (Queens paper)

claude_sdk/tool_definition.yaml

@@ -131,3 +131,55 @@ rules:
       Pass a clear one-line description as the second argument to
       `tool(name, description, schema, handler)`, stating what the tool does,
       what it returns, and when the model should reach for it.
+
+  - id: CSDK-017
+    title: Tool description is a placeholder
+    severity: low
+    confidence: 0.85
+    language: python
+    applies_to:
+      - claude_sdk_tool
+    scope: tool
+    match:
+      has_description_text:
+        - todo
+        - tbd
+        - fixme
+        - placeholder
+        - no description
+        - does stuff
+    explanation: >
+      The description passes the has-docstring check but carries a
+      placeholder marker instead of real content. The Claude Agent SDK
+      forwards this text to the model verbatim as the tool's selection
+      signal, so a stub like "TODO: describe this tool" is functionally
+      indistinguishable from no description at all — the model still has to
+      guess from the function name, causing mis-selection under ambiguous
+      prompts.
+    fix: >
+      Replace the placeholder with a real one-paragraph description covering
+      what the tool does, what it returns, and when the model should call it.
+
+  - id: CSDK-018
+    title: Tool description is too short to guide model selection
+    severity: low
+    confidence: 0.8
+    language: python
+    applies_to:
+      - claude_sdk_tool
+    scope: tool
+    match:
+      all:
+        - has_docstring: true
+        - description_length_lt: 40
+    explanation: >
+      A description under 40 characters is rarely enough to convey what a
+      tool does, what it returns, and when to call it versus a similarly
+      named neighbor. The Claude Agent SDK passes this text to the model as
+      its only selection signal, so a stub like "Gets data." leaves the
+      model to guess at scope and preconditions, which causes mis-selection
+      or missed calls under ambiguous prompts.
+    fix: >
+      Expand the description to at least a full sentence covering inputs,
+      outputs, and the situation in which this tool should be used over
+      alternatives.

manifest.yaml

@@ -11,4 +11,4 @@
 #
 # This file is metadata, not a rule: the engine's loader skips manifest.yaml
 # when walking the pack for policy files.
-schema_version: 13
+schema_version: 14