decrypt_contest_entry

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

Goes beyond the annotations by disclosing that the private key stays in-process and is never pinned or sent to an RPC, and by advising the use of a contest-specific key — non-obvious security behavior for a decryption call. It also notes the ciphertext is fetched from IPFS when entryCid is used, adding operational context the readOnlyHint/openWorldHint flags do not convey.

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?

Two sentences with zero padding; the core action and input choice come first, with the security caveat front-loaded at the end of the second sentence. Every clause carries information.

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?

For a read-only, nested-schema decryption tool with no output schema, the description covers the input alternatives, the key-handling model, and the IPFS fetch path. It does not hint at the return value (plaintext entry), but annotations cover the safety profile and the schema is fully documented, so the gap is minor.

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 coverage is 100%, so the baseline is 3, but the description adds the either/or semantics between entry and entryCid that the schema alone leaves ambiguous (both are optional with additionalProperties false). It does not elaborate on the publicKey/privateKey pairing beyond the schema text, which is already explicit.

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+resource ('Decrypt a contest entry') plus the cryptographic context ('with the poster key pair'), clearly distinguishing it from the sibling encrypt_contest_entry. An agent knows exactly what operation this performs 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?

Explains the two mutually exclusive input paths ('Give either entryCid... or the envelope itself') and cross-references get_contest for where the CID comes from, which is genuine routing guidance. It stops short of stating when not to use the tool, but the context is clear.

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