Programmatic CRUD for AI project knowledge bases (Claude Projects, Gemini Gems)
Four tools with basic verb-noun naming (list_files, read_file, write_file, delete_file) and short descriptions (10-34 chars). All tools have input schemas with typed parameters and descriptions. However, descriptions are below the 50-200 char baseline for LLM-optimized tools, most are single sentences lacking context on WHEN to use each tool or what happens on error. Output schemas are minimally documented (write_file and delete_file return dicts with status/platform/project/file, but no formal schema declaration). No error handling guidance, no pagination support, no idempotency markers. Parameter descriptions are present but generic ('The platform: local or claude'). No tool annotations (readOnlyHint, destructiveHint). Missing recovery guidance for common failures (e.g., 'file not found' or 'permission denied').
Delete a knowledge file.
List all knowledge files in a project.
Read the contents of a knowledge file.
Create or update a knowledge file.
Descriptions are too short (10-34 chars) and lack LLM-optimized context. Should explain WHEN to use each tool, what it returns, and prerequisites. Baseline: 50-200 chars.
delete_file lacks error handling guidance and confirmation pattern. Destructive operations should support dry-run or explicit confirmation to prevent accidental data loss.
No tool annotations present. delete_file should have destructiveHint=true; read_file and list_files should have readOnlyHint=true. Annotations guide agent safety reasoning.
Output schemas not formally documented. write_file and delete_file return dicts with status/platform/project/file, but no JSON Schema declaration. LLMs cannot infer field types or plan downstream calls.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | F | 49 | 2026-07-28+ | v2 |
No error recovery guidance. If a file is not found, permission denied, or platform is invalid, the tool should return actionable error messages (e.g., 'File not found. Available files: [...]') rather than raw exceptions.