ScopeHold MCP defines 2 tools with clear, security-focused descriptions. Both tools have proper input schemas with typed parameters and descriptions. However, output schemas are not explicitly documented in the source code, only inferred from test assertions. Parameter descriptions are adequate but lack detail on constraints, formats, and error recovery guidance. The server correctly avoids exposing secrets as parameters (pattern:secret-injection), but lacks error handling guidance for common failure modes (e.g., 'Secret could not be resolved' returns only a generic 403 without recovery hints).

• Document output schemas explicitly in tool definitions. For list_available_secrets, specify: { agent: { id, workspaceId, projectId }, secrets: [{ id, kind, provider, providerDisplayName, name, environment, scopeKind, currentVersionNumber, updatedAt }] }. For resolve_secret: { credentialType, value, referenceId, secret: { id, kind, name, environment, scopeKind, providerId, providerName, providerDisplayName, version } }.
• Add error recovery guidance to resolve_secret description: 'If resolution fails, verify the provider, name, and environment match exactly what list_available_secrets returns. Contact your ScopeHold admin if the secret is missing or access is denied.'
• Clarify resolve_secret's 'environment' parameter: 'Optional. If the secret has multiple environments, specify the exact environment name from list_available_secrets. If omitted and the secret exists in only one environment, that environment is used; if multiple exist, an error is returned.'
• Add pagination guidance to list_available_secrets: 'Returns all secrets in the agent's scope. If the inventory is large, consider implementing limit/offset parameters in a future version. Currently, all secrets are returned in a single response.'
• Update both tool descriptions to state: 'These tools are read-only and idempotent. Repeated calls with the same parameters return the same result and have no side effects.'