OKSign MCP by usefulapi

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds useful behavior beyond that: it says the call returns the filename and a template flag, and the 'still exists' wording signals deletion-check semantics, though it does not explain not-found 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 dense sentence with the purpose front-loaded, followed by return information and the endpoint. 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 simple read-only existence check with full schema coverage, the description is nearly complete. The main residual gap is not stating whether a missing document yields a false result or an error.

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 single docid parameter is fully documented in the schema, including acceptable id forms and the pattern. The description adds no parameter-level meaning beyond that, so 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 ('Whether a (signed) document still exists on the platform') and adds returned fields and the underlying endpoint. It is clearly distinct from siblings like oksign_get_document_metadata, though it does not name 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?

Usage is implied: check existence before acting on a document. There is no explicit when-to-use versus when-not, nor a named alternative such as oksign_get_document_metadata for fuller information.

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, destructiveHint=false, openWorldHint=true, so the safety profile is covered and the bar is lower. The description adds real context: it maps the returned fields to their meaning and explicitly gives the unit (bytes) for account_size and max_account_size, which matters for interpreting the values. It omits auth/scope requirements and any rate-limit or caching behavior, so not a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence that puts the resource and its fields first, with no filler. The trailing endpoint reference 'GET /v1/credits/retrieve.' is the only low-value element - it restates the tool's purpose without adding decision-relevant 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?

There is no output schema, so the description's field list effectively serves as the return contract, and it names each field plus units - strong compensation. Minor gaps remain: it doesn't say what values appear when no paid plan or no subscription exists, and doesn't describe units for the credit quantity.

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, which is the baseline-4 case; there is nothing for the description to compensate for. The description correctly implies a pure account-scoped fetch with no filtering inputs.

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 retrieval and enumerates exactly what it returns: remaining credits, expiration (validuntil), plan/subscription, paid status, and storage used vs max in bytes. That is concrete and distinguishable from every sibling (documents, contacts, users, templates). It does not explicitly name a sibling it replaces, which keeps it out of 5 territory for a no-arg resource fetch.

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 rather than stated - an agent can infer this is the account-level billing/quota lookup, and no sibling covers credits or storage, so there is no real alternative to disambiguate. No guidance on when to call it (e.g., before uploads to check quota) or on freshness/caching of the figures.

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, destructiveHint=false, and openWorldHint=true, so safety is covered. The description adds genuinely non-obvious context beyond that: it is the 'v2' metadata endpoint, the underlying HTTP route, and a warning that returned field values 'can contain personal data' — a disclosure the agent would not get from structured fields. It does not discuss size limits or error behavior for an unknown docid.

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 compact sentence front-loads what is returned, followed by the version and endpoint. The parenthetical PII warning earns its place. Slightly dense packing of return fields, but no filler sentences.

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

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the burden of describing the return value, and it does so by enumerating the key metadata components. For a one-parameter read tool with full annotation coverage, that is nearly sufficient; only the shape/nesting of the field-value collection and failure modes for invalid ids are left implicit.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single parameter's schema entry already explains that docid, source_docid, or signed_docid are all accepted, with an example format. The description's '(pass the signed_docid)' is largely a restatement, though it usefully signals the parameter is mandatory. Baseline 3 applies when the schema carries the semantics.

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 (retrieve metadata of a signed document) and enumerates the payload: filename, size, signature counts/validity, signers, and completed field values. It also pins the exact API operation ('Metadata v2. GET /v2/metadata/retrieve'), so an agent can distinguish it from list-oriented siblings like oksign_list_signed_documents. It stops short of explicitly naming the sibling to use instead when the agent only has a list-level need.

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?

'pass the signed_docid' implies the tool requires an already-known document id, which is useful context, but there is no explicit when-to-use/when-not guidance. Nothing tells the agent how this differs from oksign_get_linked_document or oksign_document_exists when it has an id in hand. Usage is inferable but not 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=true, destructiveHint=false, openWorldHint=true, so the safety profile is covered. The description adds real value beyond that: it discloses that the response contains live signing URLs and warns they must only be shared with the signer — a genuine confidentiality caveat an agent would otherwise miss.

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 security warning placed after the return description, which is reasonable. However, the second sentence mixes a behavioral warning into an otherwise purely descriptive listing, and the trailing endpoint path adds little for an agent.

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

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, and the description compensates by enumerating the returned field attributes (type, page, position, signer, required, signing options) plus the signing URLs. Combined with the confidentiality caveat, an agent has everything needed to invoke and interpret 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?

