This server exposes 16 tools for Hedera token operations. Naming is generally consistent (verb_noun pattern with hedera_ prefix), and most tools have descriptions and schemas defined using Zod. However, there are critical gaps: (1) Output schemas are not documented, tools return parsed JSON from the agent kit but the expected response structure is never specified for the LLM. (2) Many parameter descriptions are superficial or include example values that LLMs tend to reuse literally. (3) Error handling is absent, no guidance on retryability, user-fixable vs. fatal errors, or recovery steps. (4) Tool 16 (hedera_transfer_native_hbar_token) has no visible input schema in the source provided. (5) Several tools lack sufficient detail on prerequisites, dependencies, and when to use them instead of similar tools. The server follows basic patterns but falls well short of production quality.
Tool 16 (hedera_transfer_native_hbar_token) has no visible input schema or parameters in the provided source code. The file reference is listed but the implementation is not shown. Cannot validate schema completeness.
No output schemas are documented for any tool. LLMs cannot infer what fields to expect in responses, making it impossible to plan chained calls. For example, hedera_create_fungible_token likely returns a token ID, but this is never explicitly stated. This violates the 'Schemas & Output' critical requirement.
Document the output schema for every tool. Create a TypeScript interface or JSON Schema example showing what each handler returns. Example: 'Returns {tokenId: string, transactionHash: string, status: "success" | "pending"}'. Include this in the tool description or as a separate OutputSchema field.
Remove example values from parameter descriptions. Instead, declare numeric ranges, enums, or format patterns in the Zod schema and reference them in the description. Example: 'The ID of the token to airdrop. Token IDs are in the format 0.0.XXXXXX (shard.realm.num).' Avoid '0.0.123456' in text.
Add error handling and recovery guidance to every handler. Use try-catch blocks and return structured errors: {error: string, retryable: boolean, suggestion: string}. Example: 'Token not found: 0.0.123456. Did you create it yet? Try hedera_create_fungible_token first.'
Add dry-run support to irreversible operations (create_*, mint_*, transfer_*, airdrop_*). Accept an optional dryRun parameter that returns 'What would happen' without executing. Example: dryRun=true returns {simulation: 'Would mint 100 tokens to account 0.0.789012'} without actually minting.
Clarify tool selection intent in descriptions. Add 'When to use' sections. Example: 'Use hedera_transfer_token for HTS fungible tokens (custom-issued). Use hedera_transfer_native_hbar_token for native HBAR balance transfers. They differ in transaction structure and fees.'
Implement tool annotations (readOnlyHint, destructiveHint, idempotentHint) for each tool based on Risk labels. Expose these in the MCP ToolDefinition so LLMs understand retry safety. Example: destructiveHint=true for hedera_create_fungible_token.
Retrieves the balance of a specified Hedera Token Service (HTS) token for a given account in base unit. If an account ID is provided, it returns the balance of that account. If no account ID is given, it returns the balance for the connected account.
Parameter descriptions include example values (e.g., '0.0.123456', '100') that LLMs tend to reuse literally in actual calls, causing failures. Replace examples with formal constraints (enums, patterns, ranges) and move examples to separate documentation.
No error handling or recovery guidance. When a tool fails (e.g., insufficient permissions, token not found, account not associated), there is no structured error response guiding the LLM on retryability, what to try next, or whether to ask the user. Handler code simply calls agent methods without try-catch or error classification.
Write and irreversible operations (create_fungible_token, airdrop_token, transfer_token, mint_*) lack confirmation or dry-run support. Agents can inadvertently create tokens or transfer funds without safeguards. No dry-run parameter or confirmation flow is offered.
Tool descriptions are minimal and do not explain when to use each tool vs. alternatives. For example, hedera_transfer_token vs. hedera_transfer_native_hbar_token is not explained, when should an LLM choose one over the other? No dependency hints or prerequisite information is provided.
No documentation of response structure. handler code calls agent.*.getStringifiedResponse() and JSON.parse(), but the LLM never sees what fields are in the result. Example: does hedera_create_fungible_token return {tokenId, txHash, timestamp}? Unknown. This prevents LLMs from planning multi-step operations.
No tool annotations (readOnlyHint, destructiveHint, idempotentHint) in the MCP tool definitions. The Risk labels (READ_ONLY, WRITE, IRREVERSIBLE) are noted in this evaluation but not exposed to the protocol. LLMs have no metadata signaling whether a tool is safe to retry or will have side effects.
Add prerequisite checks and helpful errors. For example, hedera_transfer_token should verify the account is associated with the token and return a helpful error if not: 'Account 0.0.789012 is not associated with token 0.0.123456. Call hedera_associate_token first.'
Batch related operations where possible. For example, hedera_associate_token could accept a list of tokenIds to associate multiple tokens in one call, reducing latency and token overhead for common multi-token workflows.
Document pagination and result limits. For hedera_get_token_holders and hedera_get_all_token_balances, specify the max result limit and add offset/limit parameters if results can be large. Cap at 50 items by default with pagination support.
Add optional parameters for flexibility. For example, hedera_transfer_token could accept a memo field for transaction notes, and read-only tools could accept a format parameter (json, csv, summary) to reduce response verbosity for certain use cases.