Search checkup

Keep tool metadata reliable across pets

---

Know purpose

Use these scripts to maintain search quality in pet tool metadata. They audit gaps, enrich search fields, and rewrite weak tool descriptions.

---

Run scripts

Script	Command	What it does
audit:search	bun run audit:search	Scans all pets and reports missing search, missing capabilities, placeholders, and low-signal descriptions
audit:search:json	bun run audit:search:json	Runs the same audit and outputs machine-readable JSON
enrich:search	bun run enrich:search	Infers and writes search.capabilities, intents, excludes, and status for default target pets
enrich:search:all	bun run enrich:search:all	Runs search metadata enrichment for every pet under pets/
enrich:descriptions	bun run enrich:descriptions	Rewrites low-signal tool descriptions for default target pets
enrich:descriptions:all	bun run enrich:descriptions:all	Rewrites low-signal tool descriptions for every pet under pets/
audit:corefields	bun run audit:corefields	Scans pets/*/index.ts for list/search tools missing coreFields response pruning
audit:corefields:json	bun run audit:corefields:json	Same audit with JSON output
checkup	bun run checkup	Runs full pass: enrich:search:all -> enrich:descriptions:all -> audit:search

---

Follow workflow

For a quick local pass, run targeted enrichers first, then audit. For repo-wide maintenance, run the all-pets scripts or a single checkup.

1. Quick local pass:
   • bun run enrich:search
   • bun run enrich:descriptions
   • bun run audit:search
   • bun run audit:corefields
2. Full all-pets pass:
   • bun run checkup
   • bun run audit:corefields

---

Use examples

bun run audit:search
bun run audit:search:json

bun run enrich:search
bun run enrich:search:all

bun run enrich:descriptions
bun run enrich:descriptions:all

bun run checkup

bun run audit:corefields
bun run audit:corefields:json
bun run audit:corefields:strict

---

coreFields audit

Tools that return lists (search, list, query, browse, find, fetch, scan) should define coreFields so responses are pruned to essential attributes by default. This reduces token usage and keeps LLM context focused.

Run

Script	Command	What it does
audit:corefields	bun run audit:corefields	Scans pets/*/index.ts for list/search tools and reports which have coreFields defined vs missing
audit:corefields:json	bun run audit:corefields:json	Same audit with machine-readable JSON output
audit:corefields:strict	bun run audit:corefields:strict	Exits with code 2 if any list/search tools are missing coreFields

Example output

coreFields Audit
Pets with list/search tools: 42
List/search tools found: 87
With coreFields: 1
Missing coreFields: 86

⚠ Pets missing coreFields on list/search tools:
  shopify: shopify-list-products (line 166), shopify-search-products (line 1899)
  github: github-list-repos (line 225), github-search-repos (line 542)

✓ Pets with coreFields defined:
  hypothes: hypothes-search-annotations

Fix a missing coreFields warning

Add coreFields to the tool definition in index.ts:

{
  name: "my-pet-list-items",
  description: "List items from the API",
  coreFields: {
    "items[]": ["id", "name", "status"]
  },
  schema: z.object({ ... }),
  async execute(args) { ... }
}

The key is a JSON path (items[] for arrays, data.results[] for nested). The value is the array of field names to keep. Callers can pass fullData: true to bypass pruning.

---

Review changes

These scripts mutate pets/*/commands.json when they find updates to apply. Review and commit the resulting diffs after each run.