Shareout

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

Annotations already declare destructiveHint=true, non-idempotent and openWorld, so the safety profile is partly covered. The description adds genuinely non-obvious context: 'Requires the current base_version' signals a stale-state guard, and 'prior versions remain saved' reassures that the destructive operation is recoverable. It still omits who may call it and what happens to the affected 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?

Two short sentences, zero filler, with the activation action front-loaded and the precondition and persistence guarantee following immediately. 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 three-parameter mutation with a rich annotation profile and no output schema, the description supplies the two things an agent most needs: the required concurrency token and the fact that prior versions survive. Only permission requirements and the effect on the linked documents 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 must carry the load. It clarifies that base_version must be *current* (an optimistic-lock token) and that version names the saved version to activate, but document_id is never explained and the version/base_version distinction remains implicit rather than stated.

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 ('Activate a saved version at existing unpinned links'), which distinguishes it from read-only siblings like shareout_list_versions or shareout_get_document. The scope qualifier 'at existing unpinned links' is meaningful but slightly opaque without domain knowledge, and it never explicitly contrasts itself with shareout_publish or shareout_create_link.

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 sentence 'Requires the current base_version' gives an actionable precondition, implying this is an optimistic-concurrency activation rather than a blind overwrite. However, there is no guidance on when to activate versus publish or create a new link, and no exclusions or alternative 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, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds a genuine semantic caveat — 'Counts do not verify reader identity' — which tells the agent how to interpret the numbers. It does not disclose pagination/bounding behavior or any auth constraints, so it is modest rather than rich.

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

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

Two short sentences, front-loaded with the primary purpose and followed by the caveat; no filler. Slightly terse relative to the gaps it leaves, but 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?

With no output schema, the description should characterize the return shape; it does so at a high level ('view totals and a bounded set of per-link counts'), which is adequate. However it omits pagination semantics and any signal about what document_id must be, leaving gaps for a 3-parameter analytics tool.

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

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

Schema description coverage is 0% for all three parameters, so the description must carry the load. It hints at boundedness ('bounded set') which loosely maps to limit/offset, but never explains the limit cap of 20, offset defaults, or the required document_id pattern constraint.

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 ('Get') plus the resource it returns ('view totals and a bounded set of per-link counts'), which disambiguates it from siblings like shareout_list_links or shareout_get_document. It does not explicitly name a sibling it should be preferred over, 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?

No guidance on when to call this instead of alternatives such as shareout_list_links or shareout_get_document, and no prerequisites stated. The agent must infer usage from the resource description alone.

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 the mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true). The description goes beyond that by disclosing the security model: the link grants bearer access and its URL should only be returned to the user. That is genuinely useful, non-derivable context, though it omits whether re-issuing a link duplicates or supersedes an existing one.

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 filler; the creation purpose is front-loaded and the security caveat is appended where it matters most.

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 and 0% schema coverage, the description covers the core purpose and security posture but not the parameter formats or the return value beyond 'URL'. Adequate minimum viability with clear gaps.

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

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

Schema description coverage is 0%, so the description must compensate. 'Named' implies the label parameter and 'optional expiry' implies expires, but the format of expires (relative vs absolute, ISO vs duration) and the document_id constraint are unexplained, leaving material gaps a caller could get wrong.

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 ('Create a named document viewing link') plus a key modifier (optional expiry), so the agent knows exactly what the tool produces. It does not, however, distinguish itself from the sibling shareout_revoke_link or the various read tools, leaving sibling routing to inference.

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

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

No when-to-use guidance, no prerequisites, and no reference to alternatives such as shareout_revoke_link for teardown or shareout_list_links for inspection. The agent must infer the 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 readOnlyHint, idempotentHint, non-destructive, and closed-world behavior. The description adds useful context by specifying that the tool returns the default brand JSON and CSS URLs, though it omits auth requirements, rate limits, and caching 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?

The description is a single front-loaded sentence with no wasted words. It states the core action and result efficiently.

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 no-parameter read-only tool, the description is nearly complete. Because there is no output schema, it would ideally say more about the returned JSON structure, but naming the JSON and CSS URLs provides a usable level of return context.

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

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

