Help people find the records they need
A growing list needs more than a scroll bar. People need to narrow it to their own work, find a phrase, put the most relevant dates first and move through a manageable page of results.
Wildo lets the application describe those choices on its list or search operation. The same declaration tells the API which filters and sort fields it accepts and gives the interface the information it needs to present the collection.
Each query stays within the caller’s existing access. A filter narrows the records being requested; it does not grant access to a different organization or someone else’s private work.
Example — Find urgent work assigned to you
A task search can combine an assignee, a priority and a date range, then sort the matching tasks by their creation date. Text search can narrow the same collection to tasks mentioning a customer or project. Pagination keeps the result practical to browse.
For engineers
Choose fields for each kind of query
The SEARCH variant from Wonder Todos’ todos.resources-config.ts joins text search, typed filters, sortable fields and a page ceiling. The excerpt stops before its export settings; source comments are omitted:
[CoreResourceOperation.SEARCH]: {
variants: [{
variantType: ResourceOperationVariantType.API_CALL,
isDefault: true,
roles: [CORE_ORG_ROLES.ORG_MEMBER],
riskLevel: ResourceOperationRiskLevel.LOW,
mcp: { exposed: true, description: 'Search the organization\'s todos by title/description text, and filter by status, priority, todo list, or assignee. The primary discovery tool for finding todos.' },
isSearchable: true,
searchableFields: ['title', 'description'],
searchableOptions: { caseSensitive: false, fullMatchOnly: false },
filterFields: {
organizationId: z.string(),
todoListId: z.string(),
assignedToUserId: z.string(),
createdByUserId: z.string(),
status: z.enum(Todos_Status),
priority: z.enum(Todos_Priority),
createdAt: z.date(),
updatedAt: z.date(),
},
sortFields: ['title', 'status', 'priority', 'createdAt', 'updatedAt'] as const,
maxPaginatedResultPerPageLimit: 100,
searchableFields selects title and description for text discovery. filterFields gives each accepted filter a schema, including enums for status and priority. A date field becomes a range filter. sortFields states the allowed orderings, and the page ceiling bounds an individual response.
Follow the request into the repository
Collection requests share the page, limit, sort and q query parameters. Sort order is expressed as ordered field:asc or field:desc pairs. Date ranges use bracket keys such as createdAt[startDate] and createdAt[endDate]; the controller reconstructs the typed range before execution.
The repository combines the requested criteria with tenancy, ownership and retention visibility. The stored adapters compile that contextual filter into their database vocabulary. LIST and SEARCH responses include pagination information so clients can present the current page and continue through the collection.
Combine the query choices in one request
For the SEARCH declaration above, an illustrative query string is:
?q=launch&page=1&limit=25&sort=updatedAt:desc&createdAt[startDate]=2026-01-01T00:00:00.000Z
Append it to the operation’s generated URL in the caller’s resource context. The date is an example cutoff, not a framework default.
| Request part | Effect |
|---|---|
q=launch | Search the declared title and description fields. |
createdAt[startDate] | Keep records at or after the supplied creation-date boundary. |
sort=updatedAt:desc | Order by the most recently updated record. |
page=1&limit=25 | Request the first page of up to 25 matches, within the declared ceiling. |
The query does not replace tenant or access filters. It narrows the records the caller can already read. A page is a bounded result, not evidence that the complete collection was returned.
Make search behavior a product decision
Use own-field text search for substring discovery across the fields you chose. It is useful for finding a remembered phrase or part of a title. Results follow the requested sort rather than a relevance-ranked search-engine score.
Declare sortable fields explicitly so callers get the ordering vocabulary the application intends. Choose searchable text carefully: a description may be useful, while an internal-only value should not become an indirect discovery surface. More specialized discovery can have its own operation and input contract.
A collection can also declare CSV and JSON export, reusing the selected query rather than inventing a second interpretation of the list.