register_executed_commercial_agreement

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

The description adds meaningful behavioral context beyond the annotations by explicitly stating 'performs no provider call.' Combined with 'Seal existing... evidence,' this clarifies that the tool finalizes locally held evidence rather than making an external call. It does not contradict the idempotentHint=true annotation, and the local-write nature is compatible with readOnlyHint=false.

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 a single, tightly packed sentence with no filler. It front-loads the primary action ('Seal existing governed DocuSign READ evidence') and immediately follows with the most important operational constraint ('performs no provider call'). Every word earns its place.

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?

Despite having an output schema, the tool's overall context is not complete. The description does not explain how to obtain the observation journal IDs, whether this tool should follow a specific read or resolution step, or what constitutes a valid 'candidate.' The nested input structure with zero schema coverage is a significant gap for an agent trying to invoke the tool correctly.

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 0%, and the description does not compensate by explaining company_ref, project_ref, or the nested candidate fields. The names company_ref and project_ref are somewhat self-explanatory, but envelope_observation_journal_id and document_observation_journal_id are obscure and the description only vaguely references them as 'DocuSign READ evidence.'

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 names a specific action and object: 'Seal existing governed DocuSign READ evidence.' This is more informative than a tautology and adds a key behavioral qualifier ('performs no provider call'). However, it doesn't clearly distinguish itself from sibling tools like resolve_executed_commercial_agreement, and 'seal' and 'governed' are domain jargon that could be ambiguous.

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 provides no explicit guidance on when to use this tool versus alternatives. 'Performs no provider call' hints that this is a local operation, but there is no mention of when to choose register_executed_commercial_agreement over get_executed_commercial_agreement or resolve_executed_commercial_agreement, nor any exclusion criteria.

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