Based on a design review, we have established a best practice for documenting MCP tools for AI agents: the description field in the openapi.yaml specification should serve as a comprehensive user manual, not just a brief summary.
This ticket covers the work to apply this standard to all tools in the Knowledge Base MCP server, ensuring each tool's definition includes strategic guidance, usage patterns, and examples.
Acceptance Criteria
- The
openapi.yaml file for the knowledge-base server is reviewed.
- The
description for each operation (sync_database, create_knowledge_base, embed_knowledge_base, delete_database, etc.) is expanded into a full manual using Markdown sections.
- The manuals explain the tool's purpose, when to use it, what it does behind the scenes (e.g., "this orchestrates the create and embed tools"), and any potential side effects (e.g., "this is a destructive operation").
- The
query_documents description, which already follows this pattern, can be used as a template.
Based on a design review, we have established a best practice for documenting MCP tools for AI agents: the
descriptionfield in theopenapi.yamlspecification should serve as a comprehensive user manual, not just a brief summary.This ticket covers the work to apply this standard to all tools in the Knowledge Base MCP server, ensuring each tool's definition includes strategic guidance, usage patterns, and examples.
Acceptance Criteria
openapi.yamlfile for theknowledge-baseserver is reviewed.descriptionfor each operation (sync_database,create_knowledge_base,embed_knowledge_base,delete_database, etc.) is expanded into a full manual using Markdown sections.query_documentsdescription, which already follows this pattern, can be used as a template.