# Discover and inspect

Find a candidate tool, then read its fixed contract before creating a Run.

## purrkey discover

Read matchReasons and limitations for each candidate. retrievalMode can be hybrid or keyword_fallback; semanticCoverage describes search coverage, not proof that a candidate will answer your task.

```
purrkey discover --query 'public video comments' --limit 5
```

| Flag | Meaning |
| --- | --- |
| --query | Required capability description. |
| --limit | Candidate count, default 5; the API accepts 1–20. |
| --output | Optional path for the complete JSON response. |

## purrkey inspect

Read inputSchema, outputSchema, inputExamples, limitations, behavior and delivery. Copy the returned tool and price revisions into the Run request; never guess the input fields.

```
purrkey inspect --tool '<toolId>' --revision '<toolRevision>'
```

| Flag | Meaning |
| --- | --- |
| --tool | Required tool ID from discovery or the catalog. |
| --revision | Optional tool revision; use the discovered revision to inspect that exact contract. |
| --output | Optional path for the complete JSON response. |

## purrkey tools

Reads the accessible tool directory. This command does not expose catalog pagination flags; use GET /v1/tools when you need cursor-based browsing or filtering.

```
purrkey tools --output tools.json
```

- [List tools API](/docs/api/tools): Browse with cursor, limit, provider and category filters.