SecureAnnex MCP has 11 tools with mixed quality. Tool naming follows verb_noun convention (search_, get_, analyze_) which is good. However, descriptions are present but generic (most 50-150 chars), lacking the specificity needed for LLM tool selection. Schemas are well-formed JSON Schema with types and descriptions for all parameters, but descriptions for individual parameters tend toward bare labels without constraints or format guidance. Critical security concerns exist: the tool set provides access to extension source code and manifest files without apparent rate limiting or access control patterns. No input validation, error recovery guidance, or permission gates documented. Resources are implemented but tool composition lacks idempotency documentation and error handling patterns.
Parameter descriptions lack constraint documentation. E.g., 'limit' param has no min/max bounds, 'category' has no enum values or format spec, 'extension_id' has no format pattern or length constraints. LLMs will pass invalid values (negative limits, made-up categories) without validation.
Tool descriptions are generic and lack WHEN/WHY guidance. E.g., 'Get detailed information about a specific browser extension' does not explain when to call this vs get_extension_details vs get_extension_manifest. Descriptions under 100 chars do not provide sufficient context for LLM tool selection.
Add minimum and maximum constraints to numeric parameters. E.g., 'limit': {'type': 'integer', 'minimum': 1, 'maximum': 100, 'description': 'Maximum number of results to return (1-100, default 20).'}
For search_extensions, define 'category' as an enum: e.g., enum: ['productivity', 'security', 'privacy', 'development', ...]. Include the enum list in the parameter description.
Expand tool descriptions to 100-200 chars with explicit WHEN/WHY guidance. E.g., 'Get detailed information about a specific extension, including name, version, ratings, and permissions. Use this before analyze_extension to retrieve metadata. Requires extension_id (use search_extensions to find IDs).'
Document output schemas for all tools. E.g., 'Returns object: {extension_id: string, name: string, version: string, rating: number 0-5, review_count: number, permissions: [string], ...}. Results limited to 1 item for detail tools, up to 50 for list operations.'
Add error categorization in descriptions: 'On 404, the extension_id is invalid, try search_extensions(name=...). On 429, the API quota is exceeded, wait and retry after the reset_at timestamp. On 5xx, the service is down, retry with exponential backoff.'
Implement input validation in tool handlers: validate extension_id format, limit bounds, category enum membership. Return actionable errors: 'Invalid limit: got 500, must be 1-100. Invalid category: got "foo", must be one of: [...].'
Remove debug print() statements that log server_config. Use structured logging (stderr or OpenTelemetry) without credential leakage.
No error handling or recovery guidance documented. fetch_from_api() returns raw error dicts with 'error' key, but tools do not describe what errors are retryable (429 rate limit) vs user-fixable (invalid extension_id) vs fatal. Agents cannot determine next steps on failure.
No output schema documented for any tool. The sample code shows cache structure but does not declare what fields tools return, what type each field is, or whether results are paginated. LLMs cannot plan downstream calls or extract chaining IDs without knowing the response structure.
API key exposed via environment variable SECUREANNEX_API_KEY with fallback to server_config dict. If server_config is set from untrusted config, credentials can leak. No secret vault or secure injection pattern. Code comment shows debugging output: print(f'server_config: {server_config}'), traces will log sensitive config.
get_extension_code and get_extension_manifest retrieve sensitive intellectual property without access control or permission gates. No audit trail or caller identity validation. A compromised agent could dump entire extension source code repositories. No dry-run or confirmation pattern for destructive or sensitive operations.
No rate limiting or backoff strategy visible. fetch_from_api() detects 429 (rate limit) and returns an error dict with reset_at, but tools do not implement exponential backoff or guide agents to retry later. An agent in a loop could hammer the API and exhaust quota immediately.
search_extensions accepts optional 'category' parameter with no enum constraint. LLMs will invent category names or pass typos. Code does not validate category values before sending to API.
Tool naming lacks distinction between similar operations. E.g., get_extension_details, get_extension_signatures, get_extension_manifest, get_extension_urls, get_extension_code are all 'get' operations on the same resource but serve different purposes. Descriptions do not clarify when to use which. LLMs may conflate them or call the wrong one.
Migrate API key handling to use a secure secrets manager (e.g., hashicorp/vault, AWS Secrets Manager) instead of environment variables. Never log or expose the API key in tool parameters or responses.
Add permission/scope declarations to tools that access sensitive data (get_extension_code, get_extension_manifest). Document required permissions in tool description: 'Requires scope: read:extension_code. Admin approval required for audit.'
Add audit logging to track who called which tool, with sanitized parameters (no extension_id leakage), and what the result was. Include timestamp and caller identity.
Implement per-tool rate limiting and backoff. E.g., 'On 429 response, retry after reset_at seconds with exponential backoff (max 5 retries). If quota remains exhausted, abort and inform the user.'
For tools that retrieve large data (get_extension_code, get_extension_manifest), add pagination or chunking. E.g., 'Results over 1MB are returned in chunks with a next_cursor field. Use the cursor to fetch subsequent chunks.'
Add idempotency guarantees. Document: 'This tool is idempotent, repeated calls with the same extension_id return identical results and have no side effects. Safe to retry on transient failures.'
Clarify tool relationships in descriptions. E.g., 'get_extension_manifest returns the manifest.json file. For broader details, use get_extension_details. For security analysis, use analyze_extension.'