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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It explicitly discloses the non-idempotent behavior ('a retry appends twice'), which is critical mutation-behavior information. It does not mention authentication/permission requirements or the return format, but the idempotency disclosure is the most operationally important trait for an append operation.

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 core action in sentence one and the critical non-idempotency warning in sentence two. Zero waste, all sentences earn their place. Could be slightly more structured, but it's tight and well-paced.

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 annotations and no output schema, the description should add more: the 'content' semantics, what 'updated_user' means, and whether there's a size limit on appends. The non-idempotency and doc-id-or-url notes are valuable, but the parameter semantics gap and lack of return-value expectations leave it incomplete for a 3-parameter 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% (no descriptions on any of the 3 parameters). The description mentions doc_id_or_url (accepts a doc id or URL) and implies content, but it never documents what 'content' represents (plain text? markdown? formatting restrictions?) or what 'updated_user' means semantically. With 0% schema coverage and 3 parameters, the description only partially compensates.

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+action: 'Append content to an existing shared doc.' It clearly distinguishes this from create_shared_doc (create new) and extend_shared_doc (extend). It could more explicitly contrast with extend_shared_doc, which is its nearest sibling, but the append-vs-create distinction is clear.

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

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

Provides clear usage context: it operates on existing docs, accepts a doc id or URL, and explicitly warns the agent to check with search_shared_docs before retrying due to non-idempotency. It doesn't say when NOT to use it vs extend_shared_doc (the nearest sibling), but the idempotency warning and pointer to search_shared_docs offer practical 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?

With no annotations provided, the description carries the full disclosure burden and does well: it warns that password support is unavailable on gist backend, that expiry behavior is lazy on gist, and that selfhost enforces both. This is genuinely useful behavioral context beyond the bare schema for a mutation tool that creates a public resource.

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 waste. First sentence states action and return value; second delivers the critical backend caveat. Information-dense and front-loaded.

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

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

The tool is moderately complex (creation with backend-dependent behavior, 5 params, no output schema or annotations), and the description covers the most important caveats. However, it leaves the absent output schema unaddressed (no statement of what the public URL looks like or its format), and the backend selection mechanism is unclear, making the completeness partial for a tool with this level of behavioral nuance.

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 all 5 parameters (title, content, author, password, expires_in_hours) are undocumented in the schema itself. The description explains the semantics of password and expires_in_hours indirectly via backend differences, but says nothing about title, content, or author beyond their existence being obvious. It partially compensates for the low coverage but leaves key parameters 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?

Description states a clear verb+resource ('Create a shared Markdown doc') and notes it returns a public URL, distinguishing the creation action from siblings like update_shared_doc_title or revoke_shared_doc. However, it doesn't explicitly differentiate from append_to_shared_doc or extend_shared_doc, though those are clearly post-creation operations.

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

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

The description provides meaningful backend-specific caveats (gist vs selfhost differences in password/expiry behavior) which inform when/whether to set password and expires_in_hours parameters. However, it doesn't give explicit when-to-use guidance or name alternative tools, and the backend distinction is somewhat opaque without more context on how to choose backend.

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

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

With no annotations provided, the description carries the full burden of disclosure. It comprehensively covers: permanence (irreversible), the dual effects (link death + search removal), no history retention, the confirmation requirement, and the alternative tool recommendation. This is exemplary disclosure for a destructive 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 packed sentences, each earning its place: the first states what happens, the second warns irreversibility, the third provides usage guardrails. Information-dense with zero 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 2-parameter tool with no annotations and no output schema, the description is remarkably complete. It covers purpose, behavioral consequences, safety requirements, and alternative selection, leaving almost nothing for the agent to guess.

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. It explains the confirm parameter's semantics thoroughly (must only pass after explicit user approval). However, doc_id_or_url is not elaborated—the agent must infer it accepts an ID or URL from the parameter name. Partial compensation; the confirm context is strong but doc_id_or_url lacks 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?

The description clearly states the verb (delete), resource (shared doc), and the two key behaviors: the link dies and the record disappears from search. It also explicitly differentiates from revoke_shared_doc ('unlike revoke_shared_doc, no history is kept'). This is specific and distinguishes from 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?

Excellent when/when-not guidance: explicitly states to prefer revoke_shared_doc for routine takedowns, and requires confirm:true only after explicit user approval. It also warns the operation is irreversible on both backends, giving the agent clear guardrails for appropriate invocation.

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?

