nokey provides 8 well-named tools with strong descriptions and mostly complete schemas. Tool naming follows verb_noun convention (list_secrets, exec, mint_token, revoke_token, start_proxy, stop_proxy) with clear action semantics. Descriptions are detailed and explain WHAT each tool does, WHEN to use it, and consequences (e.g., exec output redaction, token approval workflows). However, schema completeness varies: some parameters lack explicit type definitions in visible code, and output schemas are not documented in the source provided. Error handling is minimal, no recovery guidance or categorization. Security is a strength: the server enforces secret redaction, supports token-based approval workflows, and uses environment variable injection. The tool set is cohesive (secret management + command execution + proxy) with good composition and idempotent operations. Cancellation is supported. Tool annotations (readOnlyHint, destructiveHint) are present. No prompts, resources, sampling, roots, or logging observed, correct omission for current spec. STDIO transport caps protocol readiness at 50 maximum.

• Document output schemas for all tools. For list_secrets and list_tokens, specify: { type: 'object', properties: { secrets: [{ name: string, ... }], tokens: [{ id: string, ttl_seconds: number, ... }] }, ... }. For exec/exec_with_secrets, specify return structure: { stdout: string, stderr: string, exit_code: number }.
• Add error handling guidance. When a token is invalid, return: 'Token expired or invalid. Use mint_token(secrets=[...], ttl_seconds=3600) to mint a new lease token.' Categorize errors as retryable (timeout, temporary failure) vs. user-fixable (invalid token, permission denied).
• Implement pagination for list_secrets and list_tokens. Add 'limit' (default 20, max 100) and 'offset' (default 0) parameters. Return { total_count: number, results: [...], has_more: boolean }.
• Clarify start_proxy 'addr' parameter format in description. Example: 'Loopback address in format 127.0.0.1:PORT or 127.0.0.1:0 (auto). Port range 1024-65535. Non-loopback IPs are rejected for security.'
• Add per-item success/failure reporting. If mint_token is called with multiple secrets and one is invalid, return { tokens: [...], errors: [{ secret_name: string, error: string }] } so agent can retry selectively.
• Document any rate limits on token minting (e.g., 'max 100 active tokens per user') to prevent agent runaway loops.
• Specify timeout behavior for exec/exec_with_secrets. If timeout_seconds is exceeded, return { exit_code: -1, stdout: '<partial>', stderr: 'Command timed out after 30s' } and indicate this is retryable.