ClearPolicy

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

Beyond the annotations, the description discloses a meaningful side effect: when automatic request issuance is enabled, the tool assigns group documents and sends grouped attestation request notifications. This helps the agent anticipate downstream actions. It does not explicitly discuss idempotency or reversibility, but the annotations already provide readOnly, destructive, and idempotent hints, and the description does not contradict them.

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 two sentences and front-loads the core action before adding the conditional nuance. Every clause earns its place; there is no filler, restatement of the tool name, or redundant 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?

For a two-parameter membership mutation, the description provides the core action and the key automatic-request side effect, and an output schema exists to cover return values. It could mention prerequisites like whether the group must exist or how duplicates are handled, but those are partially implied by the annotations and the low complexity makes this 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?

The input schema already documents both parameters fully, including that group_id and person_id are ULIDs and that person_id refers to an active person. The description adds no additional parameter-level meaning beyond the schema, so it sits at the baseline for full schema coverage.

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: 'Add one person to a ClearPolicy group.' It unambiguously states the primary operation and distinguishes it from sibling tools like create-person-tool or publish-document-revision-tool by naming the group-membership action. The additional conditional sentence clarifies what happens when automatic request issuance is enabled.

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 first sentence implies the tool's use case: use this when you need to add a person to a group. However, the description never explicitly contrasts this tool with alternatives or states when not to use it. The conditional side-effect context is useful, but it is operational guidance rather than tool-selection 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 readOnlyHint=false, so the destructive nature is covered. The description adds 'This cannot be undone' which reinforces irreversibility but is somewhat redundant with destructiveHint. It also notes 'pending' scope, which is useful. Given the annotations cover the main behavioral profile, the description provides marginal extra 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?

Two short sentences, front-loaded with the action and resource. No filler or redundancy; every word contributes.

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 with a single parameter and an output schema. The description covers the essential purpose and the irreversible nature. It could mention what happens after cancellation or that only pending requests are eligible, but these are implied. Given the simplicity, it is sufficiently 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 the parameter 'request_id' is fully described in the schema as 'The ULID of the signing request to cancel.' The description adds no additional parameter information, which is acceptable given high schema coverage.

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 action (cancel) on a specific resource (pending document signing request). It clearly distinguishes from siblings like send-signing-request-tool and list-signing-requests-tool. The verb and object are 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?

It implies when to use: for cancelling a pending request. It doesn't explicitly state when not to use or name alternatives, but the sibling set makes the context clear. Could be improved by noting it only applies to pending requests, though that is already mentioned.

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 and destructiveHint=false, but the description adds the exact idempotent behavior ('If a draft already exists, returns that draft instead') and a document-type limitation. It omits permission/auth requirements, keeping it short of 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?

Three short sentences, front-loaded with the core action and each carrying distinct value (purpose, idempotency, limitation). No filler, though the third sentence is slightly tangential to invocation.

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 an output schema present, return values need no explanation, and the description covers the mutation's non-destructive, idempotent nature plus a real usage constraint. Complete enough for a 3-param create tool, missing only auth/permission context.

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 are documented in the schema, so the baseline of 3 applies. The description adds little parameter-level detail beyond what the schema already states (e.g., body_markdown copying prior content).

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 ('Create') plus resource ('new draft revision for an existing document'), and the qualifier 'draft' cleanly separates it from create-document-tool and publish-document-revision-tool. An agent can route to it without opening the schema.

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

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

It supplies clear context ('for example after a version was published') and an explicit exclusion with an alternative ('File-based documents (PDF/Drive) cannot be edited as rich text via ChatGPT — use the web app'). It doesn't name sibling revision tools, but the when/when-not coverage is strong.

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 non-readonly, non-destructive, non-idempotent, but do not convey the crucial trait that the output is an unpublished draft. The description supplies that state and the intended review-then-publish lifecycle, adding real behavioral value beyond the annotations, though it omits permission/auth or uniqueness requirements.

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 that front-load the primary action and then the state constraint and follow-up. No redundant restatement of the name or schema fields, every sentence earns its place.

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

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

With annotations covering the safety profile and an output schema present, the description need not explain return values; it covers purpose, draft state, and next step. It is nearly complete, lacking only mention of required inputs or permission prerequisites for creation.

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 name, summary, and body_markdown including the 255-character limit and supported Markdown constructs. The description only echoes the optional Markdown body, adding no format or constraint 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?

States a specific verb and resource ('Create a new ClearPolicy document with a draft rich-text revision') and clarifies scope by contrasting with publishing. It names publish-document-revision-tool as the alternative, but it does not distinguish this tool from the sibling create-document-revision-tool, leaving some ambiguity about which creates the container vs. the revision.

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?

