<?php

declare(strict_types=1);

namespace Plugin\tnt_mcp\src\Mcp\Action;

/**
 * One thing wrong with one caller-supplied argument, named precisely enough to fix in a single
 * follow-up call: the argument (or the expanded `$_POST` key) it is about, and what was expected.
 *
 * The mirror image of {@see CatalogValidationError} on the invocation side. The audience is
 * different — there it is a human writing YAML, here it is an LLM that has just been told "no" —
 * but the economics are the same: a message that only says "invalid" costs another round trip.
 */
final class ArgumentBindingError
{
    private function __construct(
        public readonly string $field,
        public readonly string $message,
    ) {
    }

    public static function at(string $field, string $message): self
    {
        return new self($field, $message);
    }

    /** `<field>: <message>` — one line, stable, greppable. */
    public function describe(): string
    {
        return \sprintf('%s: %s', $this->field === '' ? '<arguments>' : $this->field, $this->message);
    }
}
