souldinals_inscribe_soul

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

With no annotations present the description carries the full burden, and it does most of it well: it discloses the broadcast side effect, that the call returns immediately rather than waiting for confirmation, the 10-60 minute confirmation window, and the fixed content type. It stops short of stating that the commit spends real BTC/fees or what happens if the commit is never revealed, but the core behavioral profile is clear.

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?

The step label and the commit/reveal split are front-loaded, and the 'Returns:' line is compact and actionable. The trailing 'Tip: call earning_opportunities' is unrelated promotional content that does not help invoke this tool and slightly dilutes the definition.

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?

No output schema exists, so the description compensates by naming the exact return fields (commitTxid, revealAmount, contentBase64) and instructing the agent to preserve them for the reveal step. Combined with the prerequisite and timing info, an agent has everything needed to call this correctly and hand off to the next tool.

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 would be 3, but the description adds real meaning: parentInscriptionId carries an ownership and Taproot-address constraint, and soulContent is pinned to text/markdown regardless of input. The feeRate parameter is left entirely to the schema, which is acceptable given full coverage.

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 ('Inscribe a soul.md as a child inscription') and immediately narrows scope to STEP 1 of a two-step flow, with a clear note that content type is always text/markdown. An agent can distinguish this from inscribe_child, souldinals_reveal_soul, and the plain inscribe tool without opening any 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?

Explicitly sequences the workflow: this tool broadcasts and returns, then 'After it confirms (typically 10-60 min), use souldinals_reveal_soul to complete.' It also states a hard precondition (you must own the parent inscription and it must sit at your wallet's Taproot address), which is exactly the kind of when-to-use/when-not information that prevents failed calls.

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