Parameter descriptions entirely absent. No tool parameter explains what it accepts, validates, constrains, or controls. LLMs cannot infer parameter semantics from names alone, a 'properties' param in updateComponent could mean any JSON object, but lacks guidance on valid structure, required fields, or allowed values.
Add parameter descriptions to ALL 35 tools. For each parameter, explain: what it controls, valid values/ranges, format requirements, and dependencies. Example: 'locale: BCP 47 language tag (e.g., en-US, de-DE). Required. Determines which language version to operate on.'
Fix bulkUpdateComponents: define its input schema with explicit properties. If it bulk-updates multiple components, accept an array of component update objects with paths and properties.
Document output schemas for all tools. Add to tool description or as a separate 'Returns:' section. Example: 'Returns: {success: boolean, componentPath: string, updatedProperties: object, timestamp: ISO8601}'. Include IDs needed for chaining.
Split replicateAndPublish into two tools: replicateContent (replicate to locales) and publishContent (publish to live environment). Allows agents to replicate without publishing or publish without replication.
Add confirmation/dry-run support to destructive operations. E.g., add a 'dryRun' boolean parameter to deletePage, deleteComponent, deleteAsset. Return 'What would be deleted' without actually deleting when dryRun=true.
Add 'WHEN TO USE' context to ambiguous tool descriptions. Disambiguate getPageContent vs getPageTextContent: 'getPageContent: Get all content structure including components, fragments, and metadata. Use when building a page model. getPageTextContent: Extract only text for translation or analysis. Use when you need copywriting, not structure.'
Implement pagination with documented limits. Update listPages, searchContent, executeJCRQuery to: (1) Document max limit in description (e.g., 'limit: max 50, default 20'), (2) Return total count or next_cursor in output, (3) Explain offset/cursor behavior.
bulkUpdateComponents has empty input schema (no properties defined). Tool is non-functional, LLMs cannot determine what parameters to pass or what structure is expected. Violates JSON Schema contract.
Output schemas undocumented throughout. Tool descriptions do not explain what fields are returned, what structure to expect, or which IDs/references are available for downstream tool chaining. Agents cannot plan multi-step operations without knowing output structure.
Destructive operations (deletePage, deleteComponent, deleteAsset) lack confirmation/dry-run support and absence of warning descriptions. Tool definitions do not warn that these are irreversible. No confirmation-request pattern visible.
Composite/ambiguous tool responsibilities. replicateAndPublish combines replication AND publication in one tool (violates single-responsibility). getAllTextContent and getPageTextContent both fetch text from pages but differ in scope, unclear when to use each. scanPageComponents + updateComponent + validateComponent form a tight trio with overlapping concerns.
Tool descriptions lack 'WHEN to use' context. Most descriptions state WHAT the tool does but not WHY or when an LLM should prefer it over alternatives. E.g., 'Get page properties' vs 'Get page content', both are read operations on pages but descriptions do not disambiguate.
No pagination support documented in list/search tools. listPages, searchContent, and executeJCRQuery accept a 'limit' parameter but descriptions do not explain pagination behavior, cursor/offset mechanism, or how to handle large result sets. Missing total count or next_cursor in response documentation.
Error handling and recovery guidance absent. No tool descriptions mention error cases, recovery strategies, or what an LLM should do if a call fails. No documented error classifications (retryable, user-fixable, fatal) or error message examples.
Tool naming contains 'and' connective. replicateAndPublish signals multiple concerns (replication + publication). Should be split into replicateContent and publishContent so agents can compose operations independently.
Parameters lack enum constraints. Several tools accept open-ended string parameters (type, status, etc.) without enums. Searchable parameters like 'type' in searchContent are unconstrained, LLMs may hallucinate invalid type values.
Add error recovery guidance to descriptions. Example for deletePage: 'If deletion fails, check if page has children (use scanPageComponents first). If page is published, unpublish before deleting (use deactivatePage).'
Rename legacy tools (getNodeContent, listChildren) with a 'legacy_' prefix to signal they are deprecated and guide LLMs toward modern alternatives.
Add parameter constraints in descriptions. E.g., for depth in listPages: 'depth: max nesting level to traverse. Range 1-10, default 3. Higher depths risk performance impact.'
Consolidate overlapping read tools. Consider merging getAllTextContent and getPageTextContent into a single getPageText tool with an optional parameter (includeMetadata: boolean) to control depth.
Add tool annotations (readOnlyHint, destructiveHint, idempotentHint) to aid MCP clients in risk assessment. Mark deletePage, deleteComponent, deleteAsset with destructiveHint=true.
Document default values and their implications. E.g., if listPages defaults depth to 3, explain why and that increasing it may timeout.
Add validation examples to parameter descriptions to guide LLMs. E.g., componentPath: 'Absolute JCR path, e.g., /content/mysite/pages/home/hero-banner. Must start with /content/.'
For write operations (updateComponent, uploadAsset, etc.), clarify idempotency. Document whether repeated calls with same parameters are safe (idempotent) or risky (e.g., version increments on each call).