The facts-server provides 5 tools with explicitly registered schemas and descriptions. Tool naming follows verb_noun convention (get_, search_, set_, validate_), which is correct. All tools have input schemas with type definitions and descriptions. However, there are significant gaps: (1) parameter descriptions are sparse or missing for many fields, (2) output schemas are not documented, (3) error handling guidance is absent, (4) the set_fact tool combines create and update operations which should ideally be separate tools, and (5) descriptions are minimal (most under 50 chars, well below the 50-200 char LLM-optimized baseline). The validation.ts and storage.ts files are not provided, so we cannot verify error recovery patterns or actual implementation quality. Scoring is conservative given these gaps.
Tool descriptions are too short and lack context. All descriptions fall below 50 characters and do not explain WHEN to use each tool or WHAT to return. Example: 'Get all facts in the system' (30 chars) should explain pagination support, expected result count, and dependencies.
Parameter descriptions are missing or incomplete. The set_fact tool has many complex nested parameters (conditions, acceptanceCriteria) with no descriptions. E.g., 'conditions' array has items with 'factId' and 'type' but no explanation of what REQUIRES vs CONFLICTS_WITH mean or when to use each.
Output schemas are not documented. The code does not show what fields get_all_facts, get_fact, search_facts, or validate_criteria return. LLMs cannot plan downstream tool calls or extract the right data without knowing output structure.
get_all_factsget_factsearch_facts
Recommendations
Expand all tool descriptions to 80 - 150 characters. Include WHAT the tool does, WHEN to call it, and WHAT it returns. Example: 'Retrieve a specific fact by its ID. Call this after search_facts() to get full details. Returns fact object with all metadata and acceptance criteria.'
Add detailed descriptions to all parameters, especially nested objects. For set_fact conditions array, document: 'Conditions array (optional): Defines relationships to other facts. Each condition has factId (string: ID of related fact) and type (enum: REQUIRES means this fact depends on it; CONFLICTS_WITH means this fact cannot coexist with it).'
Document output schemas for all tools. Add a comment block or endpoint documentation showing example return objects. E.g., get_fact returns {id, content, type, strictness, category, minVersion, maxVersion, conditions[], acceptanceCriteria[], createdAt, updatedAt}.
Implement and document error handling. When get_fact is called with an invalid ID, return: {error: 'Fact not found. Try search_facts() with partial type or category to discover available facts.'}. Every error should suggest recovery.
Split set_fact into create_fact and update_fact. create_fact requires id, content, strictness, type, category, minVersion, maxVersion; update_fact requires id and allows optional updates to any other field. This makes idempotency clear.
Add pagination to get_all_facts and search_facts. Introduce limit (1 - 100, default 20) and offset (0 - n) parameters. Return {items: [...], total: number, hasMore: boolean}. Document in descriptions: 'Returns up to 20 facts per request. Use offset to paginate. Large fact bases may require multiple calls.'
Error handling and recovery guidance absent. No evidence in the source that tools return actionable error messages. E.g., if validate_criteria fails, does it tell the LLM why (missing acceptance criteria, validation failed, invalid factId) or just a generic error?
set_fact combines create and update into a single tool. This violates the single-responsibility principle. Agents cannot easily reason about idempotency or distinguish between 'create if missing' vs 'update existing' intent. Should be split into create_fact and update_fact.
Pagination and result limits not documented. get_all_facts returns all facts with no mention of limits or pagination. Should accept limit and offset params and document them explicitly.
Parameter constraints not validated or described. The set_fact schema shows enums for strictness, category, and condition types, which is good. However, fields like 'minVersion' and 'maxVersion' have no format specification (e.g., semantic versioning) or range documentation.
set_fact
Validate input early and return clear errors. For minVersion/maxVersion, enforce semantic versioning format (e.g., '1.0.0'). Return: 'Invalid minVersion: got "v1.0", must be semantic version format (e.g., "1.0.0")' so the LLM self-corrects.
Add tool annotations (tool hints) if using MCP SDK 1.5+. Mark get_* tools with readOnlyHint: true. Mark set_fact (or the split create_fact/update_fact) with destructiveHint or idempotentHint as appropriate.
Document dependencies and prerequisites in descriptions. E.g., 'validate_criteria requires a valid factId from get_fact or search_facts. If validation fails, revise the content and retry.'
Add acceptance criteria acceptance_criteria array support with clear field descriptions: items are objects with id (string), description (string), validationType (MANUAL or AUTOMATED), validationScript (optional, for AUTOMATED). Explain when each is used.