Edworking MCP

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

Annotations declare the write/non-idempotent/non-destructive profile, and the description adds genuinely new context beyond them: 'Other project members can read it' discloses the visibility/auth model, and the requestId retry guidance flags the idempotency caveat. It stops short of describing the returned resource, but that is covered by the output schema.

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

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

Three tight clauses, front-loaded with the core action and no wasted words. The visibility note and retry caveat are packed into single short sentences.

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 an output schema handling return values and annotations carrying the safety profile, the description only needs to add visibility and retry semantics, which it does. Complete for the agent's needs, though it could note how content is rendered or what project members' read access implies.

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 already documents all four parameters in detail. The description only paraphrases that content is 'optional Markdown' and implies title is required, adding little syntax or format meaning beyond the schema. 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 (Create) and resource (Doc) plus scope (the specified accessible project, with a title and optional Markdown body). The resource makes it trivially separable from create_project/create_task, but it never explicitly differentiates itself from doc siblings like update_doc or get_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?

Usage is implied by the name and by the 'specified accessible project' prerequisite, hinting that a project must exist and be accessible. There is no explicit when-to-use guidance or statement of when to reach for update_doc/edit_doc_content instead.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=false, and idempotentHint=false. The description adds useful behavior beyond annotations: it excludes user invitations and instructs the caller to preserve requestId on retries, which is valuable retry guidance for a mutating 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?

The definition is short and front-loaded with the core action. Every sentence carries distinct information: creation, invitation exclusion, description placement, and retry handling.

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 full schema coverage, output schema present, and annotations covering safety and idempotency signals, the description is nearly complete. It could mention permission or workspace context, but for a create-project tool the major behavioral points are covered.

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 already explains requestId, name, and description. The description adds only marginal semantic context by noting that an optional description is placed in the initial project document, which does not significantly exceed 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 uses a specific verb and resource: 'Create a new project for the connected user.' It also scopes the action by clarifying that it 'Does not invite users,' which helps distinguish it from project membership operations such as list_project_members.

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 says to use it 'when requested' and notes it does not invite users, giving implied usage context. However, it does not name alternatives or explicitly state when not to use this tool versus list_projects or other creation tools.

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

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

Annotations already establish that this is a non-destructive, non-idempotent, closed-world write, so the bar is lower. The description adds real behavior beyond that: the connected user is auto-assigned, status must belong to the destination project, attaching files requires files:write in addition to tasks:write, and requestId must be preserved across retries.

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 purpose in the first sentence, then stacks constraints in short declarative sentences with no filler. Four sentences for a 7-parameter create tool is efficient, though the permission notes are slightly fragmented across the text.

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 preconditions, auto-assignment, status validity, extra permission scope for attachments, and retry semantics, while the output schema handles return values. Adequate for a create tool; it could still clarify duplicate-request/dedupe behavior for the requestId.

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 every parameter is already documented in the schema (including requestId reuse and status lookup via list_project_statuses). The description largely restates those constraints rather than adding syntax or format detail, so the baseline 3 applies.

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

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

States a specific verb+resource ('Create a task') and adds the precondition that the user must have specified the target project and intended task. It is clearly distinguishable from edit_task_content/update_task by the create verb, but it never names or contrasts a sibling explicitly, which keeps it short of a 5.

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

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

Gives a clear usage condition ('after the user has specified the target project and intended task') plus the prerequisite that the initial status must belong to the project. It offers no explicit when-not or named alternative, so it stops at clear context rather than 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 declare destructiveHint=true and idempotentHint=false, and the description adds the context behind that: edits are validated by a collaborative editor, large removals require the allowRemoval flag, and retries must be idempotent via a preserved requestId. This is exactly the operational detail the booleans 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?

Four short sentences, purpose first, then editing strategy, then the two cautionary behaviors. No filler, no restatement of the title, and each clause carries an actionable instruction.

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 an output schema present and rich per-field, per-enum descriptions in the schema, the description only needed to cover workflow semantics — preconditions, edit strategy, removal gating, and conflict recovery — all of which it does. Nothing material for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes further by explaining why allowRemoval exists (the editor checks large removals) and tying requestId to the retry-after-conflict workflow. It restates some schema content, but the gating rationale and retry contract add real 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 opens with a precise verb+resource+mode: 'Apply targeted Markdown edits to a doc after reading its current content,' and the emphasis on targeted edits implicitly separates it from the coarser update_doc sibling. It never names update_doc outright, so an agent must still infer which of the two doc-mutation siblings to pick in edge cases.

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 the prerequisite (read the doc first), the preferred mode (exact text or block edits), the discouraged mode (full rewrites and large removals, which the collaborative editor inspects), and an explicit gating condition for allowRemoval. Conflict handling is also spelled out: re-read, do not blindly retry, keep requestId on retries.

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 destructive=true and idempotent=false, but the description adds genuinely new behavior: full rewrites and large removals are gated by the collaborative editor, removals require an explicit allowRemoval flag, and conflicts require re-reading with requestId preserved on retry. That conflict/retry semantics is exactly the context 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?

