Foliyo

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description nevertheless adds value by preempting the likely confusion with a web-extraction tool ('does not extract a website') and by listing what both forms include (house writing style).

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 primary retrieval behavior and ending with the negative scope boundary. Slightly routine, but every sentence carries information.

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

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

With no output schema, the description carries the return-value burden and does so adequately by enumerating the brand sheet's contents and the shared writing style. It does not describe the guide payload's shape, a minor gap for a one-parameter read 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% (baseline 3), but the description adds meaning the schema cannot: the absence of the name parameter is not merely optional, it switches the tool into brand-sheet mode. That conditional semantics is a genuine addition beyond the parameter's own 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?

States a specific verb (retrieve) and two precisely delimited resources: a named saved design guide, and the workspace brand sheet when no name is given. The dual behavior is spelled out rather than left implicit.

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

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

Explicitly tells the agent the selection condition: supply a name for a guide, omit it for the brand sheet. It also distinguishes this from sibling retrieval tools by naming the brand sheet's contents (projects, identities, audiences, guide index), though it does not name get_project/get_sender as alternatives.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuinely useful context beyond the annotations by stating what is NOT destroyed ('Does not delete previously published pages'), which an agent could not infer from the structured fields alone.

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 followed by the key caveat. No filler, though it is terse enough that it leaves obvious gaps unaddressed.

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 destructive tool with no output schema, the description covers the action, its scope, and the most important side-effect boundary, while annotations carry the safety and idempotency signals. Only the identifier's meaning is left unexplained.

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 0% for the single 'id' parameter, and the description never clarifies what the id refers to, its format, or whether it identifies a workspace-scoped audience. The phrase 'from this workspace' gives only a faint hint about the identifier's scope, so the description fails to compensate for the coverage gap.

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

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

States a specific verb and resource ('Remove a saved audience') and scopes it to 'this workspace', which clearly distinguishes it from get_audience and save_audience. It stops short of naming a sibling, so it is clear but not maximally differentiated.

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 delete operation but gives no explicit when-to-use vs when-not guidance, nor does it route to alternative tools like get_audience or save_audience. The caveat about published pages is a scope boundary, not usage 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, idempotentHint=true and readOnlyHint=false, so the safety posture is covered structurally. The description adds genuine behavioral context beyond that by clarifying that published pages survive the deletion, which is not derivable from the 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 short sentences, front-loaded with the core action and immediately followed by the scoping caveat. Nothing is redundant or padded.

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 delete whose annotations carry the destructive/idempotency profile, the description covers purpose and the key side-effect boundary. It omits permission requirements and whether the deletion is recoverable, but those gaps are minor at this complexity.

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 0% and the description says nothing about the single required 'id' parameter — its format, whether it is workspace-scoped, or how to obtain it. With one undocumented parameter the description should compensate and it does not.

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

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

States a specific verb (Remove) and resource (a saved guide) scoped to this workspace, and the follow-up sentence disambiguates it from a page-deletion operation. An agent can distinguish it from siblings like delete_page or delete_audience without opening any schema.

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

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

Usage is implied by the name and the 'does not delete previously published pages' boundary, but there is no explicit when-to-use guidance and no routing to alternatives (e.g., unpublishing vs deleting, or restore_revision for recovery). Adequate but with clear gaps.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds genuinely useful behavioral context: the deletion is permanent and the URL breaks immediately. It does not mention auth requirements or recovery options.

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 followed by the user-visible consequence. Nothing is wasted.

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

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

For a single-parameter destructive tool whose safety profile is already in annotations and whose parameter is documented in the schema, this covers the essentials. Recovery/undo and permission requirements are the only notable omissions.

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?

One parameter with 100% schema description coverage ('slug or id'), so the schema carries the semantics. The description adds nothing about the id format, which is fine but earns no credit beyond 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?

States a specific verb and resource: permanently remove a published link. The title and 'link' wording distinguish it from the delete_audience/delete_guide/delete_project siblings, though it does not name them explicitly.

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

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

No guidance on when to delete versus alternatives such as unpublishing, revoking, or restoring a revision via restore_revision. The agent must infer usage context entirely.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=false, so the safety profile is covered. The description adds one genuinely useful non-obvious fact — that published pages survive the deletion — but omits irreversibility, permission requirements, and whether pages/revisions inside the project are cascaded away.

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 with no filler; the primary action is front-loaded and the non-obvious side-effect caveat follows immediately. Nothing redundant with the title.

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

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

