Make a contract in one call, or negotiate it clause by clause with a published compromise formula.
Scored across 13 tools
Most tools target distinct resources and actions (generate vs download vs delete a deal, initiate vs join a negotiation, billing tools are clearly separate). The main ambiguity is between list_templates and list_contract_types, which both enumerate contract offerings, though the descriptions differentiate the payloads (codes/guides/laws vs clauses/options/bias). A couple of get/list pairs could be briefly confused but are workable.
Every tool follows a clean snake_case verb_noun convention (buy_credits, create_playbook, get_deal, list_templates, initiate_negotiation, etc.). No mixed styles or vague verbs appear. The pattern is highly predictable.
13 tools is well-scoped for a contract negotiation and generation platform. Each tool maps to a distinct step (discovery, generation, negotiation, retrieval, deletion, billing). No obvious filler or redundancy.
The core contract lifecycle is covered: list types, generate, negotiate, join, get, download, delete, plus billing and credits. Gaps exist around management surfaces: there is no list_deals (only get_deal by id) and the playbook is create-only with no get/list/update/delete. These are workable but leave some dead ends.
Open a hosted checkout for a pack of ten contract credits for this API key's customer (any of its keys can spend them). Returns checkoutUrl for a person to open in a browser; the credits arrive when the payment succeeds. Answers 409 where payments are off.
| Name | Required | Description | Default |
|---|---|---|---|
| currency | No | usd | |
| returnUrl | No | URL to return to after checkout |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With only readOnlyHint=false and openWorldHint=false in annotations, the description carries real behavioral detail: the operation returns a checkoutUrl rather than completing payment, credits are asynchronous (arrive on payment success), any key of the customer can spend them, and a 409 is returned where payments are disabled. That is exactly the kind of failure-mode and lifecycle disclosure annotations cannot express.
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?
Three tight sentences, each earning its place: what it does, what it returns and when credits land, and the failure case. The checkout/return information is front-loaded rather than buried.
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, yet the description names the key return value (checkoutUrl) and the async fulfillment model, plus the 409 condition, which is enough for an agent to call this correctly. Minor gaps remain around currency handling and what the customer sees on return.
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 only 50% (returnUrl is documented, currency is not) and the description says nothing about either parameter – no mention of currency choice or how returnUrl interacts with the hosted checkout flow. It fails to compensate for the coverage gap.
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 ('Open a hosted checkout') and resource ('a pack of ten contract credits'), including the scope of whose credits they are. It is clearly distinguishable from siblings like get_credit_balance, which only reads a balance.
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?
Gives clear context for when this applies: a human opens the checkoutUrl in a browser and credits arrive only when payment succeeds. It does not explicitly name alternatives such as get_credit_balance or state when not to call it, so it stops short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a negotiation playbook defining preferences for each clause: preferred option, priority (1-5), flexibility (1-5), red lines, and acceptable alternatives.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Unique playbook name | |
| entries | Yes | ||
| contractType | Yes | Contract type code: one from list_contract_types, or an A2A_ agent-to-agent protocol type from list_templates (those are negotiated only, never made with generate_contract) | |
| governingLaw | Yes | ||
| contractLanguage | No | en |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false, correctly signaling a write, but the description adds nothing behavioral beyond that: it does not say whether name collisions fail or overwrite, whether the created playbook is immediately usable, or what happens on partial/invalid entries. For a pure mutation with no output schema, this is a notable gap.
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?
A single front-loaded sentence with no filler; every clause carries information about the payload shape. Slightly dense but appropriately sized.
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 and 40% schema coverage, a create tool needs more transactional detail (unique-name behavior, required discovery of clause/option IDs, validation failures) than is provided. The entry-level semantics are covered, but the creation workflow is only minimally complete.
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 only 40%, but the description partially compensates by unpacking the nested entries fields (preferred option, priority 1-5, flexibility 1-5, red lines, acceptable alternatives). It says nothing about the required top-level fields name, contractType, governingLaw, or contractLanguage, leaving those to 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 (Create) and resource (negotiation playbook) and enumerates the clause-level preferences it defines. It is clearly distinguishable from siblings like generate_contract or initiate_negotiation, though it does not explicitly name them.
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?
No guidance on when to use this tool versus alternatives such as initiate_negotiation, nor any prerequisites (e.g., that clause/option IDs and contract types must be discovered first via list_contract_types or list_templates). The agent must infer the setup workflow entirely.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete one of your single-party deals and its data: the parties, the other side's details, the clause choices, the inputs and the contract (documents are made on request and never stored). This cannot be undone. Only the account that made the deal can delete it; for any other account it does not exist (HTTP 404, also when it was already deleted). A deal another party takes part in, such as a two-party negotiation, is refused with HTTP 409 and nothing is deleted. The payment record is kept for billing (amount, date, account and deal id, no names or contract text), and a spent credit is not given back.
| Name | Required | Description | Default |
|---|---|---|---|
| dealId | Yes | Agent deal id (dealId from generate_contract) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true, but the description goes well beyond them: it states irreversibility, the exact data cascade, ownership-based authorization, the 404/409 failure semantics, and the billing side effects (payment record retained, spent credit not refunded). That is precisely the extra context an agent needs before an irreversible call.
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?
Front-loaded with the action and its destructive scope, then layered constraints in escalating order (authorization, refusal, side effects). Every clause carries a distinct operational fact; nothing is redundant across the four sentences.
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 destructive, irreversible tool with no output schema, the description covers everything an agent needs: what is destroyed, what survives (payment record, non-refunded credit), who may call it, and how failures manifest via HTTP codes. Nothing material is left to inference.
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?
There is a single parameter and schema description coverage is 100%, with the schema already explaining that dealId comes from generate_contract. The description adds no format, source, or constraint detail for dealId beyond what the schema provides, so the baseline of 3 applies.
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 and resource (delete a single-party deal) and immediately enumerates the scope of what is removed (parties, other side's details, clause choices, inputs, contract). The single-party scoping distinguishes it from any deal operation that involves other parties, and no sibling tool performs deletion.
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?
Gives clear conditions for when the call succeeds versus fails: only the creating account may delete, others get 404 (also when already deleted), and deals involving another party are refused with 409. No alternative sibling is named because none exists for deletion, so explicit when-not guidance without an alternative is the right level.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Download the agreed contract as Markdown, HTML, PDF, DOCX or TXT (Markdown by default: agents read it best). Negotiation is free; the contract is paid when its document is first fetched: one prepaid credit of the customer is spent (any of its keys draws on the one balance). Later fetches of the same deal are free. With no credit left the answer is HTTP 402 with code PAYMENT_REQUIRED and the link to buy credits.
| Name | Required | Description | Default |
|---|---|---|---|
| dealId | Yes | Agent deal room ID | |
| format | No | md (Markdown) or html for agents and tools; pdf, docx or txt for people and printers | md |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations covering only readOnlyHint/openWorldHint, the description carries real weight: it discloses the credit-spend model, that any key draws on one balance, that repeat fetches are free, and the exact failure contract (HTTP 402, code PAYMENT_REQUIRED, link to buy credits). That is far more than the annotations provide and is exactly what an agent needs before triggering a paid action.
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?
Front-loaded with the action and formats, then the billing and error semantics. Dense but every clause carries information; the parenthetical aside about agents reading Markdown is mildly redundant with the schema but not wasteful.
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 two-parameter tool with no output schema, the description covers the return artifact (the document in the chosen format) and the payment/error outcomes. It does not say what happens if the deal is not yet agreed or the dealId is invalid, a minor gap given the paid-fetch path is well documented.
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 both parameters are already documented, including the format enum and md default. The description adds only a soft recommendation ('Markdown by default: agents read it best') that largely restates the schema's own 'md or html for agents' note, so the baseline 3 applies.
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 a specific verb and resource ('Download the agreed contract') plus the exact output formats, which cleanly separates it from sibling generate_contract (which produces the contract in the first place). An agent can tell what it gets and in what forms 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?
It gives clear situational context: the contract must already be 'agreed', negotiation is free, and the fetch is the point of payment, with later fetches free. It does not explicitly name alternatives (e.g. generate_contract or get_deal) or state the precondition as a when-not rule, so it stops short of a full routing instruction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Make a finished contract in one call: give the contract type, your side's details and, if you know them, the other side's. Clauses you leave out take the standard option. One prepaid credit is spent (the same price as any contract); with no credit the answer is HTTP 402 with code PAYMENT_REQUIRED and nothing is created. Returns the contract as Markdown, then the deal id, the link where the person can read it in Dealroom and the Markdown, HTML, PDF, DOCX and TXT links (free to fetch again).
| Name | Required | Description | Default |
|---|---|---|---|
| role | No | DPA and BAA only: the role you take (see roles in list_contract_types) | |
| party | Yes | Your side (the side the API key acts for) | |
| terms | No | Inputs by id (see inputs in list_contract_types). Send every required input in terms. A required input with a default can be left out: the default is applied. | |
| title | No | Name of the deal; made from the parties when left out | |
| inline | No | The contract itself in the answer: md (Markdown, the default here), html or txt | md |
| clauses | No | Optional clause choices: clause id to option code (see get_template) | |
| language | No | en | |
| contractType | Yes | Code (for example NDA) or guide slug (for example nda), from list_contract_types | |
| counterparty | No | The other side. Left out: its block stays blank for it to complete. | |
| governingLaw | No | Required when the contract type offers more than one | |
| idempotencyKey | No | Send the same value when retrying, so a retry never makes or charges a second contract |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare a mutating, closed-world tool, and the description goes well beyond that: it discloses that one prepaid credit is charged, that insufficient credit yields HTTP 402 PAYMENT_REQUIRED with nothing created, and that clause omissions fall back to standard options. It also documents the return payload (Markdown plus deal id, Dealroom link, and format links) and notes re-fetching is free.
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?
Three sentences, front-loaded with the purpose and input expectation, then clause defaults, then cost/failure, then return shape. Dense but every clause carries information; the trailing enumeration of return links is slightly run-on but justified given there is no output schema.
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 an 11-parameter, nested-object tool with no output schema, the description covers the two burdens the schema cannot: payment/error behavior and the return format. It leaves implicit how to recover from errors other than insufficient credit and does not explain the role parameter, but the core requirements for a correct call are present.
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 91%, so the schema already documents most parameters (baseline 3). The description adds genuine semantic value on omission behavior — unspecified clauses take the standard option and an absent counterparty leaves its block blank — which the schema does not spell out. It does not cover role or governingLaw specifics, keeping it below 5.
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 a specific verb+resource+scope: 'Make a finished contract in one call'. It is clearly distinguishable from siblings like initiate_negotiation (negotiation flow) and get_template (read-only), because it names the one-call, finished-output behavior. An agent can tell instantly this is the end-to-end contract creation path.
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?
It states what inputs to supply (contract type, your side's details, optionally the other side's) and the clause-default rule, giving clear context for invocation. It does not explicitly name alternatives or state when-not-to-use (e.g. use initiate_negotiation to negotiate terms first), so it stops short of a full when/when-not/alternatives treatment.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remaining contract credits of this API key's customer (one balance shared by all of its keys) and the latest ledger entries.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real value by clarifying that the balance is customer-scoped and shared across all of the customer's keys, and that ledger entries are bundled into the response.
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?
A single sentence with the scoping caveat in parentheses, front-loading the primary return value and appending the secondary one. No wasted words.
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 reasonably covers what comes back (balance plus latest ledger entries). It is complete enough for a no-argument read tool, though it does not say how many ledger entries 'latest' means or in what unit credits are expressed.
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?
The tool takes zero parameters, so there is nothing for the description to compensate for. Baseline 4 applies; schema coverage is 100% and no parameter meaning is needed.
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?
Names the specific resource (remaining contract credits) and the scope (this API key's customer, shared across keys) plus secondary content (latest ledger entries). An agent can distinguish it from the write-oriented sibling buy_credits, though the differencing is implicit rather than stated.
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?
No when-to-use guidance, no mention of alternatives such as buy_credits, and no prerequisites. The read intent is only inferable from the wording 'remaining' and the annotations, not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get deal details including per-clause agreed options, satisfaction scores, and reasoning.
| Name | Required | Description | Default |
|---|---|---|---|
| dealId | Yes | Agent deal room ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the agent knows this is a safe, closed-world read. The description adds that it returns per-clause agreed options, satisfaction scores, and reasoning, but doesn't disclose pagination, response limits, or error behavior. With annotations covering the safety profile, this is adequate but not rich.
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?
A single, tightly focused sentence that front-loads the verb and resource, then enumerates the key return values without any filler.
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 simple read tool with one fully documented parameter and annotations covering safety, the description is almost complete. It could benefit from mentioning usage context or return format, but nothing critical is missing given the tool's simplicity and the absence of an output schema.
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% (the only parameter dealId is fully described). The description adds no parameter detail, but with complete schema coverage the baseline is 3; the description's listing of returned data indirectly confirms the parameter's role, nudging it to 4.
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 clear verb (get) and resource (deal), specifying the returned content: per-clause agreed options, satisfaction scores, and reasoning. This distinguishes it from siblings like download_contract or get_template, though no sibling is explicitly named.
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 implies usage by outlining the returned data, but offers no explicit guidance on when to use this tool versus alternatives (e.g., download_contract). Usage is contextually implied but not specified.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List earlier per-skill subscriptions and their status. Skills are no longer sold one by one; every template is included.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely useful context that these subscriptions are legacy and no longer sold individually, but says nothing about return format, volume of historical records, or pagination.
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 short sentences, zero waste, with the primary action front-loaded and the legacy explanation following. Nothing is repeated from the title or annotations.
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 zero-parameter, read-only list tool with annotations covering the safety profile, the description is nearly sufficient. It could say slightly more about what a returned subscription record looks like, but no output schema is needed for an agent to call it 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?
The tool takes zero parameters, so the schema-side burden is nil and the baseline is 4. The description correctly implies the call is unfiltered, returning all earlier subscriptions.
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 gives a specific verb and resource ('List earlier per-skill subscriptions and their status') and the second sentence clarifies these are legacy items, which separates it from siblings like list_templates and get_template. It does not explicitly name an alternative tool, but the resource is distinct enough for an agent to route correctly.
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?
Usage is only implied: the note that 'Skills are no longer sold one by one' signals this is a historical/legacy lookup rather than something used in normal purchase flows. There is no explicit when-to-use statement, no exclusion, and no named alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get full details for a specific contract template including all clauses and their options with bias values.
| Name | Required | Description | Default |
|---|---|---|---|
| contractType | Yes | Contract type code: one from list_contract_types, or an A2A_ agent-to-agent protocol type from list_templates (those are negotiated only, never made with generate_contract) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds that the payload includes clauses, options, and bias values, which is useful, but it says nothing about auth needs, rate limits, or behavior for unknown contract types.
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?
One front-loaded sentence that names the resource and the return payload with zero filler or redundancy.
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 single-parameter lookup with no output schema, the description covers purpose and return contents adequately; only the routing relationship with list_templates/list_contract_types is left implicit.
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% and the single parameter is thoroughly documented in the schema, including the A2A negotiated-only caveat. The description adds no parameter-level detail beyond what the schema already provides, so the baseline 3 applies.
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 (get) and resource (contract template) and enumerates the returned content (clauses and their options with bias values), so an agent knows exactly what it fetches. It does not explicitly distinguish itself from list_templates or list_contract_types, which is the only thing keeping it from a 5.
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?
Usage is only implied: the schema notes contractType must come from list_contract_types or list_templates, hinting this is a follow-up call, but the description itself gives no when-to-use, when-not-to-use, or alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start a new contract negotiation. Returns a negotiation token for the respondent to join.
| Name | Required | Description | Default |
|---|---|---|---|
| dealName | Yes | Human-readable deal name | |
| playbookId | Yes | ID of your playbook | |
| initiatorEmail | Yes | ||
| respondentEmail | No | ||
| initiatorCompany | No | ||
| respondentCompany | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false and openWorldHint=false, so the agent already knows this is a closed-world write. The description usefully adds that a negotiation token is returned for the respondent to join. It says nothing about permissions, whether emails are dispatched to initiator/respondent, or reversibility.
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 short sentences with zero waste; the core action is front-loaded and the return value follows immediately.
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 should carry return-value detail — it only partially does via the negotiation token mention. It never clarifies the three optional parameters or what respondentEmail does at initiation time, leaving an agent under-informed for a 6-parameter creation 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 only 33% — dealName and playbookId are documented, while initiatorEmail, respondentEmail, initiatorCompany and respondentCompany have no descriptions. The description adds no parameter meaning at all, so it fails to compensate for the coverage gap on a 6-parameter tool.
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 states a specific verb and resource ('Start a new contract negotiation') and hints at its counterpart role by mentioning the respondent joining. It does not explicitly name the sibling join_negotiation, but the purpose is unambiguous.
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?
Usage is only implied: the tool begins a negotiation and hands a token to the respondent, which contrasts with join_negotiation. There is no explicit when-to-use guidance, no statement of prerequisites (e.g., needing an existing playbook), and no exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Join an existing negotiation as the respondent. Triggers automatic compromise resolution and returns the result.
| Name | Required | Description | Default |
|---|---|---|---|
| playbookId | Yes | ID of your playbook (must match contract type) | |
| respondentEmail | Yes | ||
| negotiationToken | Yes | Token from the initiator | |
| respondentCompany | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false and openWorldHint=false, so the agent already knows this mutates local state. The description adds genuinely new behavior: joining 'triggers automatic compromise resolution and returns the result' — an important side effect beyond a plain write. It stops short of explaining what resolution means or what permissions/state are required, so not a 5.
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 tight sentences, front-loaded with the action and role, then the behavioral consequence. No filler or redundancy.
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 mutating tool with no output schema, the description covers purpose and the resolution side effect, which is a reasonable minimum. However, it leaves the two undocumented parameters and the meaning/outcome of 'compromise resolution' unexplained, so an agent cannot fully anticipate the call's requirements or results.
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 only 50%: respondentEmail and respondentCompany have no schema descriptions, and the description supplies no parameter guidance at all. With half the parameters undocumented and a mutation tool that depends on a matching playbook, the description fails to compensate for the coverage gap.
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 and resource ('Join an existing negotiation') and disambiguates the role with 'as the respondent', which separates it from initiate_negotiation among the siblings. It doesn't explicitly name the sibling it complements, but the actor-role framing is enough for an agent to tell them apart.
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?
'Join an existing negotiation' implies the usage context (a negotiation already exists and you are the counterparty), but there is no explicit when-to-use, when-not-to-use, or pointer to an alternative tool. Usage is inferable rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Every contract type Dealroom can make, with the code to use as contractType, the guide slug, the governing laws and languages it is offered in, the role the caller can take (DPA and BAA only) and the inputs it asks for. Each input says whether it is required and, when it has one, its default; mustSend marks the required inputs without a default. Send every required input in terms. A required input with a default can be left out: the default is applied. Call this first to know what to ask the user. No API key needed.
| Name | Required | Description | Default |
|---|---|---|---|
| lang | No | Language of names and labels | en |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral facts: "No API key needed" (auth requirement) and how to interpret returned fields (mustSend, defaults, omission semantics) — context the annotations cannot 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?
Purpose (the return payload) is front-loaded, then usage guidance, then how to read the inputs. A few sentences are dense and slightly redundant around required inputs and defaults, but each 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?
With no output schema, the description carries the burden of describing return values and does so in detail, including field meanings and the mustSend/default convention. For a read-only, single-parameter catalog tool, an agent has enough to call it and act on the result.
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?
Single optional parameter with 100% schema description coverage and an enum default, so the schema fully documents it and the baseline of 3 applies. The description discusses languages offered by contract types but never ties that to the lang parameter itself, adding no meaning 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?
The description names a specific resource (contract types Dealroom can make) and enumerates the payload an agent gets back — contractType code, guide slug, laws, languages, role, and inputs. The verb (list) is implied rather than explicit and no sibling tool is named, but the catalog purpose is unmistakable.
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?
"Call this first to know what to ask the user" is an explicit when-to-use directive that positions the tool as the entry point ahead of generate_contract and the other action siblings. It stops short of naming that alternative or any when-not-to-use condition, so it is clear context without full routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List available contract templates with clauses, options, and bias values. Use this to understand which contract types are available and what options exist for each clause. Pass query to search by code, abbreviation or name in English or Spanish ("nda", "dpa", "hipaa", "confidencialidad"), best match first.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Optional search: contract code, abbreviation or name (English or Spanish) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds useful behavior beyond that: the result set includes clauses/options/bias values and is returned 'best match first' when a query is passed, and it works across English and Spanish input.
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?
Three short sentences, front-loaded with purpose, then usage, then parameter guidance. The query sentence partly restates the schema, but the added examples and ordering note justify its presence.
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 simple, parameterless-by-default read-only list tool with no output schema, the description covers what is returned, how search behaves, and language support. Only the relationship to list_contract_types is left unresolved.
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 baseline is 3. The description earns credit above baseline by supplying concrete query examples ('nda', 'dpa', 'hipaa', 'confidencialidad') and clarifying the match-order semantics ('best match first') that the schema does not state.
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?
Specific verb and resource ('List available contract templates') plus the payload contents (clauses, options, bias values), so an agent knows what comes back. It does not, however, differentiate itself from the sibling list_contract_types, which it partly overlaps with by claiming to reveal 'which contract types are available.'
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?
Gives a positive use case ('Use this to understand which contract types are available and what options exist for each clause') but names no alternatives or exclusions. With a sibling named list_contract_types covering a similar-sounding surface, the absence of routing guidance leaves ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
create_playbook3 fields changedInput schema / properties / contractType / descriptionPrevious value: -"Contract type"New value: +"Contract type code: one from list_contract_types, or an A2A_ agent-to-agent protocol type from list_templates (those are negotiated only, never made with generate_contract)"Input schema / properties / contractType / enumRemoved value: -[
- "A2A_API_ACCESS",
- "ACTA_CONSEJO_ADMINISTRACION",
- "ACTA_JUNTA_GENERAL",
- "ADVERTISING_IO",
- "ADVISORY",
- "AFFILIATE_PROGRAM",
- "A2A_MONITORING",
- "PHANTOM_SHARES_GRANT",
- "RESIDENTIAL_TENANCY_GB",
- "RESIDENTIAL_TENANCY_US_CA",
- "DELAWARE_CERT_OF_INCORPORATION",
- "A2A_COMPUTE_PROCUREMENT",
- "CONSULTING",
- "A2A_CONTENT_LICENSE",
- "RESIDENTIAL_TENANCY_ES",
- "CONVERTIBLE_NOTE",
- "DATA_LICENSING",
- "DPA",
- "A2A_DATA_SHARING",
- "EMPLOYMENT",
- "CONTRATO_LABORAL",
- "EQUITY_INCENTIVE",
- "FOUNDERS",
- "BAA_NEGOTIATOR",
- "CESION_PI",
- "IP_ASSIGNMENT",
- "INFLUENCER_MARKETING",
- "JOINT_VENTURE",
- "A2A_KNOWLEDGE_ACCESS",
- "PHANTOM_SHARES_PLAN",
- "A2A_MARKETPLACE",
- "MSA",
- "NDA",
- "A2A_ORCHESTRATION",
- "A2A_PAYMENT_AUTHORIZATION",
- "PRIVACY_NOTICE",
- "SAFE",
- "SAAS",
- "SEED_INVESTMENT",
- "CONTRATO_SERVICIOS",
- "SHAREHOLDERS",
- "PACTO_SOCIOS",
- "SOFTWARE_DEVELOPMENT",
- "A2A_SUPPLY_CHAIN",
- "A2A_TASK_DELEGATION",
- "TECHNOLOGY_LICENSE",
- "TEMPLATE",
- "TERM_SHEET",
- "A2A_TOOL_LICENSE",
- "WHITE_LABEL_RESELLER"
-]Input schema / properties / governingLaw / enumPrevious value: -[
- "CALIFORNIA",
- "NEW_YORK",
- "ENGLAND_WALES",
- "SPAIN"
-]New value: +[
+ "CALIFORNIA",
+ "ENGLAND_WALES",
+ "SPAIN"
+]generate_contract2 fields changedInput schema / properties / governingLaw / enumPrevious value: -[
- "CALIFORNIA",
- "NEW_YORK",
- "ENGLAND_WALES",
- "SPAIN"
-]New value: +[
+ "CALIFORNIA",
+ "ENGLAND_WALES",
+ "SPAIN"
+]Input schema / properties / terms / descriptionPrevious value: -"Inputs by id (see inputs in list_contract_types); required ones must be given"New value: +"Inputs by id (see inputs in list_contract_types). Send every required input in terms. A required input with a default can be left out: the default is applied."get_template2 fields changedInput schema / properties / contractType / descriptionPrevious value: -"Contract type identifier"New value: +"Contract type code: one from list_contract_types, or an A2A_ agent-to-agent protocol type from list_templates (those are negotiated only, never made with generate_contract)"Input schema / properties / contractType / enumRemoved value: -[
- "A2A_API_ACCESS",
- "ACTA_CONSEJO_ADMINISTRACION",
- "ACTA_JUNTA_GENERAL",
- "ADVERTISING_IO",
- "ADVISORY",
- "AFFILIATE_PROGRAM",
- "A2A_MONITORING",
- "PHANTOM_SHARES_GRANT",
- "RESIDENTIAL_TENANCY_GB",
- "RESIDENTIAL_TENANCY_US_CA",
- "DELAWARE_CERT_OF_INCORPORATION",
- "A2A_COMPUTE_PROCUREMENT",
- "CONSULTING",
- "A2A_CONTENT_LICENSE",
- "RESIDENTIAL_TENANCY_ES",
- "CONVERTIBLE_NOTE",
- "DATA_LICENSING",
- "DPA",
- "A2A_DATA_SHARING",
- "EMPLOYMENT",
- "CONTRATO_LABORAL",
- "EQUITY_INCENTIVE",
- "FOUNDERS",
- "BAA_NEGOTIATOR",
- "CESION_PI",
- "IP_ASSIGNMENT",
- "INFLUENCER_MARKETING",
- "JOINT_VENTURE",
- "A2A_KNOWLEDGE_ACCESS",
- "PHANTOM_SHARES_PLAN",
- "A2A_MARKETPLACE",
- "MSA",
- "NDA",
- "A2A_ORCHESTRATION",
- "A2A_PAYMENT_AUTHORIZATION",
- "PRIVACY_NOTICE",
- "SAFE",
- "SAAS",
- "SEED_INVESTMENT",
- "CONTRATO_SERVICIOS",
- "SHAREHOLDERS",
- "PACTO_SOCIOS",
- "SOFTWARE_DEVELOPMENT",
- "A2A_SUPPLY_CHAIN",
- "A2A_TASK_DELEGATION",
- "TECHNOLOGY_LICENSE",
- "TEMPLATE",
- "TERM_SHEET",
- "A2A_TOOL_LICENSE",
- "WHITE_LABEL_RESELLER"
-]delete_dealbuy_creditscreate_playbookdownload_contractgenerate_contractget_credit_balanceget_dealget_subscriptionsget_templateinitiate_negotiationjoin_negotiationlist_contract_typeslist_templatesNegotiate B2B deals agent to agent: every offer recorded, owner rules checked, agreements locked.
Negotiate for your human under PXP: tagged claims, escalation, decision brief, hash-chained ledger
Contract-change authorization for AI agents: preflight a change to an API or MCP contract, get a signed decision, and verify the receipt offline. Only a granted change can proceed.
Negotiation math engine. Pareto frontier, counteroffer generation, zero LLM tokens.
Add one secure layer between your agents and this server.