Six tight sentences, front-loaded with the core action and preference order, then the safety gate, then conflict handling. No filler or repetition; each sentence carries an actionable rule.

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 an output schema present and rich annotations, the description only needs to supply operational caveats, and it does: read-first prerequisite, edit-preference, removal gate, and conflict/retry protocol. An agent has everything needed to call this correctly on the first attempt.

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 already documents id, edits, requestId, and allowRemoval in detail. The description reinforces allowRemoval's condition and requestId reuse on retries, but largely echoes what the schema states, so the baseline 3 applies.

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

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

States a specific verb (apply targeted Markdown edits) and an unambiguous resource (a task), with the constraint that it operates on existing content after a read. This cleanly separates it from edit_doc_content, which targets a different resource, without needing to name the sibling.

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 and preferences: read current content first, prefer exact text or block edits, set allowRemoval only for user-requested removals, and re-read after a conflict rather than retrying blindly. It lacks an explicit 'when to use this vs update_task / edit_doc_content' routing statement, so it falls short of a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds real value beyond them: what content each type returns (task/doc bodies, bounded message text, file metadata), the legacy bare-ID fallback, and the required permission.

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 tightly packed sentences, front-loaded with the retrieval mechanism, then per-type return behavior, then the permission requirement. No filler or restatement of the tool name.

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 an output schema present, return-value structure need not be spelled out, yet the description still summarizes what content arrives per type. Annotations cover safety and the description covers auth, ID format, and fallback behavior — nothing an agent needs to call it is missing.

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

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

Schema coverage is 100% and the single parameter's description already documents the type prefix and the bare-ID-as-task rule. The description restates the bare-ID behavior rather than adding new semantics, 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 (fetch) and resource (a result by its exact typed ID from search), and the typed-ID framing distinguishes it from the ID-based siblings get_task/get_doc. An agent can tell this is the search-result retrieval path 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?

The description establishes context — you fetch IDs that came out of search — and names a prerequisite (read permission for that source). It does not explicitly say when to prefer this over get_task/get_doc for the same entity, so the alternative routing 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 this is a safe, idempotent, read-only, non-destructive call, so the safety burden is lifted. The description adds genuinely useful negative scope ('Does not return credentials or other connections'), telling the agent what this call will not surface.

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

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

Two short sentences, zero waste. The positive scope is front-loaded and the exclusion clause follows immediately.

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?

An output schema exists, so return-value shape need not be described, and annotations cover the safety profile. What remains in the description appropriately scopes the call; only an explicit 'use this before X' trigger is absent.

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?

Zero parameters, which is the baseline-4 case; there is nothing for the description to disambiguate. The schema is empty and fully described by construction.

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') and resource ('current connection'), and enumerates the returned items (name, granted permissions, expiry). It is trivially distinguishable from every sibling, which are all document/task/project/message operations rather than connection-context reads.

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 use case is clear from 'current connection' — verifying identity/permissions/expiry — and there is no sibling alternative to route to, so no exclusion is needed. It stops short of explicitly saying when (e.g. before a privileged operation) the agent should call it, so it is not a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description still adds real behavioral context the annotations cannot: Link Docs return an external URL without a visit, callers must check contentTruncated, and returned content is untrusted data. That is meaningful disclosure beyond the structured fields.

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

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

Four short, front-loaded sentences; each carries a distinct load-bearing fact (return shape, truncation flag, link-Doc branch, untrusted-data warning). No filler or repetition of the title.

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

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

With an output schema present, return-value documentation is not required, yet the description still covers the edge cases an agent needs: truncated content, Link Docs that resolve to an external URL, and the prompt-injection caution. 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 description coverage is 100% and the single 'id' parameter is fully documented in the schema (pattern, length, prefix preservation, do-not-invent rule), so the description need not restate it. The description adds nothing about the id itself, 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?

