Output schemas not formally documented. Tools return JSON-stringified text responses without declaring the shape of returned objects. LLMs cannot determine what fields to expect or plan downstream tool calls without parsing prose.
Error handling is generic. All tools catch errors and return 'Fel vid hämtning av...' (Error fetching...) without recovery guidance, error classification, or actionable next steps for the LLM.
Define formal output schemas for each tool. For example, searchEducationEvents should document: 'Returns {content: [{type: 'text', text: string}], isError?: boolean}', or better, parse and return structured objects with typed fields like {education_events: Array<{id, title, schoolUnitCode, ...}>, total_count, page_info}.
Add error classification and recovery guidance. Instead of generic 'Fel vid hämtning av...', return structured errors: '{isError: true, errorType: 'NOT_FOUND|INVALID_PARAM|SERVICE_UNAVAILABLE', message: 'School unit X not found. Available units: ...', suggestion: 'Try searchSchoolUnitsV4 to find valid codes'}'.
Remove duplicate tool definitions. Consolidate getSchoolUnitStatistics (appears in both advanced-tools.ts and meta-tools.ts) into a single canonical version. Clarify the role of 'meta-tools', if they are composite wrappers, document this explicitly.
Strip API version suffixes from tool names. Rename getSchoolTypesV4 → getSchoolTypes, getProgramsV4 → getPrograms, etc. Versioning is internal; the agent should not care.
Add min/max constraints and enums to parameter descriptions. Example: 'page: Pagination page number (0-indexed, default 0)' → 'page: Pagination page number (0-indexed, 0-10000, default 0)'. For typeOfSchool, use enum constraint and reference valid values in description.
Standardize pagination semantics. Document: 'page and size control pagination. limit caps total results returned. If limit is set, results may not fill all pages requested.' Ensure all tools return totalElements and indicate if hasMore.
Tool duplication and naming inconsistency. 'getSchoolUnitStatistics' appears twice (in advanced-tools.ts and meta-tools.ts) with slightly different schemas. The 'V4' suffix on some tools (getSchoolTypesV4, getGeographicalAreasV4, etc.) is API version noise, should not leak into tool names visible to LLMs.
Parameter descriptions lack format and constraint clarity. For example, 'schoolUnitCode' is described as 'Skolenhetskod (8 siffror)' but no Zod enum or pattern validates this. Parameters like 'page', 'size', 'limit' lack min/max guidance. Distance parameter is boolean in some tools, string in others (inconsistent).
Pagination handling unclear. Multiple tools accept 'page', 'size', and 'limit' parameters, but the relationship between them and total count is not documented in descriptions. Results are sliced client-side but total available is not always returned to the LLM for context on available data.
API version numbers (V4) exposed in tool names. This is internal API management leaking into the agent interface. Removes flexibility to upgrade backend APIs without renaming tools.
Enrich error responses with available alternatives. When a school unit code is not found, return available units in the same municipality/county. When a filter parameter is invalid, list valid options.
Document parameter relationships. For distance parameter (boolean vs string inconsistency), fix to single type and describe: 'For online education, set to true. For in-person, set to false.'
Add tool composition hints in descriptions. E.g., 'Before calling this, use getSchoolUnitsV4 to find a school code. Returns school_unit_code which can be passed to getSchoolUnitEducationEvents.'
Implement structured logging with request/response tracing (already declared as supported). Use correlation IDs to link tool calls across multi-step agent flows for debugging.