<?php

declare(strict_types=1);

namespace Plugin\tnt_mcp\src\Mcp\Contracts;

use Plugin\tnt_mcp\src\Mcp\Mode\EndpointClass;

/**
 * One MCP tool = one admin-equivalent operation. Keep every implementation a THIN delegate to a
 * real JTL admin service — no business logic here. `write()` tools are allowlisted + audited.
 */
interface Tool
{
    /** Stable machine name exposed to the MCP client, e.g. "get_shop_info". */
    public function name(): string;

    /** One-line human description shown to the AI client. */
    public function description(): string;

    /**
     * JSON-schema (as PHP array) of the tool's input arguments.
     *
     * @return array<string,mixed>
     */
    public function inputSchema(): array;

    /** True = mutates shop state (allowlist + confirmation + audit apply). */
    public function isWrite(): bool;

    /** Required scope, e.g. "orders:read" / "settings:write". */
    public function scope(): string;

    /**
     * Reversibility class of this endpoint — the central {@see \Plugin\tnt_mcp\src\Mcp\Mode\ModeGuard}
     * uses it to decide whether the tool may run in limited mode. Every tool MUST declare one:
     * reads + undoable writes = {@see EndpointClass::Reversible}; anything that erases or
     * irreversibly mutates data = {@see EndpointClass::Destructive}.
     */
    public function endpointClass(): EndpointClass;

    /**
     * Execute the tool. MUST delegate to the same service the admin panel calls.
     * @param array<string,mixed> $args validated against inputSchema()
     * @return array<string,mixed> result payload for the MCP client
     */
    public function run(array $args): array;
}