There are zero parameters, so there is no parameter semantics to explain. The baseline for a no-parameter tool is 4.

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

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

The description states a specific verb, resource, and scope: get the default Shareout brand JSON and CSS URLs. This uniquely identifies the tool among siblings such as get_document, get_guidelines, and get_template.

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

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

The description gives no when-to-use guidance, prerequisites, or alternatives. It does not explain when an agent should call this instead of other Shareout retrieval tools.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context beyond them: it will NOT return document content, and only documents the caller is authorized to see are accessible.

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 tight sentence with no filler, and the scope-limiting phrase ('without content') is present. It is efficient but arguably clipped for a tool whose parameter is undocumented.

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 does carry the return contract ('document summary and current version without content'), which is the key thing an agent needs. Missing only edge-case behavior (nonexistent, unauthorized, or non-current documents) for a low-complexity single-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?

One required parameter with 0% schema description coverage, so the description must compensate. It implies the ID selects exactly one authorized document, but never states the identifier's format (the ^[a-z0-9_]{1,64}$ pattern is only in the schema) or what happens for an unknown/unauthorized 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 (Inspect) and resource (one authorized document summary and current version), with the scope qualifier 'without content' that separates it from a content-read operation. It is distinguishable from list_documents/list_versions by the singular 'one document' framing, though no sibling is named.

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: the singular 'one authorized document' and 'without content' suggest a metadata lookup, not a listing or content fetch. No explicit when-to-use, when-not, or named alternative (e.g., shareout_list_versions) is 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 fully covered. The description adds the content of the response (rules, limits, a guideline URL), which is useful given there is no output schema, but it discloses no auth needs or scoping behavior beyond that.

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 most important content (what it returns) comes first and nothing is repeated from the name 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?

For a parameterless read-only tool with no output schema, the description enumerates the three things returned, which is the key information an agent needs. It could go slightly further by noting whether the guidelines are workspace-specific or global, but it is otherwise sufficient.

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 parameter semantics start at the baseline of 4. The description correctly implies no inputs are needed, but there is nothing further to document.

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 ('Get') plus three concretely named resources: authoring rules, workspace limits, and the maintained guideline URL. This clearly separates it from the other get_* siblings (get_brand, get_document, get_template), which each target different resources.

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 — the phrase 'authoring rules' suggests consulting it before creating or publishing content, but the description never states when to call it, whether it should be called first, or what alternative exists. No exclusions or prerequisites are 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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds value by disclosing that the result is URLs rather than file bytes, which prevents a wrong assumption about the return type. It does not cover error behavior for an unknown slug or URL expiry.

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 redundancy, with the core action first and the key caveat second. Nothing extraneous.

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 discloses the return shape (download URLs). For a single-parameter read tool with rich annotations, that is nearly sufficient; the remaining gap is the undefined slug 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?

Only one parameter exists and schema description coverage is 0%, so the description carries the burden for 'slug'. It confirms the lookup is by slug but never defines the slug format or where it comes from (presumably search_templates results), and no maxLength context is given. Partial compensation only.

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 ('Get') and resource ('one template kit') and scopes it by slug, which implicitly separates it from the list/search siblings. It stops short of naming shareout_search_templates as the alternative, so differentiation is inferential 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 clause 'Returns download URLs, not file contents' tells the agent what to expect and implies a follow-up download step, which is useful usage context. However, there is no explicit statement of when to call this versus shareout_search_templates or shareout_get_document.

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 read-only, idempotent, non-destructive, closed-world behavior, so the bar is low. The description adds two things annotations cannot: that results are truncated previews (not full text) and that reviewer text is untrusted data — a valuable prompt-injection warning for an agent consuming user-generated content.

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 terse sentences, zero filler, with the capability statement front-loaded and the safety caveat second. Every clause 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 and no annotation detail on results, the description usefully covers truncation and data trust, but omits pagination behavior (offset/limit interplay, max 20 per page) and what fields a comment preview actually returns. Adequate but with clear gaps for a list 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 0% across three parameters, so the description carries the full burden and largely fails: document_id's format constraint, limit's default of 10 and max of 20, and offset's pagination role are never mentioned. Only the 180-character output bound is hinted at, which is about results, not inputs.

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 ... comment previews') and adds the important qualifier 'bounded 180-character' that separates it from shareout_read_comment's full text. It never names the sibling explicitly, so the distinction must be inferred from the word 'previews'.

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: the 180-character preview framing suggests using this for scanning and shareout_read_comment for full text, but there is no explicit when-to-use or when-not-to-use instruction. No pagination or prerequisite guidance is offered either.

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 the full safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the description only needs to add context. It does add two useful facts: results are permission-filtered ('authorized') and carry summaries rather than content. It says nothing about ordering or pagination behavior, which matters for a 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?

