MCP contract: add tool annotations and standardized errors

[sajeetharan]

Problem

The MCP server doesn't provide stable, annotated hints for tool discovery or standardized error guidelines, making automated retries and agent-side error handling difficult.

Acceptance Criteria

• Provide read-only annotations for discovery tools.
• Provide state-changing annotations for introduction tools.
• Implement stable error codes and structured categories.
• Document and implement retry/rate-limit guidance for client agents.
• Tests and developer documentation.

Dependencies

• None.

[sajeetharan]

The implementation for this issue has been completed in draft PR #204.
Delivered Scope: Rich annotations and diagnostic options, including categorized errors, machine-readable diagnostics, and Link-based metadata headers (such as server-card and agent-skills).
Validation: Standardized Link header injection verified and diagnostic responses conform to the schema.

[sajeetharan]

PR #204 delivered annotations/basic categorized retryable errors. Remaining open for standard retry/rate-limit contract tests.