this repo has no description
docs: add Letta tool registration learnings
AGENTS.md:
- Added "Letta Tool Registration (Critical!)" section
- Documents json_schema format (flat, not OpenAI nested)
- Explains explicit schema requirement on create AND update
- Shows Python function signature best practices
- Covers tool attachment timing and existing tool handling
README.md:
- Added troubleshooting section for "Tools not working"
- Includes commands to verify tool schemas in Letta
- Documents how to debug tool webhook calls
- Shows how to delete/recreate agents if needed
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
+102
+71
CLAUDE.md
+71
CLAUDE.md
···
135
135
});
136
136
```
137
137
138
+
### Letta Tool Registration (Critical!)
139
+
140
+
Custom tools require careful registration. Letta's "auto-extraction from Python source" is unreliable.
141
+
142
+
**1. json_schema format** - Use Letta's flat format, NOT OpenAI's nested format:
143
+
```typescript
144
+
// WRONG (OpenAI format)
145
+
json_schema: {
146
+
type: 'function',
147
+
function: { name, description, parameters }
148
+
}
149
+
150
+
// CORRECT (Letta format)
151
+
json_schema: {
152
+
name: 'tool_name',
153
+
description: 'What it does',
154
+
parameters: {
155
+
type: 'object',
156
+
properties: { /* ... */ },
157
+
required: ['arg1']
158
+
}
159
+
}
160
+
```
161
+
162
+
**2. Always pass json_schema explicitly** - Both on create AND update:
163
+
```typescript
164
+
// When creating
165
+
await client.tools.create({
166
+
source_code: pythonCode,
167
+
description: '...',
168
+
json_schema: { name, description, parameters }, // Required!
169
+
});
170
+
171
+
// When updating existing tools
172
+
await client.tools.update(toolId, {
173
+
source_code: pythonCode,
174
+
description: '...',
175
+
json_schema: { name, description, parameters }, // Also required!
176
+
});
177
+
```
178
+
179
+
**3. Python function signatures** - Use explicit typed parameters:
180
+
```python
181
+
# WRONG - Letta won't know what args to pass
182
+
def my_tool(**kwargs):
183
+
pass
184
+
185
+
# CORRECT - Explicit parameters
186
+
def my_tool(text: str, priority: int = None):
187
+
pass
188
+
```
189
+
190
+
**4. Tool attachment timing** - Attach AFTER agent creation:
191
+
```typescript
192
+
// Tools must be attached after agent is created
193
+
// (tool_ids in create() doesn't work with letta-free)
194
+
const agent = await client.agents.create({ /* ... */ });
195
+
for (const toolId of toolIds) {
196
+
await client.agents.tools.attach(toolId, { agent_id: agent.id });
197
+
}
198
+
```
199
+
200
+
**5. Handle existing tools** - Check by name and update instead of failing:
201
+
```typescript
202
+
const existingTools = new Map<string, string>();
203
+
for await (const tool of client.tools.list()) {
204
+
existingTools.set(tool.name, tool.id);
205
+
}
206
+
// Then update if exists, create if not
207
+
```
208
+
138
209
---
139
210
140
211
## Code Quality (MANDATORY)
+31
README.md
+31
README.md
···
269
269
1. Verify bot token is correct
270
270
2. Check if another instance is running (only one can poll at a time)
271
271
3. For webhooks, ensure URL is publicly accessible with valid HTTPS
272
+
273
+
### Tools not working / "missing required parameter"
274
+
275
+
This usually means Letta doesn't know the tool's parameter schema. Check:
276
+
277
+
1. **Verify tool schema in Letta:**
278
+
```bash
279
+
curl http://localhost:8283/v1/tools/<tool-id> | jq '.json_schema'
280
+
```
281
+
If `properties` is empty `{}`, the schema wasn't registered correctly.
282
+
283
+
2. **Restart the app** to re-register tools:
284
+
```bash
285
+
# Kill and restart
286
+
bun run dev
287
+
```
288
+
Watch for "Updated tool 'xxx'" messages in the logs.
289
+
290
+
3. **Check tool webhook is receiving calls:**
291
+
Look for `🔧 TOOL WEBHOOK RECEIVED:` in the console output.
292
+
293
+
4. **Delete and recreate the agent** if tools were registered after agent creation:
294
+
```bash
295
+
# List agents
296
+
curl http://localhost:8283/v1/agents | jq '.[].id'
297
+
# Delete problematic agent
298
+
curl -X DELETE http://localhost:8283/v1/agents/<agent-id>
299
+
```
300
+
The bot will create a new agent on the next message.
301
+
302
+
See `AGENTS.md` for detailed Letta tool registration requirements.