Most tool descriptions are under 50 characters and lack actionable context. Examples: 'Create an admin', 'Find all admins', 'Delete an article' do not explain WHEN to use the tool, what prerequisites exist, or what the LLM should do next. LLMs rely on descriptions to disambiguate between similar tools (e.g., three different GET endpoints per resource) but lack guidance here.
No output schemas documented for any of the 36 tools. LLMs cannot infer response structure, they do not know which fields are returned, their types, or how to chain results to downstream tools. For example, 'POST /api/admin' returns a created admin but does not document whether it includes _id, nom, prenom, or other fields needed by 'PUT /api/admin/:id'.
POST /api/admin
Recommendations
Document output schemas for all 36 tools. Include field names, types, and whether fields are always present or conditional. Example: 'Returns {_id: string, nom: string, prenom: string, username: string, tel: string, createdAt: ISO8601}'.
Expand tool descriptions to 100-200 characters and include WHEN the tool applies. Example: 'List all articles in inventory. Use this first to check stock levels before creating a command. Returns paginated results; see limit parameter.'
Rename or deprecate duplicate endpoints. Use standard REST naming: GET /api/{resource} for list, GET /api/{resource}/:id for fetch. Remove '/find/:id' suffix.
Add pagination parameters (limit, offset/page, sort) to all list endpoints ('GET /api/admin', 'GET /api/article', etc.) with descriptions. Document result limits (e.g., max 100 per page) and return a 'total' count.
Move passwords out of tool parameters. Implement JWT-based authentication: return a token in signup/signin responses, and require clients to pass it in Authorization headers (server-side, not exposed as tool params).
Add error response examples to tool descriptions. E.g., 'Returns 409 if email is duplicate: "Email already exists. Use PUT to update that client."' or '400 if tel is not 10 digits.'
Implement soft-delete or require confirmation for DELETE tools. Document in descriptions: 'This operation is irreversible. Consider archiving instead with PUT.'
Clarify phone number format: 'Exactly 10 characters, numeric (no dashes/spaces), format: 1234567890' or 'E.164 format for international numbers'.
Confusing endpoint naming: Each resource has both a generic 'GET /api/{resource}' (list all) and 'GET /api/{resource}/find/:id' (fetch one). This violates RESTful convention and creates ambiguity, LLMs will struggle to decide between them. Standard naming is GET /api/{resource} for list and GET /api/{resource}/:id for single fetch.
No error handling guidance in tool definitions. Tools do not explain what happens on failure (e.g., duplicate email, invalid ID format, permission denied). Index.js shows a generic error handler that returns only status code and error message, with no guidance for the LLM on retry strategy or next steps. Pattern: error responses must tell the LLM what to do.
POST /api/adminPOST /api/articlePOST /api/auth/client/signupPOST /api/clientPOST /api/cmdarticlePOST /api/pubPOST /api/versement
Destructive operations (DELETE tools) lack confirmation mechanisms or idempotency guarantees. Pattern: destructive tools should warn agents or require confirmation. Source code shows AdminClass.remove(), ArticleClass.remove() perform hard deletes with no soft-delete option or undo path.
Password fields are exposed as direct parameters in signup/signin and admin/client creation endpoints. Passwords should never be passed as parameters, they risk appearing in agent logs, traces, and prompt history. Should use server-side secret injection or Bearer tokens instead.
POST /api/adminPUT /api/admin/:idPOST /api/auth/client/signupPOST /api/auth/sign-inPOST /api/auth/client/sign-inPOST /api/clientPUT /api/client/:id
Parameter descriptions lack specificity and constraints. Examples: 'Admin first name, min 2 max 20 characters' (good), but many lack format guidance. 'Client email, unique and required' does not specify email format. 'Tel' phone parameters list 'exactly 10 characters' but do not mention if this is region-specific or international format. LLMs cannot reliably enforce format constraints without explicit descriptions.
POST /api/adminPUT /api/admin/:idPOST /api/auth/client/signupPOST /api/clientPUT /api/client/:id
No pagination support documented for list endpoints ('GET /api/admin', 'GET /api/article', etc.). Tools do not accept page, limit, or offset parameters. If these endpoints return large result sets, LLM context will be exhausted. No mention of result limits or total counts in descriptions.
GET /api/adminGET /api/articleGET /api/clientGET /api/cmdarticleGET /api/pubGET /api/versement
Tool names do not clearly distinguish between listing and filtering operations. 'GET /api/cmdarticle/client/:clientId' and 'GET /api/pub/client/:clientId' are filter operations but are named like generic GETs. Should be 'list_cmdarticles_by_client' or similar to clarify that a parameter is required and the response is filtered.
GET /api/cmdarticle/client/:clientIdGET /api/pub/client/:clientIdGET /api/versement/client/:clientId
No explicit description of what auth tokens are returned by signup and signin endpoints. 'POST /api/auth/client/signup' says 'Client signup with JWT token generation' but does not document the response format (does it return a token field? Where is it?). This breaks tool chaining, downstream tools cannot use the token if the response structure is undocumented.
POST /api/auth/client/signupPOST /api/auth/sign-inPOST /api/auth/client/sign-in
Add enum constraints for status/state fields (e.g., 'etat' in cmdarticle and pub). Current descriptions say 'status, required' but do not list valid values. Should be explicit: 'etat: enum(pending, confirmed, shipped, delivered, cancelled)'.
Document required vs optional parameters more explicitly. Example: 'nom (required), prenom (optional). If omitted, defaults to empty string' rather than listing constraints without clarity.
Add permission/scope annotations to tools, e.g., 'Requires admin role' or 'Requires write:article permission'. This helps agents understand which operations they can perform.
Include sample responses in expanded descriptions (but NOT in parameter descriptions, where they risk being copied literally). E.g., 'Sample: {_id: "60f7...4d", email: "john@example.com", solde: 150.50}'.