[DOCS] inconsistent tool references: no clear best practices

Documentation Type

Unclear/confusing documentation

Documentation Location

https://code.claude.com/docs/en/best-practices

Section/Topic

"Communicate effectively" (maybe)

Current Documentation

I've looked at best practices and the tools section of "How Claude Code works",and I can't find explicit guidance on whether to use specific tool names (like "use the AskUserQuestion tool") versus natural language (like "ask the user a question") in prompts, CLAUDE.md files, or skills.

The documentation shows that Claude Code is designed to work conversationally with natural language. The "How Claude Code works" page emphasizes that "Claude Code is conversational" and you should "delegate, don't dictate" - giving context and direction rather than specifying exact implementation details.

But then some example prompts like this one specifically name the tool:

I want to build [brief description]. Interview me in detail using the AskUserQuestion tool.

Mean while, this page uses examples like "fix the failing tests", which doesn't ask for any specific tool.

What's Wrong or Missing?

I would think that it would be best practice (and most examples seem to suggest) to not specify the tool names? Given that tools to some extent could be considered "implementation details" that could change over time - e.g. if/when you discover a better approach to structuring some internal tools and decide to change them?

But the documentation doesn't seem to explicitly address this question as a best practice.

Suggested Improvement

Be explicit about which approach is expected to work best.

Update the documentation to consistently reflect best practice.

Naming tools could impart the understanding that the names are important for prompting - so if that is not the case, the documentation probably should explicitly clarify the fact that tool names are for use in front-matter (for permissions) and not intended for prompting?

Impact

Medium - Makes feature difficult to understand

Additional Context

I looked at a popular workflow for reference, and the author of this workflow seems to be confused as well, as you can see from this example, inconsistently prompting to "ask the user" and "use the AskUserQuestion tool" - Brian Casel is what I would consider an expert on this (author of several mature workflows) and even he doesn't seem sure.