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

Annotations already declare readOnlyHint=true, and the description adds useful behavioral context by listing exactly what account details are returned (email, plan, upload size, document count, locked features). It does not disclose other behavioral aspects like response format, but for a read-only account lookup this is sufficient.

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, front-loaded with the core purpose and followed by an actionable usage hint. Every word earns its place; no fluff or repetition.

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

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

For a zero-parameter read-only tool with an output schema available, the description fully covers what the tool does, what it returns, and when to use it. No additional information is needed.

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

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

The tool has zero parameters, so the baseline is 4. The description adds no parameter semantics because there are none to describe, and the schema coverage is 100% by default.

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 returns information about the connected EveryPage account: email, plan, and plan limitations. This is specific and distinguishes it from sibling tools that operate on files, sharing, and webhooks.

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 says to check this before attempting a plan-gated action, giving clear when-to-use guidance. It does not mention when not to use it or name alternatives, but that is less critical for a simple account info 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?

With annotations only indicating readOnly=false, destructive=false, idempotent=false, the description adds meaningful behavioral context: it creates links, attributes reads by name, supports per-recipient overrides, and requires Pro plan. It does not describe any side effects or system behavior in depth, but given the low annotation detail, this is a solid disclosure.

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 deliver the primary purpose, usage constraint, key features, and a requirement. Every phrase earns its place, with no filler or repetition of schema details.

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 (not shown, but present), so return values are covered. The description covers purpose, usage, constraints, and optional features, making it complete for an AI agent to decide when and how to invoke it, especially given rich sibling context.

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

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

Schema coverage is 100% and parameters are well-described, so the baseline is 3. The description adds value by explaining that all recipients should be passed in a single call and that per-recipient overrides exist, tying the schema's nested properties to the tool's purpose. This enriches the schema without redundancy.

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 ('Mint') and clearly identifies the resource (tracked links per recipient for a document) and the core value proposition (per-recipient attribution instead of anonymous totals). It also distinguishes itself from siblings like everypage_share_pdf and everypage_list_variants by focusing on per-recipient creation.

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 clear context for when to use the tool: when per-recipient read attribution is needed. It also gives an operational guideline ('Pass every recipient in a single call') and a prerequisite (Pro plan). It doesn't explicitly name alternatives or exclusions, but the implied contrast with anonymous totals guides 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 indicate destructive intent, but the description adds crucial context: the document goes to trash (restorable), the share link stops working, and setting purge to true causes permanent irreversible deletion. This goes well beyond the binary annotations and fully informs the agent of side effects.

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, front-loaded with the primary action, and every sentence adds valuable behavioral context (trash, link outage, restoration, purge irreversibility). No waste or 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 only 2 simple parameters, an output schema, and strong annotations, the description covers all essential user-facing behavior: default soft delete, restoration path, and permanent purge option. It does not need to describe return values because the output schema exists.

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

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

The input schema already describes both parameters with 100% coverage ('file' as UUID/short link/URL, 'purge' as permanent destruction). The description reiterates purge behavior but does not add new parameter-level meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description states a specific action ('Move an EveryPage document to the trash') and identifies the resource, clearly distinguishing it from sibling tools like share, list, get, or update. It also explains the intent of making the share link stop working.

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 makes it clear when to use this tool (to delete/trash a document) by describing the action and its effects. It contrasts trash vs. purge behavior but does not explicitly mention alternative tools or exclusion criteria, so it falls slightly short of a 5.

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

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

The description reveals that both operations are irreversible, that redaction makes the name permanently unsettable, and that the tool requires the Pro plan. These add behavioral context beyond the annotations' destructiveHint and idempotentHint flags.

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 concise at four sentences, front-loaded with the action, and every sentence adds essential information (modes, GDPR context, irreversibility, plan requirement). No filler or 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?

For a destructive, two-mode tool, the description covers purpose, use case, irreversibility, and prerequisites. With full schema coverage and an output schema, return values do not need explanation. The description is complete enough for an agent to select and 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?

Schema descriptions cover all three parameters, so baseline is 3. The description adds extra semantic nuance for the redact parameter by noting a redacted name can never be set again, which goes beyond the schema's simple boolean description.

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 permanently deletes a per-recipient link or redacts the recipient's name, using specific verbs and a clear resource. It distinguishes itself from sibling tools like everypage_delete_file by focusing on per-recipient links, not entire files.

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 concrete use-case guidance, explicitly recommending redaction for GDPR erasure requests and contrasting it with deletion. However, it does not explicitly name alternative tools or state when not to use this tool, so it falls short of a perfect score.

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 the description adds valuable context about the specific fields reported (share links, protection, liveness) and accepted input formats. It does not contradict annotations and goes beyond the minimal safety disclosure.

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 fluff. The first sentence states the core purpose and the second clarifies input flexibility. Perfectly sized and 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?

