/tools-resources-prompts

name: nitrostack-tools-resources-prompts
description: Guidelines and patterns for defining Tools, Resources, and Prompts in a NitroStack application with schema validation via Zod, including caching, rate-limiting, and base64 file uploads.

When to Use

Use this skill whenever you are defining, editing, or validating tools, resources, or prompts on a NitroStack MCP server.

Defining Tools with `@Tool`

An MCP tool exposes a function that an AI client can invoke. Decorate a service or controller method with `@Tool`.

Key Tool Options:

• `name`: Kebab-case or snake_case unique identifier.
• `description`: Detailed description explaining when and how the client should use it.
• `inputSchema`: A Zod object schema for strict validation of inputs.
• `outputSchema` (optional): Zod schema validating the output structure.

import { ToolDecorator as Tool, ControllerDecorator as Controller, InitialTool, z, ExecutionContext } from '@nitrostack/core';

@Controller('weather')
export class WeatherService {
  @Tool({
    name: 'get_current_weather',
    description: 'Get the current weather forecast for a specific city.',
    inputSchema: z.object({
      city: z.string().describe('The name of the city, e.g., San Francisco'),
      unit: z.enum(['celsius', 'fahrenheit']).default('celsius'),
    }),
  })
  @InitialTool() // Auto-invoked when the AI client initializes/starts
  async getWeather(
    input: { city: string; unit: 'celsius' | 'fahrenheit' },
    ctx: ExecutionContext
  ) {
    ctx.logger.info(`Fetching weather for ${input.city}`);
    // implementation
    return {
      city: input.city,
      temp: 22,
      condition: 'Sunny',
    };
  }
}

Defining Resources with `@Resource`

An MCP resource exposes static or dynamic data files/URIs that the AI client can read.

Key Resource Options:

• `uri`: URI pattern (e.g., `git://{owner}/{repo}/file` or static `app://config`).
• `name`: Unique name of the resource.
• `description`: Explanation of what data this resource provides.
• `mimeType`: Mime type of the response (e.g., `text/plain`, `application/json`).

import { Resource, ExecutionContext } from '@nitrostack/core';

export class ConfigResources {
  @Resource({
    uri: 'app://settings',
    name: 'Application Settings',
    description: 'System-wide configuration settings and parameters.',
    mimeType: 'application/json',
  })
  async getSettings(ctx: ExecutionContext) {
    return {
      environment: 'development',
      debugMode: true,
    };
  }
}

Defining Prompts with `@Prompt`

An MCP prompt exposes reusable templates or instruction sets that guide LLMs.

Key Prompt Options:

• `name`: Name of the prompt.
• `description`: Describes what task this prompt helps accomplish.
• `arguments`: Declares parameters the client can supply to customize the prompt template.

import { Prompt, ExecutionContext } from '@nitrostack/core';

export class PromptTemplates {
  @Prompt({
    name: 'code_review',
    description: 'Provide an intensive code review for a given code snippet.',
    arguments: [
      { name: 'language', description: 'The programming language, e.g., TypeScript', required: true },
      { name: 'code', description: 'The code snippet to review', required: true },
    ],
  })
  async getCodeReviewPrompt(
    args: { language: string; code: string },
    ctx: ExecutionContext
  ) {
    return {
      messages: [
        {
          role: 'user',
          content: `You are an expert software engineer. Review this ${args.language} code:\n\n${args.code}`,
        },
      ],
    };
  }
}

---

Tool Policies: Caching (`@Cache`) and Rate Limiting (`@RateLimit`)

You can control tool execution behaviors (such as performance optimization and throttling) using method decorators.

1. Caching with `@Cache`

Use `@Cache` to cache tool execution outputs for a specified duration (TTL in seconds). This reduces database or API overhead for frequent identical requests.

Options:

• `ttl`: Cache time-to-live in seconds (required).
• `key` (optional): Custom function `(input: any, context?: any) => string` that returns a unique cache key based on inputs. If not defined, a key is auto-generated from serialized input arguments.

Example:

import { ToolDecorator as Tool, Cache, z } from '@nitrostack/core';

export class StationTools {
  @Tool({
    name: 'get_system_status',
    description: 'Fetch real-time station metrics. Response is cached.',
    inputSchema: z.object({}),
  })
  @Cache({ ttl: 60 }) // Caches status for 60 seconds
  async getSystemStatus() {
    return { temperature: 21.5, oxygen: 0.98 };
  }

  @Tool({
    name: 'get_crew_status',
    description: 'Fetch status of a crew member. Cached by crew ID.',
    inputSchema: z.object({ id: z.string() }),
  })
  @Cache({
    ttl: 300,
    key: (input) => `crew:status:${input.id}`
  })
  async getCrewStatus(input: { id: string }) {
    // ...
  }
}

2. Rate Limiting with `@RateLimit`

Use `@RateLimit` to restrict the number of tool invocations within a specified time window to prevent client abuse.

Options:

• `requests`: Number of allowed requests in the window (required).
• `window`: Throttling duration window (required). Supports formats like `'1s'`, `'1m'`, `'1h'`.
• `key` (optional): Custom function `(context: ExecutionContext) => string` to group rate limits. Useful for rate-limiting per user role or API key.

Example:

import { ToolDecorator as Tool, RateLimit, z, ExecutionContext } from '@nitrostack/core';

export class DiagnosticTools {
  @Tool({
    name: 'run_deep_diagnostic',
    description: 'Run intensive diagnostics. Rate limited.',
    inputSchema: z.object({}),
  })
  @RateLimit({ requests: 3, window: '1m' }) // Max 3 requests per minute globally
  async runDeepDiagnostic() {
    return { diagnosticReport: 'All systems operational.' };
  }

  @Tool({
    name: 'request_supply_drop',
    des