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 indicate idempotentHint=true. Description adds key behavioral details: returns existing draft if one exists, and that file-based documents cannot be edited via ChatGPT. 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 concise sentences that front-load the core purpose and then add a critical caveat. Every sentence serves a clear purpose without redundancy.

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

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

Given moderate complexity (3 parameters, output schema exists), description covers main behavior, idempotency, and a usage constraint. Could briefly mention return value but output schema likely handles that.

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 covers all parameters with descriptions (100% coverage). Description adds value by explaining that body_markdown 'copies the previous rich-text content when available' if omitted, which goes 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?

Description clearly states it creates a draft revision for an existing document, and distinguishes from siblings like publish-document-revision-tool by specifying 'draft'. It also notes idempotent behavior (returns existing draft), which differentiates from creation tools.

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?

Provides clear when-to-use context (after a version is published) and a specific when-not-to-use (file-based documents cannot be edited via ChatGPT, use web app). Does not explicitly name sibling alternatives but the guidance is still helpful.

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 convey this is a non-readonly, non-idempotent write operation. The description adds behavioral context beyond what annotations provide: new documents start as a 'draft' revision and the tool 'Does not publish.' This is operational detail that directly affects how an agent sequences the workflow. 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?

Two sentences with zero filler. The first states the core operation; the second delivers the critical constraint ('Does not publish') and routes to the right sibling. Information is front-loaded and 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 an output schema present, return values need no explanation, and 100% parameter coverage handles invocation details. The description covers the critical workflow gap (draft vs. published state) and names the successor tool. The residual gap is the lack of explicit guidance distinguishing it from create-document-revision-tool, though that is reasonably inferable from 'new.'

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% — name, summary, and body_markdown are each documented in the schema. The description's phrase 'Optionally set the initial body as Markdown' is largely redundant with the schema's 'Optional Markdown body for the first draft.' Baseline 3 applies because the schema carries the parameter-documentation burden.

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

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

The description states a specific verb and resource: 'Create a new ClearPolicy document with a draft rich-text revision.' It also differentiates from siblings by clarifying that the tool creates the document along with its initial draft revision, which distinguishes it from create-document-revision-tool, and the 'Does not publish' clause separates it from publish-document-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?

The description explicitly names the follow-up tool: 'use publish-document-revision after the user reviews the draft,' which tells the agent when this tool alone is insufficient. However, it never explicitly contrasts with create-document-revision-tool for adding revisions to existing documents; the distinction is implied by the word 'new' 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?

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?

The description adds the return format (body as Markdown/text) beyond the annotations (readOnlyHint, idempotentHint). It does not detail error states or authorization needs but is adequate given the safe read nature.

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 concise sentences with no waste. First sentence states purpose and output, second provides usage tip. Front-loaded and efficient.

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 existence of an output schema, the description covers core usage and output format adequately. It lacks discussion of potential errors but is complete for a read-only tool.

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

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

Schema coverage is 100% (revision_id described as ULID). The description adds value by linking the parameter to IDs from other tools, enhancing understanding of its origin.

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 retrieves a document revision with its body as Markdown/text for reviewing or editing. It distinguishes itself from sibling tools like create-document-revision-tool and update-document-revision-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 provides explicit guidance on when to use (to review/edit a draft) and where to get the revision IDs (from create-document or get-document). It lacks explicit when-not-to-use instructions but gives sufficient context.

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

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

Annotations already declare 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?

Beyond the destructiveHint annotation, the description discloses concrete side effects: it generates a PDF and a document hash)Skip confirmation step, and positions publishing as a step before signing. No contradiction with the read/write/destructive hints.

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, then effects, then required confirmation and next step. No filler or repetition of the schema.

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

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

With a single well-documented parameter, the destructive nature is annotated, and the description covers purpose, side effects, and the follow-up action. It does not describe prerequisites or state constraints for the revision, but the overall workflow 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?

The schema already documents revision_id as 'The ULID of the draft revision to publish' with 100% coverage. The description adds no additional parameter-level nuance, so it stays at the baseline.

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

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

The description names a specific action ('Publish a draft document revision'), the exact resource ('document revision'), and the purpose ('so it can be sent for electronic signature'). It clearly differentiates this publishing step from related siblings such as send-signing-request and update-document-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?

It gives useful procedural guidance: confirm with the user before publishing an irreversible actionaine and use send-signing-request afterward. It does not spell out when to avoid publishing (e.g., wrong revision state), but the workflow direction is clear.

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

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

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 indicate destructiveHint=true and idempotentHint=true, but the description adds important context: it can only modify draft revisions, not published ones, and it replaces the body content. It also explains that passing empty summary clears it. This goes beyond what annotations provide. The idempotentHint is consistent with the replace semantics of body_markdown, adding credibility.

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

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

The description is compact, consisting of two sentences plus a tip. It front-loads the core purpose and immediately notes the critical constraint about published revisions. The recommendation for rich-text drafts is a useful addition without fluff. It could be slightly more structured but is efficient.

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 that there is an output schema (though not detailed in context signals), the description does not need to explain return values. For a mutation tool with this complexity, it covers the key constraints (draft-only, body replacement, summary clearing) and usage guidance. It is complete for an agent to decide when to invoke it.

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

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

Schema description coverage is 100%, so the schema itself already documents each parameter. The description clarifies that body_markdown is required unless only updating summary, and that summary can be cleared with empty string. However, it doesn't fully specify the side effects on existing attributes beyond body replacement, though the schema already covers that. 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 clearly states the specific verb 'update' and the resource (a draft document revision body and/or summary). It also differentiates itself from published revisions and mentions an alternative tool (create-document) for rich-text drafts. This distinguishes it from sister tools like publish-document-revision-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 states when to use this tool: for updating draft revisions only, and that published revisions cannot be edited and instead require creating a new draft first. It also explicitly recommends prefer rich-text drafts via create-document, giving clear alternatives for other scenarios. This is complete guidance.

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