Explicitly states the negative case ('Does not publish') and gives the follow-up tool with the condition ('after the user reviews the draft'), which is genuine workflow guidance. It does not say when to prefer this over create-document-revision-tool, so it is clear context without full 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?

The annotations already indicate that this is not a read-only operation Alertthe description confirms it creates a person and adds context about subsequent actions like assigning documents and adding to groups. However, it does not disclose potential failure behaviors such as duplicate email handling or required permissions. This is acceptable but not especially rich.

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

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

The description is a single, focused sentence that leads with the core action and target, then adds a brief purpose clause. There is no redundant information or boilerplate.

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 create operation, the description covers the action, target, scope, and why the new person is useful. The output schema and parameter schemas fill in the remaining details, though it could optionally mention uniqueness or validation behavior.

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 input schema provides 100% description coverage for the parameters, so the description does not need to restate them. It adds no extra parameter-level detail, which is fine, but the description itself contributes nothing 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 starts with a clear action, 'Add a new person', specifies the target scope, 'to the current ClearPolicy organization', and explains the downstream uses. This differentiates it from sibling tools like add-person-to-group-tool, which handles a different operation entirely.

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 clear context for when this tool should be used: when creating a new person in the current organization. It does not explicitly state exclusions, such as 'use add-person-to-group-tool to add an existing person to a group,' but the wording makes the primary use case unambiguous.

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/idempotent/non-destructive, so safety is covered. The description adds genuinely useful behavioral context beyond that: table-bearing blocks are returned as non-round-trippable read-only HTML in content_markdown, with explicit remediation (edit in ClearPolicy editor or omit body_markdown when copying). It stops short of covering error behavior or auth, so 4 rather than 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?

Three dense, front-loaded sentences with no filler; the core operation is stated first, caveats after. The transition between the round-trip warning and the ID-source hint is slightly abrupt 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 an output schema present, return values need not be explained, yet the description still calls out the two fields that matter for the next action (body, lock_version). For a single-parameter read tool with full annotation coverage, nothing an agent needs to call it correctly is missing.

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 documents revision_id as a ULID, so the baseline is 3. The description adds value by telling the agent where valid IDs come from (latest_draft_revision_id / latest_published_revision_id from create-document or get-document), which the schema does not.

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+resource ('Get a document revision') and names what it returns (body and lock_version). It does not explicitly differentiate itself from the sibling get-document-tool, so an agent must infer the distinction, but the purpose itself 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?

Uses 'for review' and points to create-document / get-document as the source of valid revision IDs, which implies usage context. However, it never states when to prefer this over get-document-tool or create-document-revision-tool, leaving the routing decision 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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is established. The description adds useful return-value context by mentioning signature counts, but does not disclose other behavioral details such as access requirements or not-found behavior. This is adequate but not rich.

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

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

The description is a single front-loaded sentence that includes the core purpose and the most distinguishing detail. There is no redundancy or 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 one well-documented parameter, a full output schema, and strong safety annotations, the description is nearly complete for a simple read-only fetch. The main gap is the lack of explicit sibling differentiation, but the low complexity keeps this above the minimum viable bar.

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 document_id is already documented as a required ULID. The description does not add additional meaning or constraints beyond the schema, making the baseline score of 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 states a specific verb ('Get') and resource ('details of a document'), and adds concrete information about what details are included: signed and unsigned counts. It is clear enough to distinguish from list-documents and get-document-revision, though it does not explicitly name the sibling it is not.

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 guidance on when to use this tool versus alternatives such as list-documents-tool, get-document-revision-tool, query-docs, or search-docs. No explicit when/when-not conditions or alternative routing are provided.

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. Description adds useful context about return content (counts, resource URIs) beyond annotations, but does not describe other behavioral traits like pagination or authentication.

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?

Single sentence, front-loaded with key information, no wasted words.

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

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

Given single required parameter, full annotations, and presence of output schema, description sufficiently covers purpose and return details (counts, URIs).

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 description does not add meaning beyond the schema's parameter description ('The ULID of the group to retrieve'). 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?

