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 declare destructiveHint=false, though not readOnlyHint (which is false, indicating mutation). The description doesn't contradict annotations and adds the behavioral context that the document is created as a draft, not published. However, it doesn't detail outcomes like what happens on revision creation or any unexpected side effects, but given annotations cover basic safety, this is adequate.

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 efficient information: states the action, optional body format, and the exception to not publish. No fluff, key behavioral note front-loaded.

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

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

Given the tool's moderate complexity (3 parameters, output schema present), the description covers the essential usage and behavioral constraints. The output schema is richer, so the description doesn't need to explain return values. It adequately informs the agent on how to invoke correctly, with minor gaps on revision details that are not critical.

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

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

Schema description coverage is 100%, so all parameters are already documented in the schema. The description adds context that body_markdown is Markdown for the first draft, which slightly enhances the schema's generic wording, but doesn't go beyond that. Baseline 3 is appropriate as 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 tool's specific purpose: creating a new ClearPolicy document with a draft rich-text revision, and optionally setting the initial body as Markdown. It distinguishes this action from publishing, which is a separate tool. This verb+resource+scope combination is precise and 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 explicitly notes that this tool does not publish, and instructs to use publish-document-revision after user review. This provides clear when-to-use and when-not-to-use guidance, routing to the correct sibling 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?

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 disclose readOnly, idempotent, and non-destructive behavior, so the description only needs to add extra context. It does add the useful detail that the response includes signed/unsigned counts, but doesn't go beyond that. 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?

A single, front-loaded sentence that states the action and key output detail without filler. 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?

Simple one-parameter read tool; annotations already disclose safety, and the output schema covers return value details. No missing context needed to invoke it correctly.

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

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

The single parameter is fully documented in the schema as a ULID; description adds no additional semantic detail. With 100% schema 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 specific verb and resource ('Get details of a document') and adds concrete differentiating information about signed/unsigned counts. It is clear that this is the document-level read tool, though it doesn't explicitly distinguish itself from get-document-revision-tool or the 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?

There is no guidance on when to use this tool versus alternatives like list-documents-tool, query-docs, or search-docs. The intended context is inferable from the name and one-liner, but the description never explicitly states selection criteria or exclusions.

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

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

Annotations already declare readOnlyHint=true 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds context about the document scope ('available to send for electronic signature') but does not disclose behaviors like pagination, sorting, or the effect of the include_archived flag. With annotations covering safety, this is acceptable but minimal.

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 wasted words. The core purpose is front-loaded, and the usage instruction follows naturally. 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?

Given the presence of an output schema and the simplicity of the tool (two optional parameters), the description is nearly complete. It covers what the tool does and when to use it. It does not mention the optional filters, but those are in the schema. Minor gap: it doesn't explicitly state that it lists all documents when no filters are provided, but that is implied by 'browse'. A 4 is fair.

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 and include_archived) are already documented in the input schema. The description adds no additional parameter semantics, such as how filters combine or the meaning of 'available to send' relative to the filters. Baseline 3 is appropriate when the schema fully documents the parameters.

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 ('Find') and resource ('documents available to send for electronic signature'), clearly distinguishing it from sibling tools like search-docs or query-docs. The phrase 'available to send' adds scope beyond just listing all documents, making the 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?

It explicitly says 'Use this to browse what documents the organization has ready to send,' giving a clear usage context. However, it does not mention alternatives or when not to use it (e.g., for searching archived docs or other collections), which would strengthen differentiation from siblings like search-docs.

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=true, idempotentHint=true, and destructiveHint=false, so the description's role is to add behavioral context. It fails by listing statuses 'pending' and 'signed' that do not exist in the schema enum (which includes created, sent, viewed, attested, expired, canceled, bounced, failed, complained, suppressed). This misleads the agent about valid filter values, compromising behavioral transparency.

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 captures the core action and filtering options. It is concise and to the point. However, the inaccuracy in the status examples ('pending, signed') slightly detracts from clarity, though the structure itself is sound.

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

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

The tool has an output schema (as indicated), so return values are not the description's responsibility. The description adequately covers what it does and its filters, but the status terminology mismatch and the absence of any note about all parameters being optional (though in schema) leave a minor completeness gap. It is sufficient for a simple read-only list operation but not fully precise.

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 each parameter already has a description. The tool description restates the filtering dimensions (document, person, status) but adds no new meaning beyond the schema. It does not clarify the enum mismatch, so it provides no additional semantic value. 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 states a clear purpose: checking who has signed a document and who hasn't, with filters for document, person, or status. This is a specific verb-resource combination ('list signing requests') that distinguishes it from the singular 'get-signing-request-tool' and other signing-related tools. The phrase 'track compliance' adds context without ambiguity.

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 it (for compliance tracking and filtering) but does not explicitly mention when NOT to use it or name alternatives like get-signing-request-tool for details, send-signing-request-tool for creation, or cancel-signing-request-tool. The guidance is implicit rather than explicit, leaving the agent to infer the boundaries.

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.