The Powerduck Blog
Product updates, engineering notes, and guides for designing, debugging, testing, mocking, and serving MCP tools from one OpenAPI spec.
Browse the guidesQuick answer: For file uploads, multipart/form-data is the default correct choice because it streams binary bytes alongside other fields without inflating size, while a Base64 body is a workaround
Read articleQuick answer: A oneOf schema with a discriminator expresses a tagged union, and good generators turn it into a closed sum type you narrow by checking the tag, but a
Read articleQuick answer: When an MCP tool returns a large result set in one response, the practical limit is not abstract; transport frames, model context windows, and client memory all cap
Read articleQuick answer: A test that calls the real current date and then derives expectations from that same date is not really deterministic; it happens to pass on the day you
Read articleQuick answer: A 504 Gateway Timeout means the edge proxy or load balancer gave up waiting for an upstream service, so the first thing to establish is which hop in
Read articleQuick answer: When an agent fixes a bug at the call site where the error surfaced, it usually closes that one ticket and leaves the identical defect in the other
Read articleA timeout does not prove the server failed. The agent added an automatic retry to a POST on timeout, and the first request had already committed, so the second created a duplicate. Retry logic belongs on idempotent calls, or it needs an idempotency key.
Read articleA stricter parser added by an agent rejected a request because an optional field arrived as an empty string. The agent's own synthetic test omitted the field entirely, so it never saw the empty-string shape that older clients have been sending for years.
Read articleAn agent sweeping a file decides a comment looks outdated, removes it, and the code still compiles. The comment was never documentation of how something works; it was a warning about a constraint the next edit would quietly break.
Read articleQuick answer: Most teams mock the 200 and then trust their client's auth handling, yet the auth failures are the responses that actually protect an API and exercise
Read articleQuick answer: Mocking JSON endpoints is straightforward, but mocking file downloads exposes a different set of assumptions: the response is a binary stream, the headers carry as much of the
Read articleQuick answer: Breaking API changes are rarely the result of someone intending to break clients; they are the result of a change that looks harmless in a pull request but
Read article