General principles that apply to all MCP servers in this system (gdata_mcp_server.py, misc_mcp_server.py, and any future connectors).
Every MCP tool description must include the public notes key where its usage is documented. This lets the LLM look up detailed docs, examples, and schema without the developer having to re-explain them in the prompt.
Format to append at the end of the description string:
Usage notes: <notes-key> (public notes store)Examples already applied:
• pg_query (misc_mcp_server) → location-db/usage
• gdata_mcp_server tools → gdata-server/mcp-server
Without this, the LLM only knows what fits in the tool's description field. With a notes key, the LLM can read the full usage note, schema, examples, and error-handling advice at query time — making the tool far more useful without bloating the tool schema.
When a tool may need to be retried (e.g. stale DB connection, transient network error), return a message ending with "Please try again." The LLM will retry the tool call. Never raise an unhandled exception that kills the request.
• misc-server — pg_query and any future tools
• gdata-server MCP server — all notes KV tools (get, put, patch, batch, delete, keys, outline, reorder, table_op)
• Any future MCP connector added to this system