Contracko

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

Annotations already establish readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile costs the description nothing. The credit observation (CLM consumes none, Parser bulk processing does) is a genuine behavioral fact not in the annotations, but it is vague about which operations it covers. Critically, with no output schema the description should state what a successful vs. failed confirmation looks like, and it does not.

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 with the action front-loaded, which is good, but sentence two (Parser vs. CLM credits) interrupts the flow and is not clearly connected to validating access, and sentence three jump-cuts to a re-invocation trigger. Tight, but the ordering buries the usage rule behind an aside.

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, zero-output-schema auth check, the description should be the primary carrier of return semantics — what confirmation yields and what happens on failure — since no structured data supplies it. Instead it spends its budget on credit accounting and omits the outcome entirely, leaving the agent unable to report validation 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies by rule. The empty schema and 100% coverage leave no semantic gap to compensate for.

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?

"Confirm workspace/access" gives a verb (confirm) and a target (workspace/access), and the title 'Confirm connection' reinforces it, so the general intent — validate the session/workspace — is inferable. But it never says what the confirmation produces (identity, plan, permissions) or how it differs from siblings like clm_get_contract_access, and the second sentence about Parser credits reads as unrelated billing trivia rather than purpose.

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?

There is one explicit invocation cue: "Call again when the user mentions upgrading, plans or limits," which tells the agent when to re-run the check. However, there is no guidance on when to call it initially (start of session? after errors? after a 401?) and no mention of alternatives or exclusions relative to the many clm_* siblings.

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

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

Annotations declare destructiveHint=true and idempotentHint=false, and the description adds genuinely new context beyond them: comments are attributed to the acting member and trigger email notifications to contract followers. The 'repeats create another comment' line usefully explains what non-idempotency means in practice, though it does not explain why the tool is flagged destructive.

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 compact sentences with the primary action leading and the side-effect/idempotency notes following. Phrasing is telegraphic ('Repeats create another comment') but no sentence is wasted.

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 two-parameter mutation with full schema coverage and annotations, the description covers purpose, attribution, notification side effect, and duplicate behavior. Only minor gaps remain, such as the authorization implied by 'acting member' and what 'destructive' refers to.

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 both parameters (id, content) are documented, so the schema carries the burden. The description adds no meaning about the id format or the content constraints (1–10000 chars) beyond what is already structured.

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 the action clearly (comment, attributed to the acting member) and the resource is unambiguous via the tool name and the sibling clm_list_contract_comments. It does not explicitly name the sibling tool to distinguish read vs. write, but the verb+resource pairing is specific enough for selection.

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?

There is no guidance on when to use this versus clm_list_contract_comments or the event-creation tools, and no prerequisites or exclusions are stated. Usage is only implied by the verb 'Comment'.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=true, so the safety profile is known. The description adds genuinely new context: 'replace the effective primary' identifies what is affected, and 'No Parser credits' discloses a cost trait absent from annotations. It still omits what happens to the superseded primary (deleted vs. archived) and how the idempotency key governs retries.

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 compact clauses, front-loaded with the action and its scope, with zero filler. The trailing 'No Parser credits' is useful but is unexpanded jargon that a reader may need to interpret.

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?

This is a destructive mutation with three required parameters and no output schema, so the description must carry the behavioral burden that annotations only partially cover. It is adequate on intent and cost, but silent on payload limits (inline base64 vs. remote downloadUrl), what the caller gets back, and the consequence of replacing a primary document.

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 a 3 is the baseline, but the description adds meaning the schema does not: it maps the bare 'draft'/'related'/'replace' enum to intent semantics and ties 'replace' specifically to the effective primary of an editable contract. It says nothing extra about idempotencyKey or allowDuplicate, which the schema already documents.

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 (Add / replace) and resource (contract documents) plus the three intents: draft, related, and replacing the effective primary. It also bounds the target to an 'editable contract'. It does not, however, distinguish this from nearby siblings like clm_create_upload_url, clm_create_upload_session, or clm_ingest_contract, which an agent could plausibly confuse with it.

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 phrase 'on an editable contract' is a real precondition, and 'No Parser credits' hints at a cost profile that may steer an agent away from reprocessing tools. But there is no explicit when-to-use versus when-not guidance and no named alternative for remote vs. inline uploads or for starting a new document ingestion.

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

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

The annotations already declare destructive=true, idempotent=true and openWorld=false, so the mutation profile is largely covered. The description does add genuine context beyond that: an approval gate, a client-support restriction, and the external side effects of updating scheduled emails and calendar feeds. It omits what happens on fingerprint mismatch or partial-selection failure, which matters for a destructive commit.

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, front-loaded with the approval gate, and the side-effect warning follows. The phrasing is dense and telegraphic ('only with person approval for this exact selection'), but nothing is redundant.

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 four-parameter, fully-required destructive mutation with no output schema, the description covers the critical safety facts: approval requirement, unsupported-client block, and downstream effects. What remains missing is error behavior around the fingerprint check and what the caller receives on success, a modest gap.

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 each parameter carries a description, so the baseline is adequate. The description adds a little meaning on top: 'this exact selection' clarifies that selectedProposalIds must be the user-reviewed set rather than a broad or inferred selection, which is a semantic constraint the schema alone does not convey.

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 verb 'apply' plus the object 're-read findings'/'contract reconciliation' identifies this as the commit step for a re-read run, which is distinguishable from read-side siblings like clm_get_contract_reconciliation and clm_list_contract_reconciliations. It stops short of naming those siblings explicitly, so differentiation is implied 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?

It states a hard precondition (person approval for this exact selection) and a when-not case (unsupported clients cannot apply), which is real usage guidance. However, it does not route the agent to the alternative steps (e.g., fetching or listing the reconciliation first to obtain the run ID and proposals), so the surrounding workflow must be inferred.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=false. Beyond those, the description adds meaningful side effects: date changes can update scheduled emails and calendar feeds, and results are per-contract outcomes. It still omits conflict/version behavior and atomicity, so it is not a full 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 compact sentences are front-loaded with scope and then side effects. Every sentence adds operational context; there is no 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 complex bulk mutation with no output schema, the description supplies the batch limit, per-contract outcomes, and notable side effects. The rich schema carries field/version details and annotations carry the safety profile, though partial-failure and atomicity semantics remain 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%, so the nested update object and required expectedUpdatedAt are documented by the schema. The description adds no parameter-level syntax or constraints beyond 'up to 100' and 'date changes'; 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 'Patch metadata for up to 100 contracts', giving a specific verb (patch), resource (contracts), and scope (bulk up to 100). This distinguishes it from the single-contract sibling clm_update_contract even though it does not name that sibling.

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 establishes the bulk context and 100-item limit, but gives no explicit when-not guidance or named alternative such as clm_update_contract for single updates. Usage is implied by the bulk limit rather than stated as routing advice.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=true, so the safety profile is covered. The description adds genuinely new behavior - that reminder notifications are emailed to recipients when due - but omits the batch nature (a single call creates up to 100 events) and says nothing about what happens on partial failure or what is returned.

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 or redundancy. It is efficiently sized, though the phrase 'when due' is slightly vague about trigger timing.

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 batch mutation with deeply nested reminder/recipient objects, the description covers only the headline purpose and the email side effect. Given the fully documented schema and the rich annotations, this is roughly adequate, but an agent gets no signal that this is a bulk create that can fan out up to 25 reminders per event to real email recipients.

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% and the nested schema documents events, reminders, offsets, and recipients in detail, so baseline is 3. The description only loosely gestures at the reminders array through 'optional linked notifications'; it adds no meaning about the batch 'events' array or the idempotencyKey beyond the schema's own 'Identical-input retry key' note.

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 pairs the specific verb 'Create' with the resource 'custom events', and adds that events may carry linked notifications emailed to recipients. That is enough to distinguish it from read/delete siblings, but it never mentions clm_create_event_reminders or clm_update_contract_events, so an agent cannot tell why 'linked notifications' here is different from the standalone reminders tool.

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?

There is no when-to-use guidance, no prerequisites (e.g. the contract must exist), and no named alternative such as clm_update_contract_events or clm_create_event_reminders. The reader must infer usage entirely from the tool name.

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

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

With destructiveHint=true and openWorldHint=true already declared, the bar is lower, and the description does add real context: the bearer-link exposure model, revocation/expiry boundary, and the required manage access plus sharing entitlement. It does not say what the call returns (presumably a link URL) or whether repeated calls accumulate links, which matters for a non-idempotent destructive operation.

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?

Four short sentences, each carrying distinct information: what is created, the approval gate, the access/entitlement prerequisite, and the retry rule. Front-loaded with the core action and no 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 non-idempotent, destructive, open-world mutation with no output schema, the description covers preconditions, exposure risk, expiry, and safe retry behavior. The notable gap is the return value and whether multiple links can coexist for one contract, which an agent needs before retrying or creating a second link.

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. The description mentions expiry presets (1, 7 or 28 days), which merely restates the enum, and says nothing about the five access-flag parameters (one-time use, comments, page view, document/attachment download) beyond the generic phrase 'the selected access'.

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: 'Create a bearer link' for a contract, with the nature of the artifact spelled out ('anyone with it can use the selected access'). This clearly separates it from clm_list_contract_shares and clm_revoke_contract_share, though it never names those siblings explicitly.

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 a hard precondition ('after explicit user approval') plus entitlement requirements, and it routes the agent to listing links when the outcome of a prior call is unknown ('Unknown outcomes require listing links before retrying'). No explicit when-not-to-use case is stated, which keeps it short of a 5.

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

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

