Best Practices

Be precise

The more precise the query, the better the answer. A vague query finds the general area. A specific one finds the passage you want. Describe what you want, and include every detail that changes which passage is right: the subject, the people, the period, the kind of thing (a policy, a table, a number). Write it as a description or as a question; both work. Length is not the goal. Add the words that change the answer, and leave out the words that only describe your task. The same request for one company, made clearer one step at a time:

Query	What comes back
`retainers`	A passage about director pay in general.
`director pay`	The director pay table as a whole.
`annual cash retainers paid to directors for committee service`	The retainer for each committee, chair and member.
the same with `filters.date` for 2025	The same amounts, from the document the company filed in 2025.

{
  "query": "annual cash retainers paid to directors for committee service",
  "filters": {
    "identifiers": { "ticker": ["CCI"] },
    "date": { "after": "2025-01-01", "before": "2025-12-31" }
  }
}

The fields

Field	What it does
`query`	Says clearly what you want. The only required field, at most 300 characters.
`filters.identifiers`	Names the companies. Send it whenever you know them; without it every company’s newest document is searched.
`filters.date`	Bounds the day the document became public. Send it for a period or one year.
`limit`	How many documents come back: 10 unless you say otherwise, up to 100.

Improve a result one change at a time

Change one thing, compare, then change the next. Two changes at once hide which one helped.

Add the detail that is missing

When the answer is close but not right, the query is missing a detail that would decide it: the people, the period, the kind of thing. executive pay becomes total compensation of each named executive officer for 2025.

Read the title, the date and the section

title says which document answered, date which year, and citation.section where in the document the passage sits. The right section with a weak excerpt calls for a more specific query. The wrong document calls for a filter.

Use the company's own word

Companies name the same practice differently: clawback and recoupment, special committee and ad hoc committee, relative TSR and rTSR. When a query returns nothing useful, send the other name as a second request.

Add a filter only to exclude

A filter is a constraint, not a preference. Send filters.identifiers or filters.date when a passage from outside it would be wrong. A preference for a company or a year goes in the query text.

Raise the limit last

More documents do not make the first ones better. Raise limit when the task needs more documents, not to find a passage the query missed.

Request shapes by task

You want	Send	Avoid
One fact from one company	A description of the fact with the people and the year, the ticker in `filters.identifiers`.	A one-word topic.
A whole table	The table’s name as the topic. The excerpt carries `attributes.kind` of `table` and holds every row.	Asking for one cell and reading the rest through the link.
What a company says today	The topic and the ticker, no window.	A year in the query text; it widens the search to every year.
A period, or one year	`filters.date` with `after`, `before`, or both.	A year in the query text.
The same question over a set of companies	Up to 20 tickers in `filters.identifiers` and `limit` of 100. Beyond 20, batches of 20.	One request that lists hundreds of tickers.
Yes or no for each company in a set	One request per company; read the excerpt before you decide.	Counting results. A result is the nearest passage, not a yes, and an absent company is not a no.
A practice with several names	One request per name.	One query that lists every name.

When a model writes the queries

An agent that calls Search writes vague queries unless its tool definition says otherwise. Put the rules in the parameter descriptions, make the identifiers required, and have it make one call per item.

query: A clear, specific description of what you want, with every detail that changes the answer: the subject, the people, the period, the kind of thing. A question is fine. Never a single loose word, and never a description of the overall task.
identifiers: The tickers or CIKs of the companies the question is about. Required whenever the company is known.
date: An after day and a before day. Send it only when the question is about a period or one year.

Have the agent read warnings before it concludes. no_documents means there was nothing to search for those companies in that window, not that the answer is no.

Quote the excerpt, cite the link

text is the passage as written in the document and may be quoted as such. citation.link opens the document at the passage, highlighted. Keep citation.document, citation.date and citation.section with the quotation: together they identify the document, its date and the place in it.

Keep a reference set of queries

Record about ten queries that stand for the real work. Run them all after every change to a prompt or a tool definition, so a gain on one query is not paid for by three others. Store each response’s search_id with its query. When a passage is wrong or missing, the id lets us reproduce the case exactly.

Common mistakes

Mistake	Do this instead
A one- or two-word topic	A precise description of what you want, with the details that change the answer.
No ticker when the company is known	Send it in `filters.identifiers`.
The whole task in one query	One short query per item. `query` takes at most 300 characters.
A year in the query to mean that year only	`filters.date` for the year.
Retrying a `422`	Send `filters.identifiers` with the company; the same query then succeeds. Retry only a `503`.
Judging by the excerpt alone	Read `title`, `date` and `citation.section` too. They say whether the query or a filter should change.

When another endpoint fits

Filings

The list of a company’s filings, or a whole filing and its items, rather than the part that answers a question.

Overview

Integrations

Search

Datasets

Guides

Be precise

The fields

Improve a result one change at a time

Request shapes by task

When a model writes the queries

Quote the excerpt, cite the link

Keep a reference set of queries

Common mistakes

When another endpoint fits

Filings

​Be precise

​The fields

​Improve a result one change at a time

​Request shapes by task

​When a model writes the queries

​Quote the excerpt, cite the link

​Keep a reference set of queries

​Common mistakes

​When another endpoint fits

Filings

Be precise

The fields

Improve a result one change at a time

Request shapes by task

When a model writes the queries

Quote the excerpt, cite the link

Keep a reference set of queries

Common mistakes

When another endpoint fits