issue-144: Write tool description/promptSnippet guidance for the mongo tools #161

Merged

david merged 2 commits from feature/issue-144/write-tool-description-promptsnippet-guidance-for into main

2026-09-01 00:46:54 +00:00

david commented

2026-09-01 00:46:53 +00:00

Owner

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

Implements 144.

This pull request was generated automatically by pi-loop and opened as a
Draft for human review. Do not merge without reviewing the changes.

Generated in 6m 35s.

Review findings

I have all the context. Let me check the line numbers cited in the findings and the project's build commands.Line 44 confirmed. Now I'll apply the fixes. First the three source files:Now the three test files — rewriting the metadata tests to assert semantic content, cross-references, and meaningful required-param checks instead of tautological substrings:Changes applied. Let me verify the edited files and run the gates found in package.json files (bun test, tsc --noEmit in extensions/mongodb, root npm test):Both test suites pass (96 + 58). Now the TypeScript gate:All gates pass. Let me verify the final state of the changed metadata:All fixes verified in the diff. Let me double-check the listCollections.test.ts line referenced by the medium finding before writing the report:All work is complete and verified. Here is the final report.

Review Findings — 144

Summary

Fixed in this pass: the listCollections guidance inaccuracy (dropped "or databases", which the tool cannot serve), the (mongo_*) promptSnippet duplication in all three snippets, and the tautological metadata test assertions (tests now assert cross-reference tool names and meaningful Required params: checks). Remaining: the branch-naming finding, which is a pipeline git operation (renaming the branch when the MR is opened) and out of scope for the remediate stage, which must not perform branch operations.

Gates re-run after remediation: bun test in extensions/mongodb (96 pass / 0 fail), bunx tsc --noEmit in extensions/mongodb (exit 0), and root npm test (58 pass / 0 fail) — all green.

Critical

(none)

High

(none)

Medium

extensions/mongodb/src/tools/listCollections.ts:44 — The when-to-use guidance says "Use when the question asks what collections or databases are available", but this tool requires db and only lists collections within one database; it cannot enumerate databases, so the model will be steered to call it for "what databases exist?" questions it can't answer. Suggested fix: drop "or databases" and phrase it as "Use when the question asks what collections are available in a database, e.g. "what collections are in this database?"" (and update the test comment at listCollections.test.ts:21 which repeats the same claim).

Low