With an output schema present and a simple read-only operation, the description fully covers what the agent needs: what the tool does, what inputs it accepts, and what it reports. No critical gaps.

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

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

Schema coverage is 100% with the parameter description already listing UUID, short link id, and share URL. The description repeats this information without adding new semantic detail, so 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 tool looks up a single EveryPage document and reports share links, protection status, and liveness. This is a specific verb-resource pair that distinguishes it from siblings like list_files or delete_file.

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 clearly explains the input forms (UUID, short link id, or browser URL) and the lookup purpose. While it doesn't explicitly say when not to use it or mention alternatives, the context is sufficient for an agent to infer this is for single-document retrieval, not for listing or mutation.

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 the description reinforces a read-only analytics operation. It adds context about the kind of insights returned (views, readers, drop-off) but does not go beyond annotations with additional behavioral details such as plan requirements (which are in the schema) or any side effects. Given annotations cover the safety profile, a 3 is appropriate.

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, front-loaded with the primary purpose, and every word adds value. The first sentence lists concrete deliverables, the second gives relatable examples. No filler or 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?

With a full output schema and annotations covering safety, the description is sufficient for the tool's complexity. It explains what questions the tool answers and what data is provided. It does not mention potential limitations like pagination or scope, but these are not critical for this read-only analytics 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%, so the schema fully documents all three parameters (file, includePages, includeProofing) including plan requirements. The description adds no parameter-specific meanings beyond the schema, so baseline 3 is correct.

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 ('Find out') and resource ('who read an EveryPage document and how far they got'), then lists concrete metrics (views, unique readers, read time, completion rate, countries, drop-off, per-recipient attribution). This distinguishes it from sibling tools like everypage_list_files or everypage_get_file, which are general file operations.

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 use cases ('did they read my proposal?' / 'where do people stop reading?'), which indicates when to use it. However, it does not name alternative tools or state when not to use it, so it falls short of full 5.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is known. The description adds the cursor-based incremental fetch behavior and clarifies the event stream types, which is valuable context beyond the annotation. No contradictions observed. This exceeds the baseline 3.

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 just two sentences. It is front-loaded with the core purpose, then immediately gives a practical use case. Every sentence adds value, with no redundant or filler content.

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

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

With a rich input schema, an output schema, and annotations, the description's addition of cursor semantics and polling use cases makes the tool sufficiently complete. It does not elaborate on error conditions or output structure, but those are partially covered by the output schema. The type-specific cursor constraint is in the schema, so the description's general cursor mention is adequate.

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% for all four parameters, so the schema fully documents each field. The description's mention of event types and polling use case aligns with the 'type' and 'since' parameters but does not add new semantic meaning beyond what the schema already provides. Therefore the 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 identifies the tool as listing recent read activity (view sessions, downloads, gate leads) across EveryPage documents. It specifies the resource and action with enough detail, but it does not explicitly contrast with sibling tools like everypage_get_readership, so it misses the full differentiation for 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 explicit use cases: answering 'has anyone read anything today?' or polling for new reads. This gives clear context on when to invoke the tool. However, it does not mention when not to use it or name alternative tools, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds useful behavioral context like 'newest first' ordering and scope ('on this account'), which are not in the annotations or schema. No contradictions with annotations; openWorldHint=false aligns with the concept of listing documents in this account.

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 tight two-sentence summary, front-loaded with the main action. Every word earns its place: it states what, scope, ordering, and a practical usage hint. No filler or repetition.

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 listing tool with an output schema and read-only annotation, the description is complete. It covers what is listed, what is returned, ordering, and how to filter. The output schema handles return structure, and annotations handle safety. No significant gaps remain.

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

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

Schema coverage is 100%, with both `limit` and `query` described in the schema. The description's mention of using `query` for filtering by name is redundant with the schema's existing description, adding no new parameter semantics. Baseline of 3 is appropriate when schema already documents 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 clearly states the tool's purpose: listing EveryPage documents on the account, with specific details on ordering (newest first) and included data (share links and view counts). This verb+resource structure distinguishes it from sibling tools like get_file (specific file) or delete_file (mutation).

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 guidance on using the query parameter to filter by name, but it does not explicitly contrast with alternatives (e.g., when to use everypage_get_file instead for a single document). The tool's listing purpose is implied, but no when-not-to-use or alternative is 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 readOnlyHint annotation already indicates this is a safe read operation. The description adds value by mentioning the Pro plan requirement and the specific data returned (revoked/GDPR-redacted status), without contradicting 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 a single sentence that is front-loaded with the verb 'List' and conveys all essential information with no filler.

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

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

