From 341cf09de4e4123f64a5d645df5f4760ba966f66 Mon Sep 17 00:00:00 2001
From: Tuvit Rubin Kaplan <tuvitk@wix.com>
Date: Fri, 30 Jan 2026 17:59:07 +0200
Subject: [PATCH] docs: add common mistakes sections for entities and agents

Add documentation to prevent common configuration errors:

- entities-create.md: Add warning about nested "schema" property mistake
  that causes "Invalid schema: Schema must have a 'type' field" errors

- agents-push.md:
  - Fix entity_name example to use PascalCase (Task not tasks)
  - Add agent file naming convention (underscores, not hyphens)
  - Add warning about wrong "tools" vs "tool_configs" format
  - Add best practices for agent instructions when using entity tools

These issues were discovered during real-world usage and caused
significant debugging time.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 skills/base44-cli/references/agents-push.md   | 53 +++++++++++++++++--
 .../base44-cli/references/entities-create.md  | 26 +++++++++
 2 files changed, 75 insertions(+), 4 deletions(-)

diff --git a/skills/base44-cli/references/agents-push.md b/skills/base44-cli/references/agents-push.md
index 1607bf9..afeee0c 100644
--- a/skills/base44-cli/references/agents-push.md
+++ b/skills/base44-cli/references/agents-push.md
@@ -75,7 +75,7 @@ Each agent file should be a `.jsonc` file in `base44/agents/` with this structur
   "instructions": "Detailed instructions for the agent's behavior",
   "tool_configs": [
     // Entity tool - gives agent access to entity operations
-    { "entity_name": "tasks", "allowed_operations": ["read", "create", "update", "delete"] },
+    { "entity_name": "Task", "allowed_operations": ["read", "create", "update", "delete"] },
     // Backend function tool - gives agent access to a function
     { "function_name": "send_email", "description": "Send an email notification" }
   ],
@@ -84,9 +84,54 @@ Each agent file should be a `.jsonc` file in `base44/agents/` with this structur
 ```
 
 **Naming rules:**
-- Agent names must be lowercase alphanumeric with underscores only
-- Valid: `support_agent`, `order_bot`, `task_helper`
-- Invalid: `Support-Agent`, `OrderBot`, `task helper`
+- **Agent names** must be lowercase alphanumeric with underscores only
+  - Valid: `support_agent`, `order_bot`, `task_helper`
+  - Invalid: `Support-Agent`, `OrderBot`, `task helper`
+- **Agent file names** must use underscores (matching the agent name)
+  - Valid: `support_agent.jsonc`, `order_bot.jsonc`
+  - Invalid: `support-agent.jsonc` (hyphens not allowed)
+- **Entity names in `tool_configs`** must use PascalCase (matching the entity's `name` field)
+  - Valid: `"entity_name": "Task"`, `"entity_name": "TeamMember"`
+  - Invalid: `"entity_name": "task"`, `"entity_name": "team_member"`
+
+### Common Mistake: Wrong tool_configs Format
+
+**WRONG** - Do NOT use `tools` with `type` and `entity`:
+```jsonc
+{
+  "name": "my_agent",
+  "tools": [                                    // ❌ WRONG
+    { "type": "entity_query", "entity": "Task" }
+  ]
+}
+```
+
+**CORRECT** - Use `tool_configs` with `entity_name` and `allowed_operations`:
+```jsonc
+{
+  "name": "my_agent",
+  "tool_configs": [                             // ✅ CORRECT
+    { "entity_name": "Task", "allowed_operations": ["read"] }
+  ]
+}
+```
+
+### Best Practices for Agent Instructions
+
+When giving agents access to entities, be explicit in the instructions about using the tools:
+
+```jsonc
+{
+  "name": "support_agent",
+  "instructions": "You are a helpful support agent.\n\nIMPORTANT: You have access to customer data through entity tools. When users ask about their orders or account:\n1. ALWAYS use the Order entity tool to query their order history\n2. Use the Customer entity tool to look up account details\n3. Analyze the data and provide personalized responses\n\nAlways query the relevant entities first before answering questions about user data.",
+  "tool_configs": [
+    { "entity_name": "Order", "allowed_operations": ["read"] },
+    { "entity_name": "Customer", "allowed_operations": ["read"] }
+  ]
+}
+```
+
+Without explicit instructions to use the entity tools, the agent may not proactively query user data when asked.
 
 ## Use Cases
 
diff --git a/skills/base44-cli/references/entities-create.md b/skills/base44-cli/references/entities-create.md
index ed1dc90..efb6297 100644
--- a/skills/base44-cli/references/entities-create.md
+++ b/skills/base44-cli/references/entities-create.md
@@ -65,6 +65,32 @@ Each entity file follows a JSON Schema-like structure:
 }
 ```
 
+### Common Mistake: Nested Schema Property
+
+**WRONG** - Do NOT wrap properties in a `schema` object:
+```jsonc
+{
+  "name": "Task",
+  "description": "A task entity",
+  "schema": {                    // ❌ WRONG - don't use nested "schema"
+    "type": "object",
+    "properties": { ... }
+  }
+}
+```
+
+**CORRECT** - Put `type` and `properties` at the top level:
+```jsonc
+{
+  "name": "Task",
+  "description": "A task entity",
+  "type": "object",              // ✅ CORRECT - top level
+  "properties": { ... }          // ✅ CORRECT - top level
+}
+```
+
+This is a common mistake that will cause "Invalid schema: Schema must have a 'type' field" errors when pushing entities.
+
 ## Supported Field Types
 
 ### String