[Docs]: Documentation Gap - Tools vs Prompts Usage Unclear

[mateochauchet]

Issue Type

Missing information

Where is the issue?

Hi! First of all, congratulations - the work you've done with this MCP is fantastic.

I'm trying to understand the correct usage pattern for this MCP after setting it up. After changing the architecture from tools to prompts, I have some confusion.
My confusion: Should I use natural language and let the AI model use the prompts internally, or should I manually invoke each prompt myself?

What I expected (based on docs):

Me: "Create a spec for user authentication"
Claude: [Automatically uses tools + prompts internally to create the spec]

What I'm unsure about:
Do I need to manually call prompts like create-spec specName="user-auth" documentType="requirements"?
Or should natural language trigger the workflow automatically?

What's the problem?

There's an inconsistency between the documented tools and the actual MCP tools available in the codebase, creating confusion for new users.

Documentation Issues:

1. docs/TOOLS-REFERENCE.md documents ~13 tools like:

   • create-spec-doc
   • get-template-context
   • spec-list
   • get-spec-context

   But src/tools/index.ts only exports 4 actual tools:

   • spec-workflow-guide
   • steering-guide
   • spec-status
   • approvals

2. docs/USER-GUIDE.md suggests natural language usage:

   "Create a spec for user authentication" 
   

   But doesn't explain how this maps to available tools/prompts.

3. README.md shows examples like:

   "Create a spec for user authentication"
   

   Without clarifying the actual execution flow.

Root Cause: Architecture change from Tools → Prompts that wasn't reflected in documentation.

How should it be improved?

Add a comprehensive step by step on how to use the workflow

Additional Context

No response

[Pimzino]

Hey! Yes documentation still a work in progress especially because we recently performed an Architecture change on the MCP to avoid having so many tools using up context when AI agents are fairly capable at writing to files etc.

You just prompt the agent telling it to create a spec for x feature or idea or even provide it a PRD. Based on the tool definitions the agent will be able to then follow the workflow to a T. The prompts were added at user requests which are exposed in some agents that expose MCP prompts. I dont see much use for them but it was little work to add them. I prefer natural language aspect as this is the whole point of LLMs to begin with!

[KochabStar]

Hey! Yes documentation still a work in progress especially because we recently performed an Architecture change on the MCP to avoid having so many tools using up context when AI agents are fairly capable at writing to files etc.

You just prompt the agent telling it to create a spec for x feature or idea or even provide it a PRD. Based on the tool definitions the agent will be able to then follow the workflow to a T. The prompts were added at user requests which are exposed in some agents that expose MCP prompts. I dont see much use for them but it was little work to add them. I prefer natural language aspect as this is the whole point of LLMs to begin with!

Is the prompt now only available in English?

[Pimzino]

The MCP prompts are in English yes, the instructions are also in English.

I will only support UI localisation and not MCP server localisation

[mateochauchet]

Hey! Yes documentation still a work in progress especially because we recently performed an Architecture change on the MCP to avoid having so many tools using up context when AI agents are fairly capable at writing to files etc.

You just prompt the agent telling it to create a spec for x feature or idea or even provide it a PRD. Based on the tool definitions the agent will be able to then follow the workflow to a T. The prompts were added at user requests which are exposed in some agents that expose MCP prompts. I dont see much use for them but it was little work to add them. I prefer natural language aspect as this is the whole point of LLMs to begin with!

Ok, just to make sure I understand completely:
With the existing 4 tools, the LLM will understand how the workflow functions, and using natural language it will guide me through each step from the workflow ?

[Pimzino]

Hey! Yes documentation still a work in progress especially because we recently performed an Architecture change on the MCP to avoid having so many tools using up context when AI agents are fairly capable at writing to files etc.
You just prompt the agent telling it to create a spec for x feature or idea or even provide it a PRD. Based on the tool definitions the agent will be able to then follow the workflow to a T. The prompts were added at user requests which are exposed in some agents that expose MCP prompts. I dont see much use for them but it was little work to add them. I prefer natural language aspect as this is the whole point of LLMs to begin with!

Ok, just to make sure I understand completely: With the existing 4 tools, the LLM will understand how the workflow functions, and using natural language it will guide me through each step from the workflow ?

Correct, this is shown in https://github.com/Pimzino/spec-workflow-mcp?tab=readme-ov-file#-how-to-use section of the README.