Jentic Tech Talk

Discoverable by Design: Why Better Data Beats a Bigger Model

Our new whitepaper "Discoverable by Design" shows the gains to be had when improving APIs for AI discoverability.

AI agents live or die by whether they can find the right tool at runtime. We benchmarked 8,467 API operations across 70 real enterprise APIs to work out what actually makes agents reliable, and the answer was not the model. Improving API description quality and search lifted agent retrieval accuracy from 59% to 94%.

What's inside:

• Why tool discovery, not too invocation, makes or breaks agent reliability.

• Why a cheaper model on good data beats an expensive model on bad data.

• How to prioritise the API fixes that move the needle most.

Actor-in-the-Loop: A Much-Needed Arazzo Capability

Arazzo describes workflows as deterministic sequences that run to completion. What it cannot describe is the moment a workflow has to stop, ask a question, and wait: a buy-now-pay-later checkout that hits partial eligibility, or a deployment that needs an operator to sign off before anything touches infrastructure.

My proposal adds a first-class interaction field on a step, with three modes: form for structured responses described with JSON Schema, redirect for OAuth-style callbacks, and acknowledge for approval gates. Timeouts live in the interaction itself with an onTimeout branch, and the actor’s validated response flows downstream as a normal output.

It also lines up with MCP’s Multi Round-Trip Request pattern, so an executor can resume in a stateless fashion behind a load balancer with no sticky routing. A formal proposal for Arazzo 1.2 is in progress.

API Problem Details: Error Responses Agents Can Actually Use

Error handling is the part of API design that gets deferred and then shipped as whatever was convenient. Every team ends up with a different format. Every consumer writes custom parsing logic, and that becomes brittle and expensive as agents dominate API consumption. An agent hitting an unexpected response has no reliable signal for what went wrong or what to do next, which means agent recovery behaviour remains unpredictable.

RFC 9457 is the industry's strongest answer to this. It defines a standard application/problem+json response shape with a clear extensibility model for domain-specific fields, and our API AI-Readiness scoring data puts error_standardization adoption at around 3% across public APIs. Knowing the RFC and bootstrapping consistent implementation across a codebase are different things, and the gap between the two is why adoption stays low.

We built the jentic/api-problem-details packages to close the gap for our own tooling, but have made them publicly available as open source software. They provide reusable, agent-friendly Problem Details schemas for HTTP-based APIs, with implementation packages in both Python and TypeScript. The components are designed to be referenced directly into OpenAPI documents, giving consistent error shapes across every operation defined once.