Design Tools the Model Can Use Correctly

A Tool is the function boundary between a model and real effects. Vague descriptions, permissive input, and opaque errors force the model to guess.

Minimal Plugin

import type { Context } from '@deepseek-ai/cordis'
import { defineTool } from '@deepseek-ai/dsh-tools'

export const name = 'issue-reader'
export const inject = ['tools']

export function apply(ctx: Context) {
  ctx.tools.register(defineTool({
    name: 'get_issue',
    description: 'Read one issue by numeric id. Never updates it.',
    parameters: {
      id: { type: 'number', required: true, description: 'Positive issue id' },
    },
    output: {
      schema: { type: 'string' },
      render: (_args, value) => [{ type: 'text', text: value }],
    },
    async execute(args) {
      return `Issue #${args.id}`
    },
  }))
}

inject waits for the registry. defineTool creates model-visible Schema and validates arguments before execution. The output Schema describes the canonical value; render materializes session content.

Design Rules

• Use stable verb names and separate read from write.
• Explain exclusions in the description.
• Prefer enums and structured objects to free-form shell fragments.
• Reject invalid input before any effect.
• Make deployment-specific timeout and retry values validated configuration.
• Keep render bounded and remove secrets or full authorization headers.

Side-effect Tools should support preview, require an exact target and expected prior state, use idempotency keys, return remote operation IDs, honor cancellation, and place approval at the call boundary.

Test Matrix

Test minimal valid input, missing fields, absent targets, duplicate calls, cancellation, and long responses. Verify the canonical value, rendered result, Session event, and unload cleanup all agree.

Next: Subagent Orchestration.