Tool Templates

There are 3 tool templates included. A Fill-in-the-Blank template for intermediate to advanced users. A Minimal template for simple tools. And a template for Non-Coders.

Tool Definition Template: Fill-in-the-Blank Edition

Instructions: Replace all [BLANK] sections with your specific information. Delete optional sections if not needed. Copy this entire template for each tool you create.

BASIC INFORMATION

{
"name": "[TOOL_NAME]",
// Example: "send_email", "get_user_profile", "calculate_mortgage"

"description": "[ONE SENTENCE: What does this tool do?]",
// Example: "Sends an email to a specified recipient with subject and body"
// Example: "Retrieves a single user's complete profile from the database"
// Example: "Calculates monthly mortgage payment including principal and interest"

"class": "[A, B, or C]",
// A = Read-Only (no side effects, safe to use freely)
// B = State-Change (modifies data, requires confirmation)
// C = Computational (task exceeds Claude's reasoning capability)
}

TRIGGER LOGIC (When a Model Should Use This)

"trigger_logic": {
 "use_when": [
  "[Scenario 1: When should Claude use this tool?]",
  "[Scenario 2: Another situation where this tool is appropriate]",
  "[Scenario 3: Add more as needed]"
 ],

// Examples:
// - "User asks to send an email or message"
// - "User requests information about a specific person"
// - "User needs complex financial calculation"

"dont_use_when": [
 "[Scenario 1: When should Claude NOT use this? Use reasoning instead?]",
 "[Scenario 2: When should a different tool be used instead?]",
 "[Scenario 3: What edge cases fail?]"
]

// Examples:
// - "User is asking ABOUT email (explain, don't send)"
// - "General questions about users (use search_users for multiple)"
// - "Simple calculations Claude can do (e.g., 15% of 200)"
},

PARAMETERS (What Inputs Does This Tool Accept?)

"parameters": {
 "[parameter_name]": {
  "type": "[string/number/boolean/array/object]",
  "description": "[What is this parameter for?]",
  "required": [true/false],
  "example": "[Example value]",
  "constraints": "[Any validation rules? e.g., 'must be valid email format']"
},

// Repeat for each parameter

// Example:
// "email_address": {
// "type": "string",
// "description": "Recipient's email address",
// "required": true,
// "example": "<user@example.com>",
// "constraints": "Must be valid email format (<name@domain.com>)"
 }
},

NEGATIVE CONSTRAINTS (What a Model Should NEVER Do)

"negative_constraints": {
 "do_not": [
  "[Common mistake 1: What should Claude avoid?]",
  "[Common mistake 2: What input patterns cause failure?]",
  "[Common mistake 3: What behaviors cause loops?]"
],
// Examples:
// - "Do not execute with empty or null input (validate first)"
// - "Do not assume field names that aren't in the schema"
// - "Do not retry the same failed input without modification"

"safety": [
 "[Safety rule 1: What data should never be exposed?]",
 "[Safety rule 2: What are the rate limits?]",
 "[Safety rule 3: What are the timeout thresholds?]"
]
// Examples:
// - "Never return password or API key fields in responses"
// - "Limit to 100 results maximum"
// - "Timeout after 5 seconds"
},

RETURN CONTRACT (What to Expect When the Tool Runs)

**Success Case:**
 "return_contract": {
  "success": {
   "type": "[object/array/string/number/boolean]",
   "description": "[What does successful output look like?]",
   "schema": {
   "[field_name]": "[field_type and description]"
   // Example: "message_id": "string - unique identifier for sent message"
},
   "example": {
   // Paste a real example of successful output here
   // Example: {"sent": true, "message_id": "msg_abc123"}
  }
},
Failure Cases:
  "failure_modes": {
   "[error_type_1]": {
    // Example: "invalid_email", "rate_limit", "timeout"

    "error": "[Human-readable error message]",
    // Example: "Recipient email format is invalid"

    "recovery_action": "[What should Claude DO when this happens?]",
    // Example: "Ask user to verify email address format"

    "retry": [true/false],
    // true = Claude should retry automatically
    // false = Claude should NOT retry (ask user for help)

    "user_action": "[What should Claude tell the user?]"
    // Example: "Please provide email in format: name@domain.com"
},

    // Copy this block for each error type
    "[error_type_2]": {
    "error": "[What went wrong?]",
    "recovery_action": "[What should Claude do?]",
    "retry": [true/false],
    "user_action": "[What to tell user?]"
   }
 }
}

COMPOSITION (Optional: How This Tool Relates to Others)

"composition": {
 "typically_followed_by": [
 "[tool_name_1]",
 "[tool_name_2]"
],
// Examples of tools that usually run AFTER this one
// Example: After "create_user", you typically run "send_welcome_email"

"prerequisites": [
 "[tool_name_that_must_run_first]"
],

// Tools that MUST run successfully before this one
// Example: "build_app" must run before "deploy_app"

"conflicts_with": [
 "[tool_name_that_cant_run_simultaneously]"
]
// Tools that should NOT run at the same time as this one
// Example: "delete_user" conflicts with "create_user"
 }
}

CLASS-SPECIFIC ADDITIONS

If Class B (State-Change), Add This

"confirmation_required": true,
"confirmation_template": "[This will [ACTION]. Proceed? (yes/no)]",
// Example: "This will permanently delete user_profile.json. Proceed? (yes/no)"

"reversible": [true/false],
// Can this action be undone?

"backup_strategy": "[How is data backed up before this operation?]"
// Example: "File is copied to .backup/ directory before deletion"

If Class C (Computational), Add This

"complexity_justification": "[Why can't a model do this with reasoning alone?],
// Example: "Requires 360 separate calculations (30 years × 12 months)"
// Example: "Statistical analysis on dataset with 10,000+ rows"

