The IT Glue MCP server defines 16 tools with generally good naming conventions (all use action-verb prefixes like search_, get_, create_, update_, delete_, list_). All tools have descriptions present in the schema. However, there are critical gaps: (1) Input schemas are defined in the code but parameter-level descriptions are minimal or missing for many parameters, particularly filter objects which are typed as generic 'object' with no property definitions. (2) Output schemas are not documented anywhere in the visible source code, critical for LLM planning. (3) Risk annotations (READ_ONLY, WRITE, DESTRUCTIVE) are present in metadata but not formally registered as MCP toolAnnotations in the visible schema definitions. (4) Error handling lacks recovery guidance; no examples of structured error responses. (5) The 'filter' parameter pattern (appearing in search_organizations, search_documents, search_configurations, search_passwords, search_flexible_assets) is underspecified, no description of what filters are valid or how to use them. (6) Pagination is mentioned for user_metrics but not consistently applied or documented across all list/search tools. Example: search_organizations accepts a 'filter' object but provides zero documentation of what keys that object should contain or what values are valid.

• Document the 'filter' parameter schema for each search tool. Define which keys are valid (e.g., status, type, created_date), their types, and provide 1-2 examples per tool.
• Add formal output schema documentation to every tool. Include field names, types, and which fields are suitable for chaining (e.g., 'Returns organizationId which can be passed to get_organization or passed to other tools requiring organizationId').
• Register tool annotations formally in the MCP schema: mark delete_document with destructiveHint=true, mark all read-only tools with readOnlyHint=true, mark idempotent write operations with idempotentHint=true.
• Add error recovery guidance. Update tool descriptions to include hints like 'If you receive a 'not found' error, try search_organizations() to locate the resource by name.'
• Standardize pagination. Add documented limit and offset (or cursor) parameters to all search tools. Document result limits (e.g., 'Returns max 50 results') and provide examples of multi-page queries.
• Offer name-based lookup variants. Add optional get_organization_by_name, get_document_by_name parameters alongside ID-based lookups to reduce discovery friction.
• Provide filter examples in descriptions. Instead of 'Optional filters for the search', write 'Optional filters object, e.g. {"status": "active", "location": "US"}' or link to valid filter keys.
• Document the response structure for each search tool. Clarify whether results include nested objects, what metadata fields are included, and how pagination metadata is returned (e.g., 'total_count', 'next_page').