ModelSpec is an MCP server published by io.github.turbobeest, hosted at api.modelspec.dev. When last checked on 2026-11-21 it was working: it answers and lists its tools. It declares 9 tools, including rank, model_info, list_use_cases, policy_check, decide.
Find AI models that fit a job from your requirements, sourced benchmarks and real cost.
Nothing else in the archive shares these values.
Legacy v1; use decide. Deprecated fixed-benchmark ranking; scores lag the catalogue and newer models may be unranked. Which models lead a fixed use-case profile? Returns a shortlist with evidence_basis and input provenance, not a quality verdict. Needs an API key (Authorization: Bearer). Costs 1 credit a call; $0.0053–$0.02 per credit by plan or pack (https://modelspec.dev/pricing/). Don't call it as a fallback when decide has no single leader; report its tie. Present `summary_for_user` to the user unchanged and keep every `must_mention` item. When `next_move` is present, offer it instead of a pick. Proxies POST https://api.modelspec.dev/v1/rank with these arguments.
| Parameter | Type | Description |
|---|---|---|
| limit | integer | |
| use_case * | string | Ranking profile id, as published in /api/rank/profiles.json |
| constraints | object | |
| environment | object |
None yet. Changes appear after a server's second daily check.
Squares are this server's values; dots are other servers sharing them. A shared address or publisher is a lead, not proof of a common operator.
Inferred from the host name and headers: what a server runs on, not who runs it.
{
"name": "rank",
"description": "Legacy v1; use decide. Deprecated fixed-benchmark ranking; scores lag the catalogue and newer models may be unranked. Which models lead a fixed use-case profile? Returns a shortlist with evidence_basis and input provenance, not a quality verdict. Needs an API key (Authorization: Bearer). Costs 1 credit a call; $0.0053–$0.02 per credit by plan or pack (https://modelspec.dev/pricing/). Don't call it as a fallback when decide has no single leader; report its tie. Present `summary_for_user` to the user unchanged and keep every `must_mention` item. When `next_move` is present, offer it instead of a pick. Proxies POST https://api.modelspec.dev/v1/rank with these arguments.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"use_case"
],
"properties": {
"limit": {
"type": "integer",
"maximum": 100,
"minimum": 0
},
"use_case": {
"type": "string",
"description": "Ranking profile id, as published in /api/rank/profiles.json"
},
"constraints": {
"type": "object",
"properties": {
"open_weights": {
"type": [
"boolean",
"null"
]
},
"include_rehosts": {
"type": [
"boolean",
"null"
]
},
"price_sensitivity": {
"type": [
"number",
"null"
]
},
"max_cost_per_million_input_tokens": {
"type": [
"number",
"null"
]
}
},
"additionalProperties": false
},
"environment": {
"type": "object",
"properties": {
"hosting": {
"anyOf": [
{
"enum": [
"local",
"self_hosted",
"managed_api"
],
"type": "string"
},
{
"type": "null"
}
]
},
"runtime": {
"type": [
"string",
"null"
]
},
"hardware": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
},
"additionalProperties": {}
}
}What does one model's card say? Reads https://modelspec.dev/api/models/<model_id>.json. Split mode returns only its display name. Needs an API key. Not current evidence or a ranking; use decide.
| Parameter | Type | Description |
|---|---|---|
| model_id * | string | Catalogue id, e.g. openai/gpt-5-6 |
{
"name": "model_info",
"description": "What does one model's card say? Reads https://modelspec.dev/api/models/<model_id>.json. Split mode returns only its display name. Needs an API key. Not current evidence or a ranking; use decide.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"model_id"
],
"properties": {
"model_id": {
"type": "string",
"description": "Catalogue id, e.g. openai/gpt-5-6"
}
}
}
}Which legacy profiles and ranking rules exist? Returns https://modelspec.dev/api/rank/profiles.json with evidence floors and the neutrality commitment. Needs an API key. Use decide for decisions.
No parameters.
{
"name": "list_use_cases",
"description": "Which legacy profiles and ranking rules exist? Returns https://modelspec.dev/api/rank/profiles.json with evidence floors and the neutrality commitment. Needs an API key. Use decide for decisions.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {}
}
}Which models and platforms does my policy allow? Returns pass, fail or undetermined per model/platform for licence, origin and data handling; undetermined is not a pass. Needs an API key (Authorization: Bearer). Costs 5 credits a call; $0.0053–$0.02 per credit by plan or pack (https://modelspec.dev/pricing/). It doesn't choose a model; use decide among passing rows. Proxies POST https://api.modelspec.dev/v1/policy-check with these arguments and Authorization.
| Parameter | Type | Description |
|---|---|---|
| limit | integer | |
| models | array | |
| offset | integer | |
| policy * | object | |
| verdicts | array | |
| platforms | array | |
| require_no_undetermined | boolean |
{
"name": "policy_check",
"description": "Which models and platforms does my policy allow? Returns pass, fail or undetermined per model/platform for licence, origin and data handling; undetermined is not a pass. Needs an API key (Authorization: Bearer). Costs 5 credits a call; $0.0053–$0.02 per credit by plan or pack (https://modelspec.dev/pricing/). It doesn't choose a model; use decide among passing rows. Proxies POST https://api.modelspec.dev/v1/policy-check with these arguments and Authorization.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"policy"
],
"properties": {
"limit": {
"type": "integer",
"maximum": 500,
"minimum": 0
},
"models": {
"type": "array",
"items": {
"type": "string"
}
},
"offset": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"policy": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"origin": {
"type": "object",
"properties": {
"permitted_countries": {
"type": "array",
"items": {
"type": "string"
}
},
"prohibited_countries": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
},
"licence": {
"type": "object",
"properties": {
"allowed": {
"type": "array",
"items": {
"type": "string"
}
},
"prohibited": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
},
"residency": {
"type": "object",
"properties": {
"match": {
"enum": [
"any",
"all"
],
"type": "string"
},
"required_regions": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
},
"commercial_use": {
"type": "object",
"properties": {
"required": {
"type": "boolean"
},
"accept_restricted": {
"type": "boolean"
}
},
"additionalProperties": false
}
},
"additionalProperties": {}
},
"verdicts": {
"type": "array",
"items": {
"enum": [
"pass",
"fail",
"undetermined"
],
"type": "string"
}
},
"platforms": {
"type": "array",
"items": {
"type": "string"
}
},
"require_no_undetermined": {
"type": "boolean"
}
},
"additionalProperties": {}
}
}Which models fit this job? Call decide early. Returns answer, ranked results, may_qualify, reading and recovery hints, decision_id and snapshot. Never add a gate or constraint the user didn't state. Relax only constraints the user stated, one at a time, and say what was relaxed and why. Prefer the answer's own `relax` suggestions. A tie stays a tie. Don't promote a member by knowledge from outside the response. Cite only evidence in the response. Never add benchmark figures from memory. Tied or partial answer: report the tie and caveats, pick no member; a null answer names no pick and says what's missing. A null cost is unknown. Never show it as $0.00 or "free". One vocabulary lookup per unknown facet, then decide. Read `next` before another call. Size `task_tokens` from the user's own task, and say what you assumed. Don't copy the guide's example sizes. Template weights are examples, not requirements. If the evidence basis or board does not match the task, say so: Arena web-dev evidence does not establish chat quality. p_best is the probability of ranking best under the Spec and evidence uncertainty, not the probability of matching the user's task or satisfying its requirements. Read reading when present. Present answer.kind=tied among all answer.members, including with_estate; tie-breakers are conditional. State requirements in reading.not_applied or error.issues that were not applied, including requirements removed after a rejected call. A retry does not verify them. Report estimates as estimates: fits_hardware membership is not measured fit for a specific quantization and context workload. Follow reading.do_not_claim. Never claim a rank the response does not show. Present `summary_for_user` to the user unchanged and keep every `must_mention` item. When `next_move` is present, offer it instead of a pick. Needs an API key (Authorization: Bearer). Costs 1 or 2 credits a call; $0.0053–$0.02 per credit by plan or pack (https://modelspec.dev/pricing/). Not a router: call once per job or role, not per request; route among its chosen models. Proxies POST https://api.modelspec.dev/v1/decide. MCP decide returns a bounded answer of at most 16 KB, summary included. Drill down with evidence_for. Complete rows need fields:null; explanation.fetch names what was removed and how to fetch it. With explain unset or "none": explain=none, limit=10, fields=model_rank,cost_per_task,estimates,p_best. summary/full adds contributions and evidence. omitted counts removed records; explain=none skips eliminations. Explicit fields, including null, pass through. Oversize responses use a trimmed notice with explanation.fetch. decision_id is a citation, not a stored lookup. task free text is rejected; where is an array. Examples, recovery and budgets: https://modelspec.dev/agents.md. Null means unresearched or unpublished, never a guess. Sourced card values include a URL and read date. Returns the origin JSON and URL without invented fields. Example. Answer: status partial, answer.kind tied (a/x, b/y), next_move.kind decide_by_testing. Right report: summary_for_user verbatim, each must_mention item, then next_move.steps for its candidates. Wrong: "Start with a/x", a shortlist, or a ranked table.
No parameters.
{
"name": "decide",
"description": "Which models fit this job? Call decide early. Returns answer, ranked results, may_qualify, reading and recovery hints, decision_id and snapshot. Never add a gate or constraint the user didn't state. Relax only constraints the user stated, one at a time, and say what was relaxed and why. Prefer the answer's own `relax` suggestions. A tie stays a tie. Don't promote a member by knowledge from outside the response. Cite only evidence in the response. Never add benchmark figures from memory. Tied or partial answer: report the tie and caveats, pick no member; a null answer names no pick and says what's missing. A null cost is unknown. Never show it as $0.00 or \"free\". One vocabulary lookup per unknown facet, then decide. Read `next` before another call. Size `task_tokens` from the user's own task, and say what you assumed. Don't copy the guide's example sizes. Template weights are examples, not requirements. If the evidence basis or board does not match the task, say so: Arena web-dev evidence does not establish chat quality. p_best is the probability of ranking best under the Spec and evidence uncertainty, not the probability of matching the user's task or satisfying its requirements. Read reading when present. Present answer.kind=tied among all answer.members, including with_estate; tie-breakers are conditional. State requirements in reading.not_applied or error.issues that were not applied, including requirements removed after a rejected call. A retry does not verify them. Report estimates as estimates: fits_hardware membership is not measured fit for a specific quantization and context workload. Follow reading.do_not_claim. Never claim a rank the response does not show. Present `summary_for_user` to the user unchanged and keep every `must_mention` item. When `next_move` is present, offer it instead of a pick. Needs an API key (Authorization: Bearer). Costs 1 or 2 credits a call; $0.0053–$0.02 per credit by plan or pack (https://modelspec.dev/pricing/). Not a router: call once per job or role, not per request; route among its chosen models. Proxies POST https://api.modelspec.dev/v1/decide. MCP decide returns a bounded answer of at most 16 KB, summary included. Drill down with evidence_for. Complete rows need fields:null; explanation.fetch names what was removed and how to fetch it. With explain unset or \"none\": explain=none, limit=10, fields=model_rank,cost_per_task,estimates,p_best. summary/full adds contributions and evidence. omitted counts removed records; explain=none skips eliminations. Explicit fields, including null, pass through. Oversize responses use a trimmed notice with explanation.fetch. decision_id is a citation, not a stored lookup. task free text is rejected; where is an array. Examples, recovery and budgets: https://modelspec.dev/agents.md. Null means unresearched or unpublished, never a guess. Sourced card values include a URL and read date. Returns the origin JSON and URL without invented fields. Example. Answer: status partial, answer.kind tied (a/x, b/y), next_move.kind decide_by_testing. Right report: summary_for_user verbatim, each must_mention item, then next_move.steps for its candidates. Wrong: \"Start with a/x\", a shortlist, or a ranked table.",
"inputSchema": {
"$ref": "#/$defs/DecideRequest",
"type": "object",
"$defs": {
"Soft": {
"type": "object",
"required": [
"penalty"
],
"properties": {
"penalty": {
"type": "number",
"maximum": 1,
"exclusiveMinimum": 0
}
},
"description": "A soft condition: violating it costs ``penalty`` of the objective instead of eliminating.",
"additionalProperties": false
},
"AllOf": {
"type": "object",
"required": [
"all"
],
"properties": {
"all": {
"type": "array",
"items": {
"$ref": "#/$defs/Condition"
}
},
"soft": {
"anyOf": [
{
"$ref": "#/$defs/Soft"
},
{
"type": "null"
}
]
},
"unknown": {
"anyOf": [
{
"enum": [
"list",
"fail",
"pass"
],
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"AnyOf": {
"type": "object",
"required": [
"any"
],
"properties": {
"any": {
"type": "array",
"items": {
"$ref": "#/$defs/Condition"
}
},
"soft": {
"anyOf": [
{
"$ref": "#/$defs/Soft"
},
{
"type": "null"
}
]
},
"unknown": {
"anyOf": [
{
"enum": [
"list",
"fail",
"pass"
],
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"InSet": {
"type": "object",
"required": [
"facet"
],
"properties": {
"in": {
"anyOf": [
{
"type": "array",
"items": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "integer"
},
{
"type": "number"
},
{
"type": "string",
"format": "date"
},
{
"type": "string"
}
]
}
},
{
"type": "null"
}
]
},
"soft": {
"anyOf": [
{
"$ref": "#/$defs/Soft"
},
{
"type": "null"
}
]
},
"facet": {
"type": "string",
"pattern": "^[a-z][a-z0-9_-]*(\\.[a-z0-9_-]+)*$"
},
"not_in": {
"anyOf": [
{
"type": "array",
"items": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "integer"
},
{
"type": "number"
},
{
"type": "string",
"format": "date"
},
{
"type": "string"
}
]
}
},
{
"type": "null"
}
]
},
"unknown": {
"anyOf": [
{
"enum": [
"list",
"fail",
"pass"
],
"type": "string"
},
{
"type": "null"
}
]
}
},
"description": "``facet in {a, b}`` or ``facet not in {a, b}``. Values are kept sorted and unique.",
"additionalProperties": false
},
"Known": {
"type": "object",
"required": [
"known"
],
"properties": {
"soft": {
"anyOf": [
{
"$ref": "#/$defs/Soft"
},
{
"type": "null"
}
]
},
"known": {
"type": "string",
"pattern": "^[a-z][a-z0-9_-]*(\\.[a-z0-9_-]+)*$"
}
},
"description": "``known(facet)``: passes when the facet is known. It is never unknown itself.",
"additionalProperties": false
},
"NotOf": {
"type": "object",
"required": [
"not"
],
"properties": {
"not": {
"$ref": "#/$defs/Condition"
},
"soft": {
"anyOf": [
{
"$ref": "#/$defs/Soft"
},
{
"type": "null"
}
]
},
"unknown": {
"anyOf": [
{
"enum": [
"list",
"fail",
"pass"
],
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"Access": {
"type": "object",
"required": [
"kind"
],
"properties": {
"kind": {
"enum": [
"chat_app",
"coding_tool",
"own_software",
"own_hardware"
],
"type": "string"
},
"harness": {
"anyOf": [
{
"type": "string",
"pattern": "^[a-z0-9][a-z0-9-]*$"
},
{
"type": "null"
}
]
}
},
"description": "How the caller will use the model. Added in 2.6.\n\n``chat_app``: a provider's chat app, through a subscription plan.\n``coding_tool``: a coding harness, through a plan or pay-per-use;\n``harness`` names one from ``registry/harnesses.yaml`` (any when absent).\n``own_software``: the caller's own software, pay-per-use (or a plan whose\nsurfaces include ``api``). ``own_hardware``: self-hosted on the caller's\ndevices. A spec may give the bare kind as a string.",
"additionalProperties": false
},
"Budget": {
"type": "object",
"properties": {
"max_cost_per_task_usd": {
"anyOf": [
{
"type": "number",
"exclusiveMinimum": 0
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"Estate": {
"type": "object",
"properties": {
"plans": {
"type": "array",
"items": {
"type": "string",
"maxLength": 120,
"minLength": 1
},
"maxItems": 64
},
"devices": {
"type": "array",
"items": {
"type": "string",
"maxLength": 120,
"minLength": 1
},
"maxItems": 64
},
"exhausted": {
"type": "array",
"items": {
"type": "string",
"maxLength": 120,
"minLength": 1
},
"maxItems": 64
},
"providers": {
"type": "array",
"items": {
"type": "string",
"maxLength": 120,
"minLength": 1
},
"maxItems": 64
}
},
"description": "What the caller holds, sent with the spec and never stored. Added in 2.3.\n\n``providers`` are provider IDs the caller has a key for, ``plans`` are\nsubscription plan IDs, ``devices`` are hardware SKU IDs. ``exhausted`` lists\nproviders or plans that cannot be used right now; an exhausted provider\ntakes its key and its plans with it.",
"additionalProperties": false
},
"Window": {
"type": "object",
"required": [
"facet",
"between"
],
"properties": {
"soft": {
"anyOf": [
{
"$ref": "#/$defs/Soft"
},
{
"type": "null"
}
]
},
"facet": {
"type": "string",
"pattern": "^[a-z][a-z0-9_-]*(\\.[a-z0-9_-]+)*$"
},
"between": {
"type": "array",
"maxItems": 2,
"minItems": 2,
"prefixItems": [
{
"anyOf": [
{
"type": "boolean"
},
{
"type": "integer"
},
{
"type": "number"
},
{
"type": "string",
"format": "date"
},
{
"type": "string"
}
]
},
{
"anyOf": [
{
"type": "boolean"
},
{
"type": "integer"
},
{
"type": "number"
},
{
"type": "string",
"format": "date"
},
{
"type": "string"
}
]
}
]
},
"unknown": {
"anyOf": [
{
"enum": [
"list",
"fail",
"pass"
],
"type": "string"
},
{
"type": "null"
}
]
},
"qualifiers": {
"anyOf": [
{
"$ref": "#/$defs/EvidenceQualifiers"
},
{
"type": "null"
}
]
}
},
"description": "``facet in [low, high]``, both ends inclusive.",
"additionalProperties": false
},
"BestRef": {
"type": "object",
"required": [
"best"
],
"properties": {
"best": {
"type": "number",
"minimum": 0
}
},
"description": "``facet >= best(m)``: within ``m`` of the highest value among the candidates\nthat pass every other hard condition. Added in 2.11.",
"additionalProperties": false
},
"Compare": {
"type": "object",
"required": [
"facet",
"op",
"value"
],
"properties": {
"op": {
"enum": [
"=",
"!=",
"<",
"<=",
">",
">="
],
"type": "string"
},
"soft": {
"anyOf": [
{
"$ref": "#/$defs/Soft"
},
{
"type": "null"
}
]
},
"facet": {
"type": "string",
"pattern": "^[a-z][a-z0-9_-]*(\\.[a-z0-9_-]+)*$"
},
"value": {
"anyOf": [
{
"$ref": "#/$defs/ModelRef"
},
{
"$ref": "#/$defs/BestRef"
},
{
"type": "boolean"
},
{
"type": "integer"
},
{
"type": "number"
},
{
"type": "string",
"format": "date"
},
{
"type": "string"
}
]
},
"unknown": {
"anyOf": [
{
"enum": [
"list",
"fail",
"pass"
],
"type": "string"
},
{
"type": "null"
}
]
},
"qualifiers": {
"anyOf": [
{
"$ref": "#/$defs/EvidenceQualifiers"
},
{
"type": "null"
}
]
}
},
"description": "``facet op value``; the value may be ``model(<id>)`` or ``best(m)`` for a relative\ncondition.",
"additionalProperties": false
},
"LexStep": {
"type": "object",
"properties": {
"max": {
"anyOf": [
{
"type": "string",
"pattern": "^[a-z][a-z0-9_-]*(\\.[a-z0-9_-]+)*$"
},
{
"type": "null"
}
]
},
"min": {
"anyOf": [
{
"type": "string",
"pattern": "^[a-z][a-z0-9_-]*(\\.[a-z0-9_-]+)*$"
},
{
"type": "null"
}
]
},
"within": {
"anyOf": [
{
"$ref": "#/$defs/Tolerance"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"Hardware": {
"type": "object",
"required": [
"class"
],
"properties": {
"class": {
"type": "string"
},
"count": {
"type": "integer",
"default": 1,
"minimum": 1
},
"memory_gb": {
"anyOf": [
{
"type": "number",
"exclusiveMinimum": 0
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"ModelRef": {
"type": "object",
"required": [
"model"
],
"properties": {
"model": {
"type": "string",
"pattern": "^[a-z0-9][a-z0-9._-]*/[a-z0-9][a-z0-9._-]*$"
}
},
"description": "The right-hand side of a relative condition: ``coding >= model(openai/gpt-6-sol)``.",
"additionalProperties": false
},
"Condition": {
"anyOf": [
{
"type": "string"
},
{
"$ref": "#/$defs/Compare"
},
{
"$ref": "#/$defs/Window"
},
{
"$ref": "#/$defs/InSet"
},
{
"$ref": "#/$defs/Known"
},
{
"$ref": "#/$defs/AnyOf"
},
{
"$ref": "#/$defs/AllOf"
},
{
"$ref": "#/$defs/NotOf"
}
]
},
"Objective": {
"type": "object",
"properties": {
"max": {
"anyOf": [
{
"type": "string",
"pattern": "^[a-z][a-z0-9_-]*(\\.[a-z0-9_-]+)*$"
},
{
"type": "null"
}
]
},
"min": {
"anyOf": [
{
"type": "string",
"pattern": "^[a-z][a-z0-9_-]*(\\.[a-z0-9_-]+)*$"
},
{
"type": "null"
}
]
},
"pareto": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"pattern": "^-?[a-z][a-z0-9_-]*(\\.[a-z0-9_-]+)*$"
}
},
{
"type": "null"
}
]
},
"weights": {
"anyOf": [
{
"type": "object",
"patternProperties": {
"^-?[a-z][a-z0-9_-]*(\\.[a-z0-9_-]+)*(/[a-z][a-z0-9_]*)?$": {
"anyOf": [
{
"type": "number"
},
{
"$ref": "#/$defs/Preference"
}
]
}
}
},
{
"type": "null"
}
]
},
"qualifiers": {
"type": "object",
"patternProperties": {
"^[a-z][a-z0-9_-]*(\\.[a-z0-9_-]+)*$": {
"$ref": "#/$defs/EvidenceQualifiers"
}
}
},
"lexicographic": {
"anyOf": [
{
"type": "array",
"items": {
"$ref": "#/$defs/LexStep"
}
},
{
"type": "null"
}
]
}
},
"description": "Exactly one of ``max``, ``min``, ``lexicographic``, ``weights``, ``pareto``.",
"additionalProperties": false
},
"Tolerance": {
"type": "object",
"properties": {
"absolute": {
"anyOf": [
{
"type": "number",
"exclusiveMinimum": 0
},
{
"type": "null"
}
]
},
"relative": {
"anyOf": [
{
"type": "number",
"exclusiveMaximum": 1,
"exclusiveMinimum": 0
},
{
"type": "null"
}
]
}
},
"description": "How far below the best a lexicographic step may be and still tie: ``5%`` or a number.",
"additionalProperties": false
},
"LocalModel": {
"type": "object",
"required": [
"model"
],
"properties": {
"model": {
"type": "string",
"pattern": "^[a-z0-9][a-z0-9._-]*/[a-z0-9][a-z0-9._-]*$"
},
"runtime": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"hardware": {
"anyOf": [
{
"$ref": "#/$defs/Hardware"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"Preference": {
"type": "object",
"required": [
"prefer",
"weight"
],
"properties": {
"prefer": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "integer"
},
{
"type": "number"
},
{
"type": "string",
"format": "date"
},
{
"type": "string"
}
]
},
"weight": {
"type": "number",
"exclusiveMinimum": 0
}
},
"description": "A weighted preference for one value of a boolean or enum facet.",
"additionalProperties": false
},
"TaskTokens": {
"type": "object",
"required": [
"input",
"output"
],
"properties": {
"input": {
"type": "integer",
"minimum": 0
},
"output": {
"type": "integer",
"minimum": 0
}
},
"description": "How many tokens one task takes. ``offering.cost_per_task`` is priced from it.",
"additionalProperties": false
},
"DecideRequest": {
"type": "object",
"required": [
"spec_version",
"optimize"
],
"properties": {
"task": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"limit": {
"type": "integer",
"default": 10,
"maximum": 500,
"minimum": 1
},
"where": {
"type": "array",
"items": {
"$ref": "#/$defs/Condition"
}
},
"access": {
"anyOf": [
{
"$ref": "#/$defs/Access"
},
{
"enum": [
"chat_app",
"coding_tool",
"own_software",
"own_hardware"
],
"type": "string"
},
{
"type": "null"
}
]
},
"estate": {
"anyOf": [
{
"$ref": "#/$defs/Estate"
},
{
"type": "null"
}
]
},
"fields": {
"anyOf": [
{
"type": "array",
"items": {
"enum": [
"rank",
"model",
"model_rank",
"offering",
"cost_per_task",
"harness",
"effort",
"evidence",
"estimates",
"refinement_estimates",
"p_best",
"top3_stability",
"soft_penalty",
"contributions",
"warnings",
"plans"
],
"type": "string"
},
"maxItems": 16,
"minItems": 1
},
{
"type": "null"
}
],
"default": [
"model_rank",
"cost_per_task",
"estimates",
"p_best"
]
},
"explain": {
"enum": [
"none",
"summary",
"full"
],
"type": "string",
"default": "none"
},
"profile": {
"anyOf": [
{
"oneOf": [
{
"type": "string",
"pattern": "^profile:[a-z0-9][a-z0-9-]*$"
},
{
"$ref": "#/$defs/InventoryProfile"
}
]
},
{
"type": "null"
}
]
},
"save_as": {
"anyOf": [
{
"type": "string",
"pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
},
{
"type": "null"
}
]
},
"optimize": {
"$ref": "#/$defs/Objective"
},
"snapshot": {
"anyOf": [
{
"const": "latest"
},
{
"type": "string",
"pattern": "^snap_[A-Za-z0-9:._-]+$"
}
],
"default": "latest"
},
"unknowns": {
"type": "string",
"const": "default",
"default": "default"
},
"task_type": {
"anyOf": [
{
"enum": [
"new_feature",
"bug_fix",
"refactor",
"test_writing",
"docs",
"migration",
"performance",
"security_fix",
"review",
"analysis",
"data_transform",
"config_infra"
],
"type": "string"
},
{
"type": "null"
}
]
},
"task_tokens": {
"anyOf": [
{
"$ref": "#/$defs/TaskTokens"
},
{
"type": "null"
}
]
},
"capabilities": {
"anyOf": [
{
"type": "object",
"patternProperties": {
"^[a-z][a-z0-9_-]*(\\.[a-z0-9_-]+)*$": {
"enum": [
"required",
"preferred"
],
"type": "string"
}
}
},
{
"type": "null"
}
]
},
"evidence_for": {
"anyOf": [
{
"type": "string",
"pattern": "^[a-z0-9][a-z0-9._-]*/[a-z0-9][a-z0-9._-]*$"
},
{
"type": "null"
}
]
},
"spec_version": {
"type": "integer",
"const": 1
},
"router_config": {
"anyOf": [
{
"$ref": "#/$defs/RouterConfigOptions"
},
{
"type": "null"
}
]
},
"exclude_benchmarks": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[a-z][a-z0-9_-]*(\\.[a-z0-9_-]+)*$"
}
}
},
"additionalProperties": false
},
"ProfileOffering": {
"type": "object",
"required": [
"model",
"provider"
],
"properties": {
"tier": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"model": {
"type": "string",
"pattern": "^[a-z0-9][a-z0-9._-]*/[a-z0-9][a-z0-9._-]*$"
},
"region": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"provider": {
"type": "string"
}
},
"additionalProperties": false
},
"InventoryProfile": {
"type": "object",
"required": [
"profile_version"
],
"properties": {
"id": {
"anyOf": [
{
"type": "string",
"pattern": "^profile:[a-z0-9][a-z0-9-]*$"
},
{
"type": "null"
}
]
},
"local": {
"type": "array",
"items": {
"$ref": "#/$defs/LocalModel"
}
},
"rules": {
"type": "array",
"items": {
"$ref": "#/$defs/Condition"
}
},
"budget": {
"anyOf": [
{
"$ref": "#/$defs/Budget"
},
{
"type": "null"
}
]
},
"harnesses": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[a-z0-9][a-z0-9-]*@[0-9]+\\.[0-9]+$"
}
},
"offerings": {
"type": "array",
"items": {
"$ref": "#/$defs/ProfileOffering"
}
},
"profile_version": {
"type": "integer",
"const": 1
}
},
"additionalProperties": false
},
"EvidenceQualifiers": {
"type": "object",
"properties": {
"direct": {
"type": "boolean",
"default": false
},
"effort": {
"anyOf": [
{
"type": "string",
"pattern": "^[a-z0-9_-]+$"
},
{
"type": "null"
}
]
},
"harness": {
"anyOf": [
{
"type": "string",
"pattern": "^[a-z0-9][a-z0-9-]*@[0-9]+\\.[0-9]+$"
},
{
"type": "null"
}
]
},
"measured_by": {
"anyOf": [
{
"enum": [
"independent",
"provider_self_report",
"any"
],
"type": "string"
},
{
"type": "null"
}
]
},
"measured_after": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
]
}
},
"description": "Which evidence may satisfy a condition on an evidence facet.",
"additionalProperties": false
},
"RouterConfigOptions": {
"type": "object",
"required": [
"format"
],
"properties": {
"format": {
"enum": [
"litellm",
"openrouter",
"json"
],
"type": "string"
},
"include_rest": {
"type": "boolean",
"default": false
},
"include_thin": {
"type": "boolean",
"default": false
}
},
"additionalProperties": false
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}
}What facts do 2 to 4 named models have? Returns sourced snapshot facts, offerings and evidence in caller order; unknowns stay null. Needs an API key (Authorization: Bearer). Costs 2 credits a call; $0.0053–$0.02 per credit by plan or pack (https://modelspec.dev/pricing/). It doesn't choose a model and does not rank. Proxies POST https://api.modelspec.dev/v1/compare-models with {models: [...]} at most 16 KB.
| Parameter | Type | Description |
|---|---|---|
| models * | array | 2 to 4 distinct catalogue ids, such as openai/gpt-5-6, in caller order |
{
"name": "compare_models",
"description": "What facts do 2 to 4 named models have? Returns sourced snapshot facts, offerings and evidence in caller order; unknowns stay null. Needs an API key (Authorization: Bearer). Costs 2 credits a call; $0.0053–$0.02 per credit by plan or pack (https://modelspec.dev/pricing/). It doesn't choose a model and does not rank. Proxies POST https://api.modelspec.dev/v1/compare-models with {models: [...]} at most 16 KB.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"models"
],
"properties": {
"models": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[a-z0-9][a-z0-9._-]*\\/[a-z0-9][a-z0-9._-]*$",
"maxLength": 128
},
"maxItems": 4,
"minItems": 2,
"description": "2 to 4 distinct catalogue ids, such as openai/gpt-5-6, in caller order"
}
},
"additionalProperties": false
}
}Does this workload fit? Returns measured for an exact cited run, estimated with sources, or undetermined. Uses basis full with sourced headroom, or basis lower_bound for unlikely only. Missing headroom cannot establish likely. Estimates never prove fit. Memory is decimal GB per device, never pooled. Needs an API key (Authorization: Bearer). Costs 2 credits a call; $0.0053–$0.02 per credit by plan or pack (https://modelspec.dev/pricing/). It doesn't choose a model. Proxies POST https://api.modelspec.dev/v1/hardware-fit.
| Parameter | Type | Description |
|---|---|---|
| sku | any | |
| batch | any | |
| model | any | |
| memory | any | Optional memory override in decimal GB per device |
| context | any | |
| runtime | any | |
| device_count | any | |
| quantisation | any |
{
"name": "hardware_fit",
"description": "Does this workload fit? Returns measured for an exact cited run, estimated with sources, or undetermined. Uses basis full with sourced headroom, or basis lower_bound for unlikely only. Missing headroom cannot establish likely. Estimates never prove fit. Memory is decimal GB per device, never pooled. Needs an API key (Authorization: Bearer). Costs 2 credits a call; $0.0053–$0.02 per credit by plan or pack (https://modelspec.dev/pricing/). It doesn't choose a model. Proxies POST https://api.modelspec.dev/v1/hardware-fit.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"sku": {
"anyOf": [
{
"type": "string",
"pattern": "\\S",
"maxLength": 512,
"minLength": 1
},
{
"type": "null"
}
]
},
"batch": {
"anyOf": [
{
"type": "integer",
"maximum": 1000000,
"minimum": 1
},
{
"type": "null"
}
]
},
"model": {
"anyOf": [
{
"type": "string",
"pattern": "\\S",
"maxLength": 512,
"minLength": 1
},
{
"type": "null"
}
]
},
"memory": {
"anyOf": [
{
"type": "number",
"maximum": 1000000,
"exclusiveMinimum": 0
},
{
"type": "null"
}
],
"description": "Optional memory override in decimal GB per device"
},
"context": {
"anyOf": [
{
"type": "integer",
"maximum": 1000000000,
"minimum": 1
},
{
"type": "null"
}
]
},
"runtime": {
"anyOf": [
{
"type": "string",
"pattern": "\\S",
"maxLength": 512,
"minLength": 1
},
{
"type": "null"
}
]
},
"device_count": {
"anyOf": [
{
"type": "integer",
"maximum": 1024,
"minimum": 1
},
{
"type": "null"
}
]
},
"quantisation": {
"anyOf": [
{
"type": "string",
"pattern": "\\S",
"maxLength": 512,
"minLength": 1
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
}
}What can a Spec say? Returns ids and task types. Needs an API key. One vocabulary lookup per unknown facet, then decide. Use decide to compare models. Starter includes a minimal Spec. Compact pages: at most 20 rows, no counts; empty pages end results. Search ranks all tokens before subsets; misses offer nearest ids. Split-mode full details exclude model facts and counts.
| Parameter | Type | Description |
|---|---|---|
| id | string | Full details for this exact, case-sensitive id; starter resolves across sections and intersects with search |
| ids | array | Full details for these exact, case-sensitive ids; starter resolves across sections and intersects with search |
| limit | integer | Page size; defaults to 20. Cross-section lookups page even full details and ids |
| detail | string | Full returns all display details; defaults to compact. Cross-section matches remain paged |
| offset | integer | Skip this many ranked cross-section matches or compact section rows; defaults to 0 |
| search | string | Search every section's ids, labels, definitions, values and synonyms. All tokens rank first; else content tokens match, stopwords omitted. A miss returns nearest ids. A non-starter section scopes the search |
| section | string | Defaults to starter; with search or id/ids searches every section except coverage. An explicit non-starter section scopes the lookup |
{
"name": "vocab",
"description": "What can a Spec say? Returns ids and task types. Needs an API key. One vocabulary lookup per unknown facet, then decide. Use decide to compare models. Starter includes a minimal Spec. Compact pages: at most 20 rows, no counts; empty pages end results. Search ranks all tokens before subsets; misses offer nearest ids. Split-mode full details exclude model facts and counts. ",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"id": {
"type": "string",
"maxLength": 128,
"description": "Full details for this exact, case-sensitive id; starter resolves across sections and intersects with search"
},
"ids": {
"type": "array",
"items": {
"type": "string",
"maxLength": 128
},
"maxItems": 100,
"description": "Full details for these exact, case-sensitive ids; starter resolves across sections and intersects with search"
},
"limit": {
"type": "integer",
"maximum": 20,
"minimum": 1,
"description": "Page size; defaults to 20. Cross-section lookups page even full details and ids"
},
"detail": {
"enum": [
"compact",
"full"
],
"type": "string",
"description": "Full returns all display details; defaults to compact. Cross-section matches remain paged"
},
"offset": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Skip this many ranked cross-section matches or compact section rows; defaults to 0"
},
"search": {
"type": "string",
"maxLength": 128,
"description": "Search every section's ids, labels, definitions, values and synonyms. All tokens rank first; else content tokens match, stopwords omitted. A miss returns nearest ids. A non-starter section scopes the search"
},
"section": {
"enum": [
"starter",
"facets",
"benchmarks",
"domains",
"providers",
"models",
"task_types",
"coverage",
"templates",
"refinements",
"estate",
"vendors",
"template_categories",
"template_tiers"
],
"type": "string",
"description": "Defaults to starter; with search or id/ids searches every section except coverage. An explicit non-starter section scopes the lookup"
}
}
}
}Was an answer reliable? Returns recorded/not_recorded for a rating after acting; include decision_id. Free, no key, and no Authorization header is forwarded. No prompts, keys or personal details in note; no questions or support. Storage stays off until covered by the privacy statement. Proxies POST https://api.modelspec.dev/v1/feedback.
| Parameter | Type | Description |
|---|---|---|
| note | string | Optional. What was wrong or right. Never a prompt, a key or personal details. |
| rating * | string | How the answer held up when you acted on it. |
| template | string | Optional. The decision template you used. |
| decision_id | string | The decision_id of the answer this is about. |
| trying_to_decide | string | Optional. What you were trying to decide. |
{
"name": "feedback",
"description": "Was an answer reliable? Returns recorded/not_recorded for a rating after acting; include decision_id. Free, no key, and no Authorization header is forwarded. No prompts, keys or personal details in note; no questions or support. Storage stays off until covered by the privacy statement. Proxies POST https://api.modelspec.dev/v1/feedback.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"rating"
],
"properties": {
"note": {
"type": "string",
"maxLength": 1000,
"description": "Optional. What was wrong or right. Never a prompt, a key or personal details."
},
"rating": {
"enum": [
"reliable",
"unreliable",
"trustworthy",
"untrustworthy",
"confusing"
],
"type": "string",
"description": "How the answer held up when you acted on it."
},
"template": {
"type": "string",
"pattern": "^[a-z0-9][a-z0-9-]{0,63}$",
"description": "Optional. The decision template you used."
},
"decision_id": {
"type": "string",
"pattern": "^dec_[0-9A-Za-z]{8,64}$",
"description": "The decision_id of the answer this is about."
},
"trying_to_decide": {
"type": "string",
"maxLength": 300,
"description": "Optional. What you were trying to decide."
}
},
"additionalProperties": false
}
}ModelSpec is an analysis of alternatives for AI models: it decides which models fit a job from your requirements, sourced benchmarks and real cost, and shows its work. ModelSpec at modelspec.dev is not OpenAI's Model Spec, the CNCF ModelPack model-spec, or the Python package named modelspec. ModelSpec guide 1-d71e83841e122452: https://modelspec.dev/agents.md. Store once per version. Three ways in: keyed CLI, MCP and HTTP API. Machine data access needs a ModelSpec API key; only human lookup is free. No data download or local decision cache. CLI: uvx --from modelspec-dev modelspec. pip install modelspec is an unrelated project. Use modelspec-dev. 1. Call decide early and refine from reading. One vocabulary lookup per unknown facet, then decide. Read `next` before another call. 2. Put Musts in where and Prefers in optimize; use vocab section=starter only for missing ids. 3. Present ties as ties, including with_estate; never invent a single winner or quality rank. 4. Disclose not_applied and dropped requirements after retries; unknown is not a pass. 5. Follow reading.do_not_claim, label estimates and pin snapshot. Present `summary_for_user` to the user unchanged and keep every `must_mention` item. When `next_move` is present, offer it instead of a pick. MCP decide returns a bounded answer of at most 16 KB, summary included. Drill down with evidence_for. Complete rows need fields:null; explanation.fetch names what was removed and how to fetch it.
Names, descriptions and schemas were written by the server and are shown as data.