AIContextMCP defines 8 tools with complete JSON schemas and type information, but descriptions are cryptic and parameter documentation is sparse. Tool names use domain-specific verbs (bootstrap, search, record, list, create) but lack clarity for LLM selection. Schemas are present but descriptions read like internal API docs rather than agent-optimized guidance. No output schemas documented. Error handling exists but lacks recovery guidance. Security concerns: requestId format is undocumented, mutation semantics unclear.

• Expand tool descriptions to 100-200 chars following the pattern: 'WHAT it does, WHEN to use it, WHAT it returns.' E.g., 'Search for context entries across a repository by category, branch, or commit. Returns matching entries with title, summary, and freshness status. Use this to locate existing context before recording new observations.'
• Document output schemas for all tools. Add a 'Returns' section to each description listing key fields (id, title, status, branch, commitSha, etc.) and their types. This enables LLMs to chain tools correctly.
• Add enum constraints for 'status', 'category', 'severity' parameters. Replace free-form strings with explicit allowed values (e.g., status: ['open', 'resolved', 'superseded']) to prevent hallucinated values.
• Formalize requestId validation. Define a regex pattern or format string in the schema (e.g., pattern: '^\d{10}:[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$') and reference it in the description.
• Add parameter descriptions for all shared fields (branch, commitSha, category, status, projectId, repositoryId). Explain what each controls and whether it is required, optional, or has a default.

Inferred effective spec: 2025-06-18+.

• Relies on Logging (deprecated) - log to stderr or use OpenTelemetry