MCP Tools & Prompts

Tools

Shire exposes the following tools over the Model Context Protocol:

How matching works

All four search tools (search_symbols, search_packages, search_files, search_docs) run the same FTS5 query builder:

• The query is split on whitespace and every token must match (implicit AND).
• Each token matches by prefix: handle matches handleRequest and handle_request. Tokens of one character are matched exactly instead — packages_fts and docs_fts index 2- and 3-character prefixes, while symbols_fts and files_fts deliberately carry no prefix index (a prefix query there walks a term range instead, measured as equally fast and ~28% smaller on disk), so a single-character prefix would have to scan every term.
• Each tool searches only the columns it is about. search_symbols matches the symbol name and its sub-tokens — not signatures, file paths or kinds (filter by kind with kind, find paths with search_files, and use Grep for text inside a signature). search_files matches the path, search_packages the package name, description and path, and search_docs the doc title, body and path.
• search_symbols orders exact name matches first, so searching handle — or handle*, or a pasted handle. — never buries a symbol actually called handle under its own prefixes. After that, private symbols rank after the others: the results FTS returns are reordered so public, protected and internal symbols lead, keeping their relative rank. A private symbol is never left out for being private — only ranked later.
• Symbol names are additionally indexed by their sub-tokens: verifyJwtToken is indexed as verify, jwt, token, so verify jwt, jwt and token all find it. This applies to symbol names only, not to file paths or doc bodies.
• Matching is by identifier, not regex or substring: andleRequ finds nothing.
• Operators in a query (OR, NEAR, *, -, column:) are treated as literal text, not as FTS5 syntax.

Qualified names

symbol_references, symbol_callers and change_impact take a symbol name. The reference index stores bare names (run), while enclosing_symbol / caller_name come back dot-qualified (AuthService.run) and are meant to be fed straight back in. A qualified name is resolved in three steps:

1. Literally. Some refs really are dot-named — an import of os.path. If the name matches refs as given, that is the answer.
2. Through the qualifier. Otherwise the last segment before the dot is looked up in symbols.parent_symbol: A.run finds the symbols named run whose parent is A, which is where the symbol lives. A reference row records the name and the package it was written in, never the type it resolves to, so the qualifier cannot filter references directly — what it can do is attribute them. A run written inside a package that defines its own run on some other type belongs to that package’s method, so those packages are left out; every other package is kept, because a cross-package call site is exactly what these tools exist to find.
3. Bare, and flagged. If no indexed symbol carries that qualifier, the qualifier is dropped and the bare name is matched on its own.

Whenever the rows were matched on a name other than the one passed, the result carries matched_name (the name actually matched), matched_note (what that means) and, for step 2, defined_in and excluded_packages. Because those fields need somewhere to live, a rewritten name always returns the single object form described under Result limits — results plus the match fields — even when nothing was truncated. change_impact already returns an object, and gains matched_name, qualifier_dropped and excluded_packages; it takes its home_package from the resolved symbol.

excluded_packages is worth reading before acting on a change_impact answer: those packages were left out of direct_impact, cross_package_impact, summary.affected_packages and the reverse-dep walk seeded from it, so a call site in one of them is blast radius the qualifier chose to attribute elsewhere. The list names every package that defines a symbol of that name, not only the ones that turned out to reference it — most entries will have had nothing to drop. summary.excluded_ref_count is the number that matters: how many references those packages actually held. When it is not zero, re-run with the bare name to see them.

A package filter is applied on top of the resolution, so asking for a qualified name and a package that step 2 excluded is a contradiction and returns nothing — excluded_packages in the response is what says why. In change_impact, where package is a home-package hint rather than a filter, the same combination empties direct_impact by construction (that package’s references were attributed to its own symbol), and home_package_note says so.

Which package is home_package

change_impact splits references into direct_impact and cross_package_impact by comparing each reference’s package against home_package, so that one value decides the whole answer. It is the package argument when given, and otherwise the first — by name — of the packages defining the resolved symbol. When there is more than one, that first is a tiebreak, not a fact, and the response says so:

• defined_in lists every package defining the symbol (present only when there is more than one, and narrowed to the definitions under the qualifier for a qualified name).
• home_package_note explains what was chosen and how to choose differently — pass package to make one of the others the home package.

What this cannot do is separate two same-named methods inside one package: with only the bare name recorded, A.run and B.run in the same package still merge, and both are reported. Pass package to narrow the answer; use Grep when the distinction has to be exact.

Result limits

Tool output is pasted verbatim into a model’s context, so every list-returning tool is bounded:

limit: 0 means “use the default”, not “one row”. The limit is applied in SQL, and one row beyond it is fetched to tell a page that was cut from a list that merely ends there.

A complete result is the bare JSON array. A truncated one — or, for the reference tools, one whose name was rewritten (see Qualified names) — is a single JSON object instead:

{"results": [...], "truncated": true, "limit": 20, "max": 200, "note": "showing the first 20 results …"}

so a capped list is never presented as a complete one, and a client that concatenates the result’s text blocks still gets parseable JSON. (At limit = 200 the extra row cannot be fetched, so a result that fills the ceiling is always flagged, with a note saying more rows may exist rather than that they do — and the note then asks for a narrower request rather than a bigger limit, which is already clamped at 200.)

change_impact returns an object rather than a list; when a bucket is capped it gains the same truncated / limit / max / note fields. summary.direct_count and summary.cross_package_count count every reference scanned rather than only the rows returned — but the scan itself stops at 10 000 references, so they are totals only while summary.counts_capped is false; when it is true they are floors. summary.transitive_package_count is never a total: the reverse-dep walk stops at limit, so a capped result reports a floor.

Index freshness under serve --root

With --root the server reindexes on demand. Before answering a tool call it checks how long ago the index was last built: inside the serve.debounce_s window (default 5 seconds) it answers straight from the current index, and outside it, it runs an incremental build first and answers from the result.

That build is the only freshness oracle — it compares the repo’s file tree, per-package mtimes and per-file content hashes itself, and costs on the order of 60-200 ms when nothing has changed. So an ordinary working-tree edit is picked up on the first tool call more than serve.debounce_s after it, with no need to stage anything: git add and .git/index play no part.

Raise serve.debounce_s to trade freshness for fewer rebuilds during bursts of tool calls; lower it for a repo where builds are cheap and edits frequent.

Without --root (plain shire serve --db …) the server is strictly read-only and never rebuilds — refresh the index with shire build, the watch daemon, or the PostToolUse hook.

When to use Shire vs Grep/Glob

Prompts

Prompts are pre-built templates that compose multiple queries into structured context. They give your AI a map of where concepts live in the codebase.