Annotations already declare this is a non-readonly, non-destructive, non-idempotent creation. The description adds genuinely useful side-effect information beyond them: creating a type does not fire notifications, touch calendars, trigger re-reads, or invoke AI field generation. That is valuable, but the telegraphic phrasing makes it unclear whether these are guarantees or just caveats.

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?

It is short and front-loads the action, which is good, but the second sentence is a slash-and-comma telegraph that reads as internal shorthand rather than agent-facing prose. Compression here costs clarity without saving meaningful length.

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 three parameters, full schema coverage, and annotations present, the definition is workable, but it never says what the call returns (e.g. the created type's identifier) or whether omitted optional fields default. For a creation tool an agent must chain from, that omission matters.

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 name, fields, and description are already documented in the schema, including field config semantics. The description only alludes to 'custom fields' without adding format, defaulting, or validation detail, 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?

The verb 'create' is clear, but the resource is described as 'a workspace type/custom fields' rather than a contract type, so the terminology does not match the tool name and forces the agent to infer that 'workspace type' means contract type. It is distinguishable from clm_update_contract_type and clm_get_contract_type only by the verb, not by any stated scope.

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 second sentence implies this is for new types only by ruling out 'existing-contract notification/calendar changes, re-reads or AI field generation', which hints that update/re-read/generation flows live elsewhere. However, no sibling tool is named, so the routing to clm_update_contract_type, clm_reread_contract_type, or clm_start_type_generation is left to inference.

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

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

Annotations already disclose destructiveHint=true, idempotentHint=true, readOnlyHint=false and openWorldHint=false, and the description adds genuinely new behavior: emails go out to recipients when due, and partial item failures return their reason in results rather than aborting the batch. It stops short of stating required contract permissions, whether reminders can be scheduled in the past, or the 100-item batch ceiling already enforced by the schema.

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, no filler, with the purpose front-loaded before the retry semantics. The second sentence is dense and slightly run-on, but every clause carries distinct operational 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 destructive batch mutation with a deeply nested oneOf schema and no output schema, the description covers the essentials an agent needs: side effects (outbound email), partial-failure reporting, and idempotency key discipline. Missing pieces are access/permission prerequisites and any conflict behavior when a reminder already exists for the same event and recipient.

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 real meaning the schema's terse 'Identical-input retry key' does not: a new key is required for a partial (failed-items-only) resend, and the original key may only be reused for an identical full replay. The 'custom/supported events' phrasing also clarifies the two anchorType branches.

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 concrete verb and resource ('Add notifications to custom/supported events') plus the delivery mechanism ('email recipients when due'), and the custom/supported split maps to the anchorType union in the schema. It does not name its siblings clm_update_event_reminders or clm_delete_event_reminders, so the create-vs-update distinction is left implicit.

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?

Use-as-create is only implied by 'Add notifications'; there is no explicit statement of when to call this rather than clm_update_event_reminders or clm_delete_event_reminders. The retry guidance ('resend only the failed items with a new idempotencyKey') is genuinely useful operational guidance, but it covers re-invocation of this same tool, not tool selection.

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

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

The annotations already disclose that this is a non-read-only, non-destructive, non-idempotent, closed-world operation. The description adds the useful constraint that the parent must be visible. It does not explain permissions, duplicate-name behavior, or what happens when the parent is not visible, so it adds only moderate behavioral context.

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 front-loaded sentence with no redundant wording. It communicates the operation and placement scope efficiently. For a simple two-parameter create tool, this is 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?

Given the simple schema, full parameter description coverage, and annotations covering safety traits, the description is nearly complete for calling the tool correctly. It only lacks peripheral details such as duplicate handling or permissions, which are minor for this operation. No output schema exists, so return-value explanation is not required.

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 name and parentFolderId are already documented in the input schema, including that null means root. The description reinforces the parent/root distinction but adds no syntax, format, or constraint details beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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: "Create a folder." It also clarifies that the folder can be placed at the root or under a visible parent. It does not explicitly differentiate itself from sibling folder operations such as rename_folder or move_folder, so it falls short of 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?

The phrase "at the root or under a visible parent" gives implied placement guidance and a visibility constraint. However, it does not state when to use this tool versus list_folders, get_folder, move_folder, or rename_folder, nor does it mention prerequisites or failure conditions. This is adequate but not explicit usage guidance.

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

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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent, closed-world write. The description adds a genuine cross-field constraint (taxId/registrationNumber are organisation-only, presumably rejected or ignored for individuals) plus the workspace-ownership scope, neither of which is derivable from annotations. It says nothing about duplicate handling or what happens when a conflicting party already exists, which matters for a non-idempotent create.

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, front-loaded with the action and resource; no filler whatsoever. The telegraphic phrase "Tax/registration numbers: organisations only" is clipped to the point of reading like a fragment, which slightly hurts structure but not length.

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 17-parameter, non-idempotent creation tool with no output schema, the description covers the core action and one important constraint but leaves out the relationship between the top-level contact* fields and the party itself, and says nothing about what identifier comes back for subsequent clm_get_party or clm_update_party calls. Adequate given full schema coverage, but thin for a create in a 17-param surface.

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%, and the schema itself already documents taxId and registrationNumber as "org-only", so the description's second sentence largely restates structured data. The "company/person" phrasing does hint that the type enum covers more than two values (individual, company, non-profit, government) while only two are named, which is a small loss of precision rather than added meaning. 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?

"Create a ... party" gives a specific verb plus the resource, and the qualifiers "workspace company/person" pin down that it is a workspace-scoped party record of either an individual or an organisation. Sibling tools (clm_get_party, clm_list_parties, clm_update_party) are implicitly distinguished by the verb, but none are named explicitly.

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?

There is no guidance on when to create versus when to update an existing party, no mention of checking for duplicates via clm_list_parties first, and no stated prerequisites or permissions. The only usage-like constraint is "Tax/registration numbers: organisations only", which is a field rule rather than a when-to-use rule.

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

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

Annotations already establish that this is a non-read-only, non-destructive, non-idempotent, closed-world operation. The description adds nothing beyond that — it does not say a pre-signed/temporary URL is issued, whether an upload session or server-side state is created, whether the URL expires, or what constraints apply to the subsequent PUT. 'Not a contract' is the only behavioral signal and it is about scope, not behavior.

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?

It is a single short sentence with no filler, so it is concise in the literal sense. However, the brevity comes from under-specification: the one clause it does contain ('not a contract') is not the most useful thing to front-load, and the agent learns nothing about the operation being performed.

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 three-required-parameter mutation that hands back an upload URL with no output schema, the description should at minimum state what is returned and how it is used. It omits the return value, the upload step, and any sequencing with clm_start_type_generation, leaving the agent to infer the entire flow from the tool name.

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% with clear field names, byte limits, and a MIME enum, so the schema already fully documents fileName, fileSize, and mimeType. The description contributes no additional parameter meaning (e.g., which extensions pair with which MIME types), which is acceptable at this coverage level but not value-adding.

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 sentence 'Prepare a type-generation example, not a contract' restates the title ('Prepare type generation document') rather than saying what the tool actually produces — an upload URL for a type-generation example file. The only added information is a negative scoping note ('not a contract'), and the tool's name (create_type_generation_upload_url) carries more purpose than the description does.

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?

There is no guidance on when to call this versus clm_create_upload_url, clm_add_contract_documents, or clm_start_type_generation, and no hint about the likely workflow (obtain URL, upload, then start generation). The 'not a contract' phrase gestures at a distinction from contract-upload siblings but gives no actionable condition for choosing this one.

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

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

Annotations already establish that this is a non-read-only, non-destructive, non-idempotent creation operation. The description adds useful behavioral details—one-hour expiry, signed-in scope, no Parser credits, and a fallback on blocked PUT—but remains vague about what the returned link is, session lifetime after creation, and auth requirements beyond 'signed-in.'

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 short and front-loads the core action, but several sentences are cryptic fragments ('No Parser credits', 'Blocked PUT returns to an available panel') that reduce clarity rather than earning their place cleanly.

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 one-parameter creation tool with annotations and no output schema, the description covers the main purpose and some operational constraints. It is still incomplete because it does not explain how this differs from sibling upload-link tools or what the caller receives.

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 one optional parameter and schema description coverage is 100%, so the schema already explains folderId and its behavior. The description adds no additional meaning about that parameter, which is acceptable at the baseline when schema coverage is complete.

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: 'Create a one-hour signed-in batch-upload link.' It is clear what the tool produces, but it does not distinguish this from siblings such as clm_create_upload_url or clm_create_type_generation_upload_url.

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?

There is a partial when-to-use constraint: 'Claude chat: only if panel unavailable/failed and byte transfer cannot work.' However, this guidance is cryptic and does not explain when to choose this tool over the related upload URL tools or clm_import_files.

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

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

Annotations already declare write-but-not-destructive, non-idempotent, closed-world behavior; the description adds permission context ('sandbox PUT needs app-domain permission or no panel') and points at transfer safety and sha256 mismatch rejection. It does not state URL lifetime, whether uploads are single-use, or what happens if the PUT is never performed, and the 'includes an example/safety instructions' clause merely promises content instead of delivering it.

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 definition is a semicolon-separated stream of fragments with no topic sentence, and it spends a sentence advertising a 'single-command upload example and transfer safety instructions' that it never provides. Structure is poor: the most important fact (this returns a URL to PUT the document to) is never front-loaded.

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?

The tool has an output schema, 100% schema coverage, and informative annotations, so a full behavioral account is not required. Still, for an upload-URL generator, the description omits how the URL is used after the call, its expiry, and the handoff path to clm_import_contracts, leaving the workflow ambiguous despite covered parameters.

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% and every property (sha256, fileName, fileSize, mimeType enum) is documented in the schema, so the description carries no additional parameter obligation. It also adds no new meaning about size caps or MIME constraints beyond what the schema already states, making the baseline 3 appropriate.

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 is a fragment list ('User files: after PUT...; external record sync: ...; Claude chat: panel first') that never states plainly that the tool issues a URL for uploading a contract document. An agent must infer the core purpose from the tool name and the mention of PUT, and sibling confusion (clm_create_upload_session, clm_import_files, clm_create_type_generation_upload_url) is only partly resolved by the scenario hints.

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 does give scenario-based routing: user files should default to Import contracts with uploadReference, external systems go to Sync contract, and chat contexts should use the panel first. However, the branches are terse and never name the sibling tools (clm_import_contracts, clm_create_upload_session) explicitly, so the agent has to map the labels to tools itself.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description does add genuine context beyond that: the deletion cascades to linked notifications and halts their emails. It omits that the operation is permanent/irreversible, how partial failures across a batch are handled, and what effect expectedUpdatedAt has on a delete.

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, and the cascade side effect is stated up front. It is efficiently sized, though the one sentence could easily have absorbed a counterpart-tool pointer without bloat.

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, batched (1-100 events) mutation with optimistic locking and an idempotency key, the description covers the cascade but not irreversibility, batch limits, or retry/locking behaviour. Annotations and schema carry part of that load, so it is adequate rather than 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 description coverage is 100%, so the baseline is 3. The description adds nothing per-parameter, and notably does not explain the optimistic-concurrency semantics of expectedUpdatedAt, which the schema itself leaves undocumented despite being required for every event in the batch.

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 plus a cascade effect: delete custom events and their linked notifications. An agent can tell it apart from clm_list_contract_events and clm_update_contract_events, though it never explicitly names the neighbouring clm_delete_event_reminders, which deletes a different object type.

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?

There is no when-to-use or when-not-to-use guidance and no named alternative. The description does not say to prefer clm_delete_event_reminders for reminder objects or clm_update_contract_events to modify rather than remove, leaving the agent to infer routing from the name alone.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description still adds value annotations cannot: that emails associated with the reminders will stop sending, and that the parent events are retained rather than cascaded — a non-obvious side-effect and scope boundary. It does not address reversibility or partial-failure behavior, which keeps it below 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?

A single front-loaded sentence with the destructive action first and the retention caveat second; every clause carries information and nothing is padded. Structure is exactly right for a terse destructive tool.

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 batch operation (1–100 reminders) with no output schema, the definition covers scope but omits what an agent would want before firing: whether deletion is reversible, what happens if some reminderIds fail or expectedUpdatedAt is stale, and whether already-queued emails are cancelled. Minimum viable rather than 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 description coverage is 100%, with documented fields for the reminders array and idempotencyKey, so the schema carries the parameter burden and baseline 3 applies. The description adds no meaning about the reminders payload, the expectedUpdatedAt concurrency token, or the 1–100 item batch limit.

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?

"Remove linked notifications and stop their emails; retain events" gives a specific verb (remove) and resource (linked notifications/reminders), plus the clarifying clause "retain events" which separates it from the sibling clm_delete_contract_events. It stops short of 5 because the term "notifications" never resolves to the schema's "reminders" vocabulary, so the agent must infer they are the same object.

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?

"Retain events" implicitly routes the agent away from clm_delete_contract_events when the events themselves should survive, which is real but indirect guidance. There is no explicit when-to-use statement, no mention of the update/create reminder siblings (clm_update_event_reminders, clm_create_event_reminders), and no prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and closed-world, so safety is fully covered without the description. The description adds only a vague hint that the response includes documents and a filing state, and those state labels are unexplained and unparsable, adding little practical context.

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?

It is short and front-loaded, which is good, but the colon-list ending is a dangling fragment rather than a complete clause, so the brevity comes at the cost of intelligibility. No wasted sentences, but also an under-formed one.

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 get-by-id tool surrounded by many contract read siblings and with no output schema, the description should clarify what the response contains and how it differs from access, analysis and reconciliation reads. It gestures at response contents but leaves the key differentiation and the meaning of the filing states unexplained.

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 (id, uuid) with 100% schema description coverage, so the baseline of 3 applies. The description contributes no additional meaning about the identifier or what happens when it is invalid or unknown.

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 verb+resource ('Get contract') is clear and the sentence names what is returned (details, documents, filing), but the trailing fragment 'unfiled, visible folder or unavailable' is cryptic and never explained. It does nothing to separate this tool from close siblings such as clm_get_contract_access or clm_get_contract_analysis.

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?

There is no when-to-use guidance at all: no statement of prerequisites (an existing contract id), no indication of when to prefer clm_get_contract_access or clm_get_contract_analysis, and no exclusions. The agent must infer usage purely from the name.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false; the description's 'MCP cannot change access' is consistent reinforcement of that safety profile rather than new information. The genuinely additive behavioral note is the warning that access can persist through other groups, which matters when interpreting results, but nothing is said about permissions required, latency, or result size.

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 the returned content, then the ID sourcing, then the caveat. The first sentence is a dense noun pile of ACL jargon but every term maps to a real output field, so nothing is padding.

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 one-parameter read-only tool with no output schema, the description does the important work of naming what comes back (effective permission, ACL principals, exclusions, surviving grants), which compensates for the missing output schema. It falls short only on result shape or volume, which an agent handling a large ACL payload would want.

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 UUID parameter with 100% schema description coverage, so the schema already carries the semantics. The description's only parameter text mirrors the schema wording ('Contract ID from the contract list') and adds no format, sourcing, or validation detail.

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 ('Get ... access ... and ACL principals') and enumerates the returned facets: inherit/override, effective permission, saved levels, follows-role, exclusions, surviving grants. That distinguishes it from the mutation siblings, though it never explicitly contrasts with clm_list_contract_shares or clm_get_contract, so an agent must infer the boundary.

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 supplies an input hint ('Use the contract ID from the contract list') and one caveat about removing a principal while access survives via another group or Everyone, but it never says when to reach for this versus the shares/ACL listing siblings. Usage is implied rather than scoped.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world scope, so the safety profile is covered. The description adds one genuinely new behavioral fact — that calls consume no Parser credits — which is billing context not present in structured fields. It omits what happens when no analysis exists yet, which is the main behavioral risk for this kind of tool.

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 no filler; the payload description is front-loaded and the cost note is short. The wording is slightly under-specified rather than padded, so length is not the problem.

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 one-parameter read tool with no output schema and full annotation coverage, the description is close to sufficient: it names the returned content and the cost behavior. It still leaves the failure/availability path and the distinction from clm_get_contract unexplained, which matters for an AI-derived resource.

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 required parameter with 100% schema description coverage, so the schema carries the burden and baseline 3 applies. The description adds no meaning about the id — e.g. whether it is the contract ID versus an analysis/run ID — leaving that ambiguity unresolved.

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 verb 'Get' plus the resource 'contract AI summary, terms and insights' identifies the payload, which is more specific than a generic contract fetch. However, 'available' is undefined (available when? what if not?), and the description never contrasts itself with the adjacent clm_get_contract or clm_get_contract_reconciliation, so an agent must guess which read call returns which data.

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?

There is no explicit when-to-use guidance and no named alternative. 'No Parser credits' hints that this call is cheap and safe to repeat, but that is a cost note rather than a routing rule, and it does not tell the agent whether this tool triggers AI processing or only retrieves existing results.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the bar is lower. The description's one genuine addition is 'short-lived', which tells the agent the URL expires and shouldn't be cached — useful, but no expiry scale, auth prerequisites, or redirect behavior are disclosed.

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 compact clauses with the core capability front-loaded and no filler. It is slightly telegraphic — 'original/available preview-PDF URL' takes a second read to parse.

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 three-parameter read with strong annotations and no output schema, the description covers the returned artifact (a short-lived URL), the default version, and which versions are reachable. Only prerequisite/auth context is missing, which is minor here.

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 schema already documents id, fileId and the variant enum with defaults. The description echoes the same semantics ('omit for current primary', original vs available preview) without adding format or constraint detail beyond the schema, so it sits at the baseline.

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 verb and resource ('Get a ... download URL') and pins down scope with 'default: current primary' and coverage of prior/draft/related versions. That distinguishes it from siblings like clm_read_contract_document or clm_search_contract_documents, though it never names an alternative explicitly.

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 implies when to use it via the default behavior (omit fileId for current primary; pass a version for prior/draft/related), which is real selection guidance. It gives no explicit when-not-to-use or routing to a sibling tool such as clm_read_contract_document for in-band content.

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

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

Beyond the destructive and non-idempotent annotations, it discloses that this get persists reviews and refreshes comparison values and the approval version, while leaving finding decisions to humans. It does not explain exactly what the refresh overwrites or what makes the operation destructive, so the concrete impact remains somewhat opaque.

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?

It front-loads the result, then covers side effects and the safety boundary in two compact sentences with no filler. The slash-heavy terminology and subjectless “persist reviews, refresh...” wording are dense enough to require careful parsing.

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 reconciliation operation with unexpected writes, it covers the required run state, returned differences, persistence behavior, and approval guardrail. With no output schema, additional detail about the returned finding/review structure, precise refresh consequences, and run-ID discovery would make it more 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?

Both parameters already have schema descriptions and UUID formats, so the baseline is 3. “Completed” adds an implicit run-state constraint, but the description does not clarify that the generic `id` is the contract ID or provide guidance for obtaining either ID.

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?

It identifies the resource and result—differences between a completed re-read and saved fields—and separately states the review-persistence and comparison-refresh behavior. The prohibition on applying, settling, or dismissing findings also distinguishes it from clm_apply_contract_reconciliation.

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?

“Completed” scopes use to a finished re-read, while “Never apply/settle/dismiss findings” establishes an explicit when-not boundary. Requiring person approval in Contracko supplies a concrete alternative for those decisions, making the review-versus-decision boundary clear.

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

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

The annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=true, so the safety profile is partly covered. The description adds useful context with 'No Parser credits' and the queue-handoff note, but 'settle unconfirmed saved-run queue handoff' is opaque and does not clarify what gets changed or destroyed despite the destructive annotation.

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 short and front-loads the progress-check concept, but the second clause is dense jargon and the billing note is unexplained. It is concise in length, yet the fragmented phrasing makes the operational intent harder to parse.

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?

This is a destructive, non-read-only operation with no output schema and a cryptic description. An agent needs more context about what 'settle' means, what state is altered, and what the result indicates, especially given destructiveHint=true.

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 both required parameters (id and runId) are documented in the schema. The description adds no additional meaning about how those IDs are used or any constraints on them, 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?

The description names actions ('check re-read progress' and 'settle... queue handoff'), but it never identifies the resource as a contract reprocess run or explains what that run represents. An agent must infer the scope from the tool name rather than the description, and it is not clearly distinguished from related tools such as clm_reprocess_contract_document or clm_get_contract_type_reread.

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?

There is no explicit guidance on when to call this tool versus the many sibling contract tools. It implies a progress-check use case, but does not say when the 'settle' behavior is needed, when it should be avoided, or what alternatives exist.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without the description. The description's only behavioral contribution is naming two data categories in the response, which is thin and says nothing about missing-id behavior, authorization, or freshness of the returned state.

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 short sentence with no filler, front-loaded on the verb. It loses a point because the compressed phrasing creates ambiguity rather than resolving it — a slightly longer, clearer clause would have cost nothing.

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 single-parameter read with full annotation coverage and no output schema, the description is minimally adequate. It is incomplete on what the returned object contains and how it differs from sibling read tools, which is what an agent most needs here.

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 with 100% schema description coverage, so the schema fully documents the uuid `id` field. The description adds no meaning beyond it — it never says the id refers to a contract type definition rather than a contract instance, which would be genuinely useful disambiguation. 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 and resource (get a contract type) and hints at the payload contents (review state, custom fields). The trailing phrase is grammatically ambiguous — it could read as three actions rather than one retrieval returning three things — and it never differentiates itself from close siblings like clm_list_contract_types or clm_get_contract_type_reread.

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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives. An agent cannot tell from this sentence why it would call this instead of clm_list_contract_types (to discover an id) or clm_get_contract_type_reread (to refresh a stale one).

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is known; the description usefully explains where that destruction lands (stopping stuck batches) and adds the retry path. It still omits what stopping a batch terminates, whether retry is safe to repeat, and what the "check" mode returns, which is significant for an idempotent-but-destructive tool.

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 semicolon-delimited sentence with zero filler, and the monitoring purpose is front-loaded before the remediation options. It is efficient, though the compression leaves the retry/stop distinction underspecified.

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 broad intent but leaves return content unexplained (counts of what, in what shape) and gives no guidance on the consequences of the destructive path. Adequate as a pointer, thin for an agent that must decide whether it is safe to call.

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 nominally 100%, but both schema descriptions are tautologies ("ID", "Batch ID") that add no meaning, so the description must compensate and does not. Critically, nothing explains how the two required parameters relate to the two advertised modes, or which parameter selects retry versus stop.

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 (batch runs for re-reads) and two concrete actions (retry lost reads, stop stuck batches), but it muddles the verb: the tool name and title say "get", while the text describes remediation actions. An agent can guess this is batch monitoring plus remediation, but cannot tell whether the call actually mutates anything without reading the annotations.

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?

"Retry lost reads or stop stuck batches" does imply the triggering conditions (lost reads, stuck batches), which is more than most sibling tools offer. However, it never mentions the closely related siblings such as clm_reread_contract_type or clm_get_contract_reprocess_run, and does not say when to check status versus when to act.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description still adds genuine value beyond them: results are limited to visible folders, inaccessible folders are omitted from the response, and member details are 'bounded' (i.e., truncated), which tells the agent to expect partial data.

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 dense sentence with no filler. The access/omission constraint is placed at the end as a qualifier, and every clause maps to a real return-set or behavior detail.

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 it does enumerate field groups (path, visibility, limited access, permission, members). However the 'bounded' member detail is undefined, and nothing explains shape, ordering, or failure behavior for an inaccessible or missing folder ID.

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 only one required parameter (id, uuid) and schema description coverage is 100%, so the schema is fully self-documenting. The description adds no extra meaning about the identifier or expected format, which matches the baseline for a fully-covered single-parameter 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 sentence names a resource implied by 'folder path' and lists what comes back (path, visibility, limited access, permission, member details), but it never plainly states 'retrieves a single folder by its ID'. It also fails to distinguish itself from siblings like clm_list_folders or clm_rename_folder, so an agent must infer the scope from the name.

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?

There is no guidance on when to call this versus clm_list_folders (list many) or the folder mutation siblings. The only implicit cue is 'omit inaccessible folders', which describes output filtering rather than tool selection.

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

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

Annotations already establish readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds genuinely new behavior: no Parser credits are consumed, the default is a non-blocking snapshot, and wait:true caps at 25s and reports progress plus elapsed time. Undisclosed is what an agent sees when the job ID is unknown or the import failed outright beyond the mention of 'failures'.

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 and information-dense, with cost, timing, and ID selection all stated in clause fragments. The telegraphic style ('No Parser credits. Default: snapshot') and the opaque final clause 'Related classification is not attachment' cost clarity, since that sentence's meaning is not recoverable without outside context.

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 must partially explain returns, and it does: progress, elapsed time, failures, and fields. It also covers the timing contract, credit cost, and the no-job duplicate case. The remaining gap is failure-mode behavior (invalid ID, expired session), which a polling tool of this kind would ideally mention.

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 every parameter is already documented, making 3 the baseline. The description does add real semantics on top: the three IDs are alternatives (send exactly one), importId is a legacy alias of jobId, and uploadSessionId comes from the upload-link flow rather than the import flow. That mutual-exclusivity detail is the only thing the schema does not already say.

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?

Opens with a specific verb and resource: 'Get import/sync progress, failures and fields', which tells an agent exactly what comes back. It distinguishes this poll-style status tool from siblings like clm_get_type_generation or report_get_generation_status only implicitly through the 'import/upload-link' framing, and the closing sentence 'Related classification is not attachment' is too terse to read as real differentiation.

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 concrete calling conditions: poll for a snapshot by default, or set wait:true to block up to 25s. It also instructs which identifier to pass ('Send one ID from the import/upload-link result') and flags the edge case that 'a refused duplicate created no job', so there is nothing to poll. It stops short of naming the sibling calls that produce those IDs (clm_import_contracts, clm_create_upload_session), leaving that link to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is fully carried by structured data. The description adds only the hint that contact/address fields are returned; it says nothing about behavior when the party ID does not exist or whether missing records error or return empty.

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 fragment with zero filler or repetition. It is efficient, though its brevity edges into under-specification captured by the other dimensions.

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 one-parameter read tool whose annotations cover the safety profile and whose schema covers the input, the description is minimally sufficient. It leaves gaps on which fields are actually returned and on not-found behavior, which matter because there is no 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?

Single parameter with 100% schema coverage, so the schema already documents the required 'id' field and the baseline is 3. The description adds no clarification that this ID is a party UUID (only the tool name implies it) and nothing about format or source of the identifier.

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 a specific verb and resource ('Get party') and adds that the payload covers contact/address details, so the agent knows this is a single-record read rather than a list. It does not distinguish itself from the obvious sibling clm_list_parties, leaving sibling differentiation to the name 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?

There is no when-to-use guidance and no mention of the alternative clm_list_parties for enumeration and clm_update_party for mutation. The agent must infer from the name that this is the single-record lookup as opposed to the list endpoint.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety behavior is covered. The description adds that the run is a background/async job bound to the calling user, which is useful beyond the annotations, but it says nothing about what statuses can be returned, whether results expire, or whether a still-running run returns partial data.

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 short sentence, front-loaded with the action and resource, with no filler. It is arguably under-sized for a tool whose result semantics are undocumented, but there is no wasted wording.

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?

The tool is simple (one required param, no output schema) and its annotations cover the safety profile, so little is required. However, with no output schema the description should at least indicate what the check returns (e.g., a status/state value) so the agent knows how to interpret and act on the response.

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 runId parameter is already documented as "Run ID returned on start". The description contributes only the ownership constraint that the run must belong to this user, which is a small addition over what the schema already conveys.

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?

"Check a background type-generation run" names a specific verb and resource, and the tool is clearly the status counterpart to clm_start_type_generation. It does not, however, distinguish itself from the very similar sibling clm_get_type_generation_draft, which an agent could easily confuse for a status lookup.

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 phrase "started by this user" implies the tool is called after clm_start_type_generation returns a run ID, but no explicit when-to-use guidance is given. Nothing says how often to poll, whether to poll until completion, or when to prefer clm_get_type_generation_draft instead.

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

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

Annotations already establish readOnly, idempotent, non-destructive, closed-world behavior. The description adds that evidence is not editable and that this read creates nothing, plus notes reviewed-state behavior on save, which goes beyond the annotations though the wording is slightly ambiguous.

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 definition is short and front-loads the returned artifacts. The final sentence is a bit cryptic, but there is little wasted wording.

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 one-parameter read tool with rich annotations but no output schema, the description lists key return values and the immutability constraint. It would be stronger if it explicitly contrasted with nearby type-generation status/get siblings.

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 only one parameter, runId, and the schema already documents it at 100% coverage. The description adds no additional syntax or format guidance beyond the schema baseline.

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 read operation and enumerates the result payload: created type ID, read-only examples, source quotes, or an existing-type verdict. It does not explicitly distinguish this from the sibling clm_get_type_generation, so it misses full sibling differentiation.

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 implies the tool is used to look up current generated definitions and evidence, and warns that this read creates nothing, helping separate it from save/create flows. It does not state when to prefer it over clm_get_type_generation or other type-retrieval siblings.

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

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

Adds substantive behavior beyond annotations: default term extraction, no Parser credit consumption, a processing handle for status/progress/extracted summaries, and the rule that related classification does not attach documents. It does not detail permission requirements or duplicate-handling consequences, but annotations already cover idempotency and non-destructiveness.

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 content is compact but poorly structured as a single dense paragraph mixing client-specific instructions, limits, alternatives, and return behavior. Some points ('One contract per document' and 'Related classification does not attach documents') overlap, reducing front-loading and scanability.

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?

Covers the key operational context for an import mutation: source types, client-specific delivery, file-size constraints, the alternative for related documents, and the returned processing handle because no output schema exists. It could be stronger on error/retry semantics, but the combination of schema and description is nearly 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 100%, so all four parameters are documented in the schema, including the three file kinds, folderId, allowDuplicate, and idempotencyKey. The description reinforces file limits and preferred upload paths but adds little new meaning beyond the schema, making 3 the appropriate baseline.

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 the action (adding files) and outcome (purpose-built term extraction, one contract per document), and explicitly routes related-document imports to clm_add_contract_documents. However, the core object 'contract' is implied rather than stated in the opening sentence, so it is clear but not maximally crisp.

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 explicit alternatives (use Add contract documents for related documents), client-specific pathways (ChatGPT attachments, Claude chat panel, prepared uploads/base64/HTTPS for other clients), and notes that no Parser credits are consumed. This is actionable routing guidance rather than general context.

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

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

Annotations already declare non-read-only, idempotent, non-destructive, open-world behavior, and the description adds genuinely new context: URLs are short-lived, one contract is created per document, credit consumption, trial caps, and accepted formats with a 50 MiB ceiling. It omits what happens after the call (whether processing is asynchronous and where the resulting import is surfaced), which is the main behavioral 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?

It is short and front-loads the core action before the sibling routing and constraints. The telegraphic fragments ('No Parser credits. Subscribe to lift trial caps.') are efficient but slightly clipped, costing a little clarity for the economics context.

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, open-world import with no output schema, the description covers inputs, limits, credits, and the sibling alternative. It is missing any pointer to clm_get_import_status for tracking the resulting import, which is the one thing an agent would need after invoking it.

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 constraints the schema does not express: the allowed document types (PDF, Word .docx, text, RTF) and the per-file size limit, which govern what may be supplied in the files array. The folderId and allowDuplicate semantics are left entirely 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?

The description states a specific verb and resource ('Import chat attachments from short-lived URLs') and immediately scopes it ('One contract per document'), then names the sibling it is not ('To attach related documents, use Add contract documents'). An agent can distinguish it from clm_add_contract_documents and clm_import_contracts 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?

It gives an explicit routing rule to the alternative tool for related documents, plus eligibility context (no Parser credits, trial caps lifted by subscription). It does not state when this tool should NOT be used, nor any prerequisite about obtaining the short-lived URLs first, so it stops short of full when/when-not coverage.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false, and readOnlyHint=false, so the description need not restate safety. It does add genuinely new behavior: AI extraction runs regardless of supplied fields, consumption counts against trial caps, no Parser credits are used, retries with identical input and source ids resolve to the same contract, and the call returns processing.jobId. It stops short of describing async timing, failure modes, or what happens on a conflicting existing link, which keeps it below 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?

Seven short sentences, front-loaded with the routing decision before the cost and return-value details, and each sentence carries a distinct fact. The phrasing is telegraphic in places ("No Parser credits.") but nothing is redundant padding.

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 mutation tool with a large nested contract schema and no output schema, the description covers the missing pieces an agent most needs: idempotency semantics, quota/cost impact, the alternative tools, and the return value (processing.jobId) that feeds status polling. It does not explain how ingestion interacts with an already-linked record or what the job status lifecycle looks like, which is the remaining gap.

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 the schema already carries the per-parameter semantics (externalId, externalSystem, folderId, metadata, allowDuplicate, files, contract). The description reinforces the 'real source ids, never invent' constraint but adds nothing about allowDuplicate, folderId, or metadata usage beyond what the schema documents, 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 names a specific operation (ingest a contract record) and constrains it to existing records from another system with real source ids, which separates it from uploading brand-new documents. The only weakness is that the alternatives are referred to by human-facing titles ("Import contracts", "Add contract documents") rather than the exact sibling tool names, so an agent must map them itself.

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 explicit routing rules: use Import contracts for new documents/attachments, use this tool only for existing records with real source ids, and use Add contract documents for related files. Both a positive condition and two alternatives with their selecting conditions are stated, leaving nothing to inference.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds one genuine behavioral fact beyond the annotations: results are filtered to what the acting member can access. It says nothing about ordering, pagination, or empty-result behavior, which keeps it at an adequate-but-thin level.

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 resource and the access constraint front-loaded and no filler. It is efficient, though its brevity leaves the noted gaps rather than being padded.

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 one-parameter read-only listing tool with full annotation coverage and no output schema, the description covers who-can-see-what, which is the main non-obvious behavior. It still omits result shape hints such as ordering or pagination, which an agent may want when the list is long, so it is complete enough to call but not fully informative.

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% for the single required parameter, so the baseline is 3. However, the schema's own description is only 'ID', and the tool description only indirectly implies it is a contract identifier via 'on a contract'; it adds no format, validity, or error semantics beyond the structured field.

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 ('List comments on a contract') and adds an access scope ('the acting member can access'), which distinguishes it from clm_add_contract_comment by direction of operation. It does not explicitly name siblings, but the list-vs-add distinction is unambiguous from the verb.

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?

There is no explicit when-to-use or when-not-to-use guidance and no named alternative tool. The phrase 'the acting member can access' implies a permission precondition, but an agent gets no instruction about when listing comments is the right call versus fetching the contract or reading documents.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds the useful content scope (dated events plus linked notifications) but says nothing about ordering, pagination, or volume of results.

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 tightly written sentence with no filler, and the resource scope is front-loaded after the verb. Nothing is redundant, though there is no structural elaboration to earn a top mark.

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 single-parameter, read-only, closed-world list tool with rich annotations and no output schema, the definition supplies enough to call it correctly. Only minor gaps remain around result ordering and pagination.

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% and the single parameter already documents itself as a UUID sourced from clm_list_contracts or clm_get_contract. The description only restates that identification is by contract ID, adding no format or scoping detail beyond the schema, 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 (List) and resource (dated events and linked notifications of one contract), which clearly separates it from the create/update/delete contract-event siblings. It never names a sibling explicitly, but the read-only list framing 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: an agent can infer it should call this to see a contract's events, but the description gives no explicit conditions, prerequisites, or alternatives (e.g. when to use this vs. clm_get_contract). The pointer to clm_list_contracts/clm_get_contract for the ID lives in the schema, not the description.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral detail beyond that: the listing includes completed-but-unopened reviews, which tells the agent results are not limited to pending work. It says nothing about ordering, pagination, or how many results come back.

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 short sentence with no padding, and the most distinctive detail (including unopened completed reviews) is placed up front. Nothing is wasted, though there is also very little to structure.

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 one-parameter read-only list tool with no output schema and strong annotations, the description is thin but not fatal. The remaining gap an agent actually needs filled is what the required 'id' scopes and whether results are bounded, neither of which is addressed.

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 nominally 100%, but the sole parameter's description is just 'ID', which resolves nothing. The description does not clarify whether that id is the contract ID, a reconciliation ID, or something else, so it fails to compensate for a technically covered but semantically empty schema field.

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 verb (list) and a resource ('contract re-reads'), but renames the resource relative to the tool name 'reconciliations' without explaining the relationship, so an agent has to infer that a 'reconciliation' is a contract re-read. It also never states that listing is scoped to a specific contract, which is the key ambiguity given the single 'id' parameter.

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 versus the closely named sibling clm_get_contract_reconciliation, nor versus clm_list_contracts or clm_get_contract_type_reread. The only implicit hint is the phrase 'completed but unopened reviews,' which suggests a review-queue use case but is not stated as a when-to-use condition.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds two non-annotation facts: filters combine conjunctively, and reads remain available after trial lapse — useful operational context — but says nothing about pagination behaviour or result ordering despite cursor/limit parameters.

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 the resource, and no filler. The phrase "and filing" is vague enough to be near-waste, but overall the definition is compact and readable.

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 12-parameter, zero-required list tool with no output schema, the description covers the resource and filter conjunction but not what a no-filter call returns, how paging interacts with cursor, or which fields the listed contracts expose. It is minimally sufficient to invoke correctly, not enough to invoke confidently.

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 every one of the 12 parameters is already documented in the schema and the baseline 3 applies. The one piece of added meaning is "All filters must match" (conjunctive AND semantics across query, status, date ranges, folderId, counterpartyId), which the per-parameter descriptions do not state — a small genuine increment, but no guidance on defaults or no-filter behaviour.

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?

"Find workspace contracts" names the resource, but the verb is loose (find vs. list vs. search) and the trailing "and filing" is ambiguous — it never clarifies whether folding/folder filing is a filter or a returned attribute. Nothing distinguishes it from clm_get_contract (single record) or clm_search_contract_documents (document text search) for an agent choosing among ~50 siblings.

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?

There is no when-to-use or when-not-to-use guidance and no named alternative. "All filters must match" tells how filters combine, not when this tool rather than clm_get_contract or clm_search_contract_documents should be selected, leaving the routing decision entirely to the agent.

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

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

Annotations already declare readOnly=true, idempotent=true, destructive=false, so the safety profile is covered. Beyond that, the description adds real value: results are filtered to active links only, non-managers will not get usable URLs (a permission-dependent response shape), and the returned links are bearer secrets requiring careful handling. Only the return payload structure is left unstated.

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, each carrying distinct information: what is listed and with what scope, who gets usable URLs, and how to handle the output. The scoping clause is front-loaded and there is no redundant restatement of 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 single-parameter read tool with no output schema, the description covers scope, permissions, and output sensitivity, which is most of what an agent needs. It stops short of describing the returned fields (link, expiry, access options) as a shape, which would have made it self-sufficient.

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 'id' is documented as 'Contract ID' with a uuid format, so the schema does the work. The description adds nothing about which contract to pass or what happens for a contract with no shares, which is acceptable at baseline 3 but no better.

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+resource ('List active external links') plus the scope qualifier 'active', which implicitly separates it from clm_create_contract_share and clm_revoke_contract_share. It does not name those siblings outright, so an agent must infer that create/revoke are the mutating counterparts.

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?

There is no explicit when-to-use or when-not-to-use guidance, and no named alternative among the many clm_* share/access siblings (clm_get_contract_access, clm_revoke_contract_share). The manager-permission note is a behavioral fact rather than a usage selection rule, so the intended trigger for calling this tool is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds a small amount of behavioral value by indicating that each type carries review state and custom-field data, which matters for downstream field mapping, but it says nothing about result size, ordering, or whether the full workspace type set is always returned.

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 compact sentence with the resource front-loaded and zero filler. Nothing could be removed without losing 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 zero-parameter read-only listing tool with full annotation coverage, the definition is nearly sufficient: it names the resource and the notable fields returned. With no output schema present, a brief note on the shape of the returned list would have closed the remaining gap.

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 no parameters, so the baseline is 4. The description correctly implies an unfiltered workspace-wide listing, which is consistent with the empty 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 gives a clear verb plus resource ("List workspace contract types") and hints at the payload contents (review state, custom fields). It is distinguishable from the singular sibling clm_get_contract_type, but it never names that sibling or explicitly contrasts the two, and the trailing phrase "review state and custom fields" is slightly ambiguous about whether those are returned per type or listed separately.

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?

There is no guidance on when to choose this tool over clm_get_contract_type, clm_create_contract_type, or clm_search_tools; the agent must infer that this is the discovery/listing call. Usage is only implied by the verb "List".

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

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

Annotations already cover read-only, idempotent, non-destructive, closed-world behavior, so the description's job is to add filtering semantics — and it does: inaccessible folders, their ancestors, and member lists are omitted from results. That's real context an agent could not derive from the annotations. It stops short of describing ordering or page-cursor behavior.

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. The middle clause ('Everyone/restricted visibility and limited access') is dense enough to be slightly ambiguous, which keeps it from a 5.

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-only list tool with full annotation coverage and a fully documented schema, most of what an agent needs is present. Gaps remain around result ordering, how the continuation cursor behaves in practice, and what fields each returned folder carries (no output schema exists).

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 limit, continuation, and parentFolderId are already fully explained in the schema; the description's 'visible root' merely echoes the parentFolderId description. Baseline 3 applies since the schema does the heavy lifting.

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+resource ('List visible folders') plus the visibility scope that governs results. It doesn't explicitly contrast with clm_get_folder or clm_create_folder, but list-vs-get is unambiguous from the names, so only the sibling differentiation is missing.

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 description conveys that this enumerates visible folders and that inaccessible ones are dropped, and the schema's parentFolderId implies root-vs-children browsing. There is no explicit 'use this when...' or named alternative such as clm_get_folder for a single known folder.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false and destructiveHint=false, so safety and side-effect behavior are covered structurally. The description's only added behavioral fact is that results are workspace-scoped, which is useful but thin; nothing is said about result ordering, pagination, or result limits. No annotation contradiction.

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 short sentence with no filler, and the resource and scope are front-loaded. It is efficient, though its brevity comes at the cost of the missing usage and return-shape context rather than being a model of tight structure.

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-optional-parameter read tool with no output schema and rich read-only annotations, the description is close to adequate but leaves one material gap: whether it returns all workspace parties or only those tied to contracts, which is exactly what determines the choice against clm_get_party and the create/update siblings. Pagination behavior is also unaddressed.

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%, with both 'type' and 'query' fully documented including the enum and the case-insensitive substring matching rule, so the baseline of 3 applies. The description adds essentially nothing beyond the schema, and the phrase 'company/person' is less precise than the enum's four values.

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 (List) and resource (contract parties) with the scope qualifier 'workspace', so an agent can tell it is the collection read rather than the single-record clm_get_party or the write-side clm_create_party. The 'company/person' fragment hints at party kinds but is never reconciled with the 'type' enum, so the resource is clear while the scope of what is returned stays slightly fuzzy.

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?

There is no when-to-use guidance, no statement of when to prefer this over clm_get_party, and no note that it is workspace-wide rather than scoped to a specific contract. The agent must infer the choice entirely from the tool name.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, and the description goes beyond them by naming the actual side effects: inherited access may be lost, scheduled emails may be reassigned to the contract owner, and restoring the move requires both edit rights and access to the current folder. It also pre-empts a misread of the destructive flag by clarifying the contract itself is never deleted. Minor gap: no mention of response or failure behavior when the destination folder is inaccessible.

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 with the core action and the null case front-loaded, then consequences. The semicolon-compressed phrasing ('return needs contract/destination edit and current-folder access') is dense and slightly telegraphic, costing some readability, but nothing is redundant.

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 mutation with no output schema, the description covers the essential risk surface: access loss, scheduled-email reassignment, and the conditions required to reverse the move. What remains unstated — pagination or return payload, and behavior on invalid or inaccessible destination folders — is modest for a tool of this complexity.

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 schema already documents folderId as 'null: root', so the description's parenthetical restates existing structured information. The one piece of added meaning is the 'visible folder' qualifier, implying the target must be one the caller can see, which is genuinely new but brief.

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 pair ('File in a visible folder or unfile (folderId:null), never delete'), which clearly delimits the operation as a folder-assignment move rather than a deletion or metadata edit. It does not name any sibling tool explicitly, so an agent must still infer the boundary against clm_update_contract or clm_move_folder from tool names 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?

It gives concrete conditions for the unfiling case ('folderId:null') and warns about return requirements, but never states when to prefer this tool over clm_update_contract or how it differs from clm_move_folder. Usage is implied by the described mechanics rather than by explicit routing guidance.

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

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

With destructiveHint=true and idempotentHint=false already declared, the description still adds real value: inherited folder/content access may be lost, moving to root disables limited access, a return to the original state requires current permissions and is not restored automatically, and lost access can reassign scheduled emails to the contract owner. That is substantive consequence disclosure beyond the annotations.

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?

Dense and front-loaded with the operation and its validation rules before the side effects. A few clauses are telegraphic to the point of ambiguity, notably 'return needs current permissions and does not restore it', which costs some clarity.

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 destructive move with no output schema, it covers rejection conditions, access-loss consequences, and the root special case. What is missing is only the direct comparison to sibling move/rename tools and any explicit statement about the response.

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 parentFolderId already documents null=root, but the description adds meaning the schema lacks: the destination must be a visible/authorized parent, and moving to root specifically disables limited access. That constrains how parentFolderId may legitimately be set.

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 (Move) and implies the resource via 'visible parent/root' and 'folder/content access', matching the title and id. It is clear what happens, though it never explicitly names the folder resource or distinguishes itself from the sibling clm_move_contract.

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 preconditions rather than selection guidance: destinations must be visible, and cycles or unauthorized destinations are rejected. There is no explicit when-to-use versus clm_move_contract or clm_rename_folder, so routing guidance is implied rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds genuine context beyond that: results are access-scoped ('accessible'), text comes back in cited sections, and the cursor continues the remaining text. It does not say what happens on an invalid or expired cursor, or whether text is truncated per section.

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 compact sentence with no filler, and the pagination behavior is placed last where an agent will look for it after learning the core purpose. It is slightly telegraphic – 'cited sections' is unexplained – but nothing is wasted.

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 four-parameter read tool with no output schema, the description covers the core purpose and the pagination loop, which is the main thing an agent must get right. Gaps remain around the two competing ID parameters and the shape of 'cited sections' in the response, which the absent output schema leaves undocumented.

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 the baseline is 3. The description earns its keep by explaining cursor semantics ('continues remaining text'), but it does not clarify the potentially confusing distinction between 'id' (required) and 'documentId' (effective primary or related document), nor what 'limit' bounds in practice.

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 verb and resource (read document text) and scopes it to 'accessible' documents returned in 'cited sections'. That is clear enough to distinguish it from a download-URL tool, though it never names the closest sibling (clm_get_contract_document_download_url) or the search tool explicitly.

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?

There is no when-to-use or when-not-to-use guidance, and no alternative is named despite several siblings that could plausibly be confused with it (download URL, search documents, get contract). The word 'accessible' implies an access precondition but does not state how to check or satisfy it.

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

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

The annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the risk profile is documented structurally. The phrase "the user can manage" adds a genuine permission precondition beyond the annotations, but the description does not explain why rename is flagged destructive (e.g., broken links) or what happens on name collisions.

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 zero filler, correctly placing the operation first. It is arguably under-specified rather than verbose, which costs nothing structurally but leaves value on the table.

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 rich annotations and no output schema, this is close to minimally sufficient: the agent knows the operation and the permission gate. Missing are notes on name collisions, idempotency implications, and whether folder paths or child references are affected.

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%, though the schema's own descriptions are thin placeholders ("ID", "Name"). The description adds no meaning about the id format, name constraints, or uniqueness behavior, so it neither compensates nor detracts; baseline 3 applies when the schema carries the burden.

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 uses a specific verb and resource ("Rename a folder"), which clearly separates it from siblings like clm_move_folder, clm_get_folder, and clm_list_folders by name. It does not explicitly contrast with those siblings, but the CRUD-style operation 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?

There is no guidance on when to use this tool versus clm_move_folder (which relocates a folder) or how to obtain a folder id first. The only contextual cue is the implicit precondition that the user must be able to manage the folder; no exclusions or alternatives are named.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description reinforces this by specifying exactly what gets replaced: the saved extraction snapshot and status. It adds non-obvious operational context about credits, trial caps, and that proposals require human approval in Contracko. It stops short of saying whether the prior snapshot is retained or recoverable.

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?

Four short clauses, front-loaded with the core action and effect, with no filler. Some phrasing ("Contracko", "CLM trial caps") is terse to the point of being cryptic, but nothing is 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 destructive mutation with no output schema, the description covers the effect, the cost model, the quota constraint, and the downstream approval flow. It omits whether a reprocess run identifier is produced (relevant given the clm_get_contract_reprocess_run sibling), which is a minor gap.

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 id, fileVersionId, idempotencyKey, readMode, and customFieldKeys are already documented. The description adds no parameter-level meaning, 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?

"Re-read a document via external AI; replace saved extraction snapshot/status" gives a specific verb, resource, and resulting effect. The replacement clause implicitly distinguishes it from the read-only clm_read_contract_document, but no sibling is named outright.

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 implied by "re-read" and cost context ("No Parser credits", trial caps), and the description states what the tool does not do (field proposals are not applied). However, it never explicitly says when to pick this over clm_read_contract_document or clm_get_contract_reprocess_run.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=true, and openWorldHint=false. The description adds useful context beyond those annotations: one extraction per contract, saved fields remain unchanged, and human approval is required. It still leaves unclear how the destructive hint relates to 'saved fields unchanged' and what exactly happens during re-read.

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 compact, front-loaded, and free of filler. Each clause adds relevant scope or behavior without repeating the schema or annotations unnecessarily.

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?

The definition is complete enough to understand the general operation, and annotations plus schema cover much of the structured context. However, for a destructive, approval-gated operation, it does not explain the approval workflow, what the re-read returns, or how it differs from closely related siblings.

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 the input schema already documents id, idempotencyKey, and customFieldKeys. The description does not add meaning beyond the schema for these parameters, especially the ambiguous required 'id' field, so the baseline score of 3 is appropriate.

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: re-read custom fields for contracts of a type with primary documents. It is fairly clear what the operation does, but it does not distinguish this tool from the similarly named sibling clm_get_contract_type_reread or clarify whether the required id is a contract type ID or a contract ID.

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 gives no when-to-use guidance, no exclusions, and no alternative tool suggestions. Phrases like 'human approval required' describe behavior but do not tell an agent when this tool should be selected over clm_get_contract_type_reread, clm_reprocess_contract_document, or other reread/reprocess siblings.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, yet the description still adds genuinely new behavior: an authorization requirement, the explicit user-approval gate, and the crucial caveat that already-downloaded copies persist with recipients. The retry guidance directly addresses the non-idempotent hazard that the annotation only encodes numerically.

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?

Four short sentences, each carrying a distinct operator-relevant fact: action, approval gate, access requirement, residual risk, and retry protocol. The action and its precondition are front-loaded with zero 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 destructive, non-idempotent mutation with three fully documented parameters and rich annotations, the description covers authorization, approval, irreversibility limits, and error recovery. The only gap is that with no output schema present, it says nothing about what a successful revocation returns or how to verify it.

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% and all three parameters (id, shareId, approved) are documented with formats and constraints, so the schema carries the load. The description reinforces the meaning of `approved` by making approval a procedural precondition, but adds no syntax or identifier detail 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 opens with a specific verb and resource ("Revoke an external link"), which unambiguously separates it from the sibling creation tool clm_create_contract_share. It implicitly points at clm_list_contract_shares via "list active links," but never names a sibling tool outright, so it falls just short of full differentiation.

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 the gating condition ("after explicit user approval") and the prerequisite ("Requires contract manage access"), plus a recovery path when outcome is unknown. It does not say when to prefer this versus re-issuing a share or how to confirm success, so context is clear but not exhaustive.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description nevertheless adds a genuinely valuable disclosure not present in structured fields: semantic/hybrid queries send content to an external embedding provider, which is a data-egress consideration an agent should factor in before choosing a mode.

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 core action and followed by the external-provider disclosure. Slightly dense phrasing ("cited exact/semantic/hybrid matches") costs a little readability but nothing is wasted.

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 7 parameters, an enum, and no output schema, the definition covers the essential action and one important behavioral caveat. It leaves unexplained what "cited" matches mean in the result, how the cursor paginates, and what includeRelated actually pulls in, all of which the schema only partially clarifies.

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 all seven parameters are already documented in the schema, making 3 the baseline. The description reinforces the meaning of the mode values but adds no syntax, cursor lifecycle, or contractId/documentId relationship detail 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?

States a specific verb ("Search") and resource ("accessible text" within contract documents), and enumerates the three match modes. It distinguishes itself reasonably from read-oriented siblings like clm_read_contract_document by being a query tool, though it never names an alternative explicitly.

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?

There is no explicit when-to-use guidance, no when-not conditions, and no named alternatives among the many siblings (e.g. clm_read_contract_document, clm_search_tools). The mode names hint at query intent, but the agent must infer when a search is preferable to reading a document directly.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds useful cost context about Parser credits, which annotations cannot express, but says nothing about result format, ranking, or result limits — notable for a discovery tool.

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?

It is a single short sentence, so nothing is bloated, but the credit-policy clause leads without context and reads as a non sequitur for an agent that has not yet seen the tool list. The core purpose is dispatched in four words while the remainder is spent on billing minutiae.

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 no annotations describing returns, the description is the only source for what this tool produces, and it omits that entirely. For a discovery tool whose whole value is the returned catalog, this is a substantial gap that leaves the agent guessing how to consume 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 description coverage is 100% and both parameters (query, toolset with its enum) are documented in the schema, so the baseline of 3 applies. The description adds no syntax hints for query phrasing or guidance on which toolset value maps to which task family.

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?

"Find tools/workflows" states a specific verb and resource, and the title reinforces it as task-based tool discovery. No sibling tool performs discovery, so no differentiation is needed, though the description never explains what a result looks like (tool names, descriptions, workflows).

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?

There is no explicit statement of when to call this versus invoking a sibling tool directly, nor whether it should be used before multi-step CLM operations. The credit note ("CLM contracts use no Parser credits; separate Parser bulk processing uses Parser credits") implies a routing consideration for the toolset choice but leaves the actual selection rule implicit.

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

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

Annotations already declare this is a non-read-only, non-idempotent, non-destructive write, so the safety profile is covered. The description adds useful behavior — background execution, immediate persistence of new types, and that existing matches are left unchanged (a dedupe trait) — but key phrases like 'review in normal editor' and 'failures return trial slot' are opaque and do not tell the agent what actually happens on error.

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?

It is appropriately short and front-loads the purpose, which is good. However, the telegraphic sentence fragments ('Existing matches unchanged; failures return trial slot') sacrifice clarity for brevity and leave the reader parsing ambiguous clauses.

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 asynchronous generation tool with no output schema, the description omits the essential operational detail: how to obtain the result, whether polling is needed, and what 'trial slot' refers to. An agent could call it correctly but would not know what to do next or how to interpret failures.

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% and the single 'source' parameter is fully documented via its oneOf branches. The description's mention of 'upload/document version' merely restates the two schema variants in plain language without adding constraints, formats, or prerequisite steps.

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 ('Generate a type ... from upload/document version') and clarifies it runs in the background, which distinguishes it from the synchronous clm_create_contract_type. It stops short of naming the sibling tools, so differentiation still requires the agent to scan the list.

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?

There is no explicit guidance on when to choose this over clm_create_contract_type, clm_create_type_generation_upload_url, or clm_get_type_generation. The word 'background' implies an async workflow that must be polled elsewhere, but the description never says so or names the follow-up tool.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description adds genuinely new behavioral context: optimistic concurrency via expectedUpdatedAt with conflict on stale versions, and downstream side effects on scheduled email notifications and calendar feeds. It could go further on what 'destructive' means here (e.g., whether party roles are replaced wholesale) but the side-effect disclosure is real added value.

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 mutation semantics and concurrency rule, then the input constraint, then side effects — a sensible ordering with no filler sentences. The closing clause is hedged with two 'may's, which is honest but slightly soft for a definition meant to set expectations.

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 29-parameter nested mutation with no output schema, the description covers the essentials an agent needs before calling: partial-update semantics, the concurrency token, the minimum-field rule, and side effects. Missing is any statement of what a successful response contains or how partial failures surface, though the annotation set carries most of the safety profile.

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 baseline is 3; the description earns above that by explaining the meaning of expectedUpdatedAt as a version guard and by framing the field set as supplement-or-omit rather than a full replacement. It adds no detail on the nested parties replacement rule or the null-clearing convention, both of which remain schema-only.

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 ('Partially update approved contract metadata') and clarifies the PATCH-like semantics via 'partially' and 'using its current version'. It does not name or distinguish itself from the closest siblings, notably clm_bulk_update_contracts or clm_apply_contract_reconciliation, so an agent must infer the single-vs-bulk boundary.

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 concrete preconditions: the contract must be approved, the caller must send at least one field besides id and expectedUpdatedAt, and manual supplementation of extracted values is discouraged. It stops short of naming alternative tools for bulk edits or reconciliation, so routing guidance is incomplete rather than absent.

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

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

Annotations declare destructiveHint=true and idempotentHint=true, so the safety profile is covered, but the description adds no context beyond that. Critically, it does not say whether the events array replaces existing events/reminders or patches them, nor that it accepts up to 100 events – the most important unknown for a destructive batch update.

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?

It is short and front-loaded, but the brevity is under-specification rather than efficiency – a single semicolon-joined clause leaves the destructive batch semantics and concurrency requirement unexplained for a non-trivial mutation tool.

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, idempotency-keyed batch mutation with nested reminder recipients and optimistic locking, the description omits replacement vs merge behavior, failure modes, and email timing. With no output schema, the description should have carried more of this behavior but does not.

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 the schema carries parameter documentation and the baseline is 3. The description's "email recipients when due" hints at the reminders sub-object but adds no format or replacement semantics beyond what the schema already encodes.

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 verb+resource ("Update custom events") is identifiable, but the trailing clause "sync linked notifications; email recipients when due" muddles scope – it is unclear whether reminder emails are sent immediately, scheduled, or merely reconfigured. Nothing distinguishes it from siblings like clm_update_event_reminders or clm_create_event_reminders.

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?

There is no statement of when to use this tool versus clm_create_contract_events, clm_delete_contract_events, clm_update_event_reminders, or clm_update_contract. The required expectedUpdatedAt field implies optimistic-concurrency semantics, yet the description never warns that a stale value will fail the call.

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

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

Annotations already flag destructive and non-idempotent, but the description adds real facts beyond them: pending-review state is cleared, the field set is replaced wholesale rather than merged, and existing contracts' notifications/calendars are deliberately left untouched. That last point is a meaningful scoping guarantee an agent would otherwise have to guess.

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, front-loaded with the mutation and its side effects, with zero filler. The telegraphic style ('clear pending-review') is slightly compressed but still decodable.

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?

Covers scope and side effects for a destructive mutation, and annotations plus the full-coverage schema fill in safety and parameter details. However, it says nothing about what happens when the type is in use by existing contracts beyond notifications/calendars, and there is no output schema to explain 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?

Schema coverage is 100%, so parameter meaning is already documented, including the note that omitting fields removes them. The description reinforces that field replacement is optional and whole-set, but adds no format or constraint detail 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?

States a specific verb and resource (update a contract type) plus the concrete effects: type change, pending-review clearing, and optional custom-field replacement. It is distinguishable from clm_create_contract_type and clm_update_contract, though the phrasing 'Update type' leans on the tool name/title to be fully 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?

No indication of when to use this versus clm_reread_contract_type, clm_create_contract_type, or clm_update_contract, and no prerequisites or conditions are given. The behavioral notes imply a post-generation workflow but never state it as guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered; the description adds value beyond them by disclosing per-item partial failure semantics (failures retain their reason in results) and the exact idempotency key policy for full versus partial replays. It does not explain what state is overwritten by an update or whether unchanged fields are preserved, which matters for a destructive operation.

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 dense sentences with no filler, and the core purpose is front-loaded ahead of the failure-handling detail. The phrasing is telegraphic to the point of ambiguity in places ('linked notification' is unexplained), which keeps it just short of ideal.

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 batch mutation over a nested reminder array with up to 100 items and no output schema, the description covers failure reporting and key reuse but omits atomicity (are successful items committed when others fail?), the concurrency role of expectedUpdatedAt, and any permission requirements. It is adequate to attempt a call but leaves real gaps for a destructive batch write.

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 and the baseline applies. The description does enrich idempotencyKey semantics beyond the schema's terse 'Identical-input retry key' by explaining when to mint a new key versus reuse the original, but it says nothing about the nested reminder fields (offset direction/unit, recipient variants, expectedUpdatedAt concurrency check).

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 verb ('Change') and the exact mutable facets (timing/recipient/message) of event-linked notifications, plus the downstream effect ('email recipients when due'). The resource is clearly distinct from clm_create_event_reminders and clm_delete_event_reminders, but no sibling is named, so the separation is inferred 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?

It gives concrete operational guidance for the retry scenario: resend only failed items with a new idempotencyKey, and reuse the original key only for an identical full replay. That is genuinely useful when-to-use guidance for one case, but there is no guidance on when to prefer this tool over clm_update_contract_events or the create/delete reminder siblings, nor any precondition such as required permissions.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, idempotentHint=false and openWorldHint=false, so the risk profile is known. The description adds a genuine domain rule that tax/registration numbers are organisation-only and must be cleared on a switch to individual. It does not disclose update semantics (partial merge vs full replace) or what happens to unmentioned fields, which matters for a destructive 18-parameter mutation.

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 no filler, and the domain constraint is front-loaded after the action statement. It is efficient rather than padded, though the extreme brevity for an 18-parameter tool borders on under-specification.

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, non-idempotent update accepting 18 parameters with only 3 required, the description leaves the most consequential questions unanswered: is this a patch or a replace, are omitted fields wiped, and can type be changed freely. The single rule about tax/registration numbers is not enough context to invoke this safely.

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 the schema already documents all 18 parameters, including that taxId and registrationNumber are org-only. The description adds a valuable cross-field constraint (clear both when switching to individual) that the schema does not express, but it covers only two of the parameters and explains nothing about the null-versus-empty-string conventions.

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 ("Update workspace party"), which an agent can easily distinguish from clm_create_party and clm_get_party by name and verb. It does not explicitly name sibling alternatives, so it stops short of 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?

The only usage rule given is a conditional constraint about tax/registration numbers when switching to individual. There is no guidance on when to prefer this over clm_create_party, no prerequisites (permissions, party must exist), and nothing about whether omitted fields are preserved or cleared.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=false, so the safety profile is covered by structured data. The description's added value is the ordering constraint "Preview first," which is genuine behavioral context. It says nothing about failure modes, block ordering, or whether repeated calls stack duplicate blocks, which matters given idempotentHint=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?

Two short sentences, zero filler, with the mutation stated before the prerequisite. The telegraphic "Preview first" fragment is efficient but slightly under-specified, which keeps it from a 5.

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 non-idempotent mutation with no output schema, the definition covers the action and the preview prerequisite but omits what the call returns (e.g., a block ID) and where the config's "listed fields" come from, presumably report_describe_fields. Adequate but leaves real gaps for an agent building a dashboard programmatically.

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 dashboardId and config are documented in the schema, making 3 the baseline. The description only reinforces the single-block granularity of config; it adds no detail on the config payload, and the schema's own "using listed fields" pointer is left unexplained.

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?

"Add one block to a dashboard" gives a specific verb (add) plus resource (block) plus scope (one, to a dashboard), which is enough to distinguish it from report_update_block and report_remove_block. It stops short of naming those siblings explicitly, so differentiation is inferred from the name 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?

"Preview first" is a real usage directive that implies report_preview_block should be called before this tool, but the sibling is never named and no condition or exclusion is given. The agent must map the phrase onto the sibling list itself.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, and openWorldHint=false, so the write nature is covered structurally. The description adds that the resulting dashboard is private by default and that a preview step should precede creation, but says nothing about required permissions, whether a preview is enforced, or what happens on failure.

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 filler, with the core action and its constraint front-loaded ahead of the workflow hint. Nothing here needs trimming.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.