Description clearly states verb 'Get', resource 'ClearPolicy group', and specifies inclusions ('counts and resource URIs for its members and documents'). Distinct from sibling tools like list-groups-tool (listing all) and get-person-tool (different resource).

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 explicit guidance on when to use this tool versus alternatives (e.g., list-groups-tool). Usage is implied by name and description 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, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that it shows which documents are signed or not, which is useful outcome context, but does not go beyond that. Given annotations cover the core behavior, this is adequate but not extensive.

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 sentence with no redundant words. It is front-loaded with the core action and then adds the outcome detail, making it highly efficient and easy to scan.

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 tool with an output schema and safety annotations, the description is sufficient. It states what it does and what information is returned. It could explicitly mention when to use it over list-people-tool, but the lack is minor given the clarity of purpose. Overall, it is complete for an agent to call correctly.

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

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

Schema description coverage is 100% and describes person_id as 'The ULID of the person.' The description itself does not add additional parameter context, so it relies fully on the schema. This is the baseline 3 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?

The description clearly states the verb 'Get' and resource 'person's profile', and specifies the additional behavior of showing which documents they have or haven't signed. This distinguishes it from sibling tools like get-document-tool and get-group-tool, making its purpose 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?

The description implies usage for retrieving a single person and their signing status, which is distinct from list-people-tool (for multiple people) and get-document-tool (for document details). However, it does not explicitly state when to use this versus alternatives, so guidance is clear by implication but not spelled out.

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, covering the safety profile. The description adds that the tool returns whether a signature occurred and when, but it does not disclose additional behavioral details such as handling of missing request IDs or response shape. This is adequate given the strong annotation coverage.

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, focused sentence with no filler. It immediately states what the tool does, making it highly efficient and easy 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?

With only one parameter, clear annotations, and an output schema present, the description is complete for this simple read-only tool. The description need not explain return values because the output schema covers that, and no other context is missing.

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 schema provides 100% description coverage for the single parameter (request_id as 'The ULID of the signing request'). The description does not add additional meaning beyond the schema, so the baseline score 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 clearly states a specific verb ('Check') and a precise resource: whether a specific person has signed a document and when. This distinguishes it from siblings like list-signing-requests-tool or send-signing-request-tool by focusing on the signing status of a person rather than listing or sending requests.

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

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

The description implies a clear usage context: use this tool when you need to verify a person's signature status and timestamp. It does not explicitly mention exclusions or alternatives, but the intended use case is evident from the phrasing, matching 'clear context, no 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 establish that this is read-only, idempotent, and non-destructive. The description adds a behavioral scope by indicating the listing is limited to documents the organization has 'ready to send,' which is useful context. However, it does not disclose further behavior such as pagination or default exclusions; with strong annotation coverage, this is acceptable but not exceptional.

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 carry the full message without redundancy. The main action and scope appear in the first sentence, and the second sentence reinforces the use case. No wasted words.

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

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

For a simple list tool with two optional, fully documented parameters and a read-only annotation profile, the description is nearly complete. The presence of an output schema removes the need to explain return values. It could be slightly stronger with explicit sibling differentiation, but nothing essential is missing for correct invocation.

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 (name filter and include_archived) are already documented. The description does not add parameter-level meaning beyond the schema, so the baseline score 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 uses a specific verb-resource pair ('Find documents') and adds a clear domain ('available to send for electronic signature'), which distinguishes it from listing people, groups, or signing requests. The phrase 'ready to send' also implies a scoped subset rather than all documents, helping differentiate from broader search/query 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?

The description explicitly states the intended use: 'Use this to browse what documents the organization has ready to send.' This gives clear context for when the tool is appropriate, though it does not mention exclusions or name sibling alternatives like query-docs or search-docs that might overlap.

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 indicate read-only, idempotent, non-destructive behavior. The description adds no further behavioral context such as rate limits, authentication, or result format. With annotations covering safety, the description meets minimum expectations.

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 two sentences long (22 words), front-loads the core action ('Find groups'), and contains no unnecessary words. Every sentence earns its place.

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

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

Given the tool is a simple read-only list with one optional filter, and an output schema exists (not shown but noted), the description is largely sufficient. It could mention that the result is a list of groups and any pagination, but the current text is adequate for the tool's simplicity.

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 input schema already fully describes the single optional parameter 'name' with its filtering behavior (partial match, case-insensitive). The description does not add any extra meaning to the parameter, achieving the baseline for 100% schema coverage.

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 clearly states what the tool does ('Find groups in the current ClearPolicy organization') and provides specific usage scenarios ('when an MCP client does not support resources or when the user asks to browse groups'), which distinguishes it from sibling tools like get-group-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?

The description explicitly specifies when to use the tool ('when an MCP client does not support resources') and gives a user-driven reason ('or when the user asks to browse groups'). It does not explicitly say when not to use it, but the provided context is helpful for 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the behavioral context that results are people who can receive e-signature documents, and that search is by name or email. It doesn't disclose details like pagination, result limits, or whether archived people are excluded by default, but the schema covers include_archived. No contradiction with 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?