Given the tool's simplicity (one parameter), the presence of an output schema, and the read-only annotation, the description adequately covers the tool's purpose, requirements, and output details. It is complete for an AI agent to select and invoke 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 coverage is 100% and includes a clear description of the 'file' parameter. The tool description does not add any additional parameter semantics, so 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 tool's action ('List') and resource ('a document's per-recipient links'), and specifies the output details (labels, URLs, revoked/GDPR-redacted). This distinguishes it from sibling tools like list_files or create_variants.

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 clear context on what the tool does and notes the Pro plan requirement. It doesn't explicitly name alternatives or exclusions, but the unique functionality makes the use case evident.

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, so the description adds value by disclosing that 'Signing secrets are never retrievable - they are shown once, when the endpoint is created.' It also mentions health status, giving useful context about response content beyond the schema.

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

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

The description consists of three concise sentences, each serving a distinct purpose: what it lists, an important limitation, and when to use it. No redundancy or filler; 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 has no input parameters, an output schema is present, and annotations indicate read-only behavior, the description fully covers the needed context. It explains the purpose, key limitations, and a practical use case, making it complete for an agent to select and invoke 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?

There are no parameters, so the baseline for parameter semantics is 4. The description does not need to explain parameter meanings since the input schema is empty. It correctly focuses on the tool's purpose and return value characteristics.

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 and resource: 'List the account's webhook endpoints.' It also details what the list includes (events, health) and distinguishes itself from sibling tools like everypage_manage_webhook by focusing on listing and diagnostics rather than management.

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 a clear context for when to use the tool: 'Use this to diagnose an automation that has stopped firing.' It implies this is for reading/diagnostic purposes rather than creating or modifying webhooks, but does not explicitly name alternatives 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?

The description adds several behavioral details beyond the annotations: it mentions that deliveries are 'signed' (a security trait), that test checks reachability, and that creating returns a 'signing secret that is shown only once' – a critical one-time disclosure. These are not present in the annotations and are essential for the agent to inform the user. No contradiction with annotations was found.

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 entire description is two sentences: the first establishes the purpose, and the second lists the actions while adding the one critical nuance about the one-time secret. It is front-loaded with the purpose and wastes no 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 the rich schema (with per-parameter descriptions) and an output schema, the description effectively summarizes the core operations and key behavior (signed deliveries, one-time secret). However, it does not explicitly clarify that test/delete actions require the webhook ID, even though that is implied by the schema description for the 'webhook' parameter. This small gap prevents a perfect score, but the description is otherwise 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 input schema already has 100% coverage with detailed descriptions for every parameter (e.g., 'create: the https:// endpoint' and 'gate.completed (captured leads) requires the Pro plan'). The description only adds high-level context about the overall workflow, not new syntax or format details beyond the schema. Therefore, a 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 opens with a clear high-level statement ('Manage where EveryPage sends event notifications') and then explicitly lists the three operations: create an endpoint, send a test delivery, and delete one. The verb 'Manage' plus the focus on webhook endpoints distinguishes it from sibling everypage_list_webhooks, which only lists webhooks.

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 clearly frames the tool as for managing webhook endpoints, and the parameter descriptions further specify which parameters apply to which action (e.g., 'webhook' for test/delete and 'create:' for others). It also references the sibling everypage_list_webhooks as the source for the endpoint ID, which hints at the alternative for listing. However, it does not explicitly state 'when not to use this tool' or provide exclusions, so it falls short of a full 5.

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

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

Annotations already flag destructive and non-read-only behavior. The description adds that the previous version is unrecoverable and that a Pro plan is required, plus clarifies that existing viewers see the new version. This goes beyond the annotations and provides important usage caveats, though it could mention other potential side effects (e.g., caching).

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 and front-loaded with the core action. Each sentence earns its place: preservation of metadata, immediate visibility for existing link holders, the revival scenario, irrecoverability, and the plan requirement. There is no wasted wording.

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

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