No annotations are provided, so the description carries the full burden. It discloses a useful behavioral trait: expiry is enforced lazily on the gist backend (cleanup on next use), which is genuinely helpful context. However, it doesn't disclose what happens to the returned data, whether the operation is reversible, or any error/edge-case behavior (e.g., what if the doc is already expired). The lazy-enforcement note is a real value-add but coverage is partial.

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 waste. The first states the operation clearly, and the second adds a practical usage hint plus a behavioral disclosure. Every word earns its place.

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

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

For a mutation tool (extending expiry) with no annotations and no output schema, the description is moderately sufficient. It clarifies the hours semantic and the lazy cleanup behavior, but omits details an agent might need: max extension limits, whether expiry can only be extended (not reduced), and the return value format. Given only 2 simple params, this is adequate but not fully complete.

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

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

Schema description coverage is 0%, so the description must compensate, and it partially does. The description explains the 'hours' parameter semantics clearly (multiply days by 24), which is the most important semantic detail. However, it doesn't elaborate on 'doc_id_or_url' format (whether a full URL or just an ID is accepted), leaving some gap for a 0%-coverage schema.

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

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

The description uses a specific verb+resource ('Extend a doc expiry') and clearly states the action on a shared doc. The tool name 'extend_shared_doc' is reinforced by the description but the description adds the key detail that it extends by N hours, distinguishing it from sibling tools like create, append, reset, update, revoke, and delete.

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

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

The description provides clear usage context: it extends expiry by hours with an explicit note on how to convert days to hours ('for N days multiply by 24 first'). It doesn't explicitly say when NOT to use this vs alternatives, but the sibling set makes task separation obvious (extend vs create/append/reset/update/revoke/delete are distinct operations).

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

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

The description mentions 'Selfhost backend only' which is a useful operational constraint, and that null removes password protection. However, there are no annotations, so the description carries the full burden for behavioral disclosure. It doesn't clarify whether the password change is destructive/reversible, whether it affects other users' access, or what happens to the password on selfhost vs cloud versions. For a mutation tool with zero annotation coverage, this is a meaningful gap but the 'Selfhost backend only' note adds some context.

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

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

The description is extremely brief - two clauses that convey the purpose and the null behavior plus the backend constraint. Every element earns its place. However, it's borderline under-specified, so it leans more toward conciseness than substantive content.

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

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

For a mutation tool with no annotations, no output schema, and 0% schema description coverage on parameters, the description does not compensate. It fails to explain the return value, side effects on shared access, or the 'updated_user' parameter's role. It also doesn't clarify whether resetting to null makes the doc accessible to everyone or just removes the password entirely. The description is incomplete given the tool's complexity and the absence of any structured enrichment.

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 explain the parameters, but it barely does. The description touches on new_password via the 'null removes protection' note, and implies doc_id_or_url is a resource identifier, but does not explain updated_user at all. It doesn't clarify whether doc_id_or_url accepts a URL or just an ID format, and 'null removes protection' is the only real semantic contribution beyond the schema.

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

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

The description has a specific verb+resource ('Reset...password') and clarifies the null-removes-protection behavior. However, it does not distinguish itself from siblings like update_shared_doc or revoke_shared_doc. The core action is clear but the scope vs sibling operations is ambiguous.

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

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

The description provides no guidance on when to use this tool over siblings such as revoke_shared_doc or update_shared_doc. The 'Selfhost backend only' constraint is a limited usage note, but there's no when-to-use, prerequisites (e.g., existing password required?), or exclusion criteria. No alternatives are mentioned.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does this thoroughly: states the link stops working, the record remains searchable, describes backend-specific differences (immediate irreversible deletion on Gist vs 7-day grace on Selfhost), and clarifies that this is not the tool for full record removal.

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 deliver high information density with zero filler. Each sentence earns its place: the first states core behavior, the second covers backend differences, and the third directs to the sibling tool for the full-erase use case.

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

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

For a relatively simple revoke operation with no output schema and no annotations, the description covers the essential behavioral dimensions well. The only gap is parameter documentation (doc_id_or_url format, updated_user purpose), but the core operation semantics are complete.

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

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

Schema description coverage is 0%, so the description must compensate for both parameters. It doesn't explain what doc_id_or_url should contain (a document ID or a URL format) or what updated_user is for. The description provides zero parameter-level guidance despite having two undocumented parameters.

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

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

The description uses a specific verb+resource ('Revoke a shared doc') and clearly states the effect: the link stops working but the record stays searchable. It distinguishes itself from the sibling delete_shared_doc tool by naming it explicitly as the alternative for full erasure.

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

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

