<?php

declare(strict_types=1);

namespace LIT\MCP\Abilities;

use WP_Error;

defined('ABSPATH') || exit;

/**
 * One capability of the MCP server, registered with the WordPress Abilities API.
 */
interface Ability
{
    /** Ability name, e.g. "lit/guide". */
    public function name(): string;

    public function label(): string;

    public function description(): string;

    /** @return array<string, mixed> JSON Schema of the input. */
    public function inputSchema(): array;

    /** @return array<string, mixed>|null JSON Schema of the output, null for image results. */
    public function outputSchema(): ?array;

    /** @return array{readonly?: bool, destructive?: bool, idempotent?: bool} */
    public function annotations(): array;

    /** Whether the ability is listed as its own MCP tool (otherwise only via meta-tools). */
    public function isDirect(): bool;

    /** @param array<string, mixed> $input */
    public function permission(array $input): bool|WP_Error;

    /** @param array<string, mixed> $input */
    public function execute(array $input): mixed;
}