Given the destructive nature and multiple parameters, the description covers the essential behavioral outcomes, prerequisites, and a distinguishing use case. With the presence of an output schema and detailed annotation coverage, nothing critical is missing for an agent to select and invoke the tool 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 input schema already provides descriptions for all four parameters (url, file, path, keepAnchors) with 100% coverage. The description does not add parameter-level detail beyond the schema, so it sits at the baseline for 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 clearly states the specific action (swap/repalce PDF content) and the resource (existing EveryPage link), while emphasizing what remains unchanged (link, QR code, settings, readership history). This distinguishes it from sibling tools like everypage_delete_file or everypage_update_file_settings, which operate on existence or settings rather than the underlying content.

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 provides a concrete scenario ('revive a link that was burned by its view limit') and clearly implies this is the way to change content while preserving metadata. It does not explicitly name alternative tools, but the context makes the intended use obvious compared to settings updates or deletion.

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 mark readOnlyHint false, so the description's 'Upload a PDF' is expected. It adds behavioral details beyond annotations: the share link is tracked, returns an iframe and QR URL, and settings can be applied in the same call. No contradiction.

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

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

Four sentences, front-loaded with the core purpose and outcome. The third sentence about share settings is slightly redundant with the schema but reinforces that settings are applied in the same call; no filler.

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

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

Given 17 parameters, full schema descriptions, and an output schema, the description provides essential orientation: source selection (path/url), output artifacts, and tracking. It does not explicitly state that at least one source is required or how to update/delete the share, but the annotation and schema richness cover most operational details.

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

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

Schema coverage is 100% with all parameter descriptions present, so baseline 3 applies. The description only highlights 'path', 'url', and examples like 'passcode, expiry or download permission', which adds little over 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?

Clearly states 'Upload a PDF to EveryPage and get back a tracked share link, an embeddable iframe, and a QR code URL' – a specific action with a concrete resource and result. It distinguishes from sibling tools (list/get/update) by focusing on the share-creation action.

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?

Mentions 'Give either `path` (a PDF on this machine) or `url` (an https link to a PDF)' – clear usage instruction. Points to 'everypage_get_readership afterwards' as a follow-up, but does not explicitly name alternative share-management tools like update_file_settings or delete_file.

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 critical behavioral note 'Settings that are not mentioned keep their current value' is disclosed, which is essential for partial updates and goes beyond the annotations. The description also correctly implies mutation (consistent with readOnlyHint=false) and idempotency (consistent with idempotentHint=true). No contradictory information.

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

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

Two sentences, front-loaded with the action and resource, and a compact list of affected settings. The 'keep current value' caveat is included in the second sentence without waste. 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?

The tool has 16 parameters, a required 'file', an output schema, and annotations. The description covers the overall purpose and the crucial partial-update behavior. It does not mention plan gating or clearing details, but those are in the schema descriptions. The description is complete enough for correct selection and invocation, though it could have added a hint about when not to use 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?

With 100% schema coverage, the schema already describes each parameter. The description adds high-level value by grouping settings (e.g., 'vanity slug' → slug, 'page range' → pageFrom/pageTo) and by stating that omitted parameters are preserved, which clarifies the semantics of all parameters collectively.

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 ('Change'), identifies the resource ('existing EveryPage document'), and enumerates the share settings it affects. It clearly distinguishes from sibling tools like everypage_share_pdf by focusing on updating an existing document rather than creating a new share.

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 makes clear this is for existing documents and lists the range of settings, implying it is the go-to for altering share settings. It does not explicitly mention alternatives or exclusions (e.g., 'use everypage_share_pdf to create a new share'), but the context of 'existing' provides strong 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 indicate a mutating, non-destructive, idempotent operation. The description adds valuable context by explaining that revoking affects only the specified recipient ('leaving everyone else's alone') and is reversible ('it can be undone'). This goes beyond the boolean flags and clarifies the scope and side effects.

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 three sentences long, with each sentence serving a distinct purpose: listing operations, explaining the revoke behavior, and stating the Pro plan requirement. It is concise with no filler or 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 the 7-parameter schema, the presence of an output schema, and annotations, the description adequately covers the core operations and a key behavioral caveat (reversibility and per-recipient scoping). It omits edge-case details such as invalid input handling, but the schema and annotations fill these gaps, making it 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 every parameter is already described in detail. The description's high-level actions (rename, revoke, restore, change permissions) loosely map to parameters like label, revoked, pageFrom, and allowDownload, but it does not add syntax or interaction details beyond what the schema provides. 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 opens with precise verbs—'Rename, revoke or restore a per-recipient link, or change what that one recipient may do'—clearly identifying the resource and its update scope. This distinguishes it from sibling tools like delete_variant and create_variants, which handle deletion and creation respectively.

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 the use case through the listed actions and notes the Pro plan prerequisite, but it does not explicitly state when to choose this tool over alternatives. No comparisons or exclusions are given, so guidance remains implicit rather than explicit.

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