It provides explicit guidance on when to use this tool vs delete_shared_doc, and even differentiates behavior between Gist and Selfhost backends. This gives the agent clear decision rules for which action to 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?

With no annotations provided, the description carries the full burden and does so thoroughly. It discloses backend differences (selfhost returns viewCount/lastViewedAt; gist returns null), pagination behavior (limit max 100 default 20, offset >= 0, hasMore in response), and search semantics (content_query searches full content on selfhost but only the opening excerpt on gist). This goes well beyond the schema.

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

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

The description is a single dense sentence, packed with all necessary details. It front-loads the purpose and then covers parameters and backend quirks. Some might find it slightly run-on, but every phrase earns its place; a structured list could improve readability slightly, hence 4 rather than 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?

Given no annotations, no output schema, and 5 parameters, this description is exceptionally complete. It explains return data (share URL, viewCount/lastViewedAt), pagination semantics (hasMore, offset+limit), backend variations, and all filters. Nothing critical is missing for an agent to invoke and interpret the tool correctly.

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

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

The schema has 5 properties, all with no descriptions, but the tool description explains each one: title_query (title substring), content_query (body text with backend caveat), status (active/revoked/expired), limit (max 100, default 20), offset (must be >= 0, used for pagination). This fully compensates for the schema's lack of descriptive coverage.

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

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

The description opens with a specific verb+resource: 'Find previously shared docs and their links.' It clearly distinguishes this from sibling tools, which are all mutating operations (create, update, revoke, delete). It also clarifies the no-argument default behavior, reinforcing purpose.

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

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

Usage context is clear: call with no arguments to list newest docs, or use filters (title_query, content_query, status, limit, offset) to narrow results. It does not explicitly name alternatives, but the sibling set is all write/update/delete operations, making the read-only search role obvious. No exclusions are needed beyond that.

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

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

With no annotations, the description carries the burden of disclosing behavior. It explicitly reveals idempotency, that title/password/expiry are left unchanged, and that a doc id or URL is accepted. These are valuable behavioral traits beyond the basic operation, though return format or error conditions are not covered.

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

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

The description is two sentences long, with the main action front-loaded and additional details (idempotency, input format) in the second sentence. Every sentence adds value, with no fluff or redundancy.

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

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

Despite having no annotations or output schema, the description provides key behavioral context: what the operation replaces, what remains unchanged, and idempotency for retries. It is reasonably complete for a simple mutation tool, though it omits return value details and does not explain updated_user.

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. It clarifies that doc_id_or_url accepts a doc id or URL and implies content is the replacement text, but it does not explain the updated_user parameter at all. Thus it adds partial meaning but leaves one parameter undocumented.

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

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

The description clearly states the tool's purpose: 'Replace the entire content of an existing shared doc' with a specific verb and resource. It also notes what is not changed (title, password, expiry) and explicitly distinguishes itself from append_to_shared_doc, making it unambiguous.

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

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

The description provides usage guidance by contrasting with append_to_shared_doc ('unlike append_to_shared_doc...') and mentioning idempotency for safe retries. It also specifies accepted input format ('Accepts a doc id or URL'), giving clear context on when to use this tool. However, it does not explicitly list other alternatives or exclusions.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not state whether this requires specific permissions, whether the change is reversible, what happens on failure, or any side effects. The only behavioral constraint disclosed is the non-empty title requirement.

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 efficient sentence with zero waste. It front-loads the core purpose clearly. However, the brevity comes at the cost of missing important behavioral and parameter details.

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

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

For a mutation tool with no annotations, no output schema, and 0% parameter coverage, this description is insufficient. It should explain permission requirements, error behavior for non-existent docs, and clarify the roles of updated_user and doc_id_or_url. The single line leaves too much for the agent to infer.

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 for the 3 undocumented parameters. The description mentions 'title' which maps to new_title, but leaves doc_id_or_url and updated_user completely unexplained beyond the schema. The non-empty constraint adds value for new_title, but the other two params get no additional meaning.

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 action (update a shared doc title) with a clear constraint (must be non-empty). It distinguishes itself from siblings reasonably, since other tools like create/append/extend/delete are clearly different operations, though it could name the 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?

No guidance on when to use this tool vs alternatives. It doesn't mention prerequisites (e.g., doc must exist, user must have permission), nor does it exclude cases where this tool would be inappropriate. The description is purely declarative with no usage context.

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