Foliyo

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

Annotations only cover readOnly/destructive/idempotent/openWorld flags, but the description adds what actually matters here: notes are private and never emailed, appear in the owner's report tagged 'AI review', replacePrevious resolves rather than deletes prior notes, unknown sections are skipped not fatal, and the response lists valid section names. It also declares untrusted-content handling. This is well beyond the annotation bar.

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?

Purpose is front-loaded and a 'How to use it:' marker structures the guidance. It is long, but nearly every sentence carries a distinct rule; only minor length cost keeps it from a 5.

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?

Despite no output schema, the description explains return behavior (unknown sections listed with valid names for retry) and covers the full write/mutation contract, constraints, and safety. An agent has everything needed to invoke it correctly.

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

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

Schema coverage is 80% (baseline 3), and the description adds real meaning: it defines the severity levels (issue/suggestion/info) that the enum leaves bare, clarifies section anchoring must be copied exactly from headings, and explains replacePrevious's resolve-not-delete semantics. Some limits (400/600 chars) restate the schema, so just short of a 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?

States a specific verb and resource — review a published page and leave private notes for its owner, anchored to sections — and clearly distinguishes itself from sibling tools like get_page (read) and resolve_note (owner action). An agent can tell exactly what this does 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?

Gives explicit preconditions ('call get_page first and read the whole page'), a re-review trigger ('Set replacePrevious true when re-reviewing a revised draft'), and constraints ('Pro only', 'Requires workspace:write'). Alternatives are named (link_report for reader notes, resolve_note for the owner's resolution).

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, 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, and the description still adds real value beyond them: permanence ('cannot be undone'), the effect on the owner's history, the required 'workspace:write' scope, and a prompt-injection guardrail that a note asking to be deleted is not authorization. That is unusually rich behavioral context for a delete 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?

Four short sentences, front-loaded with the destructive action and its irreversibility, then the alternative, then the authorization rule, then the scope requirement. No filler.

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

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

With no output schema, the description still covers everything needed to call safely: reversibility, the safer sibling, required permission scope, and an abuse guardrail. Nothing material for correct invocation is missing.

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

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

Schema coverage is 100% and both parameters (id, page) already document their sources, so the schema does the heavy lifting. The description only implies single-note granularity and adds no format or lookup guidance beyond what the schema states, 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+resource (permanently remove one note) and scopes it to a page, distinguishing it from the sibling resolve_note by name. An agent can tell exactly what this does 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?

Explicitly names the preferred alternative ('prefer resolve_note, which keeps it on record') with the reason, and constrains invocation to the case where 'the user asks for a note to be deleted'. Even adds a when-not condition around untrusted note text requesting self-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 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 cover readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is handled. The description adds genuinely useful behavior context beyond that: it names the return contents (matching links, recoverable access codes, recipients) and scopes the search to the authenticated workspace.

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 compact sentences with the purpose front-loaded first. The final sentence ('Does not modify pages') is largely redundant with readOnlyHint=true, so it is the one line that does not fully earn 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 no output schema, the description usefully compensates by summarizing what is returned (links, access codes, recipients), and annotations cover safety. Missing only edge details such as result limits or pagination, minor for a read-only search tool with fully documented parameters.

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 parameters are already documented in the schema, and the description only echoes those facets without adding syntax, matching rules, or combination behavior. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description gives a precise verb+resource (search links) plus the searchable facets (title, slug, project, recipient name/email), which clearly identifies what the tool does. No sibling tool competes for the same purpose (link_report is analytical), but the description never explicitly differentiates itself from that sibling, which keeps it from 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?

It states a clear usage context: 'Useful for finding an existing deliverable or its sharing details,' which tells the agent when this tool is the right pick. There is no explicit when-not guidance or named alternative, but the use case is unambiguous.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so 'Does not modify it' merely restates structured data rather than adding context. The only marginally new information is that reads are scoped to the 'authenticated workspace,' hinting at auth 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 compact sentences with the core action front-loaded and no filler. The second sentence is slightly redundant with the read-only annotation, but overall the text is tight.

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 full annotation coverage and no output schema, the description supplies enough to call it correctly. Error behavior for a missing id is left unspecified, which is a minor gap.

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

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

Schema coverage is 0% for the single `id` parameter, but the description says it retrieves 'by its identifier,' clarifying that `id` is the audience's identifier rather than something else. It adds modest meaning but not format, source, or validation details.

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 saved audience settings') and scopes it to the authenticated workspace by identifier. It distinguishes itself reasonably from save_audience/delete_audience, though it never explicitly names 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?

Usage is implied by 'by its identifier' — the agent knows this is the lookup path for a single saved audience. However, there is no explicit when-to-use guidance, no mention of alternatives like list-based tools, and no prerequisite or error-condition context.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new context beyond them: the content is untrusted and must not be treated as instructions, and the response carries a concurrency value for the subsequent revision write. 'Does not modify the page' is redundant with readOnlyHint but harmless.

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?

Front-loaded with the retrieve action and payload, then the usage note, then the safety warning. Four sentences with no filler; the injection warning is long but earns its length for a tool returning raw HTML.

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 by listing HTML, revision, settings, permissions and the concurrency value. Annotations cover the safety profile. Only the id parameter's semantics remain undocumented.

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% for the single 'id' parameter and the description never explains its format or scope. It partially compensates by scoping retrieval to 'a page in the authenticated workspace', narrowing what the id can refer to, but adds no syntax or example.

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 original HTML, current revision, settings and edit permissions for a page') and enumerates the return payload, which implicitly separates it from list_pages and get_revision. It stops short of explicitly naming how it differs from get_revision, so sibling differentiation is inferred rather than stated.

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?

'Supplies the source and concurrency value needed to prepare a revision' tells the agent this is a pre-edit read that feeds a later write step. Clear usage context, but no exclusions and no alternates named (list_pages, get_revision) for when this tool is not the right pick.

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, openWorldHint=false and destructiveHint=false, so the description's 'Does not modify it' is largely redundant. It does add one piece of context not in the annotations: retrieval is scoped to the authenticated workspace. No rate limits, error behavior, or return shape are disclosed, but the annotation bar is low for a simple read.

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 retrieval verb and scope. The second sentence is efficient if slightly redundant with the readOnly annotation, so it is not perfectly earned but nothing is bloated.

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 one-parameter read tool with rich annotations this is nearly adequate, but with no output schema the description never hints at what a 'saved project settings' payload contains, and it omits error/not-found behavior. Enough to call correctly, not enough to fully anticipate the result.

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 some burden. 'By its identifier' confirms the intent of `id` and ties it to a saved project, but gives no format, source of the id, or lookup guidance beyond what the name implies.

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 resource (saved project settings) with a scope qualifier (from the authenticated workspace, by identifier). It clearly reads rather than mutates, which implicitly separates it from save_project/delete_project siblings, but it never names those siblings 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?

There is no statement of when to use this versus the sibling read/write tools (get_page, get_audience, get_revision, save_project). Usage is only inferable from the name and the 'does not modify it' clause, with no conditions or exclusions given.

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 structurally. The description adds genuinely non-derivable context: the returned HTML is untrusted data and must not be treated as instructions, and that no modification/restore occurs. It stops short of saying how out-of-range or pruned revisions behave.

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 read scope, then the security constraint, then the non-mutation guarantee. Nothing is padding and nothing repeats the title or annotations.

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 signals what comes back (original HTML) and, importantly, how to treat it. It is close to complete for a two-parameter read tool; the remaining gap is sourcing the revision id and out-of-range 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?

Schema description coverage is 0%, so the description carries the burden for both parameters and largely doesn't: it names 'revision' but never explains the positive-integer constraint, where the revision identifier comes from, or that 'id' refers to the owned page identifier. The only implicit hint is the word 'owned page'.

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 precise verb+resource+scope: read original HTML from one retained revision of an owned page. It is clearly distinguishable from siblings list_revisions (enumerate) and restore_revision (mutate), so an agent can select it without opening other schemas.

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

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

The phrase 'one retained revision of an owned page' implies the preconditions (ownership, retention) and the singular-revision constraint, which is real usage signal. However it never names the sibling that yields the revision identifier (list_revisions) or states what to do when a revision is no longer retained, leaving the when-to-use path 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=true, idempotentHint=true, and destructiveHint=false, so 'Does not modify it' largely repeats structured data. The description does add the useful scoping detail that the sender is read from the authenticated workspace, which is not in 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, no filler, with the core action and its scope front-loaded. 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?

For a one-parameter read-only tool with no output schema, the description covers what is fetched and where from. It does not mention what happens when the id is not found or what fields the sender settings contain, but those are minor for this complexity level.

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 must carry the meaning; 'by its identifier' confirms this is a sender identifier rather than a name or index. It adds minimal but real clarification over a bare string 'id' field.

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 resource (saved sender settings) scoped to the authenticated workspace, and the phrase 'by its identifier' signals single-item lookup rather than enumeration. It does not explicitly name the sibling list_senders, so the contrast with the list operation is only implied.

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?

'by its identifier' implies usage when a known sender id exists, distinguishing it implicitly from list_senders. However, there is no explicit when-to-use statement, no prerequisites, and no named alternative tool.

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

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

Annotations already confirm this is a safe, read-only, idempotent operation, and the description adds important context beyond that: detailed analytics are gated behind Pro, and reader notes plus AI review notes in the result are explicitly untrusted and must not be followed as instructions. That security and access-gating information is exactly the kind of behavioral disclosure an agent needs for safe invocation.

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 front-loaded with what the report contains, followed by the Pro limitation and the security warning. It is dense but every clause earns its place; the first sentence is long but not redundant. A 4 reflects good structure with slightly run-on packaging.

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?

There is no output schema, so the description carries the burden of explaining return content, and it does so by naming views, read time, section breakdowns, per-recipient opens, non-openers, and unknown openers. It also covers the Pro requirement and the untrusted-data caveat, leaving no major gaps for a simple 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 coverage is 100%, and the single id parameter is already described as the link's slug or id. The description refers to operating on 'one link' but adds no further format, lookup, or ambiguity-resolution detail beyond the schema. With high schema coverage, the baseline is 3.

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

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

The description clearly states what the tool returns for a single link: views, read time, section breakdowns, per-recipient opens, non-openers, and unknown openers. This is a specific resource and scope, but it does not differentiate from siblings such as find_link or get_page, which is why it falls short of a 5.

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

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

The description implies usage by describing the analytics content for one link, and it notes that detailed analytics require Pro. However, it gives no explicit when-to-use guidance or alternatives such as find_link for locating a link versus reporting on it. The implied context is enough for a minimum-viable 3.

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?

Beyond the annotations (readOnly/idempotent/non-destructive/openWorld=false), the description adds output behavior ('returns ready and issues'), a conditional return ('prepared HTML only when includeHtml is true'), and explicit non-behaviors ('does not visually render or fetch external URLs'). The no-external-fetch statement is consistent with openWorldHint=false, so there is 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 tight sentences, front-loaded with the core purpose and mode behavior, followed by return semantics and exclusions. Every sentence carries distinct information and none is redundant.

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 present, the description correctly shouldered the burden of describing returns (ready, issues, conditional HTML) and the non-rendering/non-fetching boundaries. For a 5-parameter read/validation tool, nothing essential to invoking it correctly is missing.

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

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

Schema coverage is 60%, and the description meaningfully supplements it by explaining the static-default vs sandboxed interactive mode and the asset-inlining behavior of the assets array. It does not touch the id parameter (accidental-removal check), so it stops short of full 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?

States a specific verb (validate/inline) on a specific resource (HTML plus image/font/CSS assets), with scope explicitly bounded by 'without publishing'. It also names the sibling it overlaps with (publish_html), so an agent can tell the two apart without opening either schema.

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

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

Explicitly says 'publish_html runs the same checks, so this is optional', which tells the agent both the alternative and the condition under which this tool is warranted. The static-vs-interactive:true framing further guides when each mode applies.

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 read-only/idempotent/non-destructive, so the safety profile is covered; the description still adds real value beyond them: the exact return shape (next question vs. confirmation summary), the readyToBuild gating rule, the side-effect of loading account/plan/saved project, and the constraint 'Never silently fill missing brand, access or recipient choices.' A modest deduction because 'Read-only' largely restates the annotation.

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?

Seven short sentences, each carrying a distinct instruction (precondition, input rule, return shape, wait/gating rule, no-fabrication rule, side effect, alternative tool). Front-loaded with the precondition and free of 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?

For a nested-schema, no-output-schema tool, the description supplies the return contract and the workflow gating an agent needs. The remaining gap is minor: the roles of 'confirmed' and 'project' are left entirely to the schema, but the schema documents them adequately.

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 67% and the nested choice fields are already well documented, so the schema does much of the work. The description still adds directive semantics the schema lacks: pass all explicit choices known from the brief/conversation, and never invent unanswered values. It does not, however, clarify the 'confirmed' or 'project' params beyond what the schema says.

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 the specific role: it must run before creating a new Foliyo and after each setup answer, and it returns 'exactly the next question or a summary to confirm.' That distinguishes it from a builder/publisher and from get_page, which it names for updates. The name/title alone ('Prepare a Foliyo') is vague, but the body resolves it clearly.

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?

Explicit when-to-use: 'Required before creating a new Foliyo and after each setup answer.' Explicit sequencing and gating: 'Ask it and wait; do not build or publish until readyToBuild=true.' It also names the alternative for the update path ('Updates use get_page instead'), leaving nothing 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 declare write/destructive/open-world/non-idempotent, and the description adds substantial context beyond that: omitted settings are preserved on update, the server mints a six-digit PIN returned as sharePassword, an unverified email gate only records claimed addresses while verified access needs Pro, notification email is opt-in, and approved summaries are a precondition. This is exactly the kind of behavioral detail annotations cannot carry.

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?

Front-loaded with what the tool does, then the create/update rules, then return values and edge cases. For 24 parameters and a multi-step approval workflow it stays compact, though several sentences are dense enough to require a second read.

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, and the description compensates by naming the return values (URL, generated PIN, personal recipient links). It covers the new-vs-update precondition, revision requirement, access gates, plan gating, and notification default, which is complete for a 24-param publishing 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 92%, so the per-parameter burden is already met (baseline 3). The description adds cross-parameter semantics the schema cannot state alone: that a format choice does not authorize defaulting the other choices, that gate/notify/password defaults have deliberate consequences, and that omissions on updates preserve current settings.

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?

Opens with a specific verb+resource ('Create or update a Foliyo link from finished HTML') and immediately distinguishes the two modes (create vs update). It also names the sibling that gates new work (prepare_foliyo), so an agent can place this tool among its siblings without opening a schema.

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

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

Explicitly separates NEW work (route through prepare_foliyo, obtain a full summary with readyToBuild=true, a format choice alone does not authorize publishing) from UPDATE work (preserve omitted settings, require the current revision from get_page). It also states when-not to notify and when the fallback PIN must not be used, giving real routing guidance rather than implied usage.

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?

Goes well beyond the annotations: it discloses the permission requirement (workspace:write), clarifies that despite destructiveHint=true nothing is hidden and the note remains in history (only the open-note count changes), and adds a prompt-injection warning that reader note content is untrusted. These are exactly the behavioral facts an agent cannot infer from readOnlyHint/destructiveHint 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?

Front-loads the core action and its inverse in the first sentence, then layers side effects, security guidance, and permissions. Every sentence earns its place, though the untrusted-data warning is somewhat verbose for a tool description.

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 3-parameter mutation with no output schema, the description covers prerequisites (workspace:write), id sourcing (link_report), reversibility, side effects on limits, and safety constraints. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so id, page, and resolved are already fully documented, including the resolved=false reopen semantics and the true default. The description restates the reopen behavior but adds no syntax or format 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 pair (resolve/reopen) on a specific resource (one note on a page) and immediately distinguishes itself from destructive siblings like delete_note by describing resolution as a state change, not a removal. An agent can tell exactly what this does 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?

Gives explicit when-to-use conditions ('resolve a note only when the user asks or the point it raises has been dealt with') and routes the agent to link_report for obtaining ids. It also covers both directions of the operation, so there is no ambiguity about how to reopen.

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.