Skip to content

feat(mcp): add MCP-027, MCP-028 TypeScript description quality rules - #91

Open
bradAGI wants to merge 1 commit into
trustabl:mainfrom
bradAGI:feat/mcp-ts-description-quality
Open

feat(mcp): add MCP-027, MCP-028 TypeScript description quality rules#91
bradAGI wants to merge 1 commit into
trustabl:mainfrom
bradAGI:feat/mcp-ts-description-quality

Conversation

@bradAGI

@bradAGI bradAGI commented Aug 24, 2026

Copy link
Copy Markdown

The TypeScript counterpart to MCP-025/026 (#88). MCP-011 only checks that a description exists, so a registration described "TODO: describe this tool." or "Gets data." passes today while publishing no selection signal to connecting clients.

Carries the same protocol-boundary argument as the Python pair, which is what makes this more than a lint:

  • The consumer has no fallback context — it can't read this repo's source, the neighboring tools, or the project's docs.
  • The server's authors never observe the mis-selection — it surfaces in someone else's client session as a wrong answer, not as an error on this side.
  • The competition isn't just this server's tools — a client typically connects several at once and the model picks across all of them from these strings alone.

Plus the TypeScript-specific point in MCP-028: the Zod input schema doesn't close the gap. It constrains the arguments once the model has chosen this tool, not whether choosing it was right.

Verification — engine built at main:

$ trustabl rules validate .
OK: 85 rule pack(s), 208 rule(s) valid under rule schema version 14

Fire (one server.tool described "TODO: describe this tool.", one "Gets data."): MCP-027, MCP-028
Silent (full description naming when to prefer the neighboring tool): no findings

MCP-028 pairs description_length_lt: 40 with has_docstring: true so it doesn't double-report against MCP-011 on an empty description, same as CSDK-018.

No new predicates, so no schema_version bump.

Merge note: this and #88 both append to mcp/tool_definition.yaml, so whichever lands second will need a trivial rebase — the two rule blocks are independent and the resolution is "keep both." Ping me and I'll rebase, or take them in either order and I'll follow up. This is the only pair among my open PRs that touches the same file; the rest are all distinct files.

The TypeScript counterpart to MCP-025/026. MCP-011 only checks that a
description exists, so a registration described "TODO: describe this
tool." or "Gets data." passes today while publishing no selection signal
to connecting clients.

Same protocol-boundary argument as the Python pair — the consumer has no
fallback context, the server's authors never observe the mis-selection,
and the model chooses across every connected server from these strings
alone — plus the TypeScript-specific point that the Zod input schema
constrains the arguments once the model has chosen this tool, not whether
choosing it was right.
@jhumel-code

Copy link
Copy Markdown
Collaborator

Thanks @bradAGI, this is a clean pack change. Both has_description_text and description_length_lt already exist on main, so no schema_version bump is right, and pairing description_length_lt: 40 with has_docstring: true is exactly the guard the schema comment asks for, keeping an empty description as MCP-011's finding. Severity, confidence and the needle list line up with the CSDK-017/018 precedent, and the explanation and fix are genuinely rewritten for the MCP protocol boundary rather than carried over from the Claude framing. The engine half in trustabl/trustabl#168 mirrors this byte for byte, which I checked.

The one blocker is not yours. MCP-027 and MCP-028 are also claimed by #100 (with trustabl/trustabl#135) for unrelated rules covering idempotency keys and ambiguous names. Whichever pair lands first keeps the numbers and the other renumbers and rebases, so I will sequence those rather than ask you to change anything yet.

One thing to carry forward: todo and placeholder as bare substrings will fire on a legitimate description such as "Create a new todo item", so that belongs in the known gaps section of the rulebook rationale doc this pack still needs before the rules ship. We can write that or pair with you on it, it is not a request on this PR.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants