Docfarm

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so safety is covered structurally; the description adds the meaningful behavioral trait that writes are guarded by an app_read_doc revision, i.e. a concurrency check. It does not say what happens on a stale/mismatched rev or how the response looks, so it stops short of full transparency.

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 with the audience constraint front-loaded, then the action, then the routing to the sibling. Every sentence earns its place with no filler.

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

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

For a mutation tool with no output schema, the description covers caller, action, concurrency guard, and the correct alternative. It leaves minor gaps around stale-revision failure behavior and return semantics, but an agent has enough 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 75%, so most parameters are already documented. The description clarifies the purpose of rev (the guard returned by app_read_doc) but adds no syntax or meaning for edits, its loc/html items, or account beyond what the schema provides. Baseline 3 is appropriate.

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

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

States a specific verb+resource ('Saves text ... as exact edits of the stored HTML') and immediately scopes the caller ('used by the docfarm doc view inside the chat, not by the assistant'). It also distinguishes itself from the sibling patch_doc, 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 gives both when-not-to-use ('not by the assistant') and the alternative ('Assistants edit docs with patch_doc instead'), plus the prerequisite that edits must be guarded by the rev from app_read_doc. Nothing about tool selection 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 readOnly=true, non-destructive, closed-world, so the safety profile is covered. The description adds value by disclosing what is actually returned: HTML annotated for in-place text editing plus a content revision. It stops short of explaining what the revision is used for or the size/shape of the payload.

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, zero filler, audience constraint front-loaded before the return description and the alternative-tool pointer. 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 tool the agent is told not to use, this is nearly complete: audience, return content, and the correct substitute are all present. The only gap is that without an output schema it doesn't clarify the annotated-HTML or revision semantics, though that matters little given the tool is out of scope for the assistant.

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 both the slug and account parameters are documented in the schema, including the list_accounts pointer. The description adds nothing further about parameters, 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 and resource ('Returns a doc's HTML annotated for in-place text editing plus a content revision') and explicitly separates itself from the sibling get_doc_html. An agent can immediately tell this is a UI-facing read, not an assistant-facing one.

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 an explicit when-not ('not by the assistant') and names the correct alternative for the agent's use case ('Assistants read docs with get_doc_html instead'). This is exactly the routing guidance the definition needs.

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 readOnlyHint=false; the description adds real value by disclosing polling behavior, the side effect (publishes a new HTML doc in the user's farm), the idempotency guarantee, and the returned payload. It doesn't explain how a failed/invalid rebuild_id is handled, nor reconcile the 'safe to call repeatedly' claim with the destructive hint, so 4 rather than 5.

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

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

Four short sentences, each earning its place: purpose first, then polling behavior, then completion effects, then idempotency. No filler or repetition of 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 compensates by naming the return values (current stage while building; share link and quality scores once done). Combined with the polling and idempotency notes, an agent has everything needed to invoke and interpret the call.

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

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

Schema description coverage is 100%, so the schema fully documents `name`, `account`, and `rebuild_id`. The description only hints at where rebuild_id originates (`rebuild_doc`) and adds nothing on the other two parameters, 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 (check a rebuild, publish when done) and ties the resource back to its creator tool (`rebuild_doc`), so an agent can separate it from the sibling that starts rebuilds. The two-phase nature (poll then publish) is 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?

Clearly says to call this after `rebuild_doc` and to re-call after a pause while the build is still running, which is exactly the context an agent needs. No alternatives are named (e.g. `get_doc_status`), but for this specific workflow the guidance is sufficient.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false, yet the description goes well beyond them: it enumerates exactly what is destroyed (share links, analytics, chat, comments, suggestions, collaborators, stored file), states IRREVERSIBLE explicitly, and discloses the owner-only authorization requirement. This is rich behavioral context an agent cannot get from the annotations 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?

The destructive consequence and irreversibility are front-loaded, and the confirmation guidance and identification hints follow in priority order. Every clause carries actionable information; the enumeration of deleted artifacts is dense but not 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?

For a destructive tool with no output schema, the description covers everything an agent needs: authorization, irreversibility, scope of deletion, user-confirmation policy, and target identification. 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 coverage is 100%, so the baseline is 3, but the description adds a genuine nuance not in the schema: doc_name is fuzzy-matched, which affects how the agent should pass the value. It also reinforces slug as the alternative identifier. The added matching behavior earns a step above 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 (permanently delete) and resource (doc), plus the ownership qualifier that constrains it. An agent can immediately distinguish this from siblings like duplicate_doc, patch_doc, or update_doc_settings 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?

Gives clear preconditions — only the owner can delete, and the agent should confirm with the user when there's ambiguity — plus how to identify the target. It stops short of naming an alternative tool for non-owner flows, but the destructive framing makes that distinction largely self-evident.

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

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

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), and the description adds real context beyond them: the copy is server-side and 'content never passes through your context,' the read permission requirement ('any doc the user can read'), and the ~1s cost. It stops short of stating what happens on a name collision or whether an existing destination doc is overwritten.

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 dense, front-loaded sentences with no filler; the purpose, workflow position and performance comparison each earn their place. The closing speed comparison slightly overlaps the 'THE fast path' claim but is what makes the alternative concrete.

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?

Covers purpose, permission scope, cost, and the follow-up tool to use, which is nearly everything needed to invoke it correctly. With no output schema, however, it does not say what the copy returns (new doc name/slug/URL), which the agent would need to chain into patch_doc.

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 slug, account, doc_name and new_name are already documented in the schema. The description only reinforces 'under a new name' and the farm destination, adding no format or disambiguation detail (e.g. slug vs doc_name precedence) beyond structured data. Baseline 3 is correct here.

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: 'Server-side copy of any HTML doc the user can read (their own OR shared with them) into their own farm under a new name.' It immediately distinguishes itself from the get_doc_html/host_html_content path named in the same sentence, so an agent can tell it apart from siblings 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 workflow it belongs to ('THE fast path for building a modified version of an existing doc... then use patch_doc for the differences') and names the alternative it beats ('Vastly faster than get_doc_html + re-hosting'). The condition selecting this tool over the alternative is 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 readOnlyHint=false and destructiveHint=true; the description reinforces this by disclosing the in-place overwrite path and that it 'verifies the uploaded object exists before publishing' (a pre-flight validation the agent should anticipate failing). It stops short of describing the return payload or what happens to the previous doc version, so it adds context but not a full behavioral picture.

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, zero filler, with the step-sequencing front-loaded before the outcome branches. Every clause carries operational information the caller needs.

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, but the description states the observable outcome of both branches (new doc + share link, or same share link retained), which is what an agent most needs. It does not say what the call itself returns (URL, status, or id), leaving a small gap for a publish operation.

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 baseline is 3, but the description adds real semantics for `name` (new vs. existing determines create-vs-update) that the schema only gestures at via 'existing name = in-place update'. `slug` and `account` semantics are left to the schema, which is acceptable given 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 and resource ('call this to publish' the uploaded doc) and situates itself precisely as 'FAST PATH step 2/2' following `get_upload_url`. The name-collision rule ('NEW name → new doc', 'matching EXISTING HTML doc → updated in place') separates it from sibling writers like host_html_content and patch_doc.

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 an explicit precondition ('after PUTting the file to the signed URL from get_upload_url') and names that sibling as the required prior step. It also tells the agent the two outcome branches keyed on `name`, so the caller knows which behavior to expect before invoking.

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

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

Annotations already cover the safety profile (readOnlyHint true, non-destructive, closed world), so the bar is lower. The description nonetheless adds real behavioral context: roughly 3,000 tokens of cost, verbatim asset-token substitution, the prohibition on pasting base64, and the publish-time scoring side effect. It stops short of describing the document's structure or whether the payload is chunked.

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 imperative call to action, then cost, then the token mechanics. Dense but every sentence earns its place — the token/base64 guidance and the scoring rationale both change agent behavior. Slightly long, but not 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?

There is no output schema, so the description carries the burden of describing returns — and it does, listing the standard's components and the brand payload (colours, typefaces, asset tokens for logo and fonts). Nothing an agent needs in order to call it and use its output 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 the baseline is 3. The description goes beyond the schema by tying `doc_name` to the downstream `brand_from` argument on host_html_content and by explaining the asset-token verbatim rule, which gives the agent a reason to preserve the exact doc name it reads from.

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

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

States a specific verb and resource: it returns the docfarm house standard plus the user's brand (colours, typefaces, asset tokens). It is immediately distinguishable from siblings like app_read_doc or get_skills, and even enumerates the sub-topics inside the standard (archetype, type scale, spacing, logo rules, motion, budgets, language rules).

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 ('READ THIS FIRST, before writing a single line of HTML') plus a named downstream dependency: pass the same doc name as `brand_from` on host_html_content. It also explains why reading first matters (scoring on publish), which routes the agent correctly rather than by 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 readOnly/non-destructive, but the description adds substantial behavior beyond them: the exact return fields, the default base64-image stripping and its consequence ('hosting a stripped copy back would drop those images'), and offset/max_chars paging with a continuation offset. That is rich, non-redundant 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?

Front-loaded with purpose and the patch_doc precursor relationship, and every sentence carries useful content. It is dense and somewhat long, but no sentence is filler, so it stays just short of maximal conciseness.

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

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

With no output schema, the description must carry the return contract, and it does (title, share URL, role, HTML, paging continuation). Combined with the stripping caveat and account handling, 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 100%, so the baseline is 3, but the description adds meaning the schema does not: that a stripped copy re-hosted would lose images (justifying strip_data_uris: false), and that offset comes from the previous response's continuation note. doc_name fuzzy-matching is largely a restatement of 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?

States a specific verb and resource ('Read the current HTML body') and immediately scopes it ('their own docs OR docs other people have shared with them'). It also names the return payload (title, share URL, role, full HTML), letting an agent distinguish it from siblings like app_read_doc without opening 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?

Explicit routing: 'ESSENTIAL precursor to patch_doc: call this first whenever the user asks for any change to a doc you don't have in context.' It also gives selection guidance for doc_name vs slug and for the strip_data_uris branching, so when-to-use is fully covered.

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

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

Annotations already cover the safe/read-only and closed-world profile, so the bar is lower; the description earns credit by adding the Owner-only access restriction and the note that viewer data stays with the doc's owner. It does not mention caps or latency, but the auth/permission context is exactly the kind of thing annotations cannot express.

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 purpose and return contents, then usage intents, then the access caveat. Dense but every clause carries information; the long enumeration of returned fields borders on verbose relative to what the agent strictly needs.

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 steps up to describe the return payload, and it covers the owner-only constraint and doc identification. What remains unstated - pagination of the 'ten most recent viewers' or freshness of the stats - are minor omissions for a read-only 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%, so all three parameters are already documented, including the fuzzy-matching note on doc_name and the 'this or slug' relationship. The description restates the doc_name/slug identification without adding format or fallback semantics beyond the schema, capping it at 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?

The description gives a specific verb+resource framing ('Who read a doc and how') and then enumerates exactly what is returned - share link, views, reading time, last-opened, recent viewers. It is clearly distinct from sibling reads like app_read_doc or get_doc_html, which fetch content rather than engagement stats.

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 names concrete user intents ('who saw it', 'how is it doing', 'what is the link') and even the downstream use case (material for a follow-up email), plus the access condition (Owner only). An agent has no ambiguity about when to pick this over the content-reading siblings.

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 this a non-destructive read. The description adds real behavioral detail beyond them: the URL is signed, time-limited, and expires per ttl_seconds. It does not disclose error behavior (e.g. invalid slug) or whether the URL is unauthenticated, which keeps it short of a 5.

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

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

Effectively two sentences, front-loaded with the core action and followed by usage triggers. Dense but each clause earns its place; no filler or repetition.

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

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

No output schema exists, and the description adequately conveys what comes back (a time-limited signed download URL) plus its expiry semantics. It omits failure modes and whether the URL works without auth, which are the only notable 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?

With 60% schema coverage, the schema already documents account, ttl_seconds, and download_filename. The description restates the ttl default/max but adds no meaning for slug, doc_name, or download_filename beyond what the schema provides, 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 and resource ('Get a time-limited signed URL that downloads the raw file of any doc') and names the scope ('any doc the user has access to'). It explicitly distinguishes itself from get_doc_html by noting it applies when the doc isn't HTML.

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 three concrete triggers: handing the file off to another tool or LLM, the user asking for a download link, or the doc not being HTML. It names the alternative tool (get_doc_html) and the condition under which that alternative is inapplicable, leaving little 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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real context beyond that: what each mode returns (the full skill, keyword matches, or a name-and-description listing) and that a skill is instructions the agent is expected to follow. It doesn't cover pagination or return size, keeping it just short of 5.

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

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

Four sentences, zero waste, front-loaded with the core verb+resource before the usage modes. Each sentence carries a distinct payload: definition, example, parameter routing, and the recall directive.

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, the description fully compensates by explaining what is returned in each of the three modes and when the agent should reach for the tool. Nothing needed to call 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 100%, so the baseline is 3, but the description goes further by tying each parameter to a distinct behavior mode and providing a concrete example id ('docfarm/onboarding') plus the id-is-array case. This adds selection semantics beyond the field-level text.

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 (Load) and resource (Docfarm skill) and immediately defines what a skill is: 'written instructions for a task that you then follow.' No sibling tool touches skills, so it is unmistakable in the toolset.

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 maps every invocation mode: 'id' for the full skill, 'query' to search by keyword, or nothing to list everything, plus the routing rule 'When the person asks to use a Docfarm skill by name, call this with that id first.' The agent knows exactly which parameter to pass for which 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 only declare the generic safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), leaving the mechanics unexplained. The description adds genuinely non-obvious behavior: the URL is short-lived, the transfer is a raw HTTP PUT with Content-Type: text/html, a shell and unrestricted outbound HTTP are prerequisites, and a second call (finalize_upload) is mandatory to complete the operation. No contradiction with 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?

Front-loads the what and the why in the first clause, then the how, then the failure mode and alternative. Every sentence carries information the agent needs; none is 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 correctly supplies the return value (upload_path) and the exact follow-up call signature. It also covers environment prerequisites and the fallback tool, so an agent has everything needed to either execute or route around this 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?

There is a single parameter and schema description coverage is 100%, so the schema already documents the account field, its default, and the list_accounts pointer. The description adds nothing about the parameter, which is acceptable given the schema does the work, but it is the minimum-viable baseline rather than added value.

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 ('Returns a short-lived signed upload URL') and immediately frames itself as 'Step 1 of 2' in a named workflow, so the agent knows exactly what it produces and what consumes it. It also names the sibling tools it pairs with (finalize_upload) and the one it competes with (host_html_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?

Explicitly states the condition that selects it ('large HTML file that is already on disk, without sending its bytes through the model's context') and the condition that rules it out ('the PUT will not succeed where outbound network access is restricted'), naming host_html_content as the inline alternative. This is a textbook when/when-not/alternative block.

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?

Very rich beyond the annotations: it discloses exactly what an overwrite preserves (share link, password, view stats), what happens to similarly-named docs (untouched, and the response names them), the scoring-on-ingest behavior, and that the response carries the score. This is the meaningful context destructiveHint=true only hints at, and nothing contradicts 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?

Front-loaded with the core host/overwrite behavior and each sentence carries operational weight. It is long for a tool description, though, and the name-matching rule is repeated almost verbatim in both the description and the `name` schema field.

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 tells the agent what comes back (share link and standard score) and covers the full publish workflow, the account scoping, and the brand-asset prerequisite. Nothing an agent needs to call this correctly for a 6-param tool 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 the baseline is 3, but the description adds real semantics beyond the schema: the case/whitespace-insensitive exact-match rule for `name`, and the workflow ordering that determines when `slug` applies (only for new docs, after suggest_link approval). It largely restates schema content for `replace` and `brand_from` rather than extending it, keeping it below 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 ('Host an HTML doc') plus the return value (its share link), and cleanly separates itself from siblings by explaining that exact-title matches overwrite while similar names create new docs. An agent can distinguish this from patch_doc or duplicate_doc without reading 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?

Gives explicit routing conditions: use `get_doc_html` + `patch_doc` for small changes, call `get_build_brief` before writing HTML, and call `suggest_link` before publishing a new doc to get the user-approved slug. Names concrete alternatives and the conditions that select them.

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 destructiveHint/openWorldHint annotations already set, the description still adds real value: it discloses the docfarm landing behavior, the immediate-vs-pending outcomes for existing vs new users, that the result reports whether an invite email was sent, and the fork-vs-overwrite side effect that explains the destructive flag. It stops short of noting rate limits or exact permission requirements, so not quite 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?

Dense single paragraph, but front-loaded with the core action and outcome, then the required params, then the clarification instructions. A couple of clauses (the fork/auto-share detail) are repeated between description and schema, costing a little tightness without bloat.

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, yet the description covers the meaningful return signal (whether an invite email went out), the ownership/auth precondition, the account scoping sibling, and both doc-identification routes. Nothing needed 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 the baseline is 3, but the description goes further by explaining the fork/auto-share-back semantics of allow_overwrite and noting that doc_name is fuzzy-matched and slug is an alternative identifier. That meaning is not expressed in the schema text itself.

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 (invite) and resource (collaborator on a doc) plus the constraint that the user must OWN the doc, which distinguishes it from sibling tools like update_doc_settings or duplicate_doc. An agent immediately knows this is the invite/share path, not a general edit.

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 and when-to-ask: 'If you don't have the email, ask for it' and 'if the user hasn't said whether the person should edit directly or only make a copy, ask before calling, don't guess.' It also surfaces the ownership precondition, so the agent can route elsewhere when the doc isn't owned.

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, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond that: the two farms are separate, and docs, links, viewers, and analytics never mix between them, which helps the agent understand data isolation.

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 purpose, then moves directly into usage triggers and the downstream routing step. Every sentence earns its place by clarifying when to call this tool and how its result should be used, without 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 zero-parameter, read-only tool with no output schema, the description supplies enough context to invoke it correctly: what farms are listed, when to call it, and what the returned account is used for. No critical information is missing for the agent to act.

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?

This tool has zero input parameters and 100% schema description coverage, so the baseline is 4. The description does not need to add parameter meaning, and its mention of passing `account` downstream is about another tool rather than this tool's own 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 states a specific verb and resource: list the farms this connection can reach. It precisely defines what is returned, including the signed-in account and an optional connected account, and explains the work/personal split that distinguishes this account-listing tool from the document-oriented 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?

It gives explicit when-to-use guidance: call this FIRST whenever a request could concern either farm, when the person says 'my personal', 'my work', 'my other account', or names an address that is not the signed-in one. It also tells the agent what to do next by passing the selected account to the actual target 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 declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds real behavioral content beyond that: the ordering of results and, notably, that shared docs carry an edit behavior that either overwrites the original or makes the user's own copy – context neither the annotations nor the single-parameter schema convey.

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 sentence, front-loaded with the core action and organizing the output into two clear groups. The parenthetical about edit behavior is dense but earns its place by removing real ambiguity.

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 compensates by describing what is returned (docs, share links, edit behavior). It stops short of covering result size, pagination, or ordering guarantees for large doc sets, which is the only meaningful gap.

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

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

There is a single optional parameter (account) with 100% schema description coverage, including the pointer to list_accounts. Schema coverage is high, so the baseline is 3; the description adds no parameter-level detail of its own.

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 (user's docs), and goes further by naming the two result groups and their content (owned docs with share links, shared docs with edit semantics). An agent can distinguish this from show_doc, get_doc_url, and get_doc_html without opening another 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?

The description implies usage (retrieve an overview of all docs) but never states when to prefer it over siblings such as show_doc or get_doc_status, nor any prerequisites beyond the schema's note about connected accounts. Usage is inferable but not guided.

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 readOnlyHint=false, but the description adds substantial context beyond them: preserved state (share link, password, view counts, comments), atomic all-or-nothing semantics for patches, sequential validation, and failure behavior on ambiguous matches. It does not, however, state permission/auth requirements for the edit itself.

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?

Dense but well front-loaded — the default-tool claim and cost rationale come first, then the workflow. It is long, and the cost-saving point is restated twice ("~50 tokens instead of ~7000" and "costs far less than re-sending"), which is slight 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 7-param mutation tool with no output schema, the description covers the full workflow, the alternative invocation mode, atomicity, preserved state, and failure modes. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: the either/or relationship between doc_name and slug, that before_snippet must be a unique chunk, and that patches is an alternative to the single-snippet params. occurrence_index is left to the schema, which handles it adequately.

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 (edit) and resource (existing hosted doc) with the exact mechanism (replace a snippet of HTML). It explicitly positions itself as the default against siblings like host_html_content and re-hosting, so an agent can distinguish 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?

Provides explicit when-to-use ("DEFAULT TOOL for ANY edit"), a numbered workflow, the prerequisite of calling get_doc_html first, the choice between single before/after and a patches array, and doc_name-vs-slug selection. Ambiguity handling ("fails with context for each candidate") is also disclosed.

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 only tell the agent it is non-read-only and non-destructive. The description adds the async contract that matters most: it takes ~3 minutes, STARTS the job and returns immediately with a rebuild_id, and the result must be collected via `check_rebuild`. It also discloses the layout-rewriting behavior and the PDF/PPTX-only limitation, which annotations cannot convey.

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 purpose and the async behavior, and every sentence carries real information. It is on the long side and repeats the brand_from assets-only caveat already in the schema, which costs it a point, but there is 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?

No output schema exists, yet the description still explains what comes back (a rebuild_id) and how to retrieve the finished page. Between the format limits, the async pattern, and the brand_from preconditions, an agent has everything needed to invoke this correctly and set correct user expectations.

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 baseline is 3. The description goes beyond the schema by explaining *why* and *when* to populate `brand_from` (ask the user; it is the difference between their brand and a generic page), though the 'assets only, never layout' caveat is largely duplicated from the schema text.

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 (rebuild) and resource (PDF/PowerPoint on docfarm into a live HTML page) plus the crucial scope constraint that it rewrites rather than reproduces layout. It names the sibling it hands off to (`check_rebuild`) and the supported input formats, so an agent can distinguish it from `app_read_doc`, `patch_doc`, or `show_doc` 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?

Gives explicit when-to-use (retrofit an existing PDF/PPTX into a mobile-readable live page), when-not (it does NOT reproduce original layout), the follow-up step (`check_rebuild`), and a prerequisite conversation (ask about `brand_from` before starting). It even pre-empts a wrong question ('Do not ask them how it should look'), which is unusually actionable 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 only declare a safe read operation; the description adds host-dependent rendering (claude.ai/Desktop/mobile get the live view, text-only hosts get a share link), the interactive edit-and-save behavior, and immediate share-link propagation — all beyond what annotations provide.

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 core action, then usage and exclusions; dense but every clause carries functional information. Slightly run-on, which 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?

With no output schema, the description still tells the agent what the caller will see (live doc, edit capability, or a share link in text-only hosts) and how it relates to sibling tools, leaving no operational 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 100%, so slug/account/doc_name are already documented. The description only lightly reinforces slug's ability to accept a share URL; baseline 3 applies since the schema carries the parameter 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 (open/show) and resource (doc) plus the mode ('live view of the page' inside chat), immediately distinguishing it from read-only siblings like get_doc_html or app_read_doc.

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 when to call it (see/preview/check/hand-edit, or when a doc.farm link is pasted) and when not to (do not call straight after host_html_content, patch_doc, or duplicate_doc, which already show the view). This is exactly the routing guidance an agent needs.

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 only declare readOnly/non-destructive/openWorld=false; the description adds non-obvious behavior: the answer reports whether the ending is free and offers an alternative if not, and a name matching an existing doc returns that doc's current link because publishing updates that doc in place.

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 what the tool returns, then the workflow, then the skip condition. Dense and largely earned, though the motivational aside ('People want to see and name their link before it exists...') adds a sentence that could be trimmed.

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 carries the return-value burden and does so: it explains the response reports availability and offers a fallback ending. The name-collision case is also covered, leaving no major gap 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 coverage is already 100%, so the baseline is 3, but the description adds real meaning: slug is 'the ending they settle on' passed to the publish call, a whole link is acceptable with only the post-slash part counting, and name drives the default. It clarifies how the params connect to the downstream publish call.

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+scope: it returns 'the share link a NEW doc would get, before you publish it.' It explicitly positions itself relative to siblings host_html_content and finalize_upload, so an agent can tell it apart without opening 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?

Gives explicit when-to-use (before host_html_content or finalize_upload creates a new doc), explicit when-to-skip (when the person already chose the link or asked to just publish), and the alternative path for validating a suggested ending via slug.

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 destructive and idempotent, and the description substantially enriches that: renaming keeps the link, new_slug permanently breaks the old link for everyone holding it, the first call changes nothing and returns a warning, and confirmation is required before the destructive action. This is exactly the 'what gets destroyed / what happens next' context the agent needs.

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 operation and its field surface before the dangerous-link explanation. The safety flow is necessarily multi-sentence; a small amount of the middle (field enumeration) repeats the schema, but nothing is truly 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 11 params, no output schema, and destructive behavior, the description covers the ownership requirement, patch semantics, and the two-phase link-change return ('returns a warning with both links'). It omits only the account/farm scoping, which the schema already documents.

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 each parameter's meaning is already carried by the schema. The description restates the field list and the new_slug/confirm_new_link flow but adds little that the per-parameter schema descriptions do not already say; 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 and resource ('Change a doc ... settings') and enumerates the exact settings surface (password, ask_name, allow_downloads, notify, title, slug). This separates it cleanly from content-editing siblings like patch_doc and app_apply_edits, which an agent can rule out 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?

Gives clear preconditions ('a doc the user OWNS') and patch semantics ('Only the fields you pass are changed'), plus an explicit multi-step procedure for new_slug. It does not name sibling alternatives for related tasks (e.g. content edits via patch_doc), so it stops short of full 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 cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds useful non-schema context: it is 'cheap and self-contained — no doc lookup needed,' which tells the agent it can call it freely without first resolving a document ID.

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

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

Two sentences, both front-loaded and purposeful: the first states what is returned, the second states when to call it and its cost profile. No filler or restated boilerplate.

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 no-parameter, no-output-schema discovery tool with full annotation coverage, the definition supplies everything an agent needs to call it correctly, including the self-contained/cheap behavioral note. The only marginal gap is a slightly vague 'grouped overview' return shape, which is acceptable given no output schema exists.

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

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

The tool takes zero parameters, which per the rubric is a baseline 4. The description correctly implies no inputs are required, consistent with the empty schema and additionalProperties=false.

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 ('show') and a specific resource ('a grouped overview of everything docfarm can do'), then enumerates the capability domains (reading, editing, sharing, tracking, drafting follow-ups, collaborating). This is unmistakable against siblings like get_doc_status or list_docs, which are concrete data tools rather than capability discovery.

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 lists the trigger utterances ('what can you do?', 'what does docfarm do?', 'show me what's possible', 'help') and ties invocation to them. Nothing is left to inference about when to reach for this tool over the sibling document operations.

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