<?php
// SPDX-License-Identifier: GPL-3.0-or-later
declare(strict_types=1);

namespace Aiwend\Tools;

use Aiwend\Policy\Principal;

interface Tool
{
    public function name(): string;

    /** Policy operation the principal must pass. */
    public function operation(): string;

    /** @return array<string, array{type:string, max?:int, min?:int}> exact argument schema */
    public function schema(): array;

    /** True if the tool changes anything (requires server-issued confirmation). */
    public function mutates(): bool;

    /** Object-level authorization for the concrete arguments. */
    public function authorizeObject(Principal $principal, array $args): bool;

    /** @return array<string, mixed> */
    public function execute(Principal $principal, array $args): array;
}