By name: "tool-default-alignment" description: "Keep agent-facing tool signatures aligned with MCP and REST defaults so model tool calls do not fail before execution" domain: "backend-api" confidence: "high" source: "earned from Apex Grill Southwest performance-tool failure"
Context
Use this skill when a Retail Pulse API tool proxies an MCP or REST endpoint. The model reasons over the proxy signature, not the downstream controller or MCP implementation, so any mismatch in optional vs required parameters can break tool invocation even when the data layer is healthy.
Patterns
- Mirror optional defaults across all three layers: API proxy tool, MCP tool, and REST endpoint.
- Prefer tenant-real examples in
[Description]attributes (Apex Grill,Southwest) so the model sees values that actually exist intenant.yaml. - When a brand/region query fails, verify the route first (
RetailOpsRouter), then inspect proxy signatures before blaming the seeded data. - Add a regression test that omits the optional argument and asserts the generated request still carries the default.
Examples
src\RetailPulse.Api\Tools\DepletionStatsTool.csnow defaultsperiod = "YTD"to matchsrc\RetailPulse.McpServer\Tools\GetDepletionStatsTool.cs.src\RetailPulse.McpServer\Program.csexposes/api/depletion-statswithstring period = "YTD"so direct HTTP callers behave the same as MCP callers.tests\RetailPulse.Tests\ToolTests.csverifiesDepletionStatsToolsendsperiod=YTDwhen the model omits the argument.
Anti-Patterns
- Treating a proxy wrapper as a separate contract from the MCP tool it forwards to.
- Requiring parameters in the agent-facing tool that are optional downstream.
- Assuming a missing-answer failure means the tenant data was not seeded.