# Search by meaning (`mttr_search`)

Updated October 24, 2026.

## What does mttr_search do?

Ask a question as a buyer would and get the passages that answer it best, and each site once by its best passage, from the sites closest to the question, one market, or sites you name. Only whoever runs this mttr may make this call.

Who may call it: Owner.

## When to use it

- You want to see which sites read closest to a buyer’s question.

## What you ask

You might say: “Which sites answer “how often should a septic tank be pumped”?”

```
mttr_search({ q: "who installs french drains near me" })
```

| Argument | Type | Needed | What it is |
| --- | --- | --- | --- |
| `q` | Text | Yes | The question, in plain words. |
| `market` | Text | No | Only this market, named by the site at its centre, as mttr_markets gives it. |
| `sites` | Text | No | Only these sites, as domains separated by commas. |
| `limit` | Number | No | How many to return. |

## What comes back

- The passages closest to the question, marked as quoted.
- Each site once, by its best passage.
- Close means similar in meaning, not right, and not cited by an assistant.

A sample, with made-up sites and figures:

| What | Why | How alike |
| --- | --- | --- |
| `rival.example/guides/septic-schedule` | Every three to five years for most homes | 83% |
| `example.com/guides/septic-care` | How household size changes the schedule | 77% |

## Over HTTP

```
curl "https://mttr.si/api/v1/search?q=who+installs+french+drains+near+me" \
  -H "Authorization: Bearer $MTTR_KEY"
```

## When it fails

| When | Status | What to do |
| --- | --- | --- |
| Your assistant has no key yet | 401 over MCP | Sign up with `mttr_signup`, then connect again with the key it gives. |
| The key is a person’s, not the owner’s | 403 | Nothing: only whoever runs mttr makes this call. |

## Sources

- [Model Context Protocol: tools](https://modelcontextprotocol.io/specification/2025-06-18/server/tools), Model Context Protocol: How an assistant calls a tool.

The call in full: [mttr_search in the API reference](https://mttr.si/docs/reference#mttr_search).

## Goes with

- [Nearest sites](https://mttr.si/docs/tools/near.md)
- [Ask the assistants](https://mttr.si/docs/tools/cite.md)