Stable tool naming and error semantics keep Agent Skills, MCP clients, and REST docs aligned as the catalog grows.
Naming
| Pattern | Example | Rule |
|---|---|---|
{verb}_{resource} |
list_vendors, get_rfx |
Prefer REST-like verbs |
| Server prefix only if required | docs_search |
Avoid colliding ids across servers |
| No silent renames | — | Deprecate → dual-support → remove |
Inputs & outputs
- Arguments must match tool JSON Schema; reject unknown fields when strict mode is on.
- Prefer Tradeics REST envelopes where tools wrap HTTP (
error,reason,data). - Pagination:
page(required, ≥ 1) and optionalpage_size— same as REST guides.
Errors
| Situation | Tool behavior |
|---|---|
| Auth failure | Clear unauthorized error; no partial data |
| Missing scope | Forbidden with scope hint |
| Validation | 422-equivalent message naming the field |
| Rate limit | Retryable signal aligned with REST 429 |
Idempotency
Mutating tools should accept an optional idempotency key (placeholder name Idempotency-Key / idempotency_key) once Platform write tools GA.
Versioning
- Additive tools: non-breaking.
- Renames / removals: announce in Platform changes and keep aliases for one release window.
- Skills must update checklists in the same release.