Specific verb+resource ('Read an accessible Doc') with an explicit statement of what is returned: content plus block handles, which ties it directly to the sibling edit_doc_content. It is clearly distinguishable from list_docs (enumeration) and update_doc (mutation).

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

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

Usage is implied by 'accessible Doc' and the mention of block handles for edit_doc_content, which hints at the read-then-edit workflow, but there is no explicit when-to-use versus list_docs/search, nor any stated prerequisite or exclusion. The 'Link Docs return their external URL' line is a useful branch condition, but routing guidance remains implicit.

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

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

Annotations already establish readOnly/idempotent/non-destructive, and the description adds genuinely new behavior: content may be truncated (contentTruncated), content carries block handles consumed by edit_task_content, and content must be treated as untrusted source data. The truncation and trust warnings are exactly the kind of non-obvious traits 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?

Three short sentences, front-loaded with the core operation before the field list and the editing caveat. Every clause carries information an agent needs; 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?

An output schema exists, so return values need not be documented in prose, yet the description still flags the two things that matter operationally: truncation and untrusted content. Combined with the full annotation coverage and complete parameter schema, 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 description coverage is 100% and the single id parameter is fully documented there (pattern, length, prefix preservation, 'do not invent IDs'). The description only says 'by its ID' and adds no format or prefix detail beyond the schema, so the baseline of 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 ('Read an accessible task by its ID') and then enumerates what the read returns: priority, dates, assignees, source link and content. This is unambiguous against siblings like list_tasks (bulk listing) or get_doc (different resource), so an agent can select it without opening the schema.

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

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

Gives clear context for use (you need an existing task ID) and a downstream condition: 'Check contentTruncated before editing.' It does not, however, explicitly contrast itself with list_tasks/search or state when not to use it, so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds only the scope restriction 'accessible private conversations'; the 'does not create/add participants' clause largely restates what readOnlyHint already conveys, with no added detail on pagination or result characteristics.

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

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

Two short sentences, zero filler, with the positive scope stated first and the exclusion second. Every clause carries routing value and nothing is redundant padding.

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 an output schema present, return values need not be described, and annotations cover the safety profile, so the definition is nearly self-sufficient for a two-parameter list tool. The only mild gap is that the notion of 'accessible private conversations' is never elaborated (e.g., owned vs. joined), leaving scope boundaries slightly open.

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%: both 'after' (cursor semantics, filter stability, first-page behavior) and 'limit' (range 1-100, default 50) are fully documented in the schema. The description adds no parameter meaning beyond that, so the baseline of 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?

Clear verb+resource ('List ... conversations') with two scoping qualifiers: 'existing' and 'accessible private'. An agent immediately knows this is a read-only enumeration of private conversations. It does not, however, explicitly distinguish itself from list_docs/list_projects/list_tasks siblings beyond the resource noun.

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 second sentence provides negative scoping ('Does not create conversations or add participants'), which implicitly tells the agent this is not the write path. However, it names no positive trigger condition and no explicit alternative tool, so the when-to-use guidance remains inferential rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world, so the safety profile is covered. The description adds only the access-scoping detail ('accessible Docs'); it says nothing about pagination behavior or result shape, though the schema documents the cursor. Modest added value on top of rich annotations.

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

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

Two compact sentences with no filler, and the core purpose is front-loaded before the workflow tip. Nothing is wasted, though the second sentence is of secondary relevance to selecting this tool.

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?

An output schema exists, so return values and pagination need not be re-explained; the description correctly covers purpose, filter scope, and the follow-up get_doc step. Only the absence of explicit when-to-use versus search leaves a small gap for a read-only listing tool with five all-optional params.

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

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

Schema description coverage is 100%, so all five parameters (after, limit, order, query, projectId) are fully documented in the schema itself. The description's mention of 'project and title' filtering faintly echoes projectId and query but adds no syntax or semantics beyond the schema. 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 ('List accessible Docs') plus the filter scope ('optionally filtering by project and title'), which is enough to distinguish it from get_doc and the other list_* siblings. It stops short of explicitly naming the alternative list-like tool (search), so it is clear but not maximally differentiated.

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

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