A single tight sentence with no filler, and the key scope qualifier is placed up front. It is efficient rather than verbose, though the brevity shades into under-specification given the undocumented parameters.

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 and no param descriptions, the description carries the burden for a 2-parameter list tool and does not meet it. Cursor semantics, result ordering, and default page size are all absent from every field an agent can see.

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 two parameters, and the description adds no parameter information at all. The `before` string parameter in particular is completely opaque from every source — its meaning as a pagination cursor must be guessed, and the limit bounds/default go unmentioned.

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 authorized document summaries') and adds a scoping qualifier ('without document content') that implicitly separates it from shareout_get_document. It does not, however, name any sibling explicitly, so the agent must infer the boundary itself.

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 prerequisites, and no named alternative. The phrase 'without document content' is a hint that content retrieval lives elsewhere, but the description never routes the agent to shareout_get_document, shareout_search_templates, or any other sibling.

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 carry the full safety profile (readOnly, idempotent, non-destructive), but the description adds a genuinely useful disclosure beyond them: 'Never returns bearer tokens.' That tells the agent it cannot recover a usable link credential from this call, which is meaningful behavioral context, not a restatement.

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 zero filler; the resource and scope are front-loaded and the security caveat follows directly. 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 read-only list operation with annotations covering the safety profile and no output schema, the description tells the agent what it returns (metadata + view counts) and what it withholds (tokens). The only gap is pagination semantics for limit/offset.

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 never mentions document_id, limit, or offset. The parameters are self-evident by name (pagination + target document), but the description does not explain the default of 10, the max of 20, or that offset enables paging, so it 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 ('List') and a specific resource ('sharing-link metadata and view counts') scoped to 'one document'. This distinguishes it from create/revoke siblings by operation type, though it does not explicitly name an alternative to disambiguate against list_documents or list_comments.

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: use it to inspect existing sharing links for a given document. There is no explicit when-to-use/when-not guidance and no routing to the related create_link/revoke_link siblings, so the agent must infer 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 readOnly, idempotent, non-destructive, and non-open-world behavior, so the safety profile is covered. The description adds real value by clarifying that content is excluded and no version is activated, but it says nothing about pagination behavior or result ordering.

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

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

A single front-loaded sentence with no filler; the scope constraint follows immediately after the verb and resource. 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?

With annotations covering safety and no output schema required to be explained, the description is adequate for a read-only list. However, it omits pagination semantics and what a 'summary' actually contains, which matters for a tool with limit/offset 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 0%, so the description carries the full burden for document_id, limit, and offset. It explains none of them: no document_id format, no mention that limit is capped at 20 or that offset paginates results. The parameter gap is unaddressed.

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 ('saved document version summaries') and adds a scope delimiter ('without content or activation'). This distinguishes it from siblings like shareout_activate_version and shareout_get_document, though it does not explicitly name which sibling returns full version content.

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

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

