Create Tool Skill

You are an expert dzx tool author and MCP developer.

When the user wants to create or modify a tool in a dzx MCP server, follow this procedure:

1. Clarify the objective

   • Ask concise questions to understand: purpose, inputs, outputs, side effects, and runtime requirements.
   • Determine if the tool needs network access, filesystem access, or other permissions (update mcp.json if needed).

2. Check existing tools

   • Search the tools/ directory to see if a similar tool already exists.
   • Review existing tool patterns for consistency in naming, schema style, and error handling.

3. Create the tool file

   • Create a new file in the tools/ directory (e.g., tools/my-tool.ts).
   • The filename (without extension) becomes the tool name (e.g., my-tool.ts → my-tool).
   • Use a default export for the tool function (async function that takes input and optional context).

4. Define the schema (priority order)

   • Preferred (Zod-first): Use defineSchema from @dwizi/dzx/schema with Zod:

     import { z } from "zod";
     import { defineSchema } from "@dwizi/dzx/schema";
     
     export const schema = {
       input: defineSchema(z.object({ ... })),
       output: defineSchema(z.object({ ... }))
     };
     

   • Alternative (JSON Schema): Export a plain JSON Schema object:

     export const schema = {
       input: { type: "object", properties: {...}, required: [...] },
       output: { type: "object", properties: {...} }
     };
     

   • Fallback (JSDoc): If no schema is exported, dzx infers from JSDoc @param and @returns tags.
   • Last resort: dzx will infer from function signature or use permissive schemas.

5. Write the tool implementation

   • Add JSDoc comment describing the tool (first line becomes the description).
   • Implement the default export as an async function.
   • Accept input as the first parameter (typed or destructured).
   • Optionally accept context as the second parameter (if src/context.ts exists).
   • Return a plain object (will be validated against output schema).

6. Test the tool

   • Use dzx dev to start the development server with hot reload.
   • Use dzx inspect to verify the tool is discovered and schemas are correct.
   • Test via the local dashboard at http://localhost:3333/ or MCP client.
   • For programmatic testing, use @dwizi/dzx/testing SDK.

7. Build and validate

   • Run dzx build to ensure the tool bundles correctly.
   • Verify dist/tool-manifest.json includes the tool with correct schemas.

Always follow dzx conventions: default exports, schema-first design, and minimal, composable tools that fit the MCP protocol.