io.github.TheTsungYing/annealbridge

recommend_backend

Rank solver backends for an optimization problem to identify the best usable option, using problem structure and backend capabilities—no solving or network requests.

Instructions

Rank the solver backends of this server for a given problem, without solving it.

Advisory only: solve_optimization always uses problem.solver.backend exactly as
given and never substitutes a backend. Each entry reports whether the backend is
usable right now (installed, credentialed, permitted by policy, within limits),
the model type it would compile to, deterministic reason codes, blocking errors,
and the same warnings validate_optimization_problem would give for that backend.
Based only on the problem structure, backend capabilities and server policy —
no cost estimation, no network requests, no quota consumed.

A problem with integer variables adds reason codes: R_INTEGER_NATIVE when the
backend compiles to cqm and takes integers as they are, R_INTEGER_ENCODED when
it compiles to bqm and must binary-encode them, and R_INTEGER_BLOWUP when that
encoding also raises an INTEGER_QUADRATIC_BLOWUP warning — a backend carrying
that code is ranked after the ones without it.

The entries are ordered best first, so the first usable entry is the default
choice when the user named no backend. Among backends of the same kind, two
reason codes come from a backend's declared, measured structural preference:
R_DENSE_STRENGTH when it declares that it reaches the same energy as its
peers in a fraction of the time on large dense unconstrained models and this
problem is one, R_PENALTY_WEAKNESS when it declares a lower hit rate on
models whose hard constraints compile to penalties and this problem has an
effective hard constraint. Both shapes are bqm-path shapes, so a backend that
compiles to cqm is never matched. A backend carrying the first is ranked
ahead of its neighbours, one carrying the second behind them; neither changes
which backends are usable.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`problem`	Yes

Output Schema

TableJSON Schema

Name	Required	Description	Default
`valid`	Yes	The problem's own validity. When false, recommendations is empty.
`errors`	No	The problem's errors when it is invalid; empty otherwise.
`advisory`	No	A fixed sentence restating that a solve always uses problem.solver.backend as given and never substitutes one.	Advisory only: solve_optimization always uses problem.solver.backend as given and never substitutes a backend.
`recommendations`	No	Every registered backend, ranked best first.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 22, 2026

TDQS

A4.4/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure, and it does so thoroughly. It states the tool makes no network requests, consumes no quota, and does no cost estimation. It explains the reason codes (R_INTEGER_NATIVE, R_INTEGER_ENCODED, R_INTEGER_BLOWUP) and the ranking logic (R_DENSE_STRENGTH, R_PENALTY_WEAKNESS) in detail, disclosing exactly what each entry reports and how ordering works. This is exemplary transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is lengthy but each sentence adds substantive information: the advisory nature, the report contents, the integer reason codes, and the ranking rules. It is front-loaded with the core purpose and then systematically covers details. While not brief, it is well-structured and free of fluff, earning a score slightly above the median.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that an output schema exists, the description is not required to explain return values, yet it still describes what each entry reports (usability, model type, reason codes, blocking errors, warnings) and explains the ordering rules. It covers all important behavioral aspects and edge cases (integer variables, dense unconstrained models, penalty weaknesses). The description is complete enough for an agent to understand when and how to use the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is only one parameter, 'problem', which is a reference to a well-structured OptimizationProblem schema. The schema_description_coverage for the top-level parameter is 0%, so the description should compensate, but it adds no new information about the parameter beyond 'given a problem'. However, the schema itself provides exhaustive descriptions of all nested fields, so an agent can infer the parameter's meaning from the schema. The description does not add value here, but it does not mislead; a baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific, unambiguous statement: 'Rank the solver backends of this server for a given problem, without solving it.' It immediately distinguishes the tool from its siblings by explicitly noting that solve_optimization always uses the given backend and never substitutes, and by referencing validate_optimization_problem's warnings. This makes the tool's role and boundaries crystal clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains the advisory nature and explicitly contrasts with solve_optimization, stating it never substitutes a backend. It also mentions it gives the same warnings as validate_optimization_problem, implying a validation-like use case. However, it does not explicitly state when NOT to use this tool or when to prefer one of the siblings beyond the advisory contrast, so it stops just short of full guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server