Annotations carry the destructive/idempotent profile, so the description does not need to restate them. It is still thin for a destructive operation: no confirmation of what else is destroyed, no permission or recovery context, and the sole parameter's meaning is left implicit.

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

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

One required parameter with 0% schema description coverage; the description never clarifies whether 'id' is a project identifier, slug, or name. For a single-identifier delete tool the convention is largely guessable, so the baseline 3 is appropriate rather than a penalty.

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

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

States a specific verb and resource ('Remove a saved project') and bounds the scope ('from this workspace'). The resource noun cleanly separates it from sibling delete tools such as delete_page, delete_guide, and delete_audience, so an agent can route without opening the schema.

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

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

Usage is implied by the verb and scope, but there is no explicit when-to-use guidance, no mention of alternatives (e.g., save_project for modifying, get_project for reading), and no stated prerequisites or preconditions for 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 establish a safe read-only, idempotent, non-destructive profile, but the description adds real context beyond them: authentication is required, the page must be owned by the caller, download availability is conditional on a response flag, and the operation does not render or publicize the PDF. It also notes offline PDFs carry no access gate, analytics, or live interactions. Missing only detail on the management links themselves.

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 sentences, front-loaded with the return contents and followed by the conditional logic and scope boundary. Each sentence carries information, though the wording in the second sentence is slightly dense.

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 tool with no output schema, the description effectively specifies what comes back (link set plus directDownloadAvailable flag) and the conditions under which each link is usable. Annotations cover the safety profile, leaving little for the description to add beyond id semantics.

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 one parameter at 0% schema description coverage, the description must compensate. It only indirectly does so: 'owned page' implies id is a page identifier that must belong to the caller, which conveys an ownership/authorization constraint but no format or accepted-value detail.

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

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

States a specific verb and resource: returning export links (browser-print, PDF-download, management) for an owned page. It also draws a boundary against siblings like publish_html/preflight_html by clarifying it does not render or publicly expose a PDF. It never names an alternative tool, so sibling differentiation is implicit rather than explicit.

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 gating rule for direct download (only when directDownloadAvailable is true, otherwise use browserPrintUrl) is a genuine usage instruction. However, there is no guidance on when to choose this tool over preflight_html, publish_html, or get_page, so the agent must infer the situation.

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 need not restate safety. It nonetheless adds useful behavioral context: the return payload includes recoverable access codes, recipients, and view counts, plus an explicit 'Does not modify pages' reassurance.

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

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

Three tight sentences, front-loaded with the core action and searchable fields, followed by return contents and a scope note. Minimal waste, though the closing 'Does not modify pages' could be trimmed given the readOnly annotation.

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

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

With no output schema, the description usefully enumerates the returned data (links, access codes, recipients, view counts), and all three optional parameters are covered by the schema. Adequate for a low-complexity, zero-required-param search 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 all three optional filters are already documented in the schema. The description paraphrases the same concepts (title, slug, project, recipient) without adding syntax or format detail, which meets the baseline for a fully documented schema.

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

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

States a specific verb ('Search') and resource ('links in the authenticated workspace') and enumerates the searchable dimensions (title, slug, project, recipient name/email). No sibling tool does link lookup, so the purpose is unambiguous and distinct.

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 usage context ('Useful for finding an existing deliverable or its sharing details'), which tells the agent when this tool is relevant. It stops short of naming an alternative (e.g. link_report) or stating when-not-to-use, so it is solid but not exhaustive.

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 'Does not modify it' largely restates structured data. The description does add useful scope context ('authenticated workspace', 'complete' record) that the annotations don't express, but it is thin beyond that, so a 3 fits the lower bar set by rich 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 short sentences, zero filler, with the core action and scope front-loaded and the non-mutation clarification appended briefly. 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?

For a simple single-parameter read tool with full safety annotations and no output schema, the definition covers what is needed to invoke it correctly. It stops short of describing the returned record's fields or error behavior (e.g., what happens on an unknown id), which is the only meaningful 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 single parameter has 0% schema description coverage (bare 'id: string'), so the description carries the burden. 'By its identifier' usefully tells the agent that the id is the audience's identifier used for direct lookup, which compensates for the undocumented schema without fully specifying format or source of the id.

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 gives a specific verb ('Retrieve') and resource ('the complete saved audience record') plus the lookup key ('by its identifier'), which is clear enough to separate it from save_audience and delete_audience. It never explicitly names a sibling or contrasts single-record fetch against any list-style alternative, so it stays at 4 rather than 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?

