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

With no annotations, the description carries the burden of behavior. It discloses important validation behavior: at least one signer and one signature placeholder, and how multi-signer placeholders must be assigned via signer_fields. It does not state whether the contract is created as a draft, whether signers are notified, or what the return payload looks like.

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 description is three focused sentences, front-loading the primary action and then adding prerequisites and placeholder mechanics. Each sentence carries necessary information, with examples that clarify without bloating.

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 tool with 7 parameters, nested signers, no annotations, and no output schema, the description covers the most error-prone aspects (signer requirements, placeholders) but omits the return value, the mutual exclusivity/requirement between content and template_id, and the effect of variables/test_mode. It is adequate but has clear gaps.

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 0%, and the description adds crucial meaning beyond the schema: it explains the template vs custom content modes, ties content to signature placeholders, and maps signer_fields to per-signer placeholders with concrete examples. However, it says nothing about variables, test_mode, expires_in_days, or the output/returned contract, so compensation is incomplete.

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?

The description opens with 'Create a new contract from a template or with custom content', giving a specific action and resource, and clearly scopes the two creation modes. It does not explicitly name sibling tools such as contract_send or contract_update, so the agent must infer differentiation from the action verb alone.

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?

The description supplies preconditions ('Requires at least one signer') and content requirements (signature placeholders, signer_fields assignment), which guide valid calls. However, it never states when to prefer this tool over contract_send or contract_update, nor what should not be done; usage is only implied by the verb 'Create'.

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