The only routing guidance is a downstream workflow tip ('Read a Doc with get_doc before editing its contents'), which implies list->get_doc->edit but never says when to prefer this tool over search or the other list_* tools. Usage context is implied rather than stated.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so safety is covered. The description adds genuine boundary context by stating it does not download content or expose storage credentials, which clarifies what an agent will and will not get back. Minor gap: nothing about pagination behavior, though the schema covers that.

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

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

Two tight sentences, front-loaded with the action and scope, with the exclusion clause second. Nothing is wasted.

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

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

An output schema exists, so return values need not be explained, and the schema handles pagination. The description covers scope and boundaries well; only explicit sibling routing is missing.

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

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

Schema description coverage is 100%, with cursors, limits, ordering, and filter IDs all documented in the schema itself, so the baseline is 3. The description adds only a light restatement of the project/task filter, no extra semantics.

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

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

States a specific verb and resource ('List accessible file metadata') plus an optional scope ('within a project or task'). It also carves out what it does not do (no content download), which implicitly separates it from fetch and upload_file, though it never names those siblings.

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

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

The optional project/task scoping hints at when to reach for it, but there is no explicit when-to-use versus alternatives such as get_task, list_projects, or search. Usage is implied rather than stated.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description still adds real behavior context: no invitations are sent as a side effect, email addresses are withheld from the payload, and the returned IDs are meant to be reused as assignees. It does not mention pagination behavior in prose, but the schema covers that.

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

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

Three short sentences, front-loaded with the core verb+resource and scope, followed by the practical use and the two negative constraints. Every sentence earns its place with no redundancy.

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

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

An output schema exists, so return values need not be re-explained, and the input schema fully documents all three parameters including pagination. The description covers purpose, exclusions, and downstream use, leaving only very minor omissions such as result ordering or page size behavior.

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

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

Schema description coverage is 100%, and the schema already documents projectId, limit, and the after cursor with format, bounds, and defaults. The description adds nothing parameter-specific beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ("List existing members of an accessible project") and scopes it to accessible projects, which separates it cleanly from siblings like list_projects and list_project_statuses. It also declares the downstream purpose of the returned IDs, making the tool's role 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?

Gives clear usage context ("Use their IDs for task assignees") and two explicit exclusions: it does not invite anyone and does not expose email addresses. It stops short of naming an alternative tool to use for inviting or for fetching contact details, so it is strong but not fully routing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds pagination-stability guidance ('Keep ordering unchanged across cursor pages'), but that constraint is already repeated in the schema's cursor and order descriptions, so the added value is marginal.

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

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

Three short sentences, front-loaded with the scope before the workflow hint and pagination note. Efficient, though the final pagination sentence largely duplicates schema 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?

An output schema exists, so return values need not be explained, and annotations carry the safety profile. The description covers scope and downstream ID use adequately; only the meaning of 'accessible' (permission scoping) is left implicit.

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

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

Schema description coverage is 100%, with defaults, ranges, and an enum all documented, so the schema does the heavy lifting. The description adds no parameter-level meaning beyond what the schema already provides, which is the expected baseline of 3.

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

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

States a specific verb (List) and resource (projects) scoped to 'accessible' projects in the connected workspace, which separates it from list_docs/list_tasks/list_files by resource. It does not, however, explicitly name a sibling or explain how it differs from e.g. list_project_members.

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?

'Use returned IDs for later actions' gives implied downstream context, but there is no explicit when-to-use, when-not-to-use, or alternative routing. Usage is inferable from the resource name rather than stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds no behavioral context beyond that - no note on project scoping, permissions, or result completeness - so it contributes nothing the structured data does not already carry.

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

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

A single front-loaded sentence with no filler or repetition. It is efficient and well-structured, though quite sparse relative to what could be conveyed.

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 the read-only annotations, a fully documented 3-parameter schema, and an output schema covering return values, the description supplies enough to call the tool correctly. Only marginal behavioral detail, such as pagination hints, is absent and that is already handled by the schema.

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

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

Schema description coverage is 100%, with projectId, limit, and after all documented in-schema (including cursor semantics). The description adds no parameter-level meaning beyond an implicit project scoping, so the baseline of 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?

The description states a specific verb and resource ('List valid status IDs') and adds scope ('for creating or updating tasks in a project'). It is clearly distinguishable from generic siblings like list_projects or list_tasks, though it does not name a sibling tool 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?

