Write tool description/promptSnippet guidance for the mongo tools #144

New issue

Closed

opened 2026-08-31 22:06:19 +00:00 by david · 1 comment

david commented

2026-08-31 22:06:19 +00:00

Owner

Summary

Ensure each of the three mongo tools carries description (and promptSnippet where the runtime supports it) metadata that tells the LLM when to use that tool, so the model picks the right one per query intent.

Background

Depends on: #143

Tool descriptions are the LLM's only guide to choosing among mongo_find, mongo_count, and mongo_list_collections. If the descriptions are vague or overlapping, the model guesses wrong. This step is a review-and-adjust pass on the tool registration metadata (the tool definitions live in src/tools/find.ts, src/tools/count.ts, src/tools/listCollections.ts; check what field name the sibling extensions/postgres extension uses — description and/or promptSnippet — and match it).

Implementation Details

Per tool, the metadata must state:

mongo_find — for retrieving documents: query a collection and get matching documents back (filter/projection/sort/limit, EJSON output). Use when the question wants actual records/fields, e.g. "show me the users created last week".
mongo_count — for "how many" questions: count documents matching a filter; returns a single number, no documents. Use when the question asks how many/count, e.g. "how many orders are pending?".
mongo_list_collections — for "what collections exist": list collections in a database (optionally name-only). Use when the question asks what collections/databases are available, e.g. "what collections are in this database?".

Each description should briefly note required params (db, collection) so the model knows what to supply. Keep them distinct and non-overlapping; mention the tool's own mongo_ name.

After adjusting, run the full test suite and typecheck — nothing may regress.

Acceptance Criteria

All three tools have description (and promptSnippet if the pi runtime/sibling extensions support it) stating when to use the tool, per the spec above.
The three descriptions are distinct and non-overlapping; each names its mongo_ tool and its key params.
bun test in extensions/mongodb/ is green; tsc --noEmit is clean.

Test Plan

cd extensions/mongodb
bun test             # still green
bunx tsc --noEmit    # still clean

Manually read the three tool registrations and confirm the descriptions tell the LLM when to use each tool.

## Summary Ensure each of the three mongo tools carries `description` (and `promptSnippet` where the runtime supports it) metadata that tells the LLM **when** to use that tool, so the model picks the right one per query intent. ## Background **Depends on:** #143 Tool descriptions are the LLM's only guide to choosing among `mongo_find`, `mongo_count`, and `mongo_list_collections`. If the descriptions are vague or overlapping, the model guesses wrong. This step is a review-and-adjust pass on the tool registration metadata (the tool definitions live in `src/tools/find.ts`, `src/tools/count.ts`, `src/tools/listCollections.ts`; check what field name the sibling `extensions/postgres` extension uses — `description` and/or `promptSnippet` — and match it). ## Implementation Details Per tool, the metadata must state: - **`mongo_find`** — for retrieving documents: query a collection and get matching documents back (filter/projection/sort/limit, EJSON output). Use when the question wants actual records/fields, e.g. "show me the users created last week". - **`mongo_count`** — for "how many" questions: count documents matching a filter; returns a single number, no documents. Use when the question asks how many/count, e.g. "how many orders are pending?". - **`mongo_list_collections`** — for "what collections exist": list collections in a database (optionally name-only). Use when the question asks what collections/databases are available, e.g. "what collections are in this database?". Each description should briefly note required params (`db`, `collection`) so the model knows what to supply. Keep them distinct and non-overlapping; mention the tool's own `mongo_` name. After adjusting, run the full test suite and typecheck — nothing may regress. ## Acceptance Criteria - [ ] All three tools have `description` (and `promptSnippet` if the pi runtime/sibling extensions support it) stating when to use the tool, per the spec above. - [ ] The three descriptions are distinct and non-overlapping; each names its `mongo_` tool and its key params. - [ ] `bun test` in `extensions/mongodb/` is green; `tsc --noEmit` is clean. ## Test Plan ```bash cd extensions/mongodb bun test # still green bunx tsc --noEmit # still clean ``` Manually read the three tool registrations and confirm the descriptions tell the LLM when to use each tool.

david added this to the MongoDB: M5 - Extension Wiring milestone

2026-08-31 22:06:19 +00:00

david added the

feature

label

2026-08-31 22:06:19 +00:00

david referenced this issue

2026-08-31 22:08:02 +00:00

Reconcile DESIGN.md and implementation plan with the implementation #148

david added the

ready

label