Two sentences with no waste. The primary purpose is front-loaded, and the search capability is stated concisely. Every word earns its place.

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

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

For a read-only list/search tool with a full output schema and 100% schema parameter coverage, the description is largely complete. It could explicitly mention that archived people are excluded by default, but the schema already states that. The e-signature context adds useful framing. Minor gap: no mention of result ordering or pagination, but not critical for this tool type.

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 three parameters (name, email, include_archived) with their meanings. The description adds the high-level purpose (finding e-signature recipients) but doesn't add parameter-specific details beyond the schema. 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?

The description clearly states the tool's purpose: finding people in the organization who can be sent documents for electronic signature, with search by name or email. This distinguishes it from sibling tools like list-groups-tool or get-person-tool, and the context of e-signature recipients adds specific value.

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

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

The description implies when to use this tool: when you need to find people to send documents for signature. It doesn't explicitly state when not to use it or name alternatives, but the e-signature context and search-by-name/email guidance provide clear usage context. Sibling tools like get-person-tool or create-person-tool are implicitly different.

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 adds the compliance-tracking framing and glosses status semantics ('pending', 'signed', 'expired'), which is modest added context, but it says nothing about result volume, pagination, 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?

Two short sentences, front-loaded with the core purpose followed by the filtering capability. No filler or repetition, though the status examples are redundant with the schema enum.

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, zero-required-parameter list tool with a full-coverage schema and an output schema, the description covers purpose and filtering adequately. Only pagination/ordering behavior is unaddressed, and the output schema presumably handles the return shape.

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 description only restates the filter dimensions and a partial list of statuses already enumerated in the schema enum. Baseline 3 applies since the schema carries the parameter 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 clear verb+resource ('Check who has signed a document and who hasn't') and frames the tool as a listing/tracking query over signing requests. It is distinguishable from singular siblings like get-signing-request-tool, but it never explicitly names that sibling or the document/person list tools, so differentiation is left to inference.

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?

'Filter by document, person, or status ... to track compliance' implies the usage context (compliance auditing) but gives no explicit when-to-use/when-not or alternative tool routing. There is no guidance pointing to get-signing-request-tool for a single record versus this list 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, non-idempotent, non-readOnly, so the safety profile is covered; the description adds real value by saying a PDF and document hash are produced and that user confirmation is required first. It stops short of saying the publish is irreversible or what happens to the draft state afterward.

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, front-loaded with the action, then the side effects, the safety gate, and the next tool. No repeated or filler content.

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?

Annotations carry the destructive/non-idempotent profile, the output schema covers return values, and the schema documents parameters. The description supplies the workflow context (confirm → publish → send) that the structured fields cannot express.

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 revision_id, base_version, and allow_unfilled_fields are each fully documented in the schema, including the concurrency and approval caveats. The description adds no parameter-level meaning beyond that, 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?

Specific verb+resource ('Publish a draft document revision') with the concrete outcome stated (PDF and document hash generated). It clearly distinguishes itself from create-document-revision-tool and update-document-revision-tool by describing the publish transition into the signing workflow.

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?

Explicitly states the precondition (confirm with the user before publishing) and the follow-up tool (send-signing-request to distribute it), which routes the agent correctly among 19 siblings. The when and the next step are both given, not 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 readOnly/idempotent/non-destructive; the description adds operational context: commands run inside a sandboxed virtual filesystem (rg, cat, head, tree, ls) and paths are documentation pages, not customer org data. It does not mention what output looks like, but the behavior it discloses goes beyond the annotations without contradicting them.

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. First names the tool action and mechanism; second gives usage guidance. No fluff.

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 tool with an output schema and clear sibling distinction, this covers the essential selection and invocation guidance. It gives command examples GUIDES? Actually it gives commands in description: rg, cat, head, tree, ls. It addresses path namespace. 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 already fully describes the command parameter with examples Tags: 100% coverage, baseline 3. Description reinforces legal commands and path scope (`/guides/reminders.mdx`), adding beyond 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 action ('Read or search') and a clear resource ('ClearPolicy documentation pages') plus the mechanism. It explicitly differentiates itself from search-docs, telling the agent exactly when to use this tool vs. its sibling, which satisfies sibling discrimination.

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?

States 'Prefer search-docs for conceptual questions; use this when you need exact page content, keyword/regex matches, or docs structure.' This is explicit when-to-use and when-not-to guidance with a named alternative. Nothing 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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds useful behavioral context by clarifying that the tool searches documentation rather than organization data, and reinforces the read-only nature by pointing to list/get tools for data retrieval. It doesn't contradict 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?

The description is two sentences with zero filler. The first sentence states the purpose and scope; the second gives usage guidelines and exclusions. It's front-loaded and efficiently uses every word.

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 search tool with only two parameters, full schema coverage, and an output schema present, the description covers the essential usage context (when to use, when not to use). It doesn't need to explain return values (output schema exists) or parameter details (schema covers them). Nothing essential is missing.

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 are well-described in the schema (query with examples, language with code examples). The description text itself doesn't add extra parameter semantics beyond what the schema provides, which is acceptable given the high coverage. The baseline 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 clear verb (Search) and resource (ClearPolicy customer documentation) with specific content types (how-tos, guides, API reference). It also differentiates from siblings by explicitly excluding organization-specific data, which sets it apart from list/get tools. The phrase 'Use this for "how do I…" questions' further pins down its 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?

The description provides explicit when-to-use guidance ('how do I…' questions with examples) and when-not-to-use guidance ('Do not use this for organization-specific data — use list/get tools instead'). It names the alternative category (list/get tools) even though it doesn't name specific siblings, which is sufficient for an agent to route correctly.

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 indicate a non-read, non-idempotent side-effecting operation, and the description usefully adds that the concrete effect is a reminder email. It does not explain the destructive side effect or whether repeated calls send duplicate reminders, but annotations carry much of this burden.

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 sentence with no filler, front-loaded with the action, target, and condition. It is economical while still conveying the key distinction from the initial signing-request 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 single-parameter tool with full schema coverage, an output schema, and meaningful annotations, the description is nearly complete. The main omission is not explaining duplicate-send or destructive behavior, but those concerns are partially covered by the provided annotations.

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 input schema fully describes request_id as 'The ULID of the signing request to send a reminder for,' so schema coverage is 100%. The description reinforces the connection to a signing request but does not add meaning beyond what the schema already provides.

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 clearly states the action—'sending them a reminder email'—and the target condition, 'someone who hasn't signed a document yet.' This makes it easy to distinguish from the sibling send-signing-request-tool, which would send the initial request rather than a follow-up reminder.

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 'someone who hasn't signed a document yet' gives a clear contextual trigger for when to use the tool. However, it does not explicitly name alternatives or state when not to use it, so the guidance is clear but not fully explicit.

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=false, so the safety profile is known. The description adds that the tool dispatches a document for signature to multiple people, but it does not disclose side effects like creating a signing request, notifying recipients, or whether repeated sends create duplicates. No contradiction with annotations exists.

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 only two sentences, front-loads the core action, and contains no filler. Every sentence contributes either the operation or the intended use case.

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 tool with full schema coverage, an output schema, and relevant annotations, this description is mostly sufficient. It clearly identifies what to send and to whom, though it could strengthen completeness by noting the relationship to send-reminder-tool and cancel-signing-request-tool.

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

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

Schema description coverage is 100%, and both document_id and person_ids already have clear descriptions in the schema. The description adds no new parameter-level meaning beyond the schema, 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 uses a clear verb and resource: it sends a document to one or more people for electronic signature, and it gives a concrete use case ('team to sign a policy, agreement, or compliance document'). It does not explicitly differentiate itself from sibling tools like send-reminder-tool or cancel-signing-request-tool, 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 description provides an explicit 'Use this when...' clause, which gives the agent a clear trigger condition. However, it does not mention when not to use it or point to alternatives such as send-reminder-tool for existing requests or cancel-signing-request-tool for cancellations.

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 useful context that only drafts are editable and that a published revision must be superseded by a new draft, but the replacement semantics of body_markdown and the lock_version staleness behavior live in the schema rather than the description.

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 action, then the key constraint, then the preference. Every sentence carries distinct information 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 a full output schema, complete parameter docs, and annotations covering destructive/idempotent behavior, the remaining description burden is small. It covers the draft-only constraint and preferred authoring path, leaving little an agent would need to infer.

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 revision_id, base_version, summary, and body_markdown are all fully documented in the schema, including the max-255 limit and clear-on-empty rule. The description adds no parameter detail beyond that 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?

States a specific verb (update) and resource (draft document revision), plus the exact fields affected (body Markdown and/or summary). This clearly separates it from create-document-revision-tool and publish-document-revision-tool without the agent needing to open 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?

Explicitly states the when-not condition (published revisions cannot be edited; create a new draft first) and steers toward the preferred path (rich-text drafts via create-document). It names the sibling alternatives but doesn't spell out every route, so slightly short of fully explicit routing.

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