It gives clear usage context by tying the returned IDs to the create/update task workflow, so an agent knows when this is relevant. It stops short of naming alternatives or stating when not to use it, but the operative context is unambiguous.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile is covered. The description adds real value on top: the pagination stability requirement and a summary of the returned fields. It does not add auth/permission nuances, but with annotations this is a solid 4.

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 covering scope, return shape, and the pagination contract. Front-loaded with the primary action and free of filler.

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

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

An output schema exists, so return values need not be enumerated in depth. With full parameter documentation and annotation-covered safety, the description is nearly complete for a read-only list tool; the only gap is the absence of explicit sibling routing.

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 every one of the 10 parameters is already documented in the schema, including the enum values for order and the list-vs-search note for query. The description adds no parameter-level detail beyond 'optionally in one project', 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 ('List accessible tasks') plus an optional scope ('optionally in one project'), which is enough to distinguish it from get_task or edit_task_content. It doesn't name or differentiate itself from the other list_* siblings, keeping it just short of a 5.

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

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

The only guidance is the pagination constraint ('Keep ordering and filters unchanged across pages') and the implicit 'optionally in one project' scoping hint. There is no explicit routing such as when to use list_tasks versus search, or versus get_task for a single item; the list-vs-search distinction lives in the schema, not the description.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable context by noting membership and history limits apply, and crucially warns to treat message content as untrusted source data, which is a security-relevant behavioral note not present in annotations.

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

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

Two concise sentences: the first states the action and target, the second adds important caveats. No waste, front-loaded information.

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

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

