## Tool Schema Anti-Patterns

### Naming and scoping
| Anti-pattern | Why it fails | Fix |
|---|---|---|
| `get_events_today` / `_tomorrow` / `_next_week` | Litters tool space | `get_calendar_events(date_or_range)` |
| `getData` / `doThing` | Vague, model can't choose | Descriptive verb_noun |
| `userId` vs `user_id` vs `uid` | Inconsistent concept mapping | Standardize one form across ALL tools |

### Parameter anti-patterns
| Anti-pattern | Why it fails | Fix |
|---|---|---|
| No `enum` on mode/status/type | Model emits free-text garbage | Explicitly enumerate valid values |
| Too many `required` fields | Each is a failure point | Make optional what can be defaulted/deferred |
| No per-parameter `description` | Model guesses field meaning | Document every parameter |
| No unit hint on numeric/date | Model emits unparseable values | "duration_ms", "ISO 8601 date" |

### Overlap anti-pattern
Two tools whose names/descriptions are near-identical -> model picks randomly.
**Fix**: add explicit boundary annotation in each description:
```
"Use ONLY for product search. For order status, call get_order_status."
```

### Error-surface anti-pattern
Returning a bare exception string -> model retries blindly or hallucinates cause.
**Fix**: structured error shape the model can reason about:
```json
{"status": "error", "error": "NOT_FOUND", "detail": "No order with id 42", "next_step": "Check the order id and retry"}
```

### Tool-count warning
Research shows tool-selection accuracy DEGRADES as tool count grows.
- ~10-15 tools: reliable
- ~30+ tools: selection errors climb sharply
- Consider grouping related tools or an explicit router/classifier

### JSON Schema quick reference
```json
{
  "name": "search_products",
  "description": "Search products by keyword... Use ONLY for product search.",
  "parameters": {
    "type": "object",
    "properties": {
      "keywords": {"type": "string", "description": "Search terms, e.g. 'wireless headphones'"},
      "max_price": {"type": "number", "description": "Maximum price in USD"},
      "in_stock": {"type": "boolean", "description": "Only show in-stock items"}
    },
    "required": ["keywords"]
  }
}
```