Need API Documentation Rewritten for AI
Nico discovered that MCP servers built from existing API documentation fail because the docs were written for humans, not AI agents.
Take Control Of Your Signals — Become a Naftiko Design Partner Today!
Persona Story:
Nico, the partner AI lead, discovered that MCP servers built from existing API documentation fail because the documentation was written for human developers, not AI agents.
Problem Context
- MCP tools are currently just dumps of API documentation
- Human developers bring implicit context that AI doesn’t have
- “Talking to a computer that speaks human as a second language”
Problem Impact
- AI agents misuse APIs due to insufficient context
- Quality of AI-driven integrations is “suspicious”
- Partner integrations fail despite technically correct API exposure
Naftiko Today
- Agent Skills exposure provides business-level skill grouping with AI-oriented descriptions, replacing raw API doc dumps with purposeful context
- OutputParameters normalization acts as a governance layer that shapes API responses for AI consumption, so agents see clean, relevant data rather than raw payloads
- MCP tool exposure translates API capabilities into well-structured tool definitions designed for agent consumption, not human reading
- Capability specs in YAML provide a dedicated layer for describing API behavior in terms agents understand, separate from human-facing documentation
Naftiko Tomorrow
- Tool annotations for readOnly/destructive/idempotent (May 2026) would add behavioral metadata that helps agents understand the consequences of each action
- HTML/Markdown format support (May 2026) would enable structured, AI-optimized descriptions within tool definitions
- Starter templates (May 2026) would codify best practices for writing agent-friendly capability descriptions
- OpenAPI-to-Naftiko import (May 2026) would provide a structured path to transform existing API docs into agent-ready capability specs