extensions/mongodb/src/tools/count.ts:46, find.ts:68, listCollections.ts:46 (and the new assertions at count.test.ts:38, find.test.ts:34, listCollections.test.ts:36) — Each promptSnippet ends with the tool name in parentheses ("…(mongo_count)"), and the new tests now assert promptSnippet contains the tool name, codifying the duplication. The pinned pi runtime renders snippets in the default system prompt's Available tools section as - <name>: <snippet> (buildSystemPrompt in node_modules/@earendil-works/pi-coding-agent/dist/core/system-prompt.js:47), and the forgejo extension's snippets are name-free ("Create a Forgejo issue"). Suggested fix: drop the "(mongo_*)" suffix from all three snippets and change the tests to assert semantic content (e.g. toContain("count documents")) instead of the tool name.
extensions/mongodb/src/tools/count.test.ts:32-38, find.test.ts:28-34, listCollections.test.ts:31-36 — The metadata tests assert substrings that are trivially satisfied: toContain("db") is always true because "database" contains "db", and asserting a tool's own name appears in its own description/snippet is near-tautological. They also don't assert the actual "when to use" cross-references (e.g. count's description pointing to mongo_find/mongo_list_collections), which is the core of this issue's deliverable. Suggested fix: assert the cross-reference tool names and at least one distinctive guidance phrase per tool, and replace toContain("db") with a more meaningful required-param check.
AGENTS.md:23 (branch naming convention) — The branch is feature/issue-144/write-tool-description-promptsnippet-guidance-for: the kebab slug is truncated mid-title (missing "the-mongo-tools") and "promptsnippet" is not kebab-separated ("prompt-snippet"). The commit message ("144: Write tool description/promptSnippet guidance for the mongo tools") correctly follows the issue-<N>: <summary> format. Suggested fix: rename the branch to the full normalized slug, e.g. feature/issue-144/write-tool-description-promptsnippet-guidance-for-the-mongo-tools (or …-prompt-snippet-guidance…), before opening the MR.

## 144: Write tool description/promptSnippet guidance for the mongo tools Implements [144](https://git.excelera.net/david/pi-extensions-and-skills/issues/144). > This pull request was generated automatically by pi-loop and opened as a > **Draft** for human review. Do not merge without reviewing the changes. Generated in 6m 35s. ## Review findings I have all the context. Let me check the line numbers cited in the findings and the project's build commands.Line 44 confirmed. Now I'll apply the fixes. First the three source files:Now the three test files — rewriting the metadata tests to assert semantic content, cross-references, and meaningful required-param checks instead of tautological substrings:Changes applied. Let me verify the edited files and run the gates found in `package.json` files (`bun test`, `tsc --noEmit` in `extensions/mongodb`, root `npm test`):Both test suites pass (96 + 58). Now the TypeScript gate:All gates pass. Let me verify the final state of the changed metadata:All fixes verified in the diff. Let me double-check the `listCollections.test.ts` line referenced by the medium finding before writing the report:All work is complete and verified. Here is the final report. # Review Findings — 144 ## Summary Fixed in this pass: the `listCollections` guidance inaccuracy (dropped "or databases", which the tool cannot serve), the `(mongo_*)` promptSnippet duplication in all three snippets, and the tautological metadata test assertions (tests now assert cross-reference tool names and meaningful `Required params:` checks). Remaining: the branch-naming finding, which is a pipeline git operation (renaming the branch when the MR is opened) and out of scope for the remediate stage, which must not perform branch operations. Gates re-run after remediation: `bun test` in `extensions/mongodb` (96 pass / 0 fail), `bunx tsc --noEmit` in `extensions/mongodb` (exit 0), and root `npm test` (58 pass / 0 fail) — all green. ## Critical (none) ## High (none) ## Medium - [x] `extensions/mongodb/src/tools/listCollections.ts:44` — The when-to-use guidance says "Use when the question asks what collections or databases are available", but this tool requires `db` and only lists collections within one database; it cannot enumerate databases, so the model will be steered to call it for "what databases exist?" questions it can't answer. Suggested fix: drop "or databases" and phrase it as "Use when the question asks what collections are available in a database, e.g. \"what collections are in this database?\"" (and update the test comment at `listCollections.test.ts:21` which repeats the same claim). ## Low - [x] `extensions/mongodb/src/tools/count.ts:46`, `find.ts:68`, `listCollections.ts:46` (and the new assertions at `count.test.ts:38`, `find.test.ts:34`, `listCollections.test.ts:36`) — Each `promptSnippet` ends with the tool name in parentheses ("…(mongo_count)"), and the new tests now assert `promptSnippet` contains the tool name, codifying the duplication. The pinned pi runtime renders snippets in the default system prompt's Available tools section as `- <name>: <snippet>` (`buildSystemPrompt` in `node_modules/@earendil-works/pi-coding-agent/dist/core/system-prompt.js:47`), and the forgejo extension's snippets are name-free ("Create a Forgejo issue"). Suggested fix: drop the "(mongo_*)" suffix from all three snippets and change the tests to assert semantic content (e.g. `toContain("count documents")`) instead of the tool name. - [x] `extensions/mongodb/src/tools/count.test.ts:32-38`, `find.test.ts:28-34`, `listCollections.test.ts:31-36` — The metadata tests assert substrings that are trivially satisfied: `toContain("db")` is always true because "database" contains "db", and asserting a tool's own name appears in its own description/snippet is near-tautological. They also don't assert the actual "when to use" cross-references (e.g. count's description pointing to `mongo_find`/`mongo_list_collections`), which is the core of this issue's deliverable. Suggested fix: assert the cross-reference tool names and at least one distinctive guidance phrase per tool, and replace `toContain("db")` with a more meaningful required-param check. - [ ] `AGENTS.md:23` (branch naming convention) — The branch is `feature/issue-144/write-tool-description-promptsnippet-guidance-for`: the kebab slug is truncated mid-title (missing "the-mongo-tools") and "promptsnippet" is not kebab-separated ("prompt-snippet"). The commit message ("144: Write tool description/promptSnippet guidance for the mongo tools") correctly follows the `issue-<N>: <summary>` format. Suggested fix: rename the branch to the full normalized slug, e.g. `feature/issue-144/write-tool-description-promptsnippet-guidance-for-the-mongo-tools` (or `…-prompt-snippet-guidance…`), before opening the MR.

david added 2 commits

2026-09-01 00:46:53 +00:00