knowledge-engineering

Tool annotations

3/122 tools have annotations

Add readOnlyHint or destructiveHint annotations to every tool so hosts can warn users before invoking.

All four hints declared on every tool

122/122 tools missing one or more hints — envelope_write (missing: readOnlyHint, destructiveHint, idempotentHint, openWorldHint); envelope_read (missing: readOnlyHint, destructiveHint, idempotentHint, openWorldHint); task_transition (missing: readOnlyHint, destructiveHint, idempotentHint, openWorldHint), +119 more. OpenAI's directory rejects tools where any of the four hints are missing or non-boolean.

For every tool, set all four hints (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) to explicit true/false values that match the handler’s actual behaviour.

Descriptions match behaviour

6 tools describe read intent but their handlers mutate — mailbox_ack (line 66: appendFileSync(p, JSON.stringify(obj) + "\n")); engineering_search (line 35: anchorRe.exec(html)); blog_search (line 29: anchorRe.exec(html))

Rename the tool, rewrite the description, or move the side-effect into a separate clearly-named tool.

Tool inputs are validated

87/104 tool handlers declare input schemas (84%)

Declare an inputSchema with zod/joi/yup on every tool definition.

Tool test coverage

Only 30/122 tools referenced in tests (25%)

Write tests that reference each tool by name so every tool has at least one test.

Shell command execution

13 child_process/subprocess calls in production code — runs shell commands (cowork/plugins/imessage/server.ts:460, cowork/plugins/imessage/server.ts:470, cowork/plugins/imessage/server.ts:831)

Prefer library functions over shell-outs. If you must shell out, ensure all inputs are properly escaped.

Secrets not written to files

1 secret value written to files

Avoid persisting secrets to disk. Keep them in memory or your secret manager.

Secrets not logged

11 secret values sent to console.log

Redact or omit secret values from log output.

Production dependencies are patched

0 critical, 2 high severity in production deps — hono@4.12.23 (high), ws@8.20.1 (high)

Run npm audit fix, or upgrade the affected packages to a non-vulnerable version.

Dependency freshness

2/32 production deps stale: wink-bm25-text-search@2022-11-21 (3.7y), @xenova/transformers@2024-05-29 (2.2y)

Tool description accuracy

6 tools have description/behavior mismatches: mailbox_ack: description implies read-only but handler writes/deletes/executes; engineering_search: description implies read-only but handler writes/deletes/executes; blog_search: description implies read-only but handler writes/deletes/executes

Update tool descriptions to accurately reflect all capabilities — especially write, delete, or execute operations.