Tango

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

Goes well beyond the readOnly/destructive hints by disclosing that the original receipt is never rewritten on rejection, that the decision is written into the transparency chain alongside the receipt, and by naming the authorization model (approver, org owner/admin, platform staff; workers cannot self-accept). These are exactly the behavioral facts an agent needs before mutating delivery state.

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 purpose, then handles outcomes, writes, and permissions in a tight sequence with no filler. It is dense but each clause carries operational weight; the API reference link is a reasonable trail-off rather than 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?

No output schema exists, so the description should ideally say what a successful call returns, and it only implies the decision is recorded. Everything else an agent needs for a 4-parameter mutation — required fields, outcome semantics, authorization — is present and consistent, so the gap is narrow.

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 by tying `note` to specific outcomes ('what the shortfalls are' vs 'what must change') and explaining that `superseded` requires naming a replacement task. It does not add format hints for task_id (short reference vs URL is covered in 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 (accept) and resource (a completed task's delivery), and immediately enumerates the four discrete outcomes, which separates it from siblings like complete_task and send_back_to_creator. An agent can identify this as the acceptance-decision tool 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 defines what each outcome means and the condition each implies (rejected returns to the worker with a required reason, superseded names the replacing task), which is genuine when-to-use guidance. It does not, however, route to alternatives such as send_back_to_creator or prepare_completion, so the sibling boundary is left 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 only declare readOnlyHint=false and destructiveHint=false, but the description discloses a rich behavioral contract: lease-holder attribution wins over acting_worker_id, ownership mismatch drops attribution rather than misrecording, invalid signatures reject the call and store nothing, delegated workers are signed automatically, and it references the API docs. This is far beyond what the annotations provide and covers exactly the edge cases an 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?

Dense but front-loaded: the tool's purpose and use cases come first, then file-input routing, then attribution/signing rules, then the docs link. Every sentence carries information, though the attribution/signature sentence is long and could be split for readability.

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 15-parameter, multi-route mutation tool with no output schema, the description covers input selection, evidence_kind relevance to task completion, evidence_artifact_ids wiring, attribution semantics, and signing/attestation rules. Nothing an agent needs 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 description coverage is 100%, so the baseline is 3. The description adds meaning the schema doesn't carry alone: it groups content_base64/fetch_url/upload_token as the three mutually exclusive ways to supply file bytes, clarifies content stays inline text and external_url is record-only, and explains the lease-vs-acting_worker_id interaction.

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 (attach) and resource (artifact), enumerates the concrete outputs it covers (notes, drafts, results, files, links), and explicitly separates itself from sibling create_artifact_upload by describing when each is used. An agent can distinguish this from add_comment and create_artifact_upload 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?

Explicit when-to-use for every input route: content_base64 for files up to ~6 MB, fetch_url for hosted files, create_artifact_upload for large files, content for inline text, external_url for record-only links. It also directs the agent to reference artifact ids in complete_task's evidence_artifact_ids and names create_artifact_upload as the alternative path.

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 it is a write (readOnlyHint=false) and non-destructive. The description adds genuinely behavioral context beyond that: no lease/worker identity is required, and comments surface in the task's activity timeline and the web UI, which tells the agent the side effect and visibility. It stops short of auth/rate-limit detail, so not 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?

Front-loaded with the core action, then the sibling contrast, then the visibility note. Three tight sentences with no waste; the trailing API reference URL is minor padding but harmless.

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

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

For a simple two-parameter write tool with annotations covering the safety profile and no output schema needed, the description covers purpose, alternative, and where the result appears. It omits auth requirements beyond the lease point and any rate-limit note, which keeps it from a 5.

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 both parameters (task_id accepting an id or URL, body supporting @handle mentions) are already documented in the schema. The description adds no parameter-level meaning beyond that, 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 ('leave a comment') and resource ('on a task'), with the scope made concrete ('plain comment ... for your teammates'). It explicitly names and contrasts with the sibling add_progress_note, so an agent can distinguish it 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?

States when to use it ('questions, context, and notes to whoever picks the task up next') and names the alternative (add_progress_note) plus the selecting condition (no lease or worker identity needed). This is explicit routing guidance, not 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?

Goes well beyond the annotations: it discloses the attribution precondition (active lease, or an owned acting_worker_id, or a human assignee/org owner), the exact failure mode (422 with nothing written), and the non-obvious rule that the actor is never inferred from the assignee. For a mutation tool whose annotations only say readOnly=false/destructive=false, this is rich, decision-relevant 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, then constraints, then error behavior, ending with the API reference. It is a dense paragraph rather than discrete sentences, but nearly every clause carries operational information; the reference link is the only arguably optional element.

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, preconditions, and failure behavior for a 3-parameter tool with no output schema. The one omission is what a successful call returns/adds to the event log, though the append-to-log framing makes that largely self-evident.

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 on acting_worker_id: that lease precedence overrides it and that ownership is verified. That is semantics the schema does not fully convey, lifting it 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?

The description states a specific verb and resource: 'Append a progress note to a task's event log', with the intent (teammates following work without asking) made explicit. It is clearly distinguishable from add_artifact or task-mutating siblings, though it never names add_comment or log_project_event as the closest alternatives, so the boundary against those is left to inference.

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

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

Gives concrete when-to-use guidance ('at each meaningful step — decisions, blockers, findings'), which tells the agent the cadence and content type expected. It does not, however, state when NOT to use it or explicitly route to a sibling such as add_comment for discussion-style messages.

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 readOnlyHint=false and destructiveHint=false, so the agent knows this is a non-destructive write. The description goes beyond that by disclosing the concrete side effects: the answer is recorded on the question thread and posted to the task timeline so the asking agent can read it. It does not cover permissions or what happens if the question is already answered.

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 plus an API reference link, with the core action front-loaded and no redundant restatement of the name or title. The reference URL is the only mildly expendable element, but it is a legitimate pointer rather than 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 compensates by explaining what happens to the answer (thread + timeline), which is the key return-value substitute an agent needs. Missing edge-case behavior (already-answered questions, permission requirements) keeps it from a 5, but it is adequate for a simple two-parameter write.

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 question_id (with UUID format and provenance) and answer (with 1-4000 length bounds) are fully documented in the schema. The description adds no additional semantic detail about the parameters, 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 ('Answer') and resource ('an open question raised on a task'), and the second sentence clarifies the effect. It implicitly separates itself from list_open_questions, but does not name a sibling explicitly, so it stops short of a 5.

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

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

Usage context is implied (answer an open question) and the schema points to list_open_questions/get_task as the source of question_id, which helps routing. However, there is no explicit when-to-use vs when-not guidance, nor any mention of alternatives like add_comment for non-question communication.

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 destructiveHint=true and readOnlyHint=false; the description goes far beyond by enumerating concrete effects (cannot claim/lease tasks, drops out of list_client_team and whoami, frees quota) and, importantly, what is NOT destroyed (history, receipts, transparency-log entries stay queryable). It also flags reversibility, which tempers the destructive hint meaningfully.

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

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

Three compact sentences, front-loaded with the core action and effects, followed by the reversibility escape hatch and a reference link. Every sentence earns its place; no filler.

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

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

With no output schema, the description carries the return/effect burden and does so thoroughly (state changes, list visibility, quota, preserved history, reversibility). Nothing an agent needs to invoke this destructively-but-reversibly 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 50%: worker_id carries format/pattern but no prose, while reason is documented in the schema itself ('Why this worker is being retired.'). The description adds no parameter-level meaning beyond the schema, so this sits at the baseline for a partially documented 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 precise verb+resource ('Soft-delete a worker') and immediately clarifies the scope of that soft-delete, distinguishing it from the sibling delete_worker and from unarchive_worker. An agent can pick this tool over its near-neighbors without opening any other definition.

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 reverse operation ('Reversible with unarchive_worker') and spells out the operational consequences that motivate choosing this tool. It stops short of an explicit when-to-use-this-vs-delete_worker rule, but the soft-delete framing makes the choice fairly clear.

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 this is a non-read-only, non-destructive mutation. The description goes well beyond that, disclosing the full workflow: the task is paused as blocked, the recipient is notified, the task resumes at the same point on answer, and the result surfaces via the next check_in. That is precisely the kind of state-transition context annotations cannot carry.

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

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

Front-loaded with the usage condition and the state transition, then a compact second clause covering resumption. The trailing API reference URL is marginally useful but is the one element not strictly earning its place in the prose.

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

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

No output schema exists, and the description compensates by explaining how the answer is delivered (via the next check_in), so the agent knows what to do after invoking. Combined with 100% schema coverage and annotations covering the safety profile, nothing material is missing.

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

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

Schema description coverage is 100%, including the Tango Lite default for task_id and the approver/owner default for to_user_id, so the schema already does the heavy lifting. The description adds only the 'ONE person' recipient framing, no syntax or format detail. Baseline 3 is appropriate.

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

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

States a specific verb and resource (ask a human a question) and constrains scope to 'ONE specific fact or decision from ONE person', which implicitly separates it from broadcast-style siblings like send_message or add_comment. It does not, however, name any sibling explicitly (e.g. flag_needs_more_info, answer_question), so differentiation still requires inference.

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

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

Gives an explicit triggering condition: 'Use when you need ONE specific fact or decision from ONE person before you can continue.' That is a clear when-to-use statement, but there is no when-not guidance and no named alternative for adjacent cases (e.g. when to flag_needs_more_info 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 only declare readOnlyHint=false and destructiveHint=false; the description adds the real behavioral payload (attribution of all subsequent calls, visibility in leases/receipts/audits, and the auto-provisioning default it overrides). It does not cover reversibility (how to unbind), ownership validation failure behavior, or whether the binding persists across sessions, so it falls short of a 5.

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

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

Three sentences front-loaded with the action and effect, then the when-to-use caveat, plus a docs URL. The rationale sentence is slightly long but earns its place by explaining why attribution matters; nothing is redundant with the title.

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

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

For a single-parameter identity tool with no output schema, the description covers what it does, when to use it, and the default it overrides. Missing only edge-case behavior such as invalid/unowned worker_id responses and how to undo the binding, which an agent might want before mutating connection state.

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

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

One parameter with 100% schema description coverage, so the schema already defines worker_id including the UUID format and the "from whoami" discovery hint. The description restates the ownership constraint ("a worker you own") but adds no syntax, format, or discovery detail 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 (point/bind) and resource (this MCP connection -> a worker you own) plus the downstream effect: every tool call from this connection is attributed to that worker. This is clearly separable from siblings like create_worker, whoami, or issue_worker_key, which concern worker creation or credentials rather than connection identity.

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 and the default alternative: "Tango auto-provisions one worker per connection on first use; call this only to reuse an existing worker instead." An agent can decide between doing nothing and calling this tool without 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 only supply readOnlyHint=false/destructiveHint=false, and the description adds real behavioral substance beyond them: every reference is pre-validated and the operation is all-or-nothing ('if any is unknown or ambiguous nothing changes'), the same permission rules as the app's bulk bar apply, and a per-task report of changed/skipped items is returned.

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 enumeration of actions, followed by validation/atomicity behavior, permission model, and report format, with the docs link last. The action list moderately duplicates the schema enum but is defensible as a scan-friendly summary; overall dense with little waste.

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

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

For a mutation tool with no annotations beyond hints and no output schema, the description covers atomic pre-validation, the permission model, and the shape of the result (per-task report of what changed and why it was skipped). Nothing critical for invoking it correctly is missing.

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

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

Schema coverage is 78% and most parameter semantics live in the schema, but the description adds genuine value by specifying the accepted reference formats for task_ids (full ids, short ids like fd959117, or task links) — a format the schema does not state. It does not, however, add anything for reason, status, or deadline beyond what the schema already documents.

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?

Names a specific verb (bulk update) and resource (tasks) and enumerates the exact operations available (move, set/clear deadline, set status, park/unpark, reassign), which maps cleanly onto the action enum. The 'up to 100 tasks' scoping and 'ONE change' framing immediately distinguish it from the single-task update_task 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?

Strong implicit guidance via the 'Apply ONE change' constraint (multiple changes require multiple calls) and the scope limit of 100 tasks. However, it never explicitly names the alternative for single-task edits (update_task) or states when-not to use bulk semantics, so it stops short of explicit 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 declare readOnlyHint=false and destructiveHint=false, so the safety profile is partly covered. The description adds that calls are forwarded to an external gateway, but does not disclose that downstream external tools may have side effects, auth requirements, or error propagation behavior. It adds some context without contradicting 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?

Three sentences, front-loaded with the core action and scoping, followed by use-case examples and a reference link. No wasted text, though the API URL is the least essential element.

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 gateway/proxy tool with a rich 4-param schema (including a method enum and timeout) and no output schema, the description covers purpose and routing adequately. It stops short of describing response shape or failure modes, which an agent invoking arbitrary external tools would benefit from knowing.

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 each parameter (method enum, arguments, tool_name, timeout_seconds with default) is documented in the schema. The description adds no parameter-level meaning 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 ('Forward a tool call to the organization's configured executor.sh MCP gateway') and clarifies the class of action via examples (GitHub, Slack, sandbox functions). No sibling in the list does proxy/gateway calls, so it is easy to distinguish from task/project management tools.

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

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

Explicitly says when to use it: to reach tools hosted outside Tango. It gives concrete example targets, but offers no when-not guidance (e.g., what to do if the tool is already integrated natively via list_integrations/read_integration).

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 readOnlyHint=false, which is non-obvious for something called a 'poll'; the description resolves this by disclosing that Tango persists a cursor and that repeated calls return only new items, plus the advance_cursor peek mode. It adds meaningful stateful-behavior context beyond the annotations, though it says nothing about rate limits or response shape.

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 first word 'Cursor-based poll:' front-loads the mechanism, the return contents follow, and usage cadence ends the description. It is dense but not padded; the trailing API reference URL is useful rather than 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?

There is no output schema, so the description must convey what comes back, and it does by listing the three return categories and the incremental cursor semantics. Missing detail on response structure/pagination keeps it just short of full completeness.

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 75% schema description coverage, the schema already documents worker, since, and advance_cursor, and the description only reinforces the cursor semantics ('since your last check-in'). The undocumented 'limit' parameter gets no explanation in either place, and the description adds no syntax detail beyond what the schema states.

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?

It names a specific verb and mechanism ('Cursor-based poll') and enumerates exactly what is returned: tasks newly assigned to you, tasks whose client/project context changed, and revised context objects. This is enough to distinguish it from siblings like pull_next_task, list_my_tasks, or check_in-adjacent reads 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?

It gives explicit cadence guidance: 'Call this at the start of every session or turn, and on your polling interval,' which tells the agent when to invoke it. It does not name a competing alternative or a when-not condition (e.g. versus pull_next_task or get_polling_instructions), 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 only say readOnlyHint=false and destructiveHint=false, so the description carries the real behavioral payload: a lease is taken and an existing stale lease held by another worker is released when the task is assigned to your worker. That side effect on other workers is genuinely beyond the annotations. It stops short of the obvious follow-up cases (what happens when the task is not assigned to your worker, or when a live lease is held) and doesn't mention renew_lease for keeping it.

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 action and then the disambiguation rule; no filler or restatement of the title. The trailing API reference URL is the one element that doesn't help an agent decide or invoke, keeping it just below maximum.

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

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

For a 3-parameter tool with full schema coverage and no output schema, the description supplies the missing pieces: exclusive-lease semantics, the stale-lease release side effect, and the alternative tool. It is slightly thin on failure modes (already actively leased, task not assigned to your worker) but nothing essential for correct invocation 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?

Schema description coverage is 100%, so task_id, worker_id and lease_seconds are already documented with defaults, format and bounds. The description only reiterates 'by id' and adds no syntax, defaulting or edge-case meaning beyond the schema — the baseline 3 for fully covered schemas.

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 ('Take a lease on a specific task by id') and immediately distinguishes itself from the sibling pull_next_task by the selection criterion (task_id already known). An agent can tell it apart from search_tasks, get_task, accept_task and pull_next_task 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?

Explicit routing rule: 'Use this instead of pull_next_task when you already know the task_id', plus a concrete scenario ('one that was handed off to you'). This is the exact when-to-use / alternative pairing the dimension asks for.

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, so the safety profile is covered. The description adds genuinely non-obvious context beyond that: disabling the webhook silently downgrades the worker to polling for future events. It does not clarify whether the webhook URL itself is removed or just deactivated, nor whether the change is reversible.

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 action and its effect, followed by a reference link. No filler or restatement 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?

For a single-parameter tool with an existing output-free surface and annotations that carry the destructive flag, the description covers the key behavioral consequence. Minor gaps remain around reversibility/authentication needed to invoke it.

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

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

One required parameter (worker_id) with 0% schema description coverage, though the schema itself carries a full UUID format and pattern. The phrase 'this worker's webhook URL' weakly implies worker_id identifies the target, but no explicit parameter meaning, format guidance, or error behavior is added in the description.

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

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

Names a specific action and target: 'Stop pushing events to this worker's webhook URL.' An agent can immediately distinguish this from set_webhook (configure), get_webhook (read), and rotate_webhook_secret (rotate credentials) 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?

The consequence 'Future events fall back to polling' implies when this tool is appropriate, but the description never states the use condition explicitly nor names an alternative (e.g., set_webhook to reconfigure instead of disabling). Usage is inferable 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?

Far exceeds the annotations (readOnlyHint=false, destructiveHint=false). It discloses the anti-self-approval rule, human-review routing, atomic lease release, that an invalid signature aborts with nothing written, and that the actor is never inferred from the assignee. These are exactly the transactional and authorization behaviors an agent needs before calling a mutation 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?

Front-loaded with the core action and then layered by audience: authorization rules first, edge cases (422, signature abort) second, reference link last. It is dense and long, but nearly every sentence carries a distinct behavioral constraint, so the length is largely earned rather than 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?

For a 12-parameter, 3-required mutation tool with no output schema, the description covers authorization, failure modes, atomicity, and the prepare_completion handshake. An agent has everything needed to call it correctly without inferring policy.

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 beyond the schema by tying parameters into workflow semantics: the lease holder wins over acting_worker_id, signature fields belong to a prepare_completion round-trip, and they must be passed together. It restates some schema text (outcome, acting_worker_id) but adds coordination context.

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

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

Opens with a specific verb+resource+deliverable: 'Mark a task complete with a structured receipt: summary, evidence artifact ids, open questions.' It also implicitly separates itself from siblings like accept_task/handoff_task by covering the terminal completion action and its authorization model.

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 enumerates the three valid attribution paths (active lease, acting_worker_id, human assignee/org owner), states what happens when none apply (422, nothing written), and names the prerequisite tool call (prepare_completion) for attested workers. There is no ambiguity about when this tool applies or how it will behave.

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 readOnlyHint=false and destructiveHint=false, so the description must add the real behavior: this is a non-destructive write that stamps a check timestamp without altering the stored value, plus an un-retire mode via restore:true. That's meaningful context beyond the annotations, though it does not mention permission requirements or rate limits.

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

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

Three tight sentences: what it does, when to use it, and the restore flag, with the actionable part front-loaded. The trailing API reference URL is slightly extraneous but harmless and consistent with the tool family.

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 non-destructive mutation with an optional un-retire mode and no output schema, the description covers the value-preservation guarantee, the usage trigger, and the alternative mode. It leaves minor gaps (what happens if the fact doesn't exist, whether client/project scoping is required), but nothing critical to 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 80%, so most parameters are already documented in the schema. The description reinforces key ('exactly as it appears') and restore ('bring back a retired fact'), matching the schema descriptions rather than extending them. 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 ('Stamp ... as checked and still true today') on a specific resource (one client or project fact) and explicitly notes it does NOT change the value. This cleanly separates it from update_client_context (which changes values) and retire_context_fact (the inverse operation).

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 trigger condition ('facts get_client_context lists as not confirmed in 60+ days') and names the upstream sibling tool that surfaces those facts. Also covers the restore path for retired facts, implicitly distinguishing it from retire_context_fact. It stops short of stating when NOT to use it, so a 4 rather than 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 declare readOnlyHint=false and destructiveHint=false, so safety is partly covered, but the description adds genuinely useful behavior beyond that: the URL/token are short-lived, bytes must be PUT raw with the correct Content-Type and no base64, and crucially nothing is recorded until finalize so an abandoned upload leaves no artifact. It stops short of stating permissions required or the exact expiry window, hence 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?

Dense and front-loaded: the selection condition, return values, invocation steps, and lifecycle guarantee are all present with no filler sentences. The API reference link is the only extra and is proportionate.

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 explains what is returned (signed upload URL plus upload_token) and the exact follow-up call needed. For a two-step upload flow with a mutation side-effect, the description covers everything an agent needs to avoid stranding an upload.

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 (name, task_id, mime_type, size_bytes). The description echoes task_id, name and upload_token in workflow context but adds no syntax or format detail 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 signed upload URL') and immediately distinguishes itself from the sibling add_artifact by naming the size threshold (~6 MB) that selects it. An agent can tell exactly what this tool does and when it is the right 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?

Names the alternative (add_artifact inline base64 path), the condition that selects this tool (files too big for that path, with examples), and the downstream step (call add_artifact with the same task_id, name, upload_token). The full two-step workflow is spelled out, leaving nothing to inference.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description goes well beyond by disclosing that a same-named workspace is returned rather than duplicated by default, that authorization is restricted to owners/admins, and that plan-limit failures require an owner upgrade. These are exactly the non-obvious traits an agent needs before invoking a mutation.

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, each carrying distinct information (definition, permission, dedup check, plan limit) plus a doc link. Front-loaded with the core action, though the parenthetical resource definition and the closing reference URL make it slightly longer than strictly necessary.

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 explaining the return behavior (existing workspace returned instead of a duplicate) and failure modes (plan limit rejection). Combined with complete schema coverage and annotations, nothing essential for a correct call is missing.

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

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

Schema description coverage is 100%, so all four parameters (including reuse's default-true dedup behavior and the organization default) are already documented in the schema. The description restates the reuse default without adding syntax or formatting detail beyond it, 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 ('Create a new client workspace') and immediately disambiguates the resource with a parenthetical definition ('the shared space that holds a client's projects, tasks, context and team'), which separates it from the sibling create_project. An agent knows exactly what entity is produced.

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 preconditions and alternatives are given: check with whoami or list_projects first, only owners/admins may call it, and calls are rejected when the org hits its client limit. This is the when/when-not/alternatives pattern at full strength.

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 a non-destructive write (readOnlyHint=false, destructiveHint=false), so safety is covered. The description adds non-obvious behavioral context beyond annotations: that a project lives inside a client workspace and that its goal propagates to every child task. It still omits failure/duplicate handling and permissions, so it stops short of a 5.

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

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

Front-loaded with purpose, then the guard, then the goal advice. Sentences are tight, though the trailing bare API-reference URL adds little for an agent already holding 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?

For a mutation tool with no output schema, the description covers purpose, routing, and goal semantics well. The gap is that it frames the project as 'inside a client workspace' while 'client'/'client_id' are optional in the schema (only name is required), so the client relationship is left slightly unresolved.

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 only 50%, and the description meaningfully expands on 'goal' by explaining its inheritance effect, which the schema does not. However, it never clarifies the relationship or mutual exclusivity between the optional 'client' (fuzzy name/handle) and 'client_id' (UUID), which is the main ambiguity, nor touches name/deadline/brief_md. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Create a new project inside a client workspace') and concretizes it with examples (Website, Google Ads, Newsletter, Reporting). It is clearly distinguishable from siblings like create_client and create_task, 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?

Explicitly gives the when-not condition and the alternative: 'Only create one when no existing project fits — call list_projects first.' This is a precise routing rule, not implied 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?

Goes well beyond the annotations (which only say not read-only and not destructive). Discloses the scope-check behavior ('needs_decomposition: true' response), tenant derivation from client, audit-logging of cross-agency assignments, the escalation rule for ungranted authority, and the cost of over-splitting. No annotation contradiction.

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

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

Well front-loaded with the creation act and the client requirement, then the decomposition rule. Some density in the decomposition/scope-check paragraph, but every sentence earns its place. Slightly long, but appropriate for the tool's complexity.

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 the critical behaviors for a creation tool with 25 params, nested objects, and no output schema: required fields, inheritance rules, scope check, cost of splitting, cross-agency auditing. The authority/scopes and dependency mechanics are only sketched, leaving some inference, but the description is substantively complete for a tool of this complexity.

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

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

Schema coverage is 84%, so structured fields already document most parameters. The description adds semantic policy on client (REQUIRED except subtasks), assignee (do not leave unassigned), goal and definition_of_done (always set), and allow_cross_agency. It does not explain authority, inputs, sources, depends_on, etc., beyond what the schema provides. Baseline 3 befits a high-coverage schema.

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

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

States a specific verb+resource ('Creates a task on the shared board') and immediately differentiates scope: one task = one deliverable, siblings like update_task/delete_task not confused. The one-task-per-deliverable rule distinguishes its behavior from bulk_update_tasks and request_decomposition.

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 guidance: 'ONE TASK PER DELIVERABLE... If the ask contains more than one deliverable, it is more than one task — pass them together in subtasks.' Also names the alternative (request_decomposition) and when it's needed. Rules on client, project, assignee, goal, and definition_of_done are all specified.

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 readOnlyHint=false and destructiveHint=false; the description goes well beyond that by explaining the key-custody model (Tango signs vs. self-held Ed25519 key) and the multi-step registration workflow that the 'attested' mode triggers. It stops short of describing failure modes, permission requirements, or the returned identity payload, so it is strong but not exhaustive.

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 purpose, then layers key-mode guidance, scoping, prerequisite, and a reference link in a logical order. It is a bit dense with run-on clauses, but nearly every sentence carries actionable content for a 9-parameter 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?

With 9 parameters (only 1 required), high schema coverage, and no output schema, the description supplies the workflow context the schema cannot (prerequisite whoami, post-creation follow-ups). It omits any mention of reuse/roles/harness defaults and expected return, but those are handled adequately 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 89%, so the schema already carries most parameter meaning. The description still adds real value by explaining when to choose each key_mode value and that clients scoping is optional, supplementing the enum's terse 'delegated (default)' / 'attested' definitions.

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 (provision) and resource (worker / agent identity) and frames the outcome ('so you can claim, lease, and hand off tasks'). This clearly separates it from sibling mutations like update_worker, archive_worker, and delete_worker without needing their 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 guidance for both key modes ('delegated' in an ephemeral sandbox vs 'attested' when the key is durable), names the required follow-up tools (request_key_challenge, register_worker_key), and tells the agent to call whoami first. Alternatives and conditions are all 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 declare destructiveHint=true, but the description goes well beyond that: it discloses the delete is a reversible soft delete, enumerates every surface affected (lists, links, reports, agent queues, 404 URLs), and notes platform staff can restore. That is exactly the extra context annotations cannot carry.

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

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

Tight and front-loaded: the action and its reversibility lead, then scope, then the archiving distinction, then the permission gate. The trailing API reference URL is slightly boilerplate but harmless and useful for deeper detail.

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

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

With no output schema and full schema coverage on params, the description's job is behavioral, and it is complete: reversibility, affected surfaces, restore path, and required role are all covered. Nothing an agent needs before calling this destructive 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 description coverage is 100%, so task_id, confirm, and reason are already documented in the schema, including the const:true safeguard on confirm. The description adds no syntax or format detail beyond that, so 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 ('Remove') and resource ('a Tango task') and immediately scopes the blast radius to the task plus its subtasks. It explicitly distinguishes itself from the nearest confusing sibling behavior (setting status to 'archived'), so an agent can route correctly 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 an explicit when-not: 'This is NOT the same as setting status to archived', which routes the agent between delete_task and update_task. It also states a hard prerequisite (only organization owners/admins can remove a task), covering authorization context.

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

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

Annotations already declare destructiveHint=true, but the description adds the substantive preconditions and the failure mode ('Anything with history returns 409'), which the annotations cannot convey. It also explains the rationale (audit trail survival), which is exactly the kind of context that prevents a mistaken destructive call.

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

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

Three sentences, front-loaded with the core action, then the precondition, then the failure/alternative. The trailing API reference link is compact and useful. No sentence is redundant with the title or annotations.

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

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

For a one-parameter destructive tool with no output schema, the description covers action, precondition, failure behavior, and the safe alternative — everything an agent needs to invoke it correctly and avoid misuse.

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

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

Only one parameter (worker_id), whose name and uuid format in the schema are self-explanatory, so the description need not do much. However, schema description coverage is 0% and the description says nothing about the parameter at all; it does not clarify that only mistakenly-created workers qualify, which is already covered under usage. Baseline 3 for a single well-named parameter with no compensating detail.

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

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

States a specific verb and resource ('Hard-delete a worker') and immediately scopes it, so an agent can distinguish it from archive_worker or revoke_worker_key without opening a schema. The title plus first sentence leave no ambiguity about what the tool does.

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 when it is permitted ('ONLY when the worker has never been assigned a task and holds no receipts, leases, or handoffs') and names the alternative for the excluded case ('must be retired with archive_worker instead'). This is textbook when/when-not/alternative 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 read-only, non-destructive profile, so the bar is lower. The description adds real behavioral value beyond that: it discloses the ranked-candidate return shape, the needs_disambiguation flag, that handles are pass-back usable, and that active_agency is always included even for global scope.

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

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

Three tight sentences, front-loaded with purpose before usage and return notes. The trailing API reference URL is slightly extraneous but low-cost and clearly demarcated.

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

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

With no output schema and one required parameter, the description usefully compensates by explaining the return shape (ranked candidates, handles, needs_disambiguation, active_agency). What remains thin is scope/agency filtering behavior, but overall it gives an agent enough to call and interpret the tool.

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

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

Schema description coverage is 80% with two enums already documented, so the schema does the heavy lifting. The description restates that query accepts name/handle/email but adds no syntax or constraint detail 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 ('fuzzy-search') and resource ('worker, teammate, or client') with the input modes (name, handle, email). This clearly differentiates it from exact-match siblings like resolve_mention, whoami, and list_agents.

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-to-use with a trigger scenario ('disambiguate a plain-language reference before create_task/handoff_task') and concrete examples. It does not state when NOT to use it or contrast against nearby alternatives like resolve_mention or list_agents, so it stops short of a 5.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false, but the description goes far beyond: it discloses the resulting state (`needs_more_info`, which blocks claiming until resolved), the reviewer side effect, the artifacts it drafts (brief, open questions, proposed subtasks), and that a human applies the proposal. This is exactly the kind of write-side-effect disclosure an 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-loads the primary guidance ('Use this INSTEAD of guessing...') and then adds the side effects and follow-up in compact sentences. It is dense but every clause carries useful information; the trailing API reference link is the only marginal addition.

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, yet the description compensates by explaining what the reviewer produces and how to retrieve it with `get_task_review`. Given the tool's write complexity and the human-in-the-loop step, nothing needed to invoke or interpret the call is missing.

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

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

Schema description coverage is 100%, so both parameters (task_id, reason) are already documented in the schema, and the description largely restates the trigger conditions rather than adding format/syntax detail. Baseline 3 is appropriate when the schema carries the parameter documentation.

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 (flag a task as missing information) plus the concrete mechanism: marks the task `needs_more_info` and runs the Tango PM reviewer. It distinguishes itself from siblings like resolve_needs_more_info, ask_human, and request_decomposition by describing exactly what state change and what review it triggers.

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 criteria (empty or hand-wavy goal, no checkable definition of done, unclear scope) and frames the alternative it replaces (guessing). It also routes the agent to the correct follow-up sibling (`get_task_review`) and states that a human applies the result in Tango, closing the loop.

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 and destructiveHint=false, and the description adds real behavior beyond that: binary artifacts return a short-lived download_url instead of text, and there is an inline byte cap. It stops short of describing error behavior for missing artifacts or whether download_url expiry is enforced, so it is strong but not exhaustive.

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

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

Three sentences, front-loaded with the core action, then the alternative and the fallback, then the edge case for binary payloads. Each sentence carries distinct information; the API reference link is the only mildly extraneous element.

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 carries the return-shape burden by explaining that text comes back inline and binaries come back as a download URL, and it explains the truncation scenario. Missing only failure/not-found semantics for a read tool whose safety profile is already covered by annotations.

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

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

Schema coverage is 100%, so the schema already documents each parameter and its constraints. The description adds relational meaning the schema lacks: that lookup is either by artifact_id or by the task_id + name pair, clarifying how the loosely-required parameters combine.

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 text body of an artifact attached to a task) and explicitly contrasts itself with get_task, which only lists artifacts and inlines small bodies. An agent can distinguish it from every sibling 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?

Names the alternative (get_task) and the exact conditions that select this tool: when a body was truncated or omitted, or when fetching one artifact by id or by task_id + name. It also states the mandatory workflow for synthesizers, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds value by disclosing what the bundle actually contains (brief, facts, links, decisions log), which matters because there is no output schema; it stops short of noting fuzzy-resolution failure modes or auth requirements.

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

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

Two tight sentences that front-load the verb and payload before the usage instruction. The trailing API reference URL is slightly extraneous but cheap and potentially useful.

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 enumeration of returned components (brief, facts, links, decisions) is the key information an agent needs to know what it gets, and the usage sentence covers invocation intent. What's missing is minor: behavior when the client name is ambiguous and how the decision_limit shapes the response.

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

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

Schema coverage is 67% — 'client' and 'decision_limit' are described in the schema (including fuzzy resolution and the default of 20), while 'client_id' carries only format/pattern. The description adds no parameter detail beyond that, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource ('Fetch the shared context bundle for a client/workspace') and enumerates the payload: brief, structured facts, reference links, recent decisions log. This clearly separates it from siblings like get_project_context and update_client_context.

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 trigger: 'Call this before working on any task tied to a client so you inherit the same ground truth.' It doesn't state when-not to use it or name a specific alternative, but the pre-task framing is clear.

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 and destructiveHint=false, so safety is covered. The description adds useful context by describing the three reachability mechanisms it returns and the call-once semantics, but since no output schema exists it could say more about what the response actually contains (e.g. code snippets per platform).

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 dense sentences plus a reference URL; purpose and usage are front-loaded and there is no filler. The doc link is the only arguably optional element.

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

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

For a read-only, zero-required-parameter helper with no output schema, the description covers what it returns conceptually and when to invoke it. Remaining gaps are the platform parameter's meaning and the exact return shape.

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 only 50% (worker is documented, platform's enum is not), and the description never mentions either parameter. With low coverage the description should compensate, but it offers no guidance on the worker or platform inputs beyond the schema's own 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 action (return reachability setup instructions) and enumerates the three mechanisms it covers: Tango Runner, webhook, and check_in/heartbeat polling. Clear that it returns instructions rather than performing polling, though it doesn't explicitly contrast itself with sibling tools like set_webhook or check_in.

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?

"Call this once when you connect, or whenever Tango tells you you are unreachable" gives explicit timing guidance and a trigger condition. It does not give a when-not-to-use or name an alternative tool, but the usage 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=true and destructiveHint=false, so safety is covered. The description adds real value beyond them by disclosing the shape of the returned bundle (goal, brief, facts, links, decision log), which matters given there is no output schema. It omits auth/permission needs and any pagination or size limits.

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, then the payload inventory, then the usage trigger — a sensible order with no redundant sentences. The trailing API reference URL is the only marginally expendable 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?

With no output schema, the description usefully enumerates the return contents, and all five parameters are optional so invocation is low-risk. The remaining gap is the undocumented id-vs-name parameter pairing and the fuzzy-resolution behavior, which the schema only partly hints at.

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 only 40% (client and project are described; client_id, project_id, and decision_limit are not), so the description is expected to compensate and does not. It never mentions the client/project vs. *_id duality or what decision_limit controls, leaving three of five parameters undocumented anywhere.

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?

Names a specific verb ('Fetch') and resource ('shared context bundle for a project') and enumerates exactly what the bundle contains: goal, brief, facts, links, decision log. An agent can distinguish this from get_client_context or list_context_sources purely from the description.

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 when to use it: 'Read this before working a task so your output stays aligned with the project's intent, not just the task title.' That is a clear usage trigger, but no sibling alternative or exclusion is named (e.g., when to prefer get_task or get_client_context 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=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond that: the 24-hour window, Monday look-back to Friday, and exclusion of parked/cancelled work. It does not cover auth requirements or rate limits, but for a read-only reporting tool this is reasonably transparent.

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 the tool's purpose and immediately enumerates the standup sections. It packs useful constraints and scope semantics into a compact paragraph without wasting sentences. The API reference is appropriately placed at the end.

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?

Even without an output schema, the description enumerates the standup contents (done, plan, blockers, overdue/stalled), so an agent knows what to expect. It also covers scope behavior, timing, and exclusions. This is sufficient for correct invocation of a read-only reporting tool.

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

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

Schema description coverage is 100%, so the baseline would be 3. The description goes further by defining what 'me' and 'client' mean semantically — work assigned to or owned by you versus the whole client team — which is not fully captured by the enum labels alone.

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 exactly what the tool produces: a daily standup covering done-since-last-standup, today's plan, blockers/open questions, and overdue/stalled items. It is specific enough to distinguish from generic task-list siblings like list_my_tasks or get_task, because it describes a synthesized report rather than raw task retrieval.

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 timing guidance — 'Run it at the start of your day' — and explains scope selection: 'me' for personal work, 'client' for the whole client team. It also states exclusions (parked and cancelled work). It does not name alternative tools, but no close sibling appears to serve the same daily-summary purpose.

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 and destructiveHint=false, so safety is covered. The description adds real behavioral value by detailing exactly what payload comes back (spec, handoffs, receipts, artifacts, timeline) and the workflow rule for consuming `activity` first.

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 front-loaded: the fetch purpose and the returned bundle come first, the workflow imperative follows, and the API reference is last. No sentence 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 carries the burden of describing returns and does so thoroughly, plus it supplies workflow guidance. An agent has everything needed to call and use the result 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% and the single `task_id` parameter is fully documented there, including accepted formats. The description only says 'by id', adding no syntax or constraint beyond what the schema provides, 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 ('Fetch a Tango task by id') and immediately scopes it by enumerating the returned context bundle. It is clearly distinguishable from sibling read tools like get_task_activity or get_task_review.

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 instructs 'Always read `activity` before starting work' and names the alternative route for older data ('use get_task_activity for older entries'), giving both a when-to-use directive and a sibling hand-off.

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 and destructiveHint=false, so safety is covered. The description adds genuinely useful behavior: the timeline is merged and newest-first, and it is the shared surface other teammates write to, which tells the agent what data it will see. It stops short of describing pagination behavior or output shape, so a 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 tight sentences, front-loaded with purpose before usage and related-tool context; every sentence contributes. The trailing API reference URL is minor filler rather than waste, keeping it just short of 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 does the work of telling the agent what entries and ordering to expect, and annotations cover safety; pagination is carried by the schema. It omits any statement about return shape or paging semantics beyond the params, so it is strong but not exhaustive.

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 limit, offset, types, and task_id are already documented in the schema. The description only adds the notion of filtering to a single kind of entry (mapping to `types`) and the ordering, so 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 (Read) and resource (merged, newest-first activity timeline for a task) and enumerates exactly what the timeline contains: progress notes, comments, status changes, handoffs, artifacts, escalations. It explicitly positions itself against the sibling get_task, so the agent can distinguish the two 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?

Gives an explicit selection condition ('use this when get_task's activity window (30 entries) isn't enough') and a second use case (filtering to a single kind of entry via `types`). It also names the related write tools (add_progress_note, add_comment), removing any ambiguity about which surface to read.

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 readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuine behavioral context beyond that: which gates can block a task and the full shape of the returned proposal (missing info, goal, definition of done, open questions, subtasks). It doesn't discuss staleness or caching, but this is solid added value over the annotations.

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

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

Two sentences, both front-loaded with the highest-value information (gate status first, then proposal contents, then the usage instruction). No filler, and the API reference link is tacked on without disrupting flow.

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 correctly carries the return-value burden and enumerates the proposed content fields. Combined with the usage directive and the API reference, an agent has everything it needs 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?

Only one parameter (task_id), and schema description coverage is 100% ('Task id or task URL'), so the schema already carries the meaning. The description adds nothing about the identifier format. 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 names the specific verb (returns) and the exact resource it exposes: quality-gate blocking state (`needs_more_info`/`needs_breakdown`) plus the latest Tango PM proposal with its constituent fields. This is clearly distinguishable from siblings like `get_task`, `list_open_questions`, or `get_task_activity`.

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 an explicit when-to-use directive — 'Read this before asking the human anything' — and explains why (the reviewer has usually already written the questions worth asking), which implicitly routes the agent away from `ask_human` unless the review lacks an answer. That is a concrete usage rule, not implied context.

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

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

Annotations already declare readOnlyHint=true/destructiveHint=false, so safety is covered. Beyond that, the description discloses the concrete return fields and the non-obvious behavior that a suspended webhook receives no deliveries until set_webhook is called again, which is real operational 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?

Three sentences, front-loaded with the return payload, with the suspension caveat second and the API reference last. No wasted prose, though the doc URL is mildly extraneous.

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

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

With no output schema, the description compensates by enumerating the returned fields, and it adds the suspension semantics an agent needs for interpretation. For a single-param read tool with a clean safety annotation profile, nothing essential 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 0%, so the description must compensate; 'for one of your workers' only loosely maps worker_id to a worker identifier and adds no format or sourcing guidance. The schema's own uuid format and regex pattern carry the actual constraint 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 (Return) and resource (webhook settings for a worker) and enumerates exactly what comes back: URL, subscribed events, failure count, suspension state, last delivery status. That field list implicitly distinguishes it from get_webhook_deliveries and clear_webhook, though no sibling is named.

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

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

The intent (inspect a worker's webhook configuration and health) is implied but never stated as 'use this when...'. It does not tell the agent when to prefer this over get_webhook_deliveries or when set_webhook/clear_webhook is the right sibling 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 establish the safe read-only profile, and the description adds real context: no database access is needed and it discloses the exact diagnostic fields returned (status, error text, attempt number). It doesn't mention ordering beyond 'most recent' or pagination limits, but the annotation bar is met.

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, front-loaded with the core purpose and the field list, then the use case. Efficient, though the trailing API-reference URL is boilerplate rather than informational.

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 returned fields, and it covers the debug use case and limit default context. Adequate for a two-parameter read tool, with only minor gaps around result ordering/volume.

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 50%: limit is documented in the schema (default 20), while worker_id carries only format/pattern. The description's 'for one of your workers' loosely implies worker_id's role but adds no scoping or format detail beyond the schema.

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

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

States a specific verb and resource ('returns the most recent delivery attempts for one of your workers') and enumerates the returned fields, which cleanly separates it from get_webhook and clear_webhook 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 a concrete triggering scenario ('Use this when a worker is not receiving events or its webhook has been suspended'), which is clear context. It does not, however, name alternatives such as get_webhook or explain when not to use it.

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 and destructiveHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the versioned nature of the glossary and the caching contract, plus a link to the full API reference — though it says nothing about response size for the no-argument case.

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 dense sentences plus a reference URL; the enumeration of vocabulary terms is slightly long but front-loads the purpose and the invocation modes well. Nothing is wasted, though the term list could be trimmed without loss.

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

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

For a single optional-parameter, read-only lookup with no output schema and no siblings, the description covers purpose, invocation, and caching. The main gap is that it does not sketch the shape of the returned glossary entry, which an agent consuming the output would benefit from.

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 `term` parameter is fully documented in the schema with examples. The description reinforces that omitting it returns everything, but adds no syntax or alias-resolution detail the schema lacks, 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 ('Look up Tango vocabulary') and enumerates the kind of entries the glossary holds (Epic, Feature, Task, lease, claim, handoff). No sibling tool covers glossary lookup, so an agent can route here unambiguously.

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 covers both invocation modes: no arguments for the full versioned glossary, or `term` to resolve a single word. It also tells the agent to cache by version and re-read on change, which is actionable operating guidance rather than 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?

The annotations only declare it as a non-read-only, non-destructive mutation. The description goes well beyond that: cross-agency handoffs are audited, attribution is mandatory with three acceptable paths (active lease, owned acting_worker_id, or human/org-owner), the call fails with 422 and writes nothing on missing attribution, and the actor is never inferred from the assignee. That is exactly the extra behavioral context annotations cannot carry.

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

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

The mutation behavior and attribution rule are front-loaded, and the doc link is placed last where it belongs. Sentences are dense but each carries a distinct constraint; no filler. Slightly long, but nothing is wasted.

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

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

For a 9-parameter mutation tool with no output schema and 44% param coverage, the description covers the highest-risk behaviors (auditing, attribution, empty-write failure). The gaps are the un-described recipient/lease parameters, which an agent may need to set correctly for auto_lease and lease_seconds.

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 only 44%, so the description must compensate. It adds real meaning for allow_cross_agency and acting_worker_id (ownership verification, lease override), but leaves note, to_id, to_kind, and lease_seconds without guidance in either the schema or the description. Partial compensation for a low-coverage schema.

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

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

The description opens with a specific verb+resource+recipient: 'Reassign a task to another worker or human with a required note.' An agent can immediately tell this transfers ownership of a task. It does not explicitly differentiate from siblings like claim_task or accept_task, which are the nearest alternatives, so it misses the top band.

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

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

It gives prerequisites and a failure mode (cross-agency needs allow_cross_agency: true; attribution required or 422) but never states when to choose this over claim_task, accept_task, or update_task. Usage context is implied through preconditions rather than contrasted with alternatives.

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

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

Annotations only give readOnlyHint=false/destructiveHint=false, and the description adds substantial context beyond that: the raw key is returned exactly once, it must not be re-shown in chat, an owner/admin permission is required, and the return fields (key_id, key_prefix) that feed revocation. This is exactly the kind of non-obvious behavior an 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?

Three sentences, front-loaded with the core action, then the security constraint, then the follow-up and reference link. No filler, and the most consequential warning (returned once, don't repeat) is positioned prominently.

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 2-param mutation with no output schema, the description compensates by naming the returned fields, the revocation path, the permission requirement, and a docs URL. An agent has everything needed to invoke it correctly and 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% for both parameters, so the schema already documents worker_id and label fully; the description only restates the ownership constraint already in the schema note. Baseline 3 is appropriate when the schema carries the parameter burden.

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: mint a `tng_` bearer key for a worker to call Tango's HTTP worker API. It names the API methods the key enables (pull_task, update_task, complete_task) and clearly separates itself from revoke_worker_api_key and the register/rotate 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 a clear when-to-use context — issuing a key so a worker runs outside MCP — plus the ownership precondition and the explicit follow-up tool for revocation (revoke_worker_api_key with key_id or key_prefix). It does not contrast itself against the adjacent register_worker_key/rotate_worker_key siblings, which is the only gap.

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 and destructiveHint=false, so safety is covered. With no output schema, the description adds real value by disclosing the returned fields, including webhook reachability and paused status, though it omits any pagination, auth, or rate-limit 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?

Two tightly packed sentences: purpose and return fields first, then the actionable usage tie-in, followed by a reference URL. Nothing is redundant and the key scoping information is front-loaded.

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

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

For a parameterless, read-only list tool with no output schema, the description fully compensates by enumerating the returned fields and showing how the output feeds into send_message. Nothing an agent needs 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?

The tool takes zero parameters, so the 0-param baseline of 4 applies. Nothing in the description needs to compensate for parameter documentation.

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 (Lists) and resource (agents) scoped to the Tango workspace, and enumerates the exact fields returned (@handle, name, harness, last seen, webhook reachability, paused). It reads as distinct from find_people and list_micro_workers through the noun 'agents', though it never names an alternative 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?

Gives a concrete downstream-use rule: 'Use the @handle as `to` in send_message', which tells the agent why and when to call this before messaging. It does not state when NOT to use it versus find_people or whoami, so it falls short of full explicit 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 and destructiveHint=false, so safety is covered. The description adds valuable behavioral context beyond that: server-side filtering/paging, default of open un-parked work, 50 per page, and summary mode fields plus status counts. It omits any note on auth needs or rate limits, but for a read-only list tool this is unusually rich.

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

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

Three tight sentences, front-loaded with scope, then routing guidance, then defaults and return shape. The inline API reference URL is the only slightly ancillary element; nothing else 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?

No output schema exists, yet the description compensates by describing summary row fields and status counts. With 10 parameters at 50% schema coverage, some optional filters remain unmentioned, but the critical calling context (defaults, paging, return shape, alternative) is present.

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 only 50%, so the description carries extra weight. It documents defaults the schema does not fully state (limit 50, summary true with its field set, open-work status default) and confirms parked excludes by default. It still leaves several parameters (overdue, client, client_id vs project_id interplay) unaddressed.

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

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

States a specific verb+resource+scope ('every task in one client workspace, filtered and paged on the server') and explicitly names the sibling it is not (list_my_tasks). An agent can distinguish it from search_tasks and list_my_tasks 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?

Names the alternative tool and the selecting condition: 'Use this instead of list_my_tasks when you need the full picture for a client.' Explicit when-to-use routing is provided rather than implied.

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 and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral value: what the roster contains and that the returned handles are directly reusable as inputs to create_task/handoff_task, plus the access-scoping guarantee. It omits pagination or roster-size limits for large clients.

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

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

Three sentences, front-loaded with what the roster is before the workflow advice. The API-reference link is placed last and does not interrupt the decision-relevant 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?

A read-only list tool with a fully documented two-parameter schema and no output schema; the description supplies the contents, the routing purpose, and the sibling to avoid. Nothing needed 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% and both parameters are already documented, including that 'client' accepts a name or @handle and is fuzzy-resolved. The description's @handle mention refers to output values rather than input syntax, so it adds essentially nothing 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 ('Roster of everyone who works on a client') and enumerates the contents: human teammates plus AI/robot workers with their @handles. An agent can distinguish this from find_people or list_agents 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?

Explicit when-to-use ('Call this before choosing an assignee') and an explicit exclusion ('do not guess from find_people alone'), naming the sibling it is meant to supersede. Routing intent 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=true and destructiveHint=false, so safety is covered. The description adds useful behavioral context: what is returned (org-level plus client-owned sources and curated views) and how the output is consumed downstream. It omits pagination/volume expectations, keeping it from a 5.

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

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

Three sentences that are front-loaded with the resource scope before the usage trigger, with no filler. The trailing API reference URL is useful but slightly dilutes tightness.

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

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

With no output schema, the description does the work of describing the return content (sources plus curated views with keys) and the downstream call. What remains thin is parameter selection guidance for client/client_id, but otherwise the definition is complete for a read-only listing 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 only 50%: 'client' is described but client_id carries merely a format/pattern with no prose. The description says results are scoped to a client but never explains how client vs client_id relate or which to supply, so it does not compensate for the coverage gap.

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

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

States a specific verb and resource ('List the external data sources connected to a client') and clarifies scope as organization sources plus the client's own, plus the curated views available. An agent can distinguish this from siblings like get_client_context, list_integrations, and query_context_source 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?

Explicit trigger condition is given ('when the shared brief is not enough and the answer likely lives in the agency's own systems'), with concrete examples of the target systems. It also names the follow-up action, telling the agent the returned view keys are passed to query_context_source, which establishes the workflow chain.

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 and destructiveHint=false, so safety is covered. The description adds meaningful behavior beyond that: the listing is the authoritative scope for downstream integration tools, and gateway-backed systems (Jira, Asana) are included. It omits pagination/return-shape details, but these are secondary.

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

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

Two tight sentences with the core purpose front-loaded, followed by the scope caveat and a reference URL. The parenthetical tool list is slightly long but earns its place by grounding what 'external systems' means.

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

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

With no output schema and read-only annotations, the description carries most of the load and does it well for purpose and scoping. The remaining gap is the absence of any hint about the listing's shape or the two client selector parameters.

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

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

Schema coverage is only 50% – client is documented in the schema but client_id has no description. The tool description says nothing about either parameter, so the undocumented client_id must be inferred from its name and the sibling client parameter.

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/list) and resource (external systems connected to a client workspace), and enumerates concrete examples (Slack, Linear, GitHub, Notion, gateway-backed Jira/Asana). It also disambiguates from siblings by naming read_integration and write_integration as the tools this listing gates.

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

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

The sentence 'read_integration and write_integration can only reach systems listed here' effectively tells the agent when this call is a prerequisite, which is clear contextual routing. It stops short of an explicit when/when-not rule, but the dependency relationship 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 cover the safety profile (readOnlyHint=true, destructiveHint=false), so the description's added value is the disclosure that results include enablement state and live runtime health. It does not mention caching/refresh behavior or failure modes when the runtime is unhealthy, which would push it to 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?

Front-loaded with the resource and payload, then the usage directive, then a reference link. The first sentence packs three ideas into one comma-heavy clause, but no sentence is wasted.

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

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

With no output schema, the description carries the return-value burden and does describe what comes back (roles, on/off state, runtime health, usable slugs). It stops short of describing the shape or how to detect an unhealthy runtime, but the essential picture is complete.

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

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

Only one parameter and schema description coverage is 100%, so the schema already documents client_id's purpose in full. The description says nothing about client_id or the default 'active organization' fallback beyond what the schema states, so 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 precise verb+resource ('list micro-worker roles') and enumerates the payload: available roles, which are switched on, and runtime health. That is clearly distinguishable from siblings like list_agents and list_client_team, which the description does not overlap with.

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 prescribes the precondition ('Call this before delegating specialist work') and the downstream action it enables ('set `role` on create_task to a slug that will actually be picked up'). The agent knows exactly when to reach for this tool and what it feeds into.

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 safe read, so the bar is lower; the description adds real behavioral context: results span all agencies by default, rows always carry agency_id + agency_name so callers can scope deliberately, and the key quirk that work routed to you lands in 'assigned' not 'queued'. It does not cover pagination/return shape, but with no output schema and the safety profile already annotated, this is solid added value.

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 and scope, then filters, then the critical status pitfall, then return-row context. Sentences are tight, though the trailing API-reference URL is marginally disposable and the filter-options sentence partly overlaps 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?

For a 15-param, no-required-param read tool with no output schema, the description covers purpose, the global scoping default, row contents, and the biggest correctness trap. Gaps are the absence of sibling routing (search_tasks/list_client_tasks) and no note on result volume/pagination beyond the schema's limit.

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

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

Schema coverage is 80%, so the schema already carries most parameter meaning; the description only names status/role/client_id/agency_id out of 15 params. Its most useful parameter insight (status='assigned' vs 'queued') largely duplicates the schema's own status description, and undocumented params like role and client_id remain unclarified. 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 (list), resource (Tango tasks), and scope (visible to the signed-in user, across every agency, global by default). The explicit global-by-default framing cleanly separates it from agency-scoped or client-scoped listers like list_client_tasks without the agent needing to open 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 strong context ('use for your work, default global') and an explicit exclusion: do NOT pass status='queued' when checking for your own tasks, since those are 'assigned'. It does not name sibling alternatives such as search_tasks or list_client_tasks, so routing between similar listers 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 readOnlyHint=true and destructiveHint=false, which sets the bar lower. The description adds a real constraint ('tasks you can see' visibility scoping), but says nothing about pagination, default filtering behavior, or result volume caps, so it is only moderately additive.

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 purpose, followed by usage guidance and a docs link. No filler, though the raw API-reference URL consumes space without adding invocation value.

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

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

For a simple read-only list tool with no output schema and annotations covering safety, the description is mostly sufficient. However, it omits how results are bounded/ordered and its 'with any human answers' phrasing is mildly at odds with the schema default of include_answered=false.

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

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

Schema coverage is 67%: task_id and include_answered carry their own descriptions, while limit is undocumented. The description adds no parameter-level meaning (e.g., what limit defaults to or how ordering works), so baseline 3 is appropriate.

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

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

States a specific verb and resource ('List questions raised on tasks') plus a scope qualifier ('tasks you can see') and notes answers are included. It is easy to distinguish from ask_human/answer_question, though it does not explicitly contrast with adjacent readers like get_task_activity or list_threads.

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 situational guidance: 'Use this after ask_human to check whether a human has replied before you resume work.' That names the alternative (ask_human) and the triggering condition. It lacks a when-not-to-use clause, 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 readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds that results are a dated timeline over a range and are meant for explanatory context, but says nothing about ordering, pagination, default limit, or how project/client scoping behaves — modest added value above the annotations.

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

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

Two tightly written sentences that front-load the resource, followed by the when-to-use cue and an API reference link. No filler, though the benefit sentence is somewhat soft.

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-required-parameter, seven-parameter read tool with no output schema, the definition leaves notable gaps: it does not hint at return shape or ordering, does not clarify how project/client scoping works, and does not address the undocumented parameters. Adequate to call it, but not complete.

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

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

Seven parameters with only 43% schema description coverage, and the description contributes no parameter semantics at all — it never mentions from/to, limit, or the project/client vs project_id/client_id distinction. With low coverage the description was expected to compensate and does not.

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

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

States a clear verb (Read/List) and a specific resource (the dated timeline of significant events on a project), and enumerates the event kinds (changes, launches, incidents, external shifts, milestones). This separates it from log_project_event/update_project_event (writes) and list_project_issues/milestones, though it does not explicitly contrast itself with 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?

Gives a concrete situational cue: use it to explain what analytics show over a date range before drawing conclusions. That is real when-to-use guidance, but it names no alternatives and gives no conditions for choosing another timeline/summary 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 and destructiveHint=false, so safety is covered. The description adds useful content about what a record includes, but says nothing about pagination, the limit cap, or the default status filter behavior — gaps the schema only partly fills.

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-load the core action and the usage trigger, followed by a documentation link. Nothing is padded, though the bare API reference URL adds little to selection or invocation.

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

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

With no output schema, the description does sketch the returned fields, which helps. But for a 6-parameter filtered-list tool it omits any discussion of the filterable dimensions or result limits, leaving the invocation contract under-explained.

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?

Six parameters with only 33% schema description coverage, and the description mentions none of them. It gives no hint that results can be filtered by project, client, or status, or that a limit applies, so the agent must reverse-engineer filtering from the schema alone.

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 (Read) and resource (known issues on a project), and enumerates what each record contains: blockers from external systems, severity, status, and fixing tasks. This cleanly separates it from the write siblings log_project_issue and update_project_issue.

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 trigger: read before starting work to avoid re-discovering or duplicating a known problem. That is actionable context, though it names no alternative tool and states no when-not condition.

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 readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that the payload is dated checkpoints with name/due/status, but says nothing about pagination, ordering, or whether unresolved fuzzy project matching can fail — modest added value on top of 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 front-loaded sentences stating resource and purpose, plus a bare API reference link — no filler or repetition. Slightly under-explained rather than padded, which is a mild issue but not verbosity, so it earns a 4 rather than 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?

Five parameters with zero required and only 40% schema coverage, no output schema, and no annotation detail on scoping: this is a moderately complex tool whose description leaves parameter selection and defaults unaddressed. It partially compensates by naming the returned fields, but not enough for a higher score.

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 only 40%: client, client_id, and project_id carry no schema text, and only 'project' and 'include_finished' are documented. The description compensates for none of this — it never mentions a parameter name, the fuzzy-resolution behavior, or how client/client_id/project_id interact, so an agent gets no help on the undocumented half.

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

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

The description uses a specific verb+resource combination ('Read the dated checkpoints a project is measured against') and enumerates the returned fields (name, due date, status), which is unambiguous. It does not however name or distinguish itself from close siblings like list_project_events, list_project_issues, or get_project_context, so it stops short of a 5.

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

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

It gives an explicit motivation ('judge urgency before picking up work', 'tell the human what a task is actually feeding into'), which is real usage context. But it offers no when-not guidance and never says how this differs from the other project-scoped list tools, leaving the choice 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 readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the useful workflow fact that it is a prerequisite for create_task, but says nothing about pagination, result ordering, or what include_archived defaults to.

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 written sentences that lead with purpose, then usage, then a reference link. Little waste, though the API URL is arguably non-essential padding for an agent.

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 should carry more of the return-shape burden; it gives examples of project types but not what a project record contains or whether archived projects appear by default. Adequate but with a real gap for a list tool.

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

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

Schema description coverage is only 33% – just the 'client' parameter is documented. The description says nothing about client vs. client_id disambiguation or the include_archived flag, so it fails to compensate for the undocumented parameters.

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

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

States a specific verb and resource ('List the projects'), scopes it ('that organize a client's work'), and gives concrete examples (Website, Google Ads, Newsletter, Reporting) that make the concept unambiguous. It also implicitly separates itself from create_project/update_project by being a read/list operation.

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 prescribes when to call it: before create_task, and to ask the human which project the work belongs to. It does not name an alternative or state when-not to use it (e.g. versus get_project_context or list_client_tasks), so it falls short of a full 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=true and destructiveHint=false, so the safety profile is covered. The description usefully adds that returned content includes the full conversation with Tango staff replies, but omits pagination, result limits, and any auth constraints.

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 front-loaded sentences plus an API reference link; every sentence carries information and the key conditional (ticket_id) is stated early. The trailing URL is marginally verbose but genuinely useful.

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 2-param read tool with a rich enum and readOnly annotations, the essentials are present. Gaps remain: no mention of status filtering behavior, result volume/pagination, or ordering, and there is no output schema to compensate.

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 50%: ticket_id is documented in the schema and the description reinforces its effect (fetch one thread instead of the list). The status enum is undocumented in both places, though its values are largely self-explanatory, so 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 gives a specific verb+resource (list support tickets) and clarifies the dual mode: reading full conversations and fetching a single thread via ticket_id. It implicitly distinguishes itself from the action siblings (submit_support_request, reply_to_support_request), though it never names them.

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 concrete conditional guidance for one mode ('Pass ticket_id to fetch one thread'), which implies the default list behavior. However, it says nothing about when to prefer this over reply_to_support_request or submit_support_request, and the status filter's intended use is never explained.

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 and destructiveHint=false, so safety is covered. The description adds ordering and unread-count context and a docs reference, but says nothing about pagination, result limits, or what an empty list means.

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

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

Two short sentences, front-loaded with the substantive behavior. The documentation URL is a minor filler line but still potentially useful for an agent.

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 parameters and no output schema, the description carries the return-value burden; it does so by naming unread counts and the ordering. Only pagination/volume behavior is unaddressed.

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

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

The tool takes zero parameters, so the baseline is 4. There is no parameter detail the description could add, and it does not need to.

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 ('Lists threads you're part of') plus scope detail (newest activity first, unread counts). It is clearly distinguishable from most siblings, though the nearest alternative (read_messages) is never named.

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

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

Usage is only implied by 'threads you're part of' — an agent can infer this is the overview/listing call versus read_messages, but there is no explicit when-to-use, when-not-to-use, or named alternative.

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 supply readOnlyHint=false and destructiveHint=false. The description adds meaningful behavior beyond that: the entry is appended (not overwritten), it is durable, and it is surfaced to all future agents and humans via a rolling log. It omits any permission or scoping requirements for writing to a client log.

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 action and its persistence semantics, then the exclusion, then the reference URL. Mostly efficient, though the rhetorical line 'If you don't record it, nobody else will know' is persuasion rather than specification and does not earn its place.

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

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

With no output schema, the description does not need to explain return values, and an append-only note tool has little hidden behavior to disclose. The remaining gap is the client-versus-project routing against log_project_decision and the dual client/client_id parameters, which are left for the agent to infer.

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

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

Schema coverage is 67% with 6 parameters. The description's enumeration of decision/learning/preference/constraint meaningfully maps onto the kind enum values, but it says nothing about client vs client_id (both present), task_id linkage, or the summary/detail split. Baseline 3 fits given the schema carries most of the load.

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 (append) plus resource (client's rolling decisions log) with the scope qualifier 'durable' and 'client's'. It also names the sibling add_progress_note and the condition that selects it, so an agent can separate this from progress notes 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 lists the four intended content types (decisions, learnings, preferences, constraints) and gives an exclusion with a redirect to add_progress_note. However it does not disambiguate from the client-vs-project boundary against sibling log_project_decision, leaving a plausible routing ambiguity unaddressed.

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=false, so the agent knows this is a non-destructive write. The description adds the useful framing that entries are inherited by future teammates, but says nothing about permissions, dedup/append behavior, or whether prior entries are mutated.

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 tightly written sentences that front-load the purpose, followed by the usage trigger. The trailing API-reference URL is the only borderline element and is plausibly useful rather than 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?

For an 8-param, 1-required write tool with no output schema and thin annotations, the description covers what it does and when to call it but leaves most parameter semantics and any return/confirmation behavior unstated. Adequate but with clear gaps.

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

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

Schema coverage is only 25% (6 of 8 params undocumented), and the description compensates only partially by naming the four kind values, which the enum already lists. It gives no guidance on summary vs detail, client vs client_id/project vs project_id, or task linkage, so it adds marginal value over 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 (record/log) and resource (project decision) and enumerates the four content kinds (decision, learning, preference, constraint), which matches the kind enum. It implicitly differentiates from the project-scoped sibling set by saying 'working this project', but never names the closest alternatives like log_client_decision or update_project_decision.

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 this whenever you make a judgement call that a later agent would otherwise have to re-litigate' gives a clear, concrete trigger condition. It stops short of naming when NOT to use it or which sibling handles client-level decisions, so it is clear context without explicit alternatives.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context — these events are overlaid on analytics later and should be logged on change observation — but says nothing about auth, whether entries are append-only/editable (update_project_event exists, so that matters), or duplicate handling.

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 front-loaded sentences plus a doc link; the purpose and rationale come first and the examples are dense rather than padded. Slightly trailing API-reference URL is the only structural noise.

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?

Purpose and motivation are complete, and no output schema means return values need no explanation. But for a 12-parameter, 33%-covered write tool with an update sibling, the omission of parameter meaning and edit/immutability semantics leaves real gaps.

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

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

Schema coverage is only 33%. Documented parameters (project, impact, occurred_on, ends_on) are not elaborated in the description, and eight parameters — url, title, client, client_id, project_id, task_id, category, description — are left entirely to the schema. The description does not compensate for the coverage gap.

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

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

States a specific verb (record) and resource (a significant dated event on a project) and disambiguates with concrete examples — budget change, site migration, campaign launch, outage, external algorithm update. An agent can tell this apart from update_project_event and list_project_events 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?

"Log one whenever you make or observe a change that will show up in future numbers" gives clear positive when-to-use guidance tied to downstream analytics. It stops short of naming exclusions or the sibling alternatives (e.g., log_project_decision, log_project_issue) that a confused agent might otherwise pick.

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