compare_providersReturn 2 to 6 public provider profiles together with evidence and caveats. Compare like-for-like products yourself. Does not calculate a winner, buy hosting or change data.
| Name | Required | Description | Default |
|---|---|---|---|
| ids | Yes |
| Name | Required | Description | Default |
|---|---|---|---|
| count | Yes | ||
| providers | Yes | ||
| disclosure | Yes | ||
| limitations | Yes |
Changes observed during successful MCP inspections.
Output schema / properties / providers / itemsPrevious value: -{
- "additionalProperties": false,
- "description": "",
- "properties": {
- "category": {
- "description": "Service category.",
- "type": "string"
- },
- "description": {
- "description": "Public summary.",
- "type": "string"
- },
- "id": {
- "description": "Stable provider ID.",
- "type": "string"
- },
- "location": {
- "additionalProperties": false,
- "description": "",
- "properties": {
- "backup": {
- "description": "Backup evidence and uncertainties.",
- "type": "string"
- },
- "documented": {
- "description": "Primary location evidence only, not proof for all subprocessors or backups.",
- "type": "boolean"
- },
- "limitations": {
- "description": "Limits of the location evidence.",
- "type": "string"
- },
- "passport": {
- "description": "Absolute public URL.",
- "format": "uri",
- "type": "string"
- },
- "primary": {
- "description": "Primary data location.",
- "type": "string"
- },
- "region": {
- "description": "eu, eu-ch or unknown; Switzerland is separate from the EU.",
- "type": "string"
- }
- },
- "required": [
- "region",
- "documented",
- "primary",
- "backup",
- "limitations",
- "passport"
- ],
- "type": "object"
- },
- "migration": {
- "description": "",
- "items": {
- "additionalProperties": false,
- "description": "",
- "properties": {
- "refs": {
- "description": "",
- "items": {
- "description": "ID in this provider sources array.",
- "type": "string"
- },
- "type": "array"
- },
- "text": {
- "description": "Public editorial claim.",
- "type": "string"
- }
- },
- "required": [
- "text",
- "refs"
- ],
- "type": "object"
- },
- "type": "array"
- },
- "name": {
- "description": "Provider name.",
- "type": "string"
- },
- "package": {
- "description": "Exact selected package.",
- "type": "string"
- },
- "price": {
- "additionalProperties": false,
- "description": "",
- "properties": {
- "checked": {
- "description": "Original source review date; not export time.",
- "format": "date",
- "type": [
- "string",
- "null"
- ]
- },
- "conditions": {
- "description": "Displayed price conditions, including historic status.",
- "type": "string"
- },
- "label": {
- "description": "Public displayed price.",
- "type": "string"
- },
- "offer": {
- "additionalProperties": false,
- "description": "Selected price basis only; other contract options may be explained on the profile.",
- "properties": {
- "billingMonths": {
- "description": "Billing interval in months, not necessarily the minimum contract duration.",
- "minimum": 0,
- "type": "integer"
- },
- "conditions": {
- "description": "Scope, billing unit, assumptions and limitations.",
- "type": "string"
- },
- "currency": {
- "description": "Currency of source amounts.",
- "enum": [
- "EUR"
- ],
- "type": "string"
- },
- "extras": {
- "description": "",
- "items": {
- "description": "Excluded or unconfirmed additional cost.",
- "type": "string"
- },
- "type": "array"
- },
- "introCents": {
- "description": "Source monthly or usage-unit introductory amount in eurocents, before VAT conversion.",
- "minimum": 0,
- "type": "integer"
- },
- "introMonths": {
- "description": "Months at the introductory rate; zero means no introductory period.",
- "minimum": 0,
- "type": "integer"
- },
- "kind": {
- "description": "Products with different billing models are not interchangeable.",
- "enum": [
- "subscription",
- "usage",
- "free"
- ],
- "type": "string"
- },
- "promo": {
- "description": "Whether the recorded offer is promotional.",
- "type": "boolean"
- },
- "promoEnd": {
- "description": "Recorded promotion end date YYYY-MM-DD, or empty if not specified.",
- "pattern": "^(\\d{4}-\\d{2}-\\d{2})?$",
- "type": "string"
- },
- "regularCents": {
- "description": "Source monthly or usage-unit renewal amount in eurocents; not a future price guarantee.",
- "minimum": 0,
- "type": "integer"
- },
- "setupCents": {
- "description": "One-time source setup fee; null means unconfirmed, not zero.",
- "minimum": 0,
- "type": [
- "integer",
- "null"
- ]
- },
- "term": {
- "description": "Contract, prepayment and renewal conditions.",
- "type": "string"
- },
- "vat": {
- "description": "gross: VAT included; net21: exclude 21 percent VAT; assumed_gross: inclusion assumed, not confirmed.",
- "enum": [
- "gross",
- "net21",
- "assumed_gross",
- "unknown"
- ],
- "type": "string"
- }
- },
- "required": [
- "currency",
- "kind",
- "vat",
- "introCents",
- "introMonths",
- "regularCents",
- "billingMonths",
- "setupCents",
- "promo",
- "promoEnd",
- "term",
- "conditions",
- "extras"
- ],
- "type": [
- "object",
- "null"
- ]
- },
- "renewalLabel": {
- "description": "Public renewal description.",
- "type": "string"
- },
- "sources": {
- "description": "Official evidence for the selected price basis.",
- "items": {
- "description": "Absolute public URL.",
- "format": "uri",
- "type": "string"
- },
- "type": "array"
- },
- "status": {
- "description": "checked: approved within validity rules; historical: last approved basis, not confirmed current; unknown: no publishable basis.",
- "enum": [
- "checked",
- "historical",
- "unknown"
- ],
- "type": "string"
- },
- "term": {
- "description": "Contract and billing conditions.",
- "type": "string"
- }
- },
- "required": [
- "label",
- "renewalLabel",
- "conditions",
- "term",
- "status",
- "checked",
- "offer",
- "sources"
- ],
- "type": "object"
- },
- "profile": {
- "description": "Absolute public URL.",
- "format": "uri",
- "type": "string"
- },
- "purchase": {
- "additionalProperties": false,
- "description": "",
- "properties": {
- "affiliateAvailable": {
- "description": "Profile may contain a disclosed affiliate link.",
- "type": "boolean"
- },
- "checkout": {
- "description": "Orders and payments occur with the provider, not HostDirect.",
- "type": "string"
- },
- "profile": {
- "description": "Absolute public URL.",
- "format": "uri",
- "type": "string"
- },
- "providerUrl": {
- "description": "Absolute public URL.",
- "format": "uri",
- "type": "string"
- }
- },
- "required": [
- "profile",
- "providerUrl",
- "affiliateAvailable",
- "checkout"
- ],
- "type": "object"
- },
- "sources": {
- "description": "",
- "items": {
- "additionalProperties": false,
- "description": "",
- "properties": {
- "checked": {
- "description": "Original source review date; not export time.",
- "format": "date",
- "type": "string"
- },
- "id": {
- "description": "Stable source reference.",
- "type": "string"
- },
- "label": {
- "description": "Source title.",
- "type": "string"
- },
- "url": {
- "description": "Absolute public URL.",
- "format": "uri",
- "type": "string"
- }
- },
- "required": [
- "id",
- "label",
- "url",
- "checked"
- ],
- "type": "object"
- },
- "type": "array"
- },
- "specifications": {
- "description": "",
- "items": {
- "additionalProperties": false,
- "description": "",
- "properties": {
- "refs": {
- "description": "",
- "items": {
- "description": "ID in this provider sources array.",
- "type": "string"
- },
- "type": "array"
- },
- "text": {
- "description": "Public editorial claim.",
- "type": "string"
- }
- },
- "required": [
- "text",
- "refs"
- ],
- "type": "object"
- },
- "type": "array"
- },
- "suitable": {
- "description": "",
- "items": {
- "additionalProperties": false,
- "description": "",
- "properties": {
- "refs": {
- "description": "",
- "items": {
- "description": "ID in this provider sources array.",
- "type": "string"
- },
- "type": "array"
- },
- "text": {
- "description": "Public editorial claim.",
- "type": "string"
- }
- },
- "required": [
- "text",
- "refs"
- ],
- "type": "object"
- },
- "type": "array"
- },
- "unsuitable": {
- "description": "",
- "items": {
- "additionalProperties": false,
- "description": "",
- "properties": {
- "refs": {
- "description": "",
- "items": {
- "description": "ID in this provider sources array.",
- "type": "string"
- },
- "type": "array"
- },
- "text": {
- "description": "Public editorial claim.",
- "type": "string"
- }
- },
- "required": [
- "text",
- "refs"
- ],
- "type": "object"
- },
- "type": "array"
- }
- },
- "required": [
- "id",
- "name",
- "package",
- "category",
- "description",
- "profile",
- "price",
- "location",
- "suitable",
- "unsuitable",
- "specifications",
- "migration",
- "sources",
- "purchase"
- ],
- "type": "object"
-}New value: +nullDoes the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the bar is lower; the description still adds real context by stating the result includes evidence and caveats and that no winner is computed, no hosting is purchased and no data changes. It stops short of describing behavior for unknown or duplicate IDs or whether result order follows the input order.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences with the payload, the agent's responsibility, and the explicit non-behaviors in that order. Nothing is repeated and the exclusions are front-loaded where they matter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return structure need not be explained, and the tool takes a single required array. The description covers scope, count, and side-effect boundaries adequately; only edge-case behavior for invalid IDs is unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents the sole parameter thoroughly (exact provider ID from search_providers, minItems 2, maxItems 6, uniqueItems, pattern). The description only restates the 2-to-6 cardinality, adding no new meaning about ID format, ordering, or partial-failure handling, so this sits at the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource ('Return 2 to 6 public provider profiles together with evidence and caveats') and scopes the output size. It does not name the sibling it differs from (get_provider returns one, search_providers finds IDs), so the agent must infer the multi-item boundary from the '2 to 6' phrasing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the cardinality ('2 to 6' profiles) and by the exclusion 'Does not calculate a winner', which tells the agent the ranking work is its own. There is no explicit statement of when to prefer this over get_provider or search_providers, and no note that IDs must first come from search_providers beyond what the schema says.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.