With a single param and 100% schema description coverage (including pattern and accepted docid variants), the schema carries the semantics. The description adds only the framing that the document is an 'uploaded document', not new detail on the docid argument. Baseline 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?

States a specific resource (form descriptor of an uploaded document) and enumerates what it contains: signature/form fields with attributes and per-signer signing URLs. An agent can tell this apart from oksign_get_document_metadata, but the description never explicitly contrasts the two, so the sibling differentiation 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?

The purpose implies when to reach for it (you need field layout or signing links), and the security warning about URL sharing is a useful usage note. But there is no explicit when-to-use/how-it-differs-from-alternatives guidance versus oksign_get_document_metadata or the list_* tools.

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, destructiveHint=false and openWorldHint=true, so safety is covered. The description still adds real value by disclosing the return shape (signed_docid plus timestamp, or source_docid) and the meaning of an empty result, which is the key ambiguity for an agent interpreting a null response.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two compact sentences plus the endpoint, with no filler. The conditional structure (given X, returns Y; given Z, returns W) is front-loaded and easy to parse, though the phrasing is slightly telegraphic.

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 correctly carries the burden of describing return values, including the negative case of an empty result. It is nearly complete for a single-parameter read, missing only sibling differentiation and any note on whether the lookup crosses account boundaries (openWorldHint suggests it may).

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 says the id may be a docid, source_docid or signed_docid, matching the description's wording. The description reframes the parameter as a bidirectional lookup key, which is mildly useful, but adds no format, constraint or error-handling detail beyond the schema. 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 states a specific operation: resolving the link between a source_docid and its signed_docid, in either direction. That is clearly more than a restatement of the name. It does not, however, distinguish itself from nearby siblings such as oksign_document_exists or oksign_get_document_metadata, so an agent cannot tell from the text alone which of the three to reach for.

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 describes behavior rather than when to invoke it. There is no statement of when this is preferable to oksign_document_exists (existence check) or oksign_get_document_metadata (metadata fetch), and no guidance on the unsigned-not-yet case beyond the parenthetical.

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 carry readOnlyHint/openWorldHint/destructiveHint, so the bar is lower, yet the description adds genuinely useful behavior: a hard throttling rule with the exact 429 consequence, and the meaning of the status codes (1/10/11/12/14) that govern which rows appear. It stops short of describing error handling or ordering.

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 resource scope, then the payload shape, then the throttling caveat and endpoint. It is dense but every clause carries information; the long parenthetical status table is the only place it approaches a wall of text.

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

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, and the description compensates by enumerating the returned fields, the status-code meanings, and the conditional signed_docid. Combined with the fully documented schema, an agent has enough to call it correctly; only ordering/pagination behavior (next_offset) is left to the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all five filters (limit, offset, signed, orgtoken, filename_contains) are already documented in the schema. The description adds no syntax, defaults, or interaction notes for those parameters; its field list describes return values, not inputs.

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 ('Documents in the account's Active Documents tab') and enumerates the returned fields plus the status code table, so the agent knows exactly what it gets. It never names the sibling oksign_list_signed_documents, so the boundary between 'active' and 'signed' listings must be inferred from the status codes.

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 rate-limit warning ('once every 3 minutes, 429 otherwise') implicitly tells the agent to call sparingly, and the filter params imply when to narrow. But there is no explicit 'use this instead of X when Y' guidance against the many sibling list tools, nor any statement of when a caller should not use 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the returned field set, which is useful context, but it says nothing about volume, auth needs, or the fact that results are hard-capped with no true paging.

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 lines with no filler, and the field enumeration is front-loaded. The trailing 'GET /v1/contacts/retrieve' restates the endpoint rather than adding agent-relevant information, so it is slightly wasteful but harmless.

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 schema coverage, annotations, and no excessive parameter complexity or output schema, the description is nearly sufficient. Only the missing distinction from oksign_list_users keeps it from being fully 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?

With two parameters at 100% schema description coverage, the schema already explains limit (1-500, default 100) and offset (with the next_offset hint). The description adds no meaning beyond the schema, 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 the resource (the account's contact list) and enumerates the fields returned (name, email, mobile, actingas/capacity, group), so an agent knows exactly what it gets back. It does not distinguish itself from the similar-sounding sibling oksign_list_users, which a reader could easily confuse it with.

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 call this versus alternatives such as oksign_list_users or oksign_get_linked_document, and no prerequisites or exclusions. The verb 'list' is only implied by the title; the description itself gives no situational 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 readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the concrete field list (id, name, subject, HTML body, reminder_days, repeat), which is useful since there is no output schema, but it says nothing about list size, truncation, or the next_offset mechanism beyond the endpoint reference.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One front-loaded sentence plus an endpoint reference; no filler. The trailing 'GET /v1/email-templates/retrieve' is marginally redundant but brief.

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 enumerations of returned fields is the key contribution and it is present. Parameter behavior is fully carried by the schema; only the truncation/next_offset workflow is left implicit for a tool that can silently cut 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 the schema itself documents limit (1-500, default 100, list cut here, no paging) and offset (pass previous reply's next_offset). The description adds no parameter 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?

States a specific verb and resource (list the email templates defined in the account) and enumerates the returned fields, so the agent knows exactly what comes back. No sibling tool deals with templates, so differentiation is implicit rather than needed.

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 prerequisites, and no alternatives named. The agent must infer that this is the only way to enumerate email templates.

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 readOnly/non-destructive annotations, it discloses a hard behavioral constraint an agent must respect: one call every 3 minutes, 429 otherwise. It also clarifies the filtering semantics (error events only) and the underlying endpoint, which annotations cannot convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences: purpose first, then the error-only constraint, then the rate limit. The trailing endpoint string is slightly tacked-on but each sentence carries operational value with 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?

With no output schema, the description compensates by naming the returned fields (recipient, source_docid, reason, orgtoken, timestamp) and stating that only error events appear. Combined with the rate-limit warning, an agent has everything needed to call this correctly and interpret the reply.

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 start/end/limit/offset are already fully documented, and the description only alludes to the window ('between two moments'). The field list (recipient, source_docid, reason, orgtoken, timestamp) describes return values, not parameters, so it adds no parameter meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Email and SMS delivery problems ... for signing invitations') and enumerates the exact error reasons returned (hard_bounce, soft_bounce, blocked, spam, invalid_email, deferred). No sibling tool covers notification errors, and the explicit reason list makes the scope unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Only error events are reported' tells the agent what this will and will not return, and the bounded window ('between two moments') plus the 3-minute rate limit defines when it can be called. It stops short of naming an alternative tool or an explicit when-not-to-use condition, but no sibling overlaps this behavior.

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, non-destructive, openWorld), but the description adds a genuinely non-obvious trait: a hard rate limit of one call per 3 minutes with 429 otherwise. It also scopes results to API-uploaded documents, which affects what an agent will and won't find.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and endpoint are front-loaded and the rate-limit warning is placed where it will be read before invocation. The middle field enumeration is a long run-on list, but with no output schema it earns most of its space.

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

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, so naming the returned fields (docids, signer, signature counts, credits, timestamp) is legitimately compensating value, and the rate limit and API-upload scope round it out. The main remaining gap is sibling differentiation against the active-documents listing.

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 start/end/limit/offset semantics are already fully documented, including the next_offset paging hint. The description reinforces the window-sizing constraint but adds no format or syntax 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 and resource: documents uploaded through the API signed between two moments, and even maps to the endpoint GET /v1/documents/signed. It implicitly separates itself from oksign_list_active_documents by emphasizing 'signed' and 'between two moments', but never names that sibling or contrasts the two 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?

'Keep the window short' plus the once-per-3-minutes constraint gives operational guidance on how to call it, which is useful. However, it never says when to choose this over oksign_list_active_documents or oksign_get_document_metadata, so sibling selection 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 this a safe read operation (readOnlyHint=true, destructiveHint=false), so the description only needs to add context. It does so by disclosing the returned fields and the immutability of signerid, but says nothing about result caps, failure modes, or whether the account scope is fixed by credentials.

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 clause naming the returned fields plus the endpoint path; there is no filler. It is slightly clipped (no explicit verb such as 'lists') but remains 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?

Because there is no output schema, the description usefully enumerates the response fields, which is the main completeness win. It still omits the no-paging cap and the offset/next_offset loop from the prose, leaving an agent to discover that only from the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and the schema already documents limit (1-500, no paging) and offset (pass the previous next_offset) thoroughly. The description adds nothing about either parameter, 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 resource (users of the OKsign account) and enumerates the fields it returns, so an agent knows exactly what the payload contains. It does not explicitly differentiate itself from the nearest sibling, oksign_list_contacts, which also returns people records.

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 instruction is embedded in a field note: 'use it (signerid) to tell who signed'. That tells the agent when a returned field matters, but gives no guidance on when to call this tool rather than oksign_list_contacts or a document-metadata 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, idempotentHint=false, readOnlyHint=false, so the safety profile is known; the description still adds real value with "permanently," "cannot be undone," and the recovery path. It stops short of batch semantics — with up to 200 contacts per call, whether one bad entry aborts the whole request or partially applies is not stated.

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 compact sentences, front-loaded with a "WRITE:" marker that signals the mutation class before any detail. The endpoint is appended last where it belongs; 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 destructive, single-parameter mutation with no output schema and full annotation coverage, this covers intent, identity, irreversibility, and recovery. The remaining gap is error/partial-failure behavior on a 1–200 item batch, which an agent calling it would want to know.

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 item-level fields (name, email) are already documented in the schema, including the combined-identity note. The description's restatement of "identified by its email AND name" reinforces rather than adds to 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?

The description opens with a specific verb and resource ("permanently remove contacts from the account's contact list") and pins down the exact identity rule (email AND name). It is instantly distinguishable from sibling oksign_list_contacts (read) and oksign_upsert_contacts (add/update).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives clear context for when this tool applies and names the recovery alternative ("re-add with oksign_upsert_contacts"). It does not explicitly say when not to use it (e.g., to prune a single contact after listing) or point at oksign_list_contacts for discovery, so it falls short of full routing guidance.

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

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

Beyond the destructiveHint/readOnlyHint annotations, the description adds what actually gets destroyed (the file and its pending webhook events), that the operation cannot be undone, and the specific 'Too soon' failure mode. That is exactly the behavioral context an agent needs before committing to a point of no return.

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 WRITE label and the permanence warning, then the edge case, then the endpoint. No sentence is 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 one-parameter destructive tool with no output schema, the description covers irreversibility, cascading deletion of pending webhook events, and the retry condition. Only a note on what a successful response looks like is absent, which is minor.

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 docid property already documents the accepted id variants and the format pattern. The description only restates the endpoint path, so it adds little beyond the schema; 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 an explicit verb and resource ('permanently remove a (signed) document from the OKsign platform') and even labels the operation class as WRITE. This is unmistakably distinct from the read-only siblings (list/get/document_exists) that surround 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?

It gives a concrete condition and remedy for the awkward case: a signed document removed right after its callback may answer 'Too soon', so retry later. It does not explicitly name an alternative or say when removal should be avoided entirely, but for a single destructive action with no near-equivalent sibling, the guidance is clear enough.

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 destructiveHint=true annotation, the description explains exactly what is destroyed (a matching contact's other fields are replaced) and what is not (existing contacts are never cleared), which pre-empts a misreading of the hint. It also discloses partial-failure semantics — rejected contacts are skipped and reported — and the underlying endpoint.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences, each carrying distinct information, with the WRITE marker and core behavior front-loaded. No restatement of the title 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 mutation tool with rich annotations, the description covers the semantics an agent most needs: upsert key, replacement scope, non-destruction of unrelated records, and partial-failure handling. Minor gaps remain around how skipped contacts are surfaced, since there is no output schema to explain 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% (baseline 3), and the description adds meaning the schema only hints at: the conjunction of email AND name as the match key and the consequence for the non-key fields (group, mobile, actingas) on a match. It does not discuss the per-call 1-200 contact bound, leaving that to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('add contacts ... or update them') plus the exact match key ('same email AND name'), and labels itself WRITE up front. That is enough for an agent to separate it from oksign_list_contacts and oksign_remove_contacts without opening either 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?

The update-vs-insert condition is spelled out precisely, and 'Existing contacts are never cleared' implicitly routes deletion to oksign_remove_contacts. It stops short of naming siblings or stating prerequisites/limits explicitly, so it is clear context rather than full when/when-not guidance.

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