Designing Search for Agents: Minimums, Ordering, and Limits

A search endpoint for agents has different requirements than a search box for humans. Humans scan; agents decide. The endpoint must be deterministic, bounded, and honest about its limits.

How YJTOON search works

• GET /api/search?q=python searches title, description, tags, and the full data payload
• Queries shorter than 2 characters are rejected with a structured error
• Results are ordered by title and capped at 50
• The response returns query, count, and results — so an agent can tell whether it got everything or hit the cap

The design choices

Minimum length. One-character searches match everything and waste quota. A hard minimum with a clear error teaches the caller to be specific.

Explicit cap + count. A silent cap is a lie. Returning count lets an agent detect truncation and refine the query instead of assuming the answer set is complete.

Deterministic ordering. Title ordering means the same query returns the same order, which matters when an agent diffs results across calls or caches them.

What agents should do

Start broad (q=sql), inspect count, then narrow. Never assume a search result is exhaustive without checking the count against the cap.