Tools perform operations, resources expose addressable context, and prompts provide reusable templates. Choose the primitive that matches semantics; do not turn every database record into a write tool or every policy into prompt text.
Select the Primitive
- Tool: parameterized lookup or action with validation and authorization.
- Resource: identifiable content such as
policy://returns/v8. - Prompt: optional reusable interaction template, never a security policy.
Version names and schemas. Descriptions should state what the capability does, prerequisites, side effects, and prohibited use. The server still enforces all constraints.
Separate Read, Draft, and Commit
Example:
resource policy://quotes/v3 → approved quote rules
tool get_catalog_item(sku) → read current facts
tool create_quote_draft(customer_ref, items) → DRAFT only
tool publish_quote → absent or separate approval service
prompt review_quote → formats an evidence-first review task
Resources require authorization too. Prompt templates may contain untrusted variables and must not reveal hidden server data.
Worked Example
A training business exposes a current course resource and prepare_enrollment_summary. The tool retrieves a server-fixed course fee and creates no payment or enrollment. It returns a draft with known and pending fields.
Tests verify the resource version, schema rejection, tenant isolation, absence of publish capability, and truthful error when the course is unavailable.
Also test capability discovery so an accidental new tool or resource cannot appear unnoticed after a dependency or registration change.
Failure Cases to Diagnose
- Prompt claims it can authorize: authorization belongs to code.
- Resource exposes directory traversal: resolve predefined URIs.
- Tool mixes read and irreversible write: split stages.
- Description promises more than implementation: test semantics.
- Schema change is silent: version or preserve compatibility.
- Tool result contains secrets: return minimal fields.
Operator Note
Create a capability review sheet that renders example valid and invalid requests plus exact results. A non-developer product owner should be able to see whether a tool merely prepares a draft or commits an external action. This review catches misleading names such as save_quote when the implementation actually publishes and emails it. Rename capabilities until their effect is unmistakable.
🇵🇰 Pakistan Angle
Create resources for approved Pakistan-specific policies only when sourced and versioned. Do not publish copied private contracts or customer documents as broadly discoverable resources.
Payment, tax, property, legal, or medical tools should prepare evidence for a qualified human and authoritative service, never improvise final status.
Hands-On Exercise
- Classify five capabilities as tool/resource/prompt.
- Write versioned schemas and descriptions.
- split read, draft, and commit.
- Test authorization and compatibility.
- Inspect every returned field for necessity.
Completion Rubric
- Primitive matches semantics.
- Descriptions state effects and limits.
- Reads, drafts, and commits are separated.
- Resources and prompts are authorized/minimized.
- Schemas have compatibility policy.
- Sensitive output is excluded.
Sources
Key takeaway: model the true semantics with narrow, versioned primitives, and keep authorization and consequential commits outside descriptive prompt text.