Castalia defines 3 tools with complete input schemas and descriptions in Portuguese. All tools are READ_ONLY and follow a clear naming pattern (verb_noun: search_docs, get_document, list_sources). Descriptions are substantive (150-250 chars) and explain WHEN to use each tool. However, output schemas are not documented, LLMs cannot predict response structure. Parameter descriptions are present but lack explicit constraints (e.g., top_k max=20 is mentioned in description but not in schema). No error handling guidance provided. Tool composition is sound: search_docs → get_document forms a logical chain.

• Document output schemas for all three tools. Define search_docs response as {items: [{doc_id: string, content: string, source: string, score: number}], total: number}. Define get_document response as {doc_id: string, title: string, content: string, metadata: object}. Define list_sources response as {sources: [{name: string, doc_count: number, chunk_count: number, last_ingested: string}]}.
• Formalize parameter constraints in JSON Schema. Add maxItems: 20, minimum: 0, maximum: 1 to top_k and min_score. Define filters as additionalProperties: {type: string} with description of valid keys (content_type, collection, etc.).
• Add error handling guidance. E.g., 'If results are empty, the query may not match any documented rules. Try broader terms or call list_sources to verify documentation is indexed.'
• Add pagination support to search_docs and list_sources. Include offset/limit parameters and return total_count so agents can iterate over large result sets without context explosion.
• Document idempotency and side effects. All three tools are READ_ONLY, so mark them with readOnlyHint in tool annotations (MCP 2026-07-28 feature) to signal to agents they are safe to retry.