The server provides 10 tools with complete input schemas and descriptions. Naming is mostly clear and verb-first. Descriptions are adequate but fall short of LLM-optimized length targets (baseline 194 chars; most here are 80-150 chars). Parameter descriptions exist and are specific, but some are terse. Error handling is minimal, tools throw raw errors without recovery guidance. Output schemas are not documented. No parameter constraints (enums, min/max) are visible in the schema definitions. The server handles credentials correctly via environment variable injection (DA_ADMIN_API_TOKEN). Tools follow single-responsibility pattern. Media tools have good naming distinction (check_status, refresh_cache, get_index, search, stats, find_usage). Source tools are clear (list, get, create, delete). Overall structure is sound, but falls short of production A/B grade due to sparse error handling, undocumented output schemas, and descriptions that could be richer for LLM selection.
Output schemas are not documented. Tools return JSON via daAdminResponseFormat() but LLMs cannot infer response structure. No documentation of fields in list results, media search results, or stats breakdowns.
Error handling lacks recovery guidance. In utils.js, daAdminRequest() throws raw errors with status codes and response bodies. LLMs receive 'Error: 404, {message}' instead of 'File not found at /path. Verify org, repo, and path parameters. Call da_admin_list_sources to confirm the path exists.'
Add output schema documentation to each tool. In index.js ListToolsRequestSchema handler, include 'outputSchema' alongside inputSchema. Document da_admin_list_sources returns {folder: string, sources: Array<{name, path, type}>}; da_media_search returns {total, items: Array<{url, type, name, alt, usageCount}>}; etc.
Enhance error handling in utils.js daAdminRequest(). Catch HTTP errors and return actionable messages: if 404, return 'Resource not found at {url}. Verify org={org}, repo={repo}, path={path}. Call da_admin_list_sources({org}, {repo}, {parent_path}) to confirm the path exists.' Categorize errors: 4xx as user-fixable, 5xx as retryable.
Refactor da_admin_create_source content parameter. Remove the 300+ char template from description. Instead, add a 'template' parameter (enum: 'html', 'json') that generates valid scaffolds; content becomes a smaller required string. Or document the template at the tool level with clear sections: 'HTML template: <body><header></header><main>...</main><footer></footer></body>. JSON template: {"sheet1": {"total": N, "data": [...]}}.'
Add mutual exclusivity validation to da_media_find_usage. In the handler, check that exactly one of mediaUrl or mediaName is provided. Return: 'Provide either mediaUrl or mediaName, not both. E.g., mediaUrl="/content/dam/image.png" or mediaName="image.png".'
Add pagination to da_admin_list_sources and da_media_search. Include limit (default 20, max 100) and offset parameters. Return {total, limit, offset, items: [...]}. Document in tool description: 'Returns up to 20 items per call. Use offset to fetch additional results.'
Score history
Overall score trend
↑ 22 points across a rubric change (v1 → v2)
68/100
Scored
Grade
Overall
Spec posture
Rubric
2026-09-22
C
68
2026-07-28+
v2
2026-03-09
F
46
-
v1
read only
auth
source verified
78/100
Get the complete media index (media.json) for a site. Returns all media references with timestamp.
da_admin_create_source description is 60 chars but contains a large multi-line template example (300+ chars) embedded inline. This wastes space and can confuse LLMs. Should be refactored into parameter-level guidance with formal constraints or a link to documentation.
da_media_find_usage requires either 'mediaUrl' OR 'mediaName' but both are marked as optional. No validation enforces exactly one is provided. Missing input validation with clear error message: 'Must provide either mediaUrl or mediaName, not both or neither.'
No pagination support visible. da_admin_list_sources and da_media_search could return hundreds of items. No limit, offset, or page parameters, and no result count. Violates baseline pattern for listable resources.
No confirmation step for destructive operations. da_admin_delete_source has no dry-run, preview, or confirmation pattern. Agents can irreversibly delete files without safeguards.
Tool descriptions do not state WHEN to use each media tool. da_media_check_status vs da_media_get_index are both media discovery tools. No guidance on which to call first or when check_status is preferable.
da_media_check_statusda_media_get_index
Add a confirmation mode to da_admin_delete_source. Include optional 'dryRun' boolean parameter (default false). When true, return 'Would delete {path}.{ext}. Call again with dryRun=false to confirm.' Prevents accidental destructive operations.
Enhance da_admin_list_sources description: 'Lists all sources (HTML and JSON files) in a folder. Call this first to discover available paths before calling get_source or delete_source. Useful for navigation and verification.'
Document per-tool permission requirements in descriptions. E.g., da_admin_create_source: 'Requires write access to the repository.' da_admin_delete_source: 'Requires admin access and will irreversibly remove content.' This supports audit and least-privilege agent config.
Add a 'path' parameter to media tools to indicate site hierarchy. Currently optional but not explained. Clarify: 'For hierarchical structures, path is the site folder path (e.g., "site-name" or "region/site-name"). Leave empty for flat orgs.'
Validate and describe 'ext' parameter in source tools. Currently free-form string. Change to enum: ext: z.enum(['html', 'json']) to prevent invalid extensions. Update description: 'File extension: html for web pages, json for spreadsheet data.'
Add timeout and rate-limit handling. In daAdminRequest(), catch fetch timeout and return: 'Request to {url} timed out after 30s. Verify network connectivity and try again.' Add retry-after guidance if API returns 429.