prompttool

name	prompttool
description	Write a tool definition for an agent — name, description, input schema, and output schema. Use when defining a new tool that will be registered with an agent.
license	MIT

Prompttool

Output: a tool definition written to prompts/tools/{toolname}.md (Markdown, default) or prompts/tools/{toolname}.xml (XML).

Context

Write a tool definition: the name, description, input schema, and output schema that an agent receives when the tool is registered. Most agent frameworks send these fields to the agent as structured data on every request — the description is the prompt that teaches the agent when and how to use the tool.

Tradeoff: A description that is too short leaves the agent guessing. One that is too long gets skimmed or ignored. Aim for one screen.

Scope: This skill produces tool definitions — not prompt sections. Tools are sent to the agent as structured data by the framework, not written inline in the agent prompt.

Task

Apply to the User's Input

The user invokes this skill with a description of what the tool does. Specialize every step below to that input.

• Derive the name from the action the tool performs, not its implementation.
• If the tool overlaps with another tool, identify the overlap before drafting — the description must name the alternative and say when to prefer it.
• If the input does not specify what parameters the tool takes or what it returns, ask one clarifying question before drafting.
• If the user says "xml", "as xml", or "xml format", produce XML output; otherwise default to Markdown.

Part A: Name the Tool

The name is what the agent writes when invoking the tool. It must be unambiguous, unique across the tool set, and easy to recall.

• Verb-noun form: read_file, edit_file, web_fetch, send_message.
• The verb names the action; the noun names the subject.
• Name it after what the agent gets, not the underlying mechanism: web_fetch not curl, list_directory not ls.
• One name, one tool. A tool that does two distinct things should be split or have its primary action named.

If the framework supports a short discovery phrase (used for keyword matching when tools are lazily loaded), write one separately: 3–10 words naming the capability, not the tool name — "search file contents with regex", "find files by name pattern".

Part B: Write the Opening Statement

The first line of the description sets the agent's mental model for when to reach for this tool.

• One sentence. Verb-first. State what the caller gets, not how the tool works: "Read the contents of a file" not "This tool reads files using the filesystem API".
• No "This tool…" self-reference — the name already identifies it.
• Name the output explicitly when it is non-obvious: "returns matching file paths sorted by modification time".
• State the primary use case, not every possible use.

Part C: Write the Description Body

After the opening statement, add bullets and optional labeled sections to cover constraints, capabilities, and anti-patterns.

Constraint bullets — what the tool requires, limits, or guarantees:

• Results are returned with line numbers starting at 1.
• Can only read files, not directories.
• HTTP URLs are automatically upgraded to HTTPS.

When not to use — for any tool that overlaps with another, name the preferred alternative explicitly:

When NOT to use:
- To read a specific file — use read_file instead.
- For any task a single dedicated tool can accomplish.

Never leave the anti-pattern implicit. An agent that reaches for the wrong tool is following an undertrained description.

Critical caveats — flag constraints a skimming agent would miss:

• IMPORTANT: Will fail for authenticated URLs. Check if a specialized tool provides access first.
• IMPORTANT: Will fail if the target string appears more than once in the file.
• ALWAYS read the file before editing it. The tool will error if you have not.

Labeled sections — use headers only for complex tools where a flat list is hard to scan. Most tools do not need them.

Part D: Write the Input Schema

The input schema is a JSON Schema object. Each field description is the prompt that tells the agent what value to supply.

Field descriptions follow four rules:

• Terse: "Path to the file to read" not "The path parameter that specifies the location of the file".
• Defaults inline: "Number of lines to read (default: all)".
• Examples for non-obvious formats: "Glob pattern (e.g. **/*.rs)".
• Warn about common mistakes and parameter interactions inside the field description: "Omit this field for the default behavior. Do not pass null or an empty string."

Required fields are the minimum the tool cannot run without. Make a field optional whenever the tool can infer or default it. When in doubt, prefer optional over required.

For enum or mode fields that change what the tool returns, document each option:

{
  "output_mode": {
    "type": "string",
    "description": "Output format: 'files' returns file paths only (default), 'content' returns matching lines with context, 'count' returns match counts per file."
  }
}

Part E: Write the Output Schema

Document what the tool returns so the agent knows what to expect. The output schema prevents the agent from hallucinating field names or misinterpreting results.

• List every field the tool returns, with type and a terse description.
• Mark fields that are only present under certain conditions: "present only when output_mode is 'content'".
• State when a field can be empty or absent and what that means.
• If the tool returns plain text, state the format: line-numbered, JSON, markdown, raw stdout.

Part F: State Side Effects

Classify the tool's impact on state. This determines whether it can run concurrently with other tools and whether the agent should confirm before calling it.

• Read-only: no state modified — safe to call in parallel with other read-only tools.
• Reversible write: creates or modifies state, but the change can be undone.
• Destructive: deletes, overwrites permanently, or triggers irreversible external actions — the agent should prefer alternatives or confirm before calling.

A tool can be reversible for some inputs and destructive for others. If so, state the condition: "destructive when replace_all is true".

Part G: Format the Output

Markdown (default) — write a # {toolname} file with ## Input, ## Output, ## Side Effects sections:

# {toolname}

{description text}

## Input

\`\`\`json
{input_schema}
\`\`\`

## Output

\`\`\`json
{output_schema}
\`\`\`

## Side Effects

{read-only / reversible write / destructive — one line}

XML — wrap the entire definition in a <tool> element with structured sub-elements:

<tool name="{toolname}">
{description text}
<input>
{input_schema_json}
</input>
<output>
{output_schema_json}
</output>
<side_effects>
{read-only / reversible write / destructive}
</side_effects>
</tool>

Verification

1. Name is verb-noun, unambiguous, no implementation detail.
2. Opening statement is one sentence, verb-first, no self-reference.
3. Overlapping tools are named explicitly with the preferred alternative.
4. Critical caveats cover constraints a skimming agent would miss.
5. Parameter descriptions warn about common mistakes and state interactions between parameters.
6. Enum/mode fields document each option and what it returns.
7. Every optional field states its default.
8. Required fields are the minimum needed to invoke the tool.
9. Output schema lists all returned fields and marks conditional ones.
10. Side effects are classified: read-only, reversible write, or destructive.
11. Format matches user's request: Markdown file for default, XML <tool> element for XML.

Derive the tool name (verb-noun, e.g. search_file). Create the prompts/tools/ directory if it does not exist. Write the file to prompts/tools/{toolname}.md (Markdown) or prompts/tools/{toolname}.xml (XML). Confirm the file path. No other output.