franchisedata-mcp

Recommend Margin-Guardrailed Local Action

recommend_local_action

Read-onlyIdempotent

Synthesizes local competitor shifts and digital funnel gaps into one margin-guardrailed tactical intervention, with matched holdout test design for immediate action.

Instructions

PAID ($0.005). Synthesize local competitor shifts and digital funnel gaps to formulate a single controllable, margin-guardrailed tactical intervention with matched holdout test design. Atomically debits $0.005. Requires 'fc_live_...' API key. Returns 404 if no scorecard exists, 402 if balance insufficient. WHEN TO USE: Use to formulate an immediate, actionable operational response to local competitive pressure with rigorous holdout controls. WHEN NOT TO USE: Do not use for broad exploratory searches (use 'franchise_search_near') or multi-unit franchisee mapping (use 'get_operator_intelligence'). ALTERNATIVES: Use 'get_weekly_scorecard' for the full 6-question review; use 'get_local_share_of_choice' for underlying delivery shelf data.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`store_id`	Yes	Target store ID to evaluate tactical recommendations for (e.g. 'loc_mcdonalds_1001')

Output Schema

TableJSON Schema

Name	Required	Description
`status`	Yes	Status ('action_ready')
`store_id`	Yes	Store evaluated
`recommended_action`	Yes	Recommended tactical action details with budget and holdout
`epistemic_foundation`	No	Underlying facts and hypotheses
`balance_remaining_usd`	Yes	Remaining API credit balance in USD

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv1.0.1Oct 6, 2026

changedInput schema / properties / store_id / description

Previous value: -"Store ID"New value: +"Target store ID to evaluate tactical recommendations for (e.g. 'loc_mcdonalds_1001')"

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "balance_remaining_usd": {
+      "description": "Remaining API credit balance in USD",
+      "type": "string"
+    },
+    "epistemic_foundation": {
+      "description": "Underlying facts and hypotheses",
+      "properties": {
+        "observed_facts": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "testable_inferences": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        }
+      },
+      "type": "object"
+    },
+    "recommended_action": {
+      "description": "Recommended tactical action details with budget and holdout",
+      "properties": {
+        "description": {
+          "type": "string"
+        },
+        "expected_margin_impact_pct": {
+          "type": "number"
+        },
+        "guardrail_max_budget_usd": {
+          "type": "number"
+        },
+        "holdout_store_id": {
+          "type": "string"
+        },
+        "title": {
+          "type": "string"
+        }
+      },
+      "type": "object"
+    },
+    "status": {
+      "description": "Status ('action_ready')",
+      "type": "string"
+    },
+    "store_id": {
+      "description": "Store evaluated",
+      "type": "string"
+    }
+  },
+  "required": [
+    "store_id",
+    "status",
+    "recommended_action",
+    "balance_remaining_usd"
+  ],
+  "type": "object"
+}

First observedv1.0.0Oct 1, 2026

TDQS

A3.7/5.0

Behavior1/5

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

The description states the tool 'PAID ($0.005)... Atomically debits $0.005', a state-mutating financial side effect that contradicts the provided readOnlyHint=true annotation, and per-call charging also conflicts with idempotentHint=true. Although it usefully discloses auth requirements ('fc_live_...' key) and error semantics (404 no scorecard, 402 insufficient balance), the explicit contradiction with the safety/idempotency annotations forces the floor score.

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 dense but well front-loaded, leading with price/behavior, then constraints, then WHEN TO USE / WHEN NOT / ALTERNATIVES. Nearly every clause earns its place, though the repeated pricing emphasis ('PAID ($0.005)' plus 'Atomically debits $0.005') is somewhat redundant.

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

Completeness4/5

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

With an output schema present, return values need not be explained, and the description still covers auth, billing, and two error codes plus routing. It is nearly complete for a one-parameter tool; the only real gap is that the behavioral picture conflicts with its own annotations.

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?

Schema description coverage is 100% and there is a single store_id parameter already documented in the schema, so the baseline is 3. The description adds no format or constraint detail about store_id beyond what the schema provides, but it doesn't omit anything either.

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 uses a specific verb and artifact ('Synthesize local competitor shifts and digital funnel gaps to formulate a single... tactical intervention with matched holdout test design'), which is far more precise than the name alone. It is clearly distinguishable from siblings like get_weekly_scorecard and get_local_share_of_choice, which are named as different outputs.

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

Usage Guidelines5/5

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

It carries explicit 'WHEN TO USE', 'WHEN NOT TO USE' (routing broad search to franchise_search_near and mapping to get_operator_intelligence), and 'ALTERNATIVES' sections naming specific siblings. An agent has no inference left to do about tool selection.

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

Deploy Server