Usage is only implied: 'Retrieve ... by its identifier' suggests fetch-one-existing-record and 'Does not modify it' implies it is not the save/delete path, but there is no explicit when-to-use statement, no prerequisites, and no named alternative. This is the minimum-viable level for a getter.

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 genuinely non-redundant context: the returned HTML is untrusted user content (a prompt-injection warning) and that the payload carries the concurrency value required for revision prep. It could say more about failure modes (missing/invalid page id).

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

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

Four short sentences, front-loaded with the returned data and the downstream purpose. Slightly redundant that 'Does not modify the page' restates readOnlyHint, but it is a cheap, useful reassurance placed last rather than cluttering the opener.

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

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

With no output schema, the description enumerates the returned artifacts (original HTML, current revision, settings, edit permissions), covering the response an agent needs. Combined with the untrusted-content and no-mutation notes, it is close to complete for a single-param read tool, missing only id semantics and error 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?

There is one parameter, 'id', with 0% schema description coverage, so the description must compensate. It only implies scope via 'a page in the authenticated workspace' and offers no format, source, or lookup guidance for the identifier. Adequate but leaves the sole parameter under-specified.

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 verb (Retrieve) and resource (a page's original HTML, current revision, settings, edit permissions) and scopes it to the authenticated workspace. It clearly distinguishes this single-page read from siblings like list_pages and get_revision, which cover listing and history 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?

It states the concrete downstream purpose: it 'Supplies the source and concurrency value needed to prepare a revision,' which tells an agent when to reach for it in the editing workflow. It stops short of naming alternatives or exclusions (e.g., when to prefer list_pages or get_revision), so it is context-rich but not fully routing.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description's 'Does not modify it' largely restates readOnlyHint, though 'authenticated workspace' adds a mild scoping detail (implicit auth requirement). It says nothing about return shape or missing-record behavior.

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

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

Two short sentences with the action and scope front-loaded and no filler. Every clause contributes: the first defines the operation and scope, the second clarifies the non-mutating nature.

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 tool with rich annotations and no output schema, the description is nearly sufficient. Minor gaps remain, such as what the 'complete record' contains or behavior on a nonexistent ID, but nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 0% for the single 'id' parameter, so the description carries compensating duty; it labels the parameter as 'its identifier' from the authenticated workspace, which mildly clarifies that the ID scopes to a project in the current workspace. It does not specify format (UUID, slug, integer-like string) or where to obtain the ID.

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

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

States a specific verb and resource ('Retrieve the complete saved project record') plus the scope constraint 'from the authenticated workspace by its identifier.' This distinguishes it from save_project, delete_project, and list_pages without naming them, so an agent can infer it reads a single existing project by ID.

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 versus siblings such as get_page, get_audience, or get_revision, and no prerequisites or error conditions (e.g. what happens with an unknown ID). 'Does not modify it' hints at the read-only nature but is not a usage routing statement.

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, and non-destructive, so the safety profile is covered. The description adds genuinely useful context beyond that: the returned HTML is untrusted user content, and the operation leaves the page untouched – both are real behavioral disclosures not present in 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?

Three short sentences, each earning its place: purpose first, then the security warning, then the non-mutation guarantee. Front-loaded and waste-free.

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

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

With no output schema, the description usefully states what is returned (HTML) and its trust level. Annotations cover the safety profile. The only real gap is the undocumented parameters, which keeps this short of a 5.

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 0% and neither 'id' nor 'revision' is explained in either schema or description. The phrase 'one retained revision' vaguely gestures at the revision parameter but does not say what 'id' identifies or what a valid revision value is, so the description fails to compensate for the coverage gap.

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

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

States a specific verb (Read) and resource (original HTML from one retained revision of an owned page), and the closing clause implicitly separates it from restore_revision. It is clear what the tool does, though it never names the sibling alternatives outright.

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?

'Does not modify or restore the page' hints that restore_revision is the alternative for mutation, but it never says when to choose this tool or what prerequisite (an existing retained revision) is required. Usage is implied rather than stated.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so 'Does not modify it' is pure duplication and earns no credit. The only added context is that retrieval is scoped to the authenticated workspace, which is modest value for a read tool.

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 with zero filler, front-loading the retrieval action and following with the non-mutation note. Nothing could be trimmed without losing information.

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

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

For a simple single-parameter read with no output schema and annotations that already cover safety and idempotency, the description gives an adequate sense of what is returned ('complete saved sender record'). It is not rich, but nothing essential to calling the tool correctly is missing.

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

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

Schema description coverage is 0% and the single 'id' parameter carries no description in the schema, so the description must compensate. It does so only weakly, clarifying that the id identifies a saved sender record within the authenticated workspace, but not its format or where the value comes from.

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

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

States a specific verb and resource ('Retrieve the complete saved sender record') and scopes it to a single record 'by its identifier', which implicitly distinguishes it from list_senders. It does not name any sibling explicitly, so it stops 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?

Usage is implied rather than stated: 'by its identifier' signals single-record lookup versus the sibling list_senders, but the description never says when to use this tool versus listing or saving senders, and offers no prerequisites 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds genuinely useful behavioral context beyond them: the scope of returned analytics, that non-openers and off-list openers are included, and that detailed analytics are gated behind Pro.

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?

Effectively one dense sentence listing return contents plus a short entitlement caveat. It is front-loaded with the core value and no clause is wasted, though the single sentence is long.

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

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

With no output schema, the description must convey what comes back, and it does so thoroughly (views, read time, section breakdowns, per-recipient opens, non-openers, off-list openers). For a one-parameter read tool with full annotation coverage, this is nearly complete; only explicit usage guidance 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?

There is a single parameter with 100% schema description coverage ('The link's slug or id'), so the schema already carries the semantics. The description adds no syntax or format details about the id, making the baseline 3 appropriate.

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

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

The description states a specific resource (analytics for one link) and enumerates the concrete outputs — views, read time, section breakdowns, per-recipient opens — plus the non-opener and off-list cases. It is clearly distinguishable from the CRUD-oriented siblings (get_page, list_pages, etc.), though it does not explicitly name an alternative.

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

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

Usage is implied: fetch the report for a single link. There is no explicit when-to-use/when-not guidance or named alternative, but the entitlement note 'Detailed analytics require Pro' gives a real gating condition the agent must know.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered; the description still adds ordering semantics ('most recent first'), the returned contents ('recoverable access code and intended recipients'), and an explicit non-mutation statement. It omits pagination or result-count limits, which is the main gap for an unbounded list tool.

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 scope and ordering before the filter and return details. 'Does not modify pages' is mildly redundant with the readOnlyHint annotation but is short and harmless.

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

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

With no output schema, the description carries the return-shape burden and does so ('each link, its recoverable access code and intended recipients'), plus ordering. For a list tool, the absence of pagination or maximum-result guidance is the remaining shortfall.

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 the single 'project' parameter, and the description only restates it as an optional filter ('optionally filtered by project'). No additional syntax or matching semantics are added, so 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?

States a specific verb and resource ('List links') plus scope ('published in the authenticated workspace') and ordering ('most recent first'). An agent can distinguish this from get_page or find_link, which fetch or search a single link rather than enumerating the workspace.

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 optional project filter implies when to use the narrow form, but there is no explicit when-not guidance and no mention of sibling alternatives such as find_link for targeted lookups. Usage must be inferred from the scope sentence.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description's 'without changing the page' largely restates the read-only annotation, and it adds only the mild detail that both current and retained revisions are returned. It contributes little beyond the structured fields.

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 with zero filler; the verb and scope lead, and the read-only caveat follows economically.

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

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

No output schema exists, so the description should clarify the return shape (revision entries, ordering, pagination), which it does not. Annotations cover the safety profile, so only the missing id meaning and return-shape details hold it back.

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 required 'id' parameter has 0% schema description coverage, and the description never says what the id identifies (page, guide, project, etc.) or its format. With an undocumented parameter, the description needed to compensate and does not.

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

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

States a specific verb ('List') and resource ('content revisions') and clarifies the scope as both current and retained previous revisions. It is distinguishable from get_revision (singular) and restore_revision by resource semantics, though it doesn't explicitly name those 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 when-to-use guidance, no mention of when to prefer get_revision or list_pages, and no prerequisites or exclusions. 'Without changing the page' hints at read-only intent but does not route the agent among alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds scope context ('saved on the workspace, available in every connected tool') but says nothing about ordering, pagination or whether an empty result is possible.

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 with no filler; the resource and scope come first and nothing is repeated from the title.

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, non-destructive list tool with no output schema, this is nearly complete. The only soft spot is the phrase 'available in every connected tool,' which is vague about what 'connected tool' means.

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

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

The tool takes zero parameters, so the schema needs no parameter documentation and the description correctly offers none. Baseline 4 applies for a no-parameter tool.

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

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

States a specific verb ('List') and resource ('sender identities saved on the workspace'), which separates it from get_sender (singular fetch) and save_sender (mutation). It does not explicitly name siblings, but the plural-list framing is distinct enough for an agent to select correctly.

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 when-to-use guidance is given: nothing states that this returns all senders vs. get_sender for a single one, nor any precondition for calling it. Usage is only implied by the verb 'List'.

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 and closed-world, so the safety profile is covered. The description adds genuinely new behavioral context: no visual rendering, no external URL fetching, and that it returns ready, issues and prepared HTML. It could still say more about what 'issues' look like or whether failures block publishing.

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 scope, followed by return values and exclusions. 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?

Return values are named so no output schema is needed, and the annotations cover the mutation/safety dimension. Missing pieces are minor: no guidance on asset limits (maxItems 64), and the id-vs-html interaction used for accidental content removal is unexplained.

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 only 33%, so the description must carry weight — it partially does by clarifying that assets are 'inline explicit' image/font/CSS, mapping to the assets array. However, the required html parameter and its relationship to the optional id are never explained, so gaps remain for a 3-param tool.

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

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

States a specific verb (validate) and resource (static HTML plus inline image/font/CSS assets), and the phrase 'without publishing' cleanly distinguishes it from the sibling publish_html. An agent can identify the job without opening the schema.

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

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

'Without publishing' implies the pre-publish validation workflow against publish_html, and 'Does not visually render or fetch external URLs' supplies explicit exclusions that tell the agent when this tool is the wrong choice. It stops short of naming publish_html as the follow-up, so it is not a full when/when-not statement.

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, destructiveHint=false and a closed-world scope, so the safety profile is fully covered without the description. The description reinforces the non-mutating behavior ('Does not publish or modify records') and lists what gets retrieved, but adds no new trait such as auth requirements, rate limits, or whether the questions are regenerated on each call.

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 retrieval scope, followed by the workflow purpose and the non-mutation boundary. Every clause carries information and nothing is repeated from the name or title.

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

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

With no output schema, the description correctly enumerates what the caller receives, and the annotations handle the safety profile. The remaining gaps are minor: no hint about how the numbered questions should be answered or which sibling call follows the preparation step.

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 0% for the single 'project' parameter, so the description must carry the burden. It does add two things the schema does not: that the project is optional and that it must be a 'saved project,' but it never specifies the expected format (identifier vs. display name) or how a missing value changes the returned question set.

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 concrete verb (retrieve) and enumerates the resources returned: account and plan context, an optional saved project and its design guide, and numbered creation questions. It also frames the tool as 'the first-use workflow for creating a Foliyo,' which separates it from the save_/get_/publish_ siblings without naming one directly.

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 states the context explicitly: this is the first-use workflow for creating a Foliyo, so the agent knows to call it at the start of a creation flow. The closing clause 'Does not publish or modify records' provides an exclusion, though no sibling alternative is named as a routing target.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, openWorldHint=true, so the safety profile is covered. The description still adds real behavior: return values (URL, PIN, recipient links), that new shares mint a PIN, that updates preserve omitted settings and need the current revision, that verified email access requires Pro, and that notification email is opt-in. It never states what is destroyed on update, which keeps it short of a 5.

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

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

Four front-loaded sentences, led by the core action, with each remaining sentence carrying distinct information (return values, create/update semantics, gate/Pro constraint, notification default). It is dense but not padded; the third sentence is somewhat crammed but still 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 22-parameter tool with no output schema, the description does supply the return shape (URL, PIN, recipient links) and the create-vs-update contract. It omits the surrounding workflow (validation via preflight_html, fetching the revision via get_page, identity/audience lookup via brand_guide), which are relevant for correct invocation of a tool this complex.

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 91%, so the schema already documents nearly every parameter, including nuanced guidance on password, notify, project, and sender. The description only alludes to a few (generated PIN, personal recipient links, revision) without adding syntax or formats beyond the schema, so the baseline 3 applies.

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

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

States a specific verb pair and resource: 'Create or update a Foliyo link from finished static HTML.' An agent immediately knows this is the write tool for publishing HTML. It does not name or contrast any sibling (e.g., preflight_html, prepare_foliyo, get_page), so differentiation is left to the tool list rather than the text.

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?

Implied usage is present: 'New shares default to a generated PIN; updates preserve omitted settings and require the current revision' tells the agent the create-vs-update distinction, and the Pro note scopes the verified email path. However, no alternatives are named (preflight_html for validation, get_page for the revision needed on updates, brand_guide for senders/audiences), so routing guidance is incomplete.

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, but the description adds substantial traits beyond them: what is preserved (URL, access policy, recipients, tracking), the optimistic-concurrency requirement on expectedRevision, and that no notification email is sent. These are exactly the operational facts an agent needs and are not derivable from the annotations or 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?

Three sentences, front-loaded with the action and scope, then side-effect preservation, then the concurrency precondition and email behavior. Every sentence carries distinct information with no 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 mutation tool with no output schema and three undocumented parameters, the description covers action, preserved state, concurrency safety and notification behavior well. It is only slightly short of complete because identifier semantics and any permission/ownership requirements beyond 'owned' remain unstated.

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 0%, so the description carries full burden for three required params. It explains expectedRevision ('current expectedRevision to prevent overwriting newer changes') but leaves id (page vs revision identifier) and revision (which revision is restored) to inference from 'owned page' and 'retained content'.

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

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

States a specific verb and resource ('Restore retained content as a new revision of an owned page'), which cleanly separates it from the read-only siblings get_revision and list_revisions. Scope limitations ('owned page', 'retained content') are included, so an agent knows this is not a generic revision read.

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?

Gives clear context for use: restoring retained content, and the prerequisite that the current expectedRevision is required to avoid clobbering newer changes. It does not name alternative tools (get_revision, list_revisions) or state when not to use it, 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 destructiveHint=true and idempotentHint=true, so the bar is lower, yet the description adds real value by clarifying that the operation is a soft disable that retains history and leaves other recipients untouched — refining what 'destructive' means here. It still omits any mention of permissions or what happens to already-visited links.

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 with no filler; the key scoping fact (history preserved, other recipients unaffected) comes first.

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-required-parameter mutation with 0% schema coverage and no output schema, the description should identify both parameters and any authorization requirement. It conveys only the soft-delete semantics, leaving an agent unable to call it correctly without guessing at the ids.

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 0% and the description does not name or explain either required parameter. It hints that 'recipientId' scopes to one recipient versus 'other recipients', but nothing tells the agent what 'id' refers to (link, document, or project), so the gap is largely uncompensated.

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

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

States a specific verb ('Disable') and resource ('one personal link'), and the qualifier 'preserving its history and other recipients' distinguishes this soft-disable from the delete_* siblings. It is clear without opening the schema, though it never uses the tool's own 'revoke' framing to tie back to the name.

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 clause about preserving history implicitly signals this is the non-destructive alternative to deleting a link, but the description never states when to prefer it over siblings or what precondition (e.g. an active link) applies. Usage 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 destructiveHint=true and idempotentHint=true, so the description's job is to add detail — and it does: it discloses that the full member list is replaced wholesale, that previously published recipient links survive the replacement, and that no email is sent. That is meaningful context beyond the annotations, though it omits what happens to members lacking email addresses.

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 sentences, no filler, and the core replacement behavior is front-loaded ahead of the secondary effects (link persistence, no email). 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?

For a three-parameter upsert tool with a full-coverage schema, explicit annotations, and no output schema, the description covers what an agent needs: mutation scope, replacement behavior, and the non-obvious side effect that published links stay valid. Nothing material 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 description coverage is 100%, so id, label, and members are all documented in the schema, including the in-place update behavior on id reuse. The description only hints at the members' replacement semantics, adding little beyond what the schema already 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?

States a specific verb and resource (save/replace a named recipient group) and immediately clarifies the upsert semantics — the supplied member list replaces the saved list. An agent can distinguish this from get_audience, delete_audience, and list_senders without opening any schema.

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

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

Usage is implied rather than stated: 'save or replace' tells you this is the write path for audience data, and the note about links remaining valid helps scoping decisions. However, it never names an alternative or states when NOT to use it (e.g., vs delete_audience or get_audience), so guidance is only adequate.

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 destructive=true, idempotent=true, openWorld=false; the description corroborates rather than contradicts and adds boundary context (it records a URL but does not fetch it, and does not touch published pages). It stops short of stating what a replace destroys or any permission requirements.

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

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

Two tight sentences with no waste: the action and inputs come first, then the explicit boundaries. Every clause earns its place.

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

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

With rich annotations, 100% schema coverage, and no output schema, the description supplies everything an agent needs to call it correctly: what it stores, required inputs, and what side effects it will not produce. Only the update-in-place consequence of reusing a name is left solely to the schema.

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

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

Schema description coverage is 100%, and the schema already explains the picker handle, the source URL and the markdown content. The description only names the inputs generically, adding no format or constraint detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (save/replace) and resource (named design guide) plus the inputs (markdown, source URL) and what it stores (typography, colour, layout rules). It is clearly distinguishable from delete_guide by action, but never names or contrasts with sibling brand_guide, so sibling differentiation is only implicit.

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

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

Gives explicit negative guidance on when this is the wrong tool: 'Does not visit the source URL, extract website assets or change published pages.' That steers an agent away from assuming crawling/publishing behaviour, though it does not name an alternative tool to use for those cases.

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 disclose write, non-idempotent... actually idempotentHint=true, destructiveHint=true, openWorldHint=true. The description adds that reusing a name updates in place, that existing pages keep settings, and that the hub links and access code are returned – useful context beyond the hints. It does not spell out what 'destructive' means here or what gets overwritten on update, so it stops short of a 5.

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

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

Three tight sentences: what it saves, the optional hub side effect, and the return value. Front-loaded with the verb and no wasted clauses.

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 13-parameter mutation tool with annotations present and no output schema, the description covers the main behaviors, the hub side effect, and the return value. It falls short only on update semantics (what happens to fields not passed) and permission requirements.

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 schema already documents all 13 parameters. The description adds little parameter-level detail beyond what the schema carries, but it does frame the purpose of the hub/gate fields as a group. Baseline is 3; slight credit for grouping the concepts.

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

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

States a specific verb (save/update) and resource (client or project record) and enumerates the fields it manages. Sibling tools save_audience, save_guide, save_sender exist, so the 'client or project record' scope plus the hub-creation side effect clearly differentiates it.

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

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

The description implies this is the tool to persist a project and optionally its hub, and notes that existing pages retain their own access settings, but never states when to use it versus get_project or delete_project, nor prerequisites for hub creation.

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 write/idempotent/destructive, so the description only needs to add context — and it does: Pro-gated logos and Foliyo branding removal, plus the fact that makeDefault repoints future publishing. It still does not say what is overwritten when an existing id is reused (that detail lives only in the schema) or what the call returns.

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 tight sentences, front-loaded with the core action and scoped constraint. The field enumeration ('name, label, logo, accent and footer') borders on restating the schema, but the sentence is short and orients the reader before the Pro caveat.

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 7-parameter mutation with full schema coverage and annotations, the description covers purpose, side effects (makeDefault) and plan gating. The one real gap is that no output schema exists, so the description should state what a successful save returns (presumably the id) — it stays silent.

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 3 is the baseline; the description adds cross-cutting meaning by grouping logo/accent/footer under the paid-plan constraint and by explaining makeDefault's effect on future publishing. It slightly restates fields the schema already documents in richer detail, so it is not a full 5.

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

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

Specific verb + resource: 'Save or update a sender identity used as the letterhead on published pages.' An agent immediately knows this writes sender identities and what a sender is for. It does not explicitly name the sibling it contrasts with (get_sender, list_senders, delete_audience-style siblings), but the resource noun is distinctive enough to route correctly.

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

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

Usage is implied by the purpose ('used as the letterhead on published pages') and the makeDefault sentence hints at a follow-on effect, but there is no explicit when-to-use/when-not guidance or named alternative (e.g. 'use get_sender to read, list_senders to enumerate'). Plan-gating notes are constraints, not selection guidance.

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