Tighten learned node selection instructions

Author: temiroff

docs/agent-guide.md

@@ -51,8 +51,10 @@ Do not commit local planning notes, generated scratch exports, API keys, run log
 ## Learned Nodes vs PythonFn
 
 Default rule: inspect the catalog first, use built-in nodes when they solve the
-task, and create a learned node only when a reusable missing capability is
-needed.
+task exactly, and create a learned node when a reusable missing capability is
+needed. Do not treat brittle approximations as matches; for example, generic
+regex extraction is not a structural RSS parser if the requested output is only
+article titles.
 
 Use `PythonFn` for one-shot code that belongs only to the current workflow.
 Examples: a tiny adapter between two ports, a temporary formatting expression,

docs/quickstart-mcp.md

@@ -95,11 +95,16 @@ use learned nodes only when a reusable capability is missing:
 When building Blacknode workflows, always inspect the existing node catalog first
 with list_nodes and get_node_schema.
 
-Use built-in nodes whenever they can solve the task.
+Use built-in nodes whenever they can solve the task exactly.
 
 If the task needs a reusable capability that is missing from the catalog, create
 a learned node with create_node_type instead of using one-off Python code.
 
+Do not treat a brittle approximation as a match. For example, if the user asks
+to parse RSS article titles and only a generic regex extractor exists, create a
+learned node that parses RSS structurally instead of returning feed metadata or
+other false positives.
+
 Do not create or modify files under nodes/learned directly. Use
 create_node_type, list_learned_nodes, get_learned_node_source, and
 delete_learned_node.

python/blacknode/mcp/server.py

@@ -26,18 +26,22 @@
 
 1. Always inspect the existing node catalog first with list_nodes and
    get_node_schema.
-2. Use built-in nodes whenever they can solve the task.
+2. Use built-in nodes whenever they can solve the task exactly.
 3. If the task needs a reusable capability that is missing from the catalog,
    create a learned node with create_node_type instead of using one-off Python
    code.
-4. Do not create or modify files under nodes/learned directly. Use
+4. Do not treat a brittle approximation as a match. For example, if the user
+   asks to parse RSS article titles and only a generic regex extractor exists,
+   create a learned node that parses RSS structurally instead of returning feed
+   metadata or other false positives.
+5. Do not create or modify files under nodes/learned directly. Use
    create_node_type, list_learned_nodes, get_learned_node_source, and
    delete_learned_node.
-5. Before creating a learned node, keep the interface small and typed, use
+6. Before creating a learned node, keep the interface small and typed, use
    requires_network=false unless network is strictly required, generate only a
    def run(...) function, and make sure the function parameters match the
    declared inputs.
-6. After creating a learned node, call list_learned_nodes, use it in the visual
+7. After creating a learned node, call list_learned_nodes, use it in the visual
    workflow, validate the graph, open it in the editor, and cook the final
    Output node.