Declare each tool's plan requirement and explain plan mismatches in errors

[kbennett2000]

Declare each tool's plan requirement and explain plan mismatches in errors

Stacked on the batch-amplification PR — it reuses the BraveApiError type
added there. Happy to rebase this standalone if you'd rather take them in the
other order, or land them together.

The problem

Brave sells access as plans, and a subscription token is scoped to the plan it
was issued under. A key that works for /web/search is not guaranteed to work
for /summarizer/search. But this server takes exactly one key and points it at
nine endpoints spanning at least two plans.

When that mismatch happens, the server today gives the caller nothing to work
with. brave_summarizer catches the failure and returns:

Unable to retrieve a Summarizer summary.

The real 403 — including Brave's own SUBSCRIPTION_TOKEN_INVALID body — is
discarded. It is the only tool in the server that swallows its error, and it is
also the tool most likely to hit a plan mismatch, because it needs a different
plan from the seven search tools that share its key.

This matters more than it used to. The consumer of that error is now a model.
A model can act on "this endpoint needs the Answers plan." It cannot act on
"unable to retrieve."

Changes

src/plans.ts (new) — one place that knows which endpoint needs which plan.
An ENDPOINT_PLANS map plus helpers to render it as prose. Tool descriptions
and error messages both read from this map, so they can't drift apart.

src/BraveAPI/index.ts — auth failures say which plan is required.
On 401/403/422, issueRequest appends the plan requirement to the error before
throwing. This happens once at the API boundary, so all nine endpoints get it
without touching the seven tools that have no error handling of their own.
BraveApiError also now carries endpoint and requiredPlan for callers that
want to branch on it rather than read prose.

Every tool description now states its plan. Previously two of eight
mentioned a plan at all (brave_local_search and brave_summarizer), and the
two newest — brave_llm_context and brave_place_search — said nothing. Now
each description ends with a generated line:

brave_web_search      -> Requires the Brave Search 'Search' plan.
brave_summarizer      -> Requires the Brave Search 'Answers' plan. Referred to as
                         'Pro AI' elsewhere in the Brave docs.
brave_place_search    -> Requires the Brave Search 'Search (Pro tier)' plan.

An agent reading the tool list can now see the requirement before it spends a
request finding out.

brave_summarizer stops discarding the failure. It still returns its
friendly message, with the underlying reason appended when the cause was a
Brave API error.

What an agent sees now

403 Forbidden
{"error":{"code":"SUBSCRIPTION_TOKEN_INVALID","detail":"..."}}

Requires the Brave Search 'Answers' plan. Referred to as 'Pro AI' elsewhere in
the Brave docs. If your API key is subscribed to a different plan, this request
will fail on every attempt; retrying will not help. Review or change your plan
at https://api-dashboard.search.brave.com/app/subscriptions/subscribe

Two things I need you to check

1. The plan assignments are my best read of your own docs, not authoritative.
I took the plan names from the SKILL.md banners in brave/brave-search-skills
and the plan notes already in this repo. Please correct any of these:

Endpoint	Assigned plan	Basis
web, images, videos, news	Search	skills repo banners
llmContext	Search	skills/llm-context/SKILL.md
localPois, localDescriptions	Search (Pro tier)	this repo's own local description
placeSearch	Search (Pro tier)	inferred from the shared /local/ path — least confident
summarizer	Answers	skills/answers/SKILL.md

They're one edit each in ENDPOINT_PLANS.

2. The naming is inconsistent across Brave's own surfaces. This repo calls
it a "Pro AI subscription"; brave-search-skills calls it the "Answers" plan.
I went with Answers and noted the alias, but you'll know which is current.

Tests

src/plans.test.ts plus additions to the summarizer tests. Includes a guard
that fails if a new endpoint is added without a plan assignment, and one that
asserts every registered tool states a plan requirement.

73/73 pass; tsc --noEmit and prettier --check clean.

Related

brave-search-cli#27 and brave-search-skills#27 are the same root cause in
the other two repos: one key slot, several plans. This PR doesn't fix the
single-key limitation — it makes the resulting failure legible. Multi-key
support would be the larger change, and it should probably be designed across
all three repos at once rather than here alone.