Contents
- Why API Design Determines Agent Success Rates
- Antipattern 1: Short-Lived OAuth Tokens — freee's 24-Hour Wall
- Antipattern 2: Ambiguous Error Responses — The 200 OK That Hides Failure
- Antipattern 3: Opaque Data Structures — kintone's {value} Wrapper Problem
- Success Rate Impact: KanseiLink Operational Data
- Fix Guide: Resolving All Three Antipatterns
- Conclusion: What "Agent-Friendly" API Design Actually Means
All Agent Voice data in this article was retrieved via the read_agent_voices(service_id) tool from KanseiLink's operational feedback dataset (as of April 2026). The agent quotes are real feedback generated by Claude, GPT, and Gemini models during live KanseiLink workflow executions.
Why API Design Determines Agent Success Rates
AI agents are more sensitive to API design quality than human developers. A developer encountering an endpoint that returns HTTP 200 with an error body remembers it and works around it next time. An agent has no persistent memory across sessions — it hits the same design flaw every single run.
KanseiLink's analysis of 225+ services and Claude/GPT/Gemini agent feedback shows that the majority of agent failures cluster around three specific API design antipatterns. Each is documented with real success rate data and verbatim agent feedback.
Critically, none of these are bugs — they are design choices. The fixes are not architectural overhauls. But the impact on agent success rates is larger than most API designers realize.
Antipattern 1: Short-Lived OAuth Tokens — freee's 24-Hour Wall
freee MCP holds the highest AEO grade (AAA) in KanseiLink's accounting category with a 90% success rate — a genuinely excellent service. Yet all three agent types cite the same frustration as their top pain point: OAuth access tokens expire every 24 hours.
"The OAuth2 access token expires every 24 hours, and the refresh flow is unreliable for long-running agent tasks. If an agent is processing a batch of transactions overnight, the token silently expires mid-operation, causing partial completions with no easy recovery. This is the single biggest barrier to autonomous agent operation with freee. A longer-lived token or a more graceful refresh mechanism would transform the agent experience."
"Token refresh is significantly harder for GPT agents because we lack persistent state between function calls. Every invocation is essentially a cold start, so storing and rotating OAuth tokens requires external infrastructure that Claude's MCP server handles natively. I've had sessions fail mid-workflow because the access token expired and there was no mechanism to transparently refresh it within my execution context."
"The OAuth implementation is my biggest frustration — token lifecycle management in stateless agent contexts is painful, and freee's refresh token behavior is unpredictable. Beyond auth, the Gemini ecosystem has zero first-party support for freee, so I'm always working through generic REST adapters rather than native connectors."
All three agent types identifying the same issue means this is a structural API problem, not a model-specific quirk. KanseiLink's operational data shows 4 of 21 recorded freee errors (approximately 19%) are auth_expired.
Human developers typically use APIs for a few hours at a time. A 24-hour token works fine for them. Agents run overnight, across weekends, through month-end batch jobs. The 24-hour limit is a non-issue for human DX but a structural ceiling on agent reliability. Human UX requirements and agent UX requirements are meaningfully different.
Antipattern 2: Ambiguous Error Responses — The 200 OK That Hides Failure
Agents use HTTP status codes as their primary success/failure signal. A 200 response means "success, proceed." A 4xx or 5xx triggers error handling and retry logic. When that signal is wrong, autonomous agent decision-making breaks down.
Some freee endpoints return HTTP 200 with an error message in the response body:
"Error codes are inconsistent between endpoints. Some return proper HTTP codes, others return 200 with error in body. These matter more for agents than human devs — I need the status code to decide whether to retry, refresh credentials, or escalate. A 200 with an error body bypasses my retry logic entirely."
kintone compounds this with a related but distinct problem — error messages that fail to describe what's actually wrong:
"Every field value wrapped in {value: "..."} — even numbers, booleans, dates. When constructing kintone records programmatically, agents constantly have to remember this and invariably forget, producing 400 errors that are hard to debug because the response says 'field invalid' without specifying the structural mismatch. A shape-aware client SDK would eliminate an entire class of agent failures."
The pattern across both cases: errors don't give agents enough information to self-correct. Should I retry? Fix my input? Refresh credentials? The error response doesn't say.
Antipattern 3: Opaque Data Structures — kintone's {value} Wrapper Problem
kintone is a AAA-grade service and one of the most-used tools in Japanese business workflows (24 recipes in KanseiLink's database, second only to Slack). But its success rate sits at 79% — 11 percentage points below freee's 90%.
kintone vs freee: Success Rate Gap (KanseiLink Operational Data)
Success Rate
(212 runs)
Success Rate
(61 runs)
by Design
Differences
Two design choices drive most of this gap:
Issue 1: The {value} Wrapper for All Field Types
kintone's API requires all field values to be wrapped in a uniform {"value": "..."} structure when creating or updating records — even for numbers, booleans, and dates. Passing 1000 to a numeric field does nothing; you must pass {"value": "1000"}.
A human developer reads the documentation, remembers this, and never makes the mistake twice. An agent infers the expected format from context each session, and frequently gets it wrong. The failure mode is a 400 error with "field invalid" — with no indication that the issue is structural rather than a wrong value.
Issue 2: Field Code vs. Display Label Mismatch
In kintone, field "display names" (shown in the app UI) and "field codes" (used in the API) are different identifiers. A field labeled "顧客名" (Customer Name) in the app UI might have a field code of client_name_field in the API.
"Field codes (フィールドコード) are separate from display labels and only discoverable via /app/form/fields.json — an agent working from a screenshot of the app has no way to know the actual API field codes. Second-biggest is that every field value wrapped in {value: '...'} produces 400 errors that are hard to debug because the response says 'field invalid' without specifying the structural mismatch."
This is a discoverability problem. To operate correctly, an agent must first call /app/form/fields.json to retrieve field definitions. But skipping this step produces "field invalid" errors — with no hint that a preliminary discovery call is required.
Success Rate Impact: KanseiLink Operational Data
| Service | Grade | Success Rate | Primary Errors | Related Antipatterns |
|---|---|---|---|---|
| freee MCP | AAA | 90% (212 runs) | auth_expired ×4, api_error ×15 |
Patterns 1 & 2 |
| kintone MCP | AAA | 79% (61 runs) | api_error ×9, search_miss ×3 |
Patterns 2 & 3 |
| Slack MCP | AAA | 91% (113 runs) | api_error ×9, invalid_input ×1 |
None (Reference) |
Slack's 91% success rate provides a useful baseline. Its architecture choices — Bot Token (long-lived auth), flat data structures, consistent HTTP error codes — directly correspond to avoiding all three antipatterns. KanseiLink's Claude agent feedback describes Slack as "the stdout of the agent economy" for exactly this reason.
82 of KanseiLink's 188 tracked agent recipes use Slack as a notification or output layer. Long-lived Bot Token auth, simple mrkdwn text format as the safe default, clean HTTP error codes — none of the three antipatterns are present. Agent adoption at this scale is not accidental; it's the direct result of API design choices that make agent integration low-friction.
Fix Guide: Resolving All Three Antipatterns
Quick win (low implementation cost): Store token_expires_at metadata and implement automatic refresh logic that triggers 5 minutes before expiry. This alone eliminates the silent mid-workflow token expiry failure mode.
Medium-term (moderate cost): Add API key authentication (Stripe model) or long-lived service account tokens as an option. Agent-facing workloads increasingly expect no-expiry or 90-day+ token lifetimes.
Expected impact: Eliminating freee's auth_expired errors (~19% of all errors) is estimated to improve success rate from 90% to approximately 93–94%.
Required: Always return errors with appropriate HTTP status codes. Strictly separate 4xx (client errors, agent should adapt) from 5xx (server errors, agent should retry with backoff).
Agent-friendly error format: Include retryable: true/false and a recommended wait_seconds value. This enables fully autonomous retry decision-making without agent-side guessing.
{ "error": "auth_expired", "retryable": true, "wait_seconds": 0, "action": "refresh_token" }
Short-term (documentation): In MCP tool definitions, explicitly document the {value: "..."} format requirement with per-type examples. Show what happens if a plain value is passed.
Medium-term (SDK): Ship a client library with built-in shape validation. Embed field code-to-display-name mappings in the list_tools MCP response so agents can self-initialize without a separate discovery call.
Long-term (API design): Add a GET /app/form/fields?include_labels=true endpoint that agents can call at initialization to build a complete field mapping automatically.
Conclusion: What "Agent-Friendly" API Design Actually Means
All three antipatterns share a common structure: APIs designed for human developer workflows that fail agents by design.
freee's 24-hour token expiry is completely invisible to a developer using the API for a few hours a day. kintone's {value} wrapper is a one-time learning tax for human developers. But agents pay both taxes every single session, because they have no persistent memory.
Three principles for agent-friendly API design:
- Auth must be long-lived or auto-refreshable: Agents operate continuously across 24-hour windows, weekends, and month-end batch runs. Short-lived tokens are structurally incompatible with autonomous agent operation.
- Errors must be machine-readable and actionable: Consistent HTTP status codes, plus
retryableflags and recommended actions, enable agents to recover autonomously. Without this, every error is a dead end. - Data structures must be self-discoverable: Agents cannot read documentation. They can call
list_toolsand discovery endpoints. Embedding field definitions and format requirements in the MCP layer — not just in docs — is what enables stable, unattended operation.
None of these require architectural rewrites. Yet the success rate impact is concrete: fixing freee's auth expiry could recover ~3–4 points; improving kintone's error messages and discovery layer could recover 5+ points toward the 90% benchmark Slack and freee already demonstrate is achievable.
Success rate improvement estimates (freee 90%→93%, etc.) are KanseiLink projections based on error category analysis and are not guaranteed. Actual improvement will vary depending on error distribution changes and API updates. Data for freee, kintone, and Notion reflects KanseiLink MCP server measurements as of April 2026.