CCA-F Certification Prep · lesson 4 of 10
Domain 2 — Tool Design & MCP Integration (18%)
How to define tools the LLM uses well, and how MCP fits in.
Topics
2.1 Tool description quality
- Description = teacher's note: "Use when X, don't use when Y."
- Disambiguate from sibling tools explicitly.
- Mention required params in description (model picks defaults better).
- Sub-500 tokens; long descriptions dilute.
2.2 Input schema design
- JSON Schema with
type,properties,required,enum,descriptionper property. - Enums beat free-form strings for fixed vocabularies.
- Nullable:
{"type": ["string", "null"]}. - Provide defaults for optional fields.
- Validate inputs at the tool boundary; return structured errors on violation.
2.3 Output design
- Return structured short results, not walls of text.
- Include IDs / timestamps for provenance.
- For large data: return a resource URI Claude can fetch on demand.
- Multimodal: tool results can include
imageblocks (screenshots from a browser tool, e.g.).
2.4 Tool choice control
auto— Claude decides (default).any— forces some tool call.{type: "tool", name}— forces specific tool (great for structured extraction).none— disables tools.
2.5 Parallel tool use
- Claude can return multiple
tool_useblocks per turn. - Server returns all
tool_resultin one user turn. - Encourage via independent tools + a system-prompt nudge.
2.6 Error responses (huge in this domain)
| Type | Retry? | Example message |
|---|---|---|
| transient | Yes | "Rate limited. retry_after_ms=2000." |
| permanent | No | "ticket-1234 not found." |
| validation | No (model must fix call) | "param id must be UUID." |
| uncertain | Defensive read first | "Payment status unknown; call check_payment before retrying." |
| user_declined | No | "User declined confirmation." |
| unavailable | Maybe (after delay) | "Service down for maintenance until 14:00." |
Always include is_error: true and a model-readable message.
2.7 MCP primitives — who decides
- Tools: model-controlled.
- Resources: application-controlled (the host attaches them).
- Prompts: user-controlled (slash commands).
Choosing the right primitive is a frequent question.
2.8 MCP trust & configuration
- Config scopes: project-local > project-shared > user > enterprise.
- Destructive tools should require user confirmation.
- Use scoped credentials (least privilege).
- Never put plaintext secrets in config; use env-var substitution.
2.9 MCP transports
- stdio: local subprocess. Easy. No auth.
- SSE: legacy remote.
- Streamable HTTP: current remote standard. OAuth 2.1.
Common question shapes
- "Which MCP primitive for [scenario]?" → tool / resource / prompt mapping.
- "Tool keeps getting called for the wrong question — what's the fix?" → Improve description; add explicit "don't use when".
- "Tool returned an error. What should the agent do?" → Distinguish transient/permanent/uncertain; choose retry vs adapt vs escalate.
- "How to expose internal MCP server to multiple users without local install?" → Streamable HTTP + OAuth.
- "Tool returns 20KB JSON. How to keep context lean?" → Return resource URI.
Cheatsheet
- One tool, one verb.
- Description is the prompt.
- Enums > strings, optional > required.
- Errors are structured and model-readable.
- Resources for read, tools for do, prompts for user-invoked templates.