SKILL.md and references/mcp-tools.md describe an older API — get_design_guidance gone, get_screen split, params dropped

[Emuthmartinez]

Hello — installed refero-design via npx skills add against a freshly registered Refero MCP (HTTP at https://api.refero.design/mcp). The vendored SKILL.md and references/mcp-tools.md describe a tool surface that disagrees with what the live server actually exposes. Filing this so the skill docs catch up — they otherwise route agents to tools or parameters that don't exist.

Live tools (as of 2026-05-01)

The MCP exposes exactly these 5 tools:

Tool	Required args	Optional args
refero_search_screens	query, platform (ios|web)	page
refero_search_flows	query, platform (ios|web)	page
refero_get_screen_content	screen_id	—
refero_get_flow	one of flow_id or flow_ids[]	—
refero_get_similar_screens	screen_id	limit (1–20, default 10)

Concrete mismatches in the current docs

1. refero_get_design_guidance_tool no longer exists.

   • Referenced in the description frontmatter of SKILL.md.
   • Referenced in SKILL.md line 165 in the "decision matrix" (Starting new — need best practices → get_design_guidance).
   • Documented as a separate tool in references/mcp-tools.md.
   • The whole "AI-Powered Best Practices, takes ~15-30 seconds, returns must_do/consider/avoid/examples" section in references/mcp-tools.md is no longer reachable.

2. refero_get_screen_tool has been split.

   • The current docs describe a single refero_get_screen_tool with image_size (none/thumbnail/full) and include_similar.
   • The live server has refero_get_screen_content (always returns the screenshot; no image_size arg) and a separate refero_get_similar_screens (with limit, not include_similar boolean).
   • SKILL.md line 170 (Similar approaches → get_screen + include_similar: true) and line 171 (image_size: "thumbnail") point at a parameter shape that errors against the live server.
   • SKILL.md lines 193–194 ("Pro Tips") describe both flags.

3. refero_get_flow accepts batch.

   • Live API supports flow_ids: number[] for batch retrieval (mutually exclusive with flow_id).
   • Current docs only mention flow_id.

4. _tool suffix is gone from registered names.

   • Live names are refero_search_screens, refero_search_flows, etc., not refero_search_screens_tool.
   • Worth normalizing across SKILL.md, references/mcp-tools.md, and the example workflow.

Suggested edits

• Drop get_design_guidance from the workflow and decision matrix (or replace with "two or three searches and triangulate" as the substitute behavior).
• Rewrite the get_screen section in references/mcp-tools.md as two tools.
• Add flow_ids[] to the get_flow section.
• Strip _tool from tool names everywhere.

Happy to send a PR if useful — wanted to file the issue first so you can decide on the right shape (some of these may be intentional capability changes rather than just doc lag).

— Filed from a downstream harness that vendors the skill at ~/.claude/skills/refero-design and ships an in-repo override note documenting the drift.