workflow_hints

Instructions

Implementation Reference

• src/build123d_mcp/server.py:168-213 (handler)

  The tool handler function for 'workflow_hints'. Decorated with @mcp.tool(), it returns a static string containing an 8-point workflow guide for using the MCP tools effectively.

  @mcp.tool()
  def workflow_hints() -> str:
      """Return guidance on how to use these tools effectively. Call this at the start of a session or whenever unsure which tool to reach for."""
      return """\
  BUILD123D-MCP WORKFLOW GUIDE
  
  1. ORIENT FIRST
     At the start of a session, call session_state() to see what geometry, objects, and
     snapshots are already active. Call health_check() if you suspect a missing dependency
     (VTK, display, STEP export). Call version() to confirm the server version.
  
  2. MEASURE BEFORE YOU LOOK
     After building or modifying geometry, verify with measure() before calling render_view.
     Numbers are unambiguous; renders can look correct even when the geometry is wrong.
     Recommended order: execute → measure → render_view (if you need to see it).
  
  3. VERIFY BOOLEAN OPERATIONS WITH TOPOLOGY
     After any cut, union, or intersection, call measure(topology) on the result.
     A successful boolean changes face/edge/vertex counts; a failed one leaves them unchanged.
     measure(volume) confirms the magnitude of the change.
  
  4. MEASURE THE OBJECT IN QUESTION — NOT A PROXY
     When debugging, call measure() on the actual disputed object.
     Testing an isolated reconstruction and using that as proof of the full assembly is a
     common mistake — the two may differ in ways that matter.
  
  5. NAME AND AUDIT YOUR SHAPES
     Use show(shape, "name") after creating important geometry — it also sets current_shape.
     The execute() output immediately confirms name, volume, and face count.
     Call session_state() for a full JSON view of all active shapes, objects, and snapshots.
  
  6. CHECKPOINT BEFORE EXPERIMENTS
     Call save_snapshot("name") before any operation you might want to undo.
     Snapshots are instant. restore_snapshot("name") reverts geometry without re-running code.
     Use diff_snapshot("name") to see what changed; pass format="json" for structured output.
  
  7. CROSS-SECTIONS FOR INTERNAL GEOMETRY
     render_view with clip_plane + clip_at reveals interior features.
     Use clip_at to position the cut at a specific world coordinate, not just the midpoint.
     Combine with measure(topology) on the unclipped shape to confirm what you see.
  
  8. PART LIBRARY
     search_library("keyword") returns full parameter specs.
     Call load_part("name", '{"param": value}') immediately — no second lookup needed.
     Unspecified parameters use the defaults shown in search results.
  """

• src/build123d_mcp/server.py:168-170 (registration)

  Registration of the 'workflow_hints' tool via the @mcp.tool() decorator on line 168.

  @mcp.tool()
  def workflow_hints() -> str:
      """Return guidance on how to use these tools effectively. Call this at the start of a session or whenever unsure which tool to reach for."""

• src/build123d_mcp/server.py:168-170 (schema)

  The tool has no parameters (empty signature) and returns a string. The docstring on line 170 serves as the description.

  @mcp.tool()
  def workflow_hints() -> str:
      """Return guidance on how to use these tools effectively. Call this at the start of a session or whenever unsure which tool to reach for."""

• tests/test_outcomes.py:561-561 (registration)

  Test assertion confirming 'workflow_hints' is registered as a tool name.

  "search_library", "load_part", "workflow_hints", "session_state", "health_check",