Usage is only implied: 'without content or activation' hints this is the lightweight metadata path, but there is no explicit when-to-use, when-not, or named alternative. An agent can infer intent from the purpose but gets no routing guidance against shareout_get_document or shareout_activate_version.

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 the mutation profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false). The description adds real value beyond that: it discloses the two operating modes, the ready=true return signal, and the critical constraint 'Never pass file bytes'. It omits how long a reserved upload lives, auth requirements, and what happens on failure.

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 primary file-based mode, which is good structure. But the compression is so aggressive ('reserve an HTTP upload and PUT files before publishing', 'returns ready=true after download') that clarity is sacrificed, so it reads as terse rather than concise.

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 mutating, non-idempotent tool with a nested object parameter, zero schema coverage, and no output schema, the description should do more. It leaves document_id undefined, the nested file fields unexplained, and the lifecycle/expiry of a reserved upload unstated; the only return detail given is ready=true.

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 must carry parameter meaning. It explains `file` indirectly (use a pointer, never bytes) but says nothing about the nested download_url/file_id/file_name/mime_type fields, and `document_id` is not mentioned at all despite being a top-level parameter. This leaves a documented gap rather than compensating for it.

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 conveys a specific verb+resource: staging an HTML attachment as index.html or reserving an HTTP upload to prepare a publish. However, the phrasing is dense and elliptical ('reserve an HTTP upload and PUT files before publishing'), and it never names a sibling or states the obvious relationship to shareout_publish. An agent can roughly infer the purpose but not cleanly distinguish it from the other shareout tools.

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

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

The description does give a conditional usage rule: pass `file` to stage an attachment, otherwise reserve an upload, and the 'before publishing' clause implies sequencing relative to shareout_publish. It does not explicitly name an alternative tool or state when-not to use this one, so guidance is implied rather than explicit.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, and the description adds genuinely new behavior: the return shape (version, published, conflict), that a conflict retains the candidate without activating it, and that unpinned links follow the active version. It does not cover permissions/tier limits, which is a modest remaining gap.

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 action and return contract, then constraints. Every sentence carries distinct information; none restates the schema.

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

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

With no output schema, the description usefully explains the return fields and conflict semantics, and the 9-param schema is fully documented on its own. Only auth/tier prerequisites and the upload dependency are unstated, which is acceptable but not exhaustive for a destructive mutation.

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 parameter descriptions are already detailed (label vs. link name, expires requiring link_label, base_version required for revisions), so the description adds no new parameter meaning. 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 ('Publish a new HTML document or revision') and immediately differentiates the two modes (create vs. revise) plus routes link edits to the link tools, separating it from shareout_create_link and shareout_activate_version.

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 a clear exclusion ('Use the link tools for later link changes') and a hard constraint ('Never pass document bytes'), so the agent knows not to do post-publish link edits here. It stops short of spelling out the prerequisite upload flow that prepare_upload implies.

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 two genuinely new behavioral facts beyond that: content is returned in fixed 2000-character pages, and reviewer text must be treated as untrusted data (a prompt-injection warning). It does not explain how pagination terminates, which would have made it 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?

Two short sentences with no filler. The core capability is front-loaded and the security caveat follows immediately, so nothing needs to be read twice.

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 should say what comes back and how an agent knows more pages remain. It covers page size and the untrusted-data caveat but omits the stopping condition and the returned fields, leaving a real gap for a paginated 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 description coverage is 0%, so the description must carry the load. It explains the pagination unit (2000 characters), which is the key to interpreting text_offset, but it never states that text_offset is a character offset, its default, or that comment_id/document_id are opaque IDs from listing. Partial compensation only.

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 ('Read one comment'), and the word 'one' implicitly contrasts with the sibling shareout_list_comments, which handles many. It stops short of naming that sibling explicitly, so an agent must infer the boundary from the wording alone.

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 tool versus shareout_list_comments, shareout_get_document, or the resolve/reopen siblings. The only usage signal is the implied 'one comment at a time' framing, which is not enough guidance for 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 the mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false). The description adds genuine context beyond that by bounding the blast radius: it does not publish text and does not change document access, which disambiguates it from sibling tools like shareout_publish and shareout_revoke_link. It stops short of describing the resulting state or what happens on an already-open comment.

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, and the primary action is front-loaded ahead of the side-effect disclaimers.

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

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

