md-succ-ai exposes 3 well-named tools with generally clear descriptions and valid JSON Schema input definitions. All tools start with action verbs (convert_, extract_, batch_) and serve distinct purposes. Descriptions are adequate (100-180 chars range) and explain what the tools do. However, there are meaningful gaps: output schemas are not formally documented in the visible code; error handling guidance is minimal; parameters lack some constraint details (e.g., max URL count for batch_convert is stated but not enforced via schema maxItems); and some parameter descriptions could be more actionable. The server is HTTP-based and appears stateless, which aligns with current MCP standards, but tool annotations (readOnlyHint, idempotentHint) are not present. Tool composition is reasonable, each tool has a single responsibility, and related tools (convert_url, batch_convert) have complementary interfaces. Parameter naming is verb_noun compliant and generally clear.

• Add formal output schema documentation to each tool. Include field names, types, and descriptions. E.g., for convert_url, document: { title: string, markdown: string, tokens: number, tier: string, quality: { grade: string, score: number }, totalMs: number }.
• Add tool annotations. Mark all three tools as readOnly using idempotentHint: true and readOnlyHint: true in the schema or via tool metadata.
• Enforce numeric constraints in JSON Schema. Add minItems/maxItems to the 'urls' array in batch_convert (maxItems: 20). Add minimum/maximum to max_tokens (e.g., minimum: 1, maximum: 100000).
• Replace generic error messages with actionable recovery guidance. E.g., 'URL unreachable (HTTP 404). Verify the URL is public and correct.' or 'Page too large (>100k tokens). Try mode=fit to reduce output.'
• Clarify the extract_data schema parameter. Specify: (1) which JSON Schema keywords are supported (type, enum, minimum, maximum, minLength, maxLength), (2) whether custom types are allowed, (3) an example with validation constraints. E.g., { properties: { price: { type: 'number', minimum: 0 }, title: { type: 'string', minLength: 1 } }, required: ['price', 'title'] }.
• Add per-parameter constraints to the schema. Document why mode defaults to 'full' (not 'fit') and what truncation happens when max_tokens is exceeded. Specify whether mode='fit' reduces token count by ~50% or varies by content.
• Document batch_convert partial failure responses. Clarify the structure of per-URL results: does each URL return { success: boolean, markdown?: string, error?: string }, or another format? How does the caller distinguish succeeded items from failed ones?

Inferred effective spec: 2026-07-28+.

• Relies on Logging (deprecated) - log to stderr or use OpenTelemetry