Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare readOnlyHint=false, idempotentHint=false, destructiveHint=false; the description goes far beyond them by disclosing the identity-binding rules, the on-chain key-set membership check, the REVOKED response, the returned unsigned_tx_bytes + transaction_id, the required client-side signing flow, and the gas-from-vault constraint. This is exactly the extra behavioral context annotations cannot carry.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Dense and front-loaded: purpose first, then when-to-use, then identity constraints, then action-specific rules, then the signing flow and safety cautions. Every sentence carries operational information, though the middle sections are long enough that a reader must hold several constraints at once.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description compensates by naming the return values (unsigned_tx_bytes + transaction_id) and describing how to sign and submit them with the Hiero SDK. For a 7-param, 6-required mutation-preparation tool with no annotations covering identity or safety, nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3, but the description adds real meaning the schema does not: purpose is on-chain, intro_claim_code must come from YOUR post_agent_intro, agent_username must match that intro, and register/update impose different username requirements. It does not, however, explain the ipfs_cid or vault_account_id semantics beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (prepare) plus the exact resource (an UNSIGNED registerPage/updatePage call the vault signs), and immediately separates this from the sibling prepare_agent_vault / prepare_agent_claim by scoping it to the vault's blockpage. An agent can identify the tool from the description alone without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-to-use ('when the human prompts you in their AI chat to register your blockpage or update its content'), explicit actor ('you operate the vault with your own agent key, the human doesn't sign'), and explicit action-specific preconditions (register requires a free username; update requires the vault to already own it). It also states the failure mode (REVOKED) and the prerequisite tooling (must pass intro_claim_code from post_agent_intro, check_vault_health for gas).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.