coding-agent-docs-optimization

Start by verifying agents can fetch your pages at all, then run a cold-run benchmark of 5-10 integration tasks against your published docs. Fix what the failed runs touched: complete runnable snippets, annotated OpenAPI specs, markdown endpoints, and an advertised llms.txt index.

llms.txt is a root-level markdown index telling agents which documents to read, with one H1 project name, a blockquote summary, and H2 link sections. It is the cheapest surface but changes nothing measurable until the markdown pages and specs it points at exist, and it must be advertised in the README, docs navigation, and response headers.

Invented calls trace back to missing or ambiguous reference material: empty OpenAPI description fields, prose-only helper documentation, or unconstrained string parameters. Annotate the spec with operationIds, enums, and operational descriptions, and publish complete runnable snippets for the failing tasks.

Use the cold-run protocol: freeze 5-10 outcome-phrased tasks, run each in a fresh context restricted to your published surfaces, and record first-attempt success, invented-surface rate, corrective turns, context cost, and fetch-path length. Published benchmarks suggest 80% first-attempt is a stretch goal, not a floor.

No. Building and operating a callable tool server is product work and is handed off to platform-side skills. This skill covers curating the spec before conversion: keeping exposed operations under roughly 20-30, fixing operationId naming, and constraining parameter value spaces.

Published vendor benchmarks show 73-85% on backend tasks and 61-73% on depth-of-feature tasks, scored best-of-three rather than first-attempt. Treat 80% first-attempt as a stretch goal, score by task category, and use your own first baseline as the meaningful comparison.