Single tool 'search_findings' has a well-structured input schema with proper Zod validation and comprehensive filter options. Description is adequate (118 chars) but generic. Parameter descriptions are present and mostly clear, though some lack actionable constraints. Output schema is not explicitly documented, the code trims findings but LLMs cannot see the return structure. Error handling is minimal; network failures and PDF parsing errors are caught but responses lack recovery guidance. No tool annotations (readOnlyHint, etc.) despite READ_ONLY risk classification.

• Document the output schema explicitly. Add a comment or JSDoc showing the trimmed finding structure: {id, slug, title, impact, quality_score, rarity_score, report_date, firm_name, protocol_name, protocol_categories: [{title, score}], finders: [string], tags: [string], source_link, github_link, pdf_link, ...}.
• Enhance error messages with recovery hints. E.g., 'PDF fetch failed (404): source_link may be outdated. Try searching again or check the contest_link field.' This guides LLM retry logic.
• Add tool annotations to the tool definition: readOnlyHint: true to signal safety and prevent agents from treating this as a write operation.
• Clarify minFinders/maxFinders in the filters description: 'minFinders and maxFinders are numeric strings (e.g., "1", "10") representing the range of finders who reported the issue.'
• Add pagination guidance to the tool description: 'Results are paginated. Use page (1-indexed) and pageSize (1-100, default 50) to iterate. The response includes metadata with total count for planning subsequent calls.'