Tool naming convention

Every DFL MCP tool name follows one rule. The rule makes the name tell you what the tool does before you read its description.

The rule

A tool name is verb_noun[_qualifier] in snake_case.

• The verb comes first. The verb is from the approved set below.
• The noun names the entity. Use the same word that the host page uses for that entity.
• The qualifier is optional. It makes the name more specific, for example set_plan_visibility_batch.
• Use only lowercase letters, digits and _.

Good	Bad	Why the bad name is bad
search_decisions	decisions_search	The noun comes first.
get_plan	read_plan	read is not an approved verb. Use get.
unsuppress_staging	un_suppress_staging	un takes no underscore.
update_quiz_question	quiz_update_question	A collision is broken by a longer noun, not by a prefix.

The approved verbs

Verb	Use
list	Return many. Use a plural noun.
get	Return one by id.
search	Return many by a query.
create, update, delete	The life of an entity.
archive, unarchive	A soft delete and its restore.
add, remove	A link between two entities, for example a dependency or a membership. Do not use them for an entity of its own.
set	Write one attribute, for example set_slide_camera.
upsert	Only when the natural key is the identity.
check, audit	A read that returns a verdict.
ingest, classify, post, publish, reverse, void, dispatch, approve, reject, render, export	Domain verbs.
open, close, wait, ack	Domain verbs of the agent comms thread, for example open_comms_thread.
unsuppress, unignore	The restore of suppress and ignore. un takes no underscore.

To add a verb to this set, revise the plan 20261005-mcp-docs-ia-and-fleet-naming (§3.3) first. Then change APPROVED_VERBS in scripts/check-tool-names.mjs in the same pull request.

Three more rules

1. The noun names the entity exactly as the host page section names it.
2. When two hosts have the same tool name, make the noun longer. Do not add a host prefix.
3. A rename ships with a deprecated alias. The old name stays registered for the deprecation window. Then the old name is removed.

The lint

The CI job tool-names runs node scripts/check-tool-names.mjs on every pull request. The script reads every registerTool( name in packages/*/src and applies the rule.

Some tools existed before the rule. Their names are in scripts/tool-names-baseline.json. Each entry has a name, a host, a reason, and an optional planned_rename. The baseline is a ratchet:

• A new tool name that breaks the rule fails the lint. Rename the tool. Do not add a new tool to the baseline.
• A baseline entry whose tool now passes, or no longer exists, fails the lint. Delete that entry. The baseline must only get shorter.
• A baseline entry whose tool still breaks the rule is accepted debt.

To run the lint on your machine:

node scripts/check-tool-names.mjs            # pass or fail
node scripts/check-tool-names.mjs --verbose  # also list the accepted debt and the aliases

Note

The tool-names job runs in warn mode until 2026-10-12. After that date, a failure blocks the merge.

Deprecated aliases

To rename a tool, register the new name first. Then keep the old name with registerAlias from @devfellowship/dfl-mcp-base:

server.registerTool('get_plan', config, handler);
registerAlias(server, 'read_plan', 'get_plan', { removeAfter: '2026-12-04' });

The alias calls the same handler. Its description starts with a deprecation notice. The generated docs mark it with deprecated_alias_of. Each alias call records tool.alias_of in its OTEL span, so you can see who still uses the old name.

The lint does not apply the naming rule to an alias. But the lint fails when:

• the registerAlias call has no literal removeAfter: 'YYYY-MM-DD' date, or
• the date is in the past. Remove the alias on or before that date.