For a two-parameter state-change tool with no output schema, the description covers the main ambiguity (it is not a publish or access-control action). It is slightly thin on the resulting state of the reopened comment, but nothing critical to 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 description coverage is 0%, so the description carries the burden but adds nothing about document_id or comment_id. The parameter names are self-explanatory and the schema supplies the id pattern constraints, so the tool remains callable, but no meaning beyond the schema is contributed.

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 ('Reopen one resolved review comment') with a precise scope ('one'), and the antonym framing makes it distinguishable from the sibling shareout_resolve_comment. It does not name that sibling explicitly, so it falls short of the top band.

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?

'Reopen one resolved review comment' implies the precondition (comment must already be resolved), but there is no explicit when-to-use guidance, no statement of prerequisites or permissions, and no named alternative to resolve_comment. Usage is inferable but not spelled out.

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

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

Annotations already declare destructiveHint=false and readOnlyHint=false; the description adds real context by confirming the resolution does not delete text or alter document access, which is exactly the reassurance an agent needs before mutating review state. It omits what happens on an already-resolved comment (annotations say idempotentHint=false) and any permission requirements, keeping it from 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?

Two short sentences, the action stated first and the safety caveat second. Nothing is wasted and nothing important is buried.

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

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

For a two-parameter state-change tool with annotations covering the safety profile and no output schema to explain, the description covers the essentials. The remaining gap is how to source the comment_id and what the call yields, which is minor but not zero for an agent invoking it cold.

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 two parameters carry only names and regex patterns. The parameter names document_id and comment_id are largely self-explanatory, but the description offers no hint about where to obtain a comment_id (e.g., from shareout_list_comments) or the expected scope of the document reference.

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 — 'Mark one review comment resolved' — which is unambiguous and implicitly contrasts with siblings like shareout_reopen_comment and shareout_read_comment. It stops short of naming a sibling to disambiguate explicitly, so a 4 rather than 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 usage is implied by the verb (resolve a comment after a review) but there is no explicit when-to-use, no prerequisite that the comment must currently be open, and no named alternative such as shareout_reopen_comment for undoing it. The 'Does not delete text' clause is scope clarification, not routing 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, so the safety profile is covered. The description goes beyond them by disambiguating the blast radius: 'Permanently' signals irreversibility and 'The document and versions remain' explicitly states what is NOT destroyed, which is genuinely useful for a destructive call. It does not address idempotency (annotations say not idempotent) or permissions.

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 destructive action, and the second sentence earns its place by clarifying scope of destruction. 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?

For a destructive two-parameter mutation with no output schema, the description covers the outcome for the document/versions but leaves the two parameter semantics entirely unexplained and says nothing about auth requirements or behavior on an already-revoked link. Adequate but with clear gaps.

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

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

Schema description coverage is 0% — both document_id and link_id carry only a regex pattern with no meaning. The description alludes to 'one document viewing link' but never explains the relationship between document_id and link_id or the expected identifier format, so it 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 (revoke) with a specific resource (one document viewing link) and scope ('one'), which cleanly separates it from shareout_create_link and shareout_list_links. An agent can identify the operation 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?

No guidance on when to choose this over alternatives (e.g., list_links to find the link_id first), no prerequisites, and no mention of what happens if the link is already revoked. The agent must infer the entire workflow.

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 a closed-world scope, so safety is covered. The description adds genuinely non-redundant behavior: results are bounded summaries rather than full template contents, which sets expectations since no output schema exists.

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

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

Two sentences, no filler, with the core purpose front-loaded. Nothing in the text is redundant with the name 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?

For a search tool with three undocumented parameters and no output schema, the description says nothing about what a "summary" contains, how query matching works, or how paging interacts with the limit cap. This is under-specified for correct invocation.

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

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

Schema description coverage is 0% across three parameters (limit, query, offset), and the description adds no meaning for any of them. An agent must infer that `query` is a free-text search term, that `limit` caps at 20, and that `offset` supports paging purely from bare property names and numeric bounds.

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 ("Search Shareout templates"), which cleanly separates it from retrieval siblings like shareout_get_template. However, it does not explicitly name the sibling it is not, leaving the search-vs-fetch distinction implicit in the second sentence.

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?

"Returns bounded summaries, not file contents" implies that shareout_get_template is the alternative when full content is needed, but this is never stated as an explicit rule. No guidance on when to use search at all, or on query construction.

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