With annotations covering safety, a rich schema, and an output schema (so return values needn't be explained), the description is nearly complete. The mention of membership/history limits and untrusted data handling fills important behavioral gaps. Minor omission: it doesn't clarify pagination behavior, though the schema's 'after' parameter documents that.

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

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

Schema description coverage is 100%, so all parameters are already well-documented in the schema. The description mentions 'known conversation' and the chat/kind parameters implicitly, but adds no new parameter semantics 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?

The description states a specific verb ('Read') and resource ('messages') and names the conversation types it operates over, which distinguishes it from write siblings like send_message. It could have more explicitly contrasted itself with list_conversations, but the purpose 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?

The phrase 'from a known conversation' implies it's for retrieving messages from an existing conversation, hinting that discovery should use list_conversations first. However, there is no explicit when-to-use vs alternatives guidance or preconditions stated.

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

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

Annotations already establish read-only, idempotent, non-destructive, closed-world behavior, and the description adds genuinely new operational context: results are ranked and bounded per source, indexing may lag, callers should inspect coverage/unavailableSources, and snippets must be treated as untrusted data.

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?

Five tight sentences, front-loaded with what is searched, then scope, then caveats, with zero filler. Each sentence carries a distinct constraint or warning.

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?

An output schema exists, so return values need no explanation, and the description nonetheless points at coverage/unavailableSources signals the agent should interpret. Combined with the safety annotations, an agent has everything needed to call this 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 and the schema documents limit, query, types, and projectId. The description still adds scope semantics beyond the schema, noting that types are constrained by the connection's read scopes and that omitting types defaults to all readable sources.

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 set ('Search indexed tasks, Docs, files and project messages') and immediately bounds scope to accessible projects. It also carves out what is not covered (private chats, projectless items), which separates it from the list_* and get_* 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?

Gives clear default behavior ('searches only sources this connection can read'), the condition for narrowing ('explicit types require their read scopes'), and explicit exclusions ('Does not search private chats or projectless items'). It stops short of naming an alternative tool, but the query-parameter note distinguishes list tools from search in practice.

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

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

Annotations already declare the destructive/non-idempotent/closed-world profile, so the bar is lower, and the description still adds two genuinely useful facts: the message is visible to other conversation members, and requestId must be preserved on retries. 'Preserve requestId on retries' is consistent with idempotentHint=false rather than contradicting it, since the key exists precisely because the raw call is not idempotent. It does not explain failure or partial-success behavior.

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

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

Four short sentences, front-loaded with the action and immediately followed by the guardrail, visibility note, and retry rule. No sentence is redundant 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 an output schema present and annotations covering the safety profile, the description supplies the remaining essentials: intent scope, ambiguity guardrail, audience visibility, and retry identity. Only minor gaps remain, such as what happens when the destination is inaccessible or the send fails.

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

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

Schema description coverage is 100%, and the schema already documents body, chat.id, chat.kind, and requestId reuse semantics. The description's retry note on requestId merely mirrors what the schema property description already states, so nothing new is added. Baseline 3 applies when the schema does the heavy lifting.

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

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

The description names a specific verb and resource ('Send the message ... to a specified accessible conversation'), which makes it trivially distinguishable from read-oriented siblings like read_messages and list_conversations. The scoping phrase 'explicitly requested by the user' further narrows intent beyond a generic send.

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 a clear precondition for when to act ('explicitly requested by the user') and an explicit when-not/verify rule ('Confirm ambiguous destinations or wording before calling'). It stops short of naming alternatives (e.g., using list_conversations to resolve a destination), so it is clear context without 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 declare destructiveHint=true, idempotentHint=false, and openWorldHint=false, so the mutation/idempotency profile is covered. The description adds retry guidance ('Preserve requestId on retries') and permission framing ('accessible'), but never says the previous title is overwritten irreversibly — the key destructive consequence. Moderate added value over annotations.

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

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

Three short sentences, no filler, with the core action front-loaded and the routing hint immediately after. 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?

An output schema exists, so return values need not be explained, and annotations carry the safety profile for this mutation. The one gap is the absence of any statement about what happens to the existing title or permission failures, which for a destructive-headlined tool would be worth a clause.

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

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

Schema description coverage is 100%, so id, title, and requestId are fully documented in the schema, including the retry semantics the description repeats. The description adds nothing the schema does not already say about parameters; 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?

The description states a specific verb+resource+scope: 'Update the title of the specified accessible Doc.' This differentiates it cleanly from create_doc (creation), get_doc (read), and edit_doc_content (body edits), which it names 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?

It gives a clear routing rule: use this tool for title changes, use edit_doc_content for body changes. That is explicit when-to-use guidance with a named alternative. It stops short of stating exclusions (e.g. locked/trashed docs) beyond the word 'accessible'.

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 idempotentHint=false, so the safety profile is covered. The description goes further by disclosing replacement semantics ('assigneeIds replaces the entire list; [] unassigns everyone'), null-vs-omit clearing behavior, and retry safety via requestId. It does not describe return payload or partial-failure behavior, but the destructive edge cases an agent must know are surfaced.

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?

Five tight sentences with zero filler; the field list, prerequisite ordering, alternative routing, and edge-case semantics all earn their place. Front-loaded with the core action and progressively narrows to warnings.

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 an output schema present the description need not explain returns, and it covers the remaining gaps: ordering constraints, the sibling boundary, destructive list replacement, null-clearing, and requestId reuse on retries. An agent has everything needed to invoke this mutation safely.

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 every parameter is already documented, including the same replacement and null-clearing rules. The description consolidates these into one readable rule set, which aids correct invocation, but it largely restates schema text rather than adding new meaning. Baseline 3 is appropriate.

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

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

States a specific verb (Update) plus the resource (task) and enumerates the mutable fields up front. It also explicitly carves out the sibling edit_task_content for the description field, so an agent can separate the two without reading either schema. No ambiguity about what this tool touches.

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

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

Gives a concrete prerequisite sequence ('Resolve the target, status and members first') and routes the description-writing case to edit_task_content by name. There is no explicit when-not guidance against create_task or get_task, but the mutation context is clear enough to act on.

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?

Adds substantial context beyond the annotations: server-side URL validation, a concrete 50 MiB / 30-second download ceiling, a credential prohibition, and a privacy disclosure that other project members may see the file. The retry/requestId instruction also explains the practical dedup semantics behind the idempotentHint=false declaration.

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 carrying distinct information – purpose, limits, security, visibility, retry – with the core purpose front-loaded. Nothing is redundant with the title or restated.

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?

An output schema exists, so return values need not be explained. The description covers the constraints an agent needs before calling – size/timeout limits, HTTPS/public requirement, no credentials, and retry identity – making it complete for this 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 description coverage is 100%, so the schema already documents all six parameters including the URL's credential/private-network restriction and requestId reuse. The description adds no per-parameter format or default detail beyond what the schema states, so the baseline 3 applies.

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

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

The description states a specific verb and resource ('Import a user-specified public HTTPS file') and pins the destination scope ('into an accessible project or task'). It clearly separates this URL-import tool from read/list siblings like list_files, but it never names or contrasts an alternative tool 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?

It gives operational rules ('Do not include credentials in the URL', 'Preserve requestId on retries') but no when-to-use/when-not-to-use guidance relative to siblings such as create_doc or a hypothetical local upload. Usage is implied by the constraint list rather than routed.

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