"estimated_duration": "[How long does this typically take?]",
// Example: "2-5 seconds for typical inputs"

"timeout_threshold": "[When should this operation time out?]"
// Example: "30 seconds maximum"

QUICK REFERENCE CHECKLIST

Before finalizing your tool definition, verify:

[ ] Name is clear and descriptive (not generic like "do_thing")
[ ] Description is ONE sentence explaining what it does
[ ] Class is assigned (A, B, or C)
[ ] Trigger Logic has at least 2 "use_when" scenarios
[ ] Trigger Logic has at least 2 "dont_use_when" scenarios
[ ] Parameters all have types, descriptions, and examples
[ ] Negative Constraints list common mistakes to avoid
[ ] Return Contract includes success schema AND example
[ ] Failure Modes include at least 2 error types with recovery actions
[ ] Class B tools have confirmation templates
[ ] Class C tools have complexity justification

COMPLETE EXAMPLE (Filled Template)

Here's what a fully-completed template looks like:

{
 "name": "send_email",
 "description": "Sends an email to a specified recipient with subject and body content",
"class": "B",

"trigger_logic": {
 "use_when": [
  "User explicitly asks to send an email or message",
  "Workflow requires notification via email",
  "User provides recipient, subject, and message content"
],
 "dont_use_when": [
  "User is asking ABOUT email (explain, don't send)",
  "Recipient email is missing or unclear (ask for clarification first)",
  "User wants to draft email (write content, don't send)"
 ]
},

"parameters": {
 "to": {
  "type": "string",
  "description": "Recipient's email address",
  "required": true,
  "example": "<user@example.com>",
  "constraints": "Must be valid email format (<name@domain.com>)"
},

"subject": {
 "type": "string",
 "description": "Email subject line",
 "required": true,
 "example": "Meeting Reminder",
 "constraints": "Maximum 200 characters"
},

"body": {
 "type": "string",
 "description": "Email message content",
 "required": true,
 "example": "Hi, this is a reminder about our 3pm meeting.",
 "constraints": "Maximum 10,000 characters"
 }
},

"negative_constraints": {
 "do_not": [
  "Send email with empty subject or body",
  "Send to invalid email addresses (validate format first)",
  "Retry sending the same email multiple times on rate limit errors"
],

"safety": [
 "Never include API keys or passwords in email content",
 "Rate limit: maximum 10 emails per minute",
 "Never send to more than 50 recipients in a single call"
 ]
},

"return_contract": {
 "success": {
 "type": "object",
 "description": "Confirmation that email was sent successfully",
 "schema": {
 "sent": "boolean - true if email sent successfully",
 "message_id": "string - unique identifier for tracking"
},
"example": {
 "sent": true,
 "message_id": "msg_abc123xyz"
 }
},

"failure_modes": {
 "invalid_email": {
  "error": "Recipient email format is invalid",
  "recovery_action": "Ask user to verify email address format",
  "retry": false,
  "user_action": "Please provide email in format: <name@domain.com>"
},

"rate_limit": {
 "error": "Rate limit exceeded (max 10 emails/minute)",
 "recovery_action": "Wait 60 seconds, then retry automatically",
 "retry": true,
 "user_action": "Email will be sent in 60 seconds due to rate limiting"
},
 "smtp_failure": {
  "error": "Email server temporarily unavailable",
  "recovery_action": "Inform user, do not retry",
  "retry": false,
  "user_action": "Email system is temporarily unavailable. Please try again in a few minutes."
  }
 }
},

"composition": {
 "typically_followed_by": ["log_email_sent", "update_notification_status"],
 "prerequisites": ["validate_email_address"],
 "conflicts_with": []
},

"confirmation_required": true,
"confirmation_template": "This will send an email to {to} with subject 'subject}'. Proceed? (yes/no)",
 "reversible": false,
 "backup_strategy": "Email is logged in sent_emails table before sending"
}

MINIMAL TEMPLATE (For Simple Tools)

If your tool is simple (like a Class A read-only tool), here's a shorter version:

{

"name": "[TOOL_NAME]",
"description": "[ONE SENTENCE: What does this do?]",
"class": "A",

"trigger_logic": {
 "use_when": [
  "[When to use this]"
],
 "dont_use_when": [
  "[When NOT to use this]"
 ]
},

"parameters": {
 "[param_name]": {
  "type": "[type]",
  "description": "[what is this?]",
  "required": [true/false],
  "example": "[example]"
 }
},

"return_contract": {
 "success": {
  "type": "[type]",
  "example": {...}
},

"failure_modes": {
 "not_found": {
  "error": "[What went wrong]",
  "recovery_action": "[What to do]",
  "retry": false
   }
  }
 }
}

WORKSHEET FORMAT (For Non-Coders)

Prefer a questionnaire style? Answer these questions:

BASIC INFO:

1. Tool name: ____________________

2. What does it do (one sentence)? ____________________

3. Risk level?

[ ] Class A - Just reads data (safe)

[ ] Class B - Changes data (needs confirmation)

[ ] Class C - Complex calculation

WHEN TO USE:
4. Model should use this when:
 ____________________
 ____________________

WHEN NOT TO USE
5. Model should NOT use this when:
 ____________________
 ____________________

INPUTS:
6. What information does this tool need?

Parameter 1: ____________________
Parameter 2: ____________________
SAFETY:
7. What should Model never do with this tool?
 ____________________
 ____________________

OUTPUTS:
8. What does success look like? (Give an example)
____________________

9.What errors can happen?

Error 1: ____________________
What to do: ____________________
Error 2: ____________________
What to do: ____________________

CONFIRMATION (If Class B):
10. What should Model ask before using this tool?
"This will ____________________. Proceed?"

END OF SKILLS C: TOOL TEMPLATES version:1.0 2026-02-24