Tango

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

The description goes well beyond the sparse annotations (readOnlyHint=false, destructiveHint=false). It discloses that Tango downloads and stores fetch_url files, that external_url is not copied, that invalid signatures reject the call with nothing stored, and that delegated workers are signed for automatically. It also explains the subtle attribution behavior: if you don't own the worker, attribution is dropped rather than misrecorded.

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 dense but each sentence earns its place, covering purpose, content modes, attribution, and signing behavior. It is front-loaded with the working-agreement context. The only minor issue is that it reads as one long block; bulleted mode routing would improve scannability without adding length.

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

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

For a tool with 15 parameters and multiple content modes, the description covers nearly everything an agent needs: all storage modes, size limits, attribution, signing, and the relation to complete_task. The main gap is that it does not describe the success response or returned artifact id, and it does not mention evidence_kind selection beyond a passing reference, though the schema documents that parameter.

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 significant meaning: size limits for content_base64 vs fetch_url, the role of upload_token as a finalize step after create_artifact_upload, the distinction between stored content and merely recorded external links, and the JCS-canonical payload requirement for worker_signature. These semantics are not inferable 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?

The description states a precise verb-resource pair ('Attach every concrete output ... as an artifact') and clearly scopes what qualifies: notes, drafts, results, files, links. It also differentiates the tool from chat-oriented siblings by saying the artifact should be 'part of the task record, not just chat', and from create_artifact_upload by describing the upload-token handoff.

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

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

The description gives explicit mode routing: content_base64 for files up to ~6 MB, fetch_url for hosted files up to 50 MB, create_artifact_upload plus upload_token for large files, content for inline text, and external_url for links only recorded. It also tells the agent when attribution logic changes (lease active vs acting_worker_id) and directs artifact ids into complete_task's evidence_artifact_ids.

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 provide basic safety signals (readOnlyHint=false, destructiveHint=false), and the description goes beyond them by clarifying that no lease or worker identity is required and that comments surface in the activity timeline and web UI. This adds useful behavioral context for a write operation.

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

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

Three short sentences, each earning its place: what it does, when to use it instead of the alternative, and where the result appears. The most decision-relevant 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 simple two-parameter tool with full schema coverage, the description covers purpose, usage distinction, and visibility of results. It is slightly above the minimum because it also addresses provenance of the comment, but a brief note on output/return behavior would make it fully complete.

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

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

Both parameters are fully described in the schema with 100% coverage, so the description does not need to add much parameter detail. The mention of 'plain comment' and the alternative tool's context slightly reinforces the body semantics but adds no essential new meaning.

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

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

The description uses a specific verb and resource ('Leave a plain comment on a task') and immediately differentiates from add_progress_note. An agent can tell exactly what this tool does and how it differs from its closest 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?

It explicitly names the alternative (add_progress_note), states the distinguishing condition ('needs no lease or worker identity'), and gives the intended use cases ('questions, context, and notes'). This leaves no ambiguity about when to choose this 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?

The description extensively discloses behavioral requirements beyond annotations: attribution rules, lease or acting_worker_id requirements, the 422 rejection outcome, the guarantee that nothing is written on failure, and that the actor is never guessed. This is exactly the kind of behavioral context that annotations alone do not provide.

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

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

The description is dense but every sentence earns its place: purpose, timing, attribution, failure mode, and explicit non-guessing guarantee. It is front-loaded with the core action and use context, and the length is justified by the authentication 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?

The description covers what the tool does, when to use it, authentication prerequisites, and failure behavior. No output schema exists, so a mention of the return value or confirmation payload would be nice, but it is a minor omission given the side-effect-focused nature of 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 coverage is 100%, so the baseline is 3. The description goes beyond the schema by explaining who may act without a worker identity (human assignee or org owner) and what happens when no valid actor is supplied. This enriches the acting_worker_id semantics meaningfully.

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

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

The description names a specific action and resource: 'Append a progress note to a task's event log.' It also clarifies the purpose ('so teammates can follow the work without asking'), which helps distinguish it from generic add_comment. It could more explicitly contrast with add_comment or other similar tools, but the action is clear.

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

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

The description gives clear usage timing: at each meaningful step — decisions, blockers, findings — as part of the Tango working agreement. It also states the condition under which the tool should NOT be used implicitly by requiring valid attribution. It does not explicitly name alternatives, but the context is strong enough for an agent to route correctly.

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

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

The description discloses a meaningful behavioral trait beyond the annotations: the answer is recorded on the question thread and posted to the task timeline. This explains side effects and audience. It aligns with readOnlyHint=false and destructiveHint=false, with no contradiction. It doesn't discuss failure modes, permissions, or idempotency, but the stated effects are valuable.

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

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

The description is two sentences and 31 words. It front-loads the core action in the first sentence, then adds the critical side effects in the second. There is no redundancy, tautology, or fluff; every word earns its place.

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

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

For a simple 2-parameter write operation with no output schema, the description explains the primary flow: answer recorded, posted to timeline, readable by the asking agent. It does not mention response/confirmation behavior or any preconditions, but the schema covers parameter sourcing. Slightly more could be said about what happens after posting, but overall it is nearly complete.

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

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

Schema description coverage is 100%: both answer and question_id have descriptive schema entries, including the origin of question_id ('from list_open_questions or get_task'). The tool description adds no additional parameter-level meaning, so a baseline 3 is appropriate because the schema already carries the semantic 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?

The description clearly states the tool's function: 'Answer an open question raised on a task.' It also specifies the distinct side effects (recorded on question thread, posted to timeline) that set it apart from generic comment tools. It lacks an explicit comparison to sibling tools, but the 'open question' phrasing and effect descriptions provide reasonable differentiation.

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

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

The description implies when to use it: when an open question exists on a task (especially 'so the asking agent can read it'). However, it provides no explicit alternative guidance, such as when to use add_comment or reply_to_support_request instead, or any conditions that would exclude use. The usage context is clear but under-specified relative to the sibling set.

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

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

The description adds substantial behavioral context beyond the annotations: it specifies exactly what changes (no new claims/leases, visibility changes, quota impact) and what is preserved (history, receipts, transparency logs). It also clarifies that despite destructiveHint: true, this is a reversible soft delete, which is valuable, non-contradictory nuance.

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

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

Three dense sentences cover the core action, all relevant side effects, retained data, and reversibility. There is no filler, and the most important semantic qualifier—'soft-delete'—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 two-parameter tool with a self-evident required ID and a fully described optional reason, the description provides everything an agent needs: behavioral effects, historical data preservation, quota impact, and the unarchive path. No output schema exists, but none is needed to invoke this tool correctly.

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

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

The description does not explain the parameters, and schema coverage is 50% because worker_id lacks a description. However, worker_id is semantically obvious and required, while reason already has an explanatory schema description. The description adds no parameter-level meaning beyond what the schema and tool name provide.

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 and resource—'Soft-delete a worker'—and enumerates concrete consequences (no task claiming, disappears from list_client_team and whoami, no longer counts against quota). This clearly distinguishes it from siblings like delete_worker and unarchive_worker.

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 makes the soft-delete semantics explicit and names the reversal path through unarchive_worker, which gives an agent a clear condition for choosing this tool. It does not explicitly contrast with delete_worker as a hard-delete alternative, so it stops short of fully explicit when-not guidance.

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

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

Adds important side effects beyond the annotations: the task is paused, a specific human is asked, and the task enters review. Annotations already mark it non-read-only and non-destructive, and the description substantiates those flags with concrete state changes.

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

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

Two concise sentences, with the primary action front-loaded and the routing guidance placed second. Every sentence earns its place; nothing is redundant.

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

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

For a simple three-parameter tool with full schema coverage and a clear description, this is nearly complete. It lacks explicit detail on what happens after the human answers, but the review-state mention covers the most important post-invocation behavior.

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

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

The schema covers all three parameters at 100% with useful descriptions, including the optional recipient's default behavior. The description adds only the 'specific human' notion, which aligns with to_user_id but does not materially extend schema semantics.

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

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

States a specific action sequence (pause, ask, put in review) with a clear resource (specific human, task). Distinguishes from siblings like answer_question by making the direction of communication explicit.

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

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

Gives an explicit usage criterion: prefer this when a decision requires human input rather than guessing. Does not name alternative tools, but the guidance is clear enough for an agent to select it appropriately.

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 are minimal (not read-only, not destructive), so the description carries the behavioral burden. It adds meaningful context: the binding persists across subsequent tool calls, affects attribution in leases/receipts/audits, and requires an owned worker. It doesn't spell out whether an existing binding is overwritten or how to reverse it, but the core stateful behavior is disclosed.

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, each earning its place: purpose, behavioral impact, and usage boundary. The most important constraint ('call this only to reuse an existing worker') is clearly positioned at the end without burying the core definition.

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, no-output-schema tool, the description is complete: it explains what happens, when to call it, when not to, and where to get the required worker_id. An agent has enough context to select and invoke this tool correctly.

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

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

Schema coverage is 100% and the schema already describes worker_id as 'A worker you own, from whoami' with format/pattern constraints. The description adds no additional parameter-level meaning, 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 action ('Point this MCP connection ... at a specific worker you own') and a clear resource (the connection/worker binding). It also distinguishes itself from the sibling creation flow by explaining that Tango auto-provisions on first use and this tool is only for reuse.

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 explicitly says when to use the tool: 'call this only to reuse an existing worker instead.' It also explains the default alternative (auto-provisioning) and the consequence of use (subsequent calls attributed to that worker), giving an agent clear decision criteria.

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 mark the call as read-only=false and not destructive, so the description carries the behavioral burden. It explains the tool is a passthrough to an external gateway, but does not disclose that the invoked external tool may have arbitrary side effects, nor does it describe response/error behavior. This is adequate but not rich.

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

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

Two concise sentences that front-load the core purpose and then give concrete examples. No filler or redundant 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 generic passthrough tool, the description is understandable and all parameters are documented, but there is no mention of what the call returns or how errors surface. Given there is no output schema, a brief note on the response shape would make this more complete.

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

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

Schema description coverage is 100%, so the description does not need to re-explain parameters. It adds no extra semantics beyond schema, which matches the baseline for full coverage.

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

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

The description uses a specific verb ('Forward') and identifies the resource ('executor.sh MCP gateway' / any MCP-compatible gateway). It also clarifies scope by stating it reaches tools hosted outside Tango, differentiating it from sibling tools like call_integration.

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 use context: 'Use this to let Tango reach tools hosted outside Tango, such as GitHub, Slack, or custom sandbox functions.' It does not list exclusions or when to prefer alternatives, but the intended scenario 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 signal readOnlyHint=false and destructiveHint=true, and the description adds meaningful behavioral context: every call is recorded as an integration event and the task's client determines which workspace is reachable. This goes beyond the structured annotations and warns the agent about side effects and prerequisites.

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 compact and front-loaded: it states the core function in the first clause, supplies varied concrete examples, and then gives the essential usage preconditions. Every sentence earns its place without redundancy or filler.

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

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

For a generic integration executor with no output schema, the description covers the critical operational context: lease requirements, workspace routing, event recording, and the need to inspect available connections first. It does not describe response shape or error behavior, but those are provider-dependent and less essential than the stated preconditions.

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 parameters are already well-documented in the input schema. The tool description adds examples of actions but does not provide additional semantic meaning for body, query, or method beyond what the schema already states. A 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 uses a specific verb phrase ('Perform one call against a system this client has connected') and gives concrete examples such as posting a Slack reply and reading a Linear issue. It clearly differentiates this execution tool from list_integrations and from the many task-management siblings by framing it as the generic integration invocation tool.

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 explicitly states preconditions ('must hold an active lease') and directs the agent to 'Call list_integrations first to see what is connected.' It does not explicitly enumerate when not to use this tool versus other alternatives, but the context and the call to list_integrations make the intended usage 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 provide readOnlyHint=false and destructiveHint=false. The description adds valuable behavioral context by explaining that Tango persists a cursor and that repeated calls only return new items, implying a stateful, cursor-advancing poll. It does not explicitly state that the cursor advances by default, though advance_cursor in the schema hints at this.

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 with no filler. The description front-loads what the tool returns, then gives when to call it, then explains cursor behavior. Every sentence earns its place.

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

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

The description explains the return categories, cursor semantics, and invocation timing. Since there is no output schema, this conceptual description of returns is helpful. It could slightly expand on default limit behavior or how advance_cursor interacts with the stored cursor, but these are also covered in 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 75%: limit has no description, while since, worker, and advance_cursor do. The free-text description itself does not explain any parameter semantics, so it adds little beyond the schema. The undocumented limit parameter is a clear gap, but the schema covers most parameters.

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

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

The description opens with a specific behavior: 'Cursor-based poll: returns tasks newly assigned to you, tasks whose client/project context changed under you, and the context objects that were revised since your last check-in.' This clearly names the resource and what the tool does, and the notion of incremental newness distinguishes it from related sibling tools like pull_next_task or list_my_tasks.

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 usage context: 'Call this at the start of every session or turn, and on your polling interval.' This is clear when-to-use guidance. It does not explicitly mention when not to use it or name alternative tools, 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 say readOnlyHint=false and destructiveHint=false, so the description carries the behavioral burden. It explains the lease semantics and the notable stale-lease release behavior when the task is assigned to the current worker, which is useful beyond the schema.

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

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

The description is three sentences with no filler. The core action is front-loaded, and the alternative tool guidance and behavioral nuance each earn their place.

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

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

For a tool with full schema coverage and no output schema, the description provides enough context: what it does, when to use it, and an important behavioral effect. It does not explain what happens if the task is not assigned to the worker, but this is a minor gap given the clarity provided.

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

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

Schema description coverage is 100%, and the schema already describes task_id, worker_id, and lease_seconds along with defaults and constraints. The description adds little parameter-level detail beyond the schema, which matches the baseline for full schema coverage.

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

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

The description uses a specific verb ('Take a lease') and resource ('a specific task by id'), immediately clarifying what the tool does. It also distinguishes itself from pull_next_task by noting the key difference: claim by known ID rather than pulling the next task.

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 explicitly says to use this tool instead of pull_next_task when the task_id is already known. This gives the agent a clear selection rule relative to its most relevant sibling.

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

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

Annotations already indicate the operation is destructive and not read-only. The description adds meaningful behavioral context beyond that: after calling, future events are delivered via polling rather than the webhook URL. It does not discuss reversibility or exact deletion semantics, but the key behavioral consequence is disclosed.

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 deliver the core action and the key fallback behavior without unnecessary detail. Every word earns its place.

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

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

This is a simple one-parameter destructive action with annotations already covering its safety profile. The description covers the immediate effect and the alternative delivery behavior. It could mention re-enabling via set_webhook, but that is not essential for correct invocation.

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

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

Schema description coverage is 0%, so the description must clarify the worker_id parameter's role. It does so by referring to 'this worker's webhook URL,' tying the single parameter to the affected resource. The schema supplies the uuid format, so no additional syntax explanation is needed.

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 action verb ('Stop pushing events') with a clear resource ('this worker's webhook URL'). It is immediately distinguishable from sibling tools like set_webhook, get_webhook, and rotate_webhook_secret.

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

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

The phrase 'Future events fall back to polling' provides clear context: this tool is appropriate when push delivery should stop but event availability should continue through polling. It does not explicitly name alternatives or exclusions, 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?

Discloses significant behavior beyond the annotations: agents cannot self-approve, completions attributed to workers land in human review, completion atomically releases the lease, invalid signatures abort with nothing written, and the actor is never guessed from the assignee. These are exactly the non-obvious behaviors an agent needs to know.

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 long but every sentence carries a distinct behavioral or routing rule. It is front-loaded with the step and purpose, then moves through approval, attribution, side effects, and signing modes without repetition or filler.

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

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

For a complex 12-parameter mutation tool with no output schema, the description covers the receipt contents, error paths, prerequisites, side effects, and mode differences. No critical operational gap remains for an agent deciding whether and how 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?

Schema coverage is 100%, so the baseline is 3. The description adds workflow-level meaning beyond the schema: it connects worker_signature, worker_kid, and worker_signed_at to prepare_completion, explains why they matter, and clarifies acting_worker_id ownership checking.

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

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

States a specific verb and resource: 'Mark a task complete with a structured receipt' and anchors it as 'Step 5 of the Tango working agreement (finish).' This clearly separates it from sibling tools like update_task or pause_task by defining completion as a finalizing action with a receipt.

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 and prerequisites: attested workers must call prepare_completion first, delegated workers get automatic signatures, humans may complete without worker identity, and calls without valid attribution are rejected with 422. It also clarifies that agent 'done' is recorded as 'review', preventing misuse.

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 indicate readOnlyHint=false and destructiveHint=false, so the description carries the behavioral burden and handles it well. It discloses that the URL is short-lived, that the upload requires a raw PUT with no base64, that nothing is recorded until finalization, and that an abandoned upload leaves no artifact. This materially clarifies side effects and lifecycle behavior beyond 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?

Four sentences, each earning its place: when to use, what is returned, how to complete the flow, and the consequence of abandonment. The most important routing information is front-loaded, and no redundant content or schema repetition weakens it.

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

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

Despite lacking an output schema, the description explains the returned upload_url and upload_token, the required PUT step, and the finalize step with add_artifact. It also covers the failure edge case of an abandoned upload. Together with 100% parameter schema coverage, the agent has everything needed to call this tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3 even though the description adds little about individual parameters. It does connect task_id and name to the finalize step with add_artifact, and mentions upload_token as a returned value, but mime_type and size_bytes remain solely documented by the schema. This is adequate given the high schema coverage.

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

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

The description states a specific verb and resource ('Get a signed upload URL for a large file') and differentiates itself from add_artifact's inline base64 path by size ('too big for add_artifact's inline base64 path (~6 MB)'). An agent can immediately tell this serves the two-step large-file upload flow rather than direct artifact creation.

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 explicitly tells the agent when to use this tool ('when you need to attach a file too big for add_artifact's inline base64 path'), names the sibling alternative (add_artifact), and gives the exact follow-up sequence: PUT bytes to upload_url, then call add_artifact with the same task_id, name, and upload_token. This is clear, actionable routing guidance.

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

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

Annotations only mark the tool as non-read-only and non-destructive, so the description adds useful behavioral context: projects are scoped to a client workspace and the goal seeds intent inherited by tasks. It does not discuss duplicate handling, auth, or return behavior, but those are secondary for a create tool already annotated as non-destructive.

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: the action, the precondition, and the key guidance. It is front-loaded, scannable, and every sentence earns its place.

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

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

For a 6-parameter mutation with no output schema, the description gives the essential before-create workflow and a meaningful rule for setting goals. It omits what the call returns and how to disambiguate client vs client_id, but the schema covers some of that and sibling tools like get_project_context and list_projects provide follow-up paths.

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 exactly 50%, with goal, client, and brief_md already described. The description adds meaningful guidance for the goal parameter ('every task under it inherits the intent'), but it does not compensate for the undocumented name, deadline, or client_id parameters beyond what the schema types/formats provide.

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 concrete action ('Create') and resource ('a new project inside a client workspace') with concrete examples like Website and Google Ads. It clearly distinguishes this from list_projects and update_project, so an agent can identify the right 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?

It gives explicit when-to-use guidance by saying to call list_projects first and only create a project when no existing one fits. It also names the relevant alternative, which is exactly the kind of decision guidance an agent needs.

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

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

Annotations only provide readOnlyHint=false and destructiveHint=false, so the description carries the behavioral burden. It adds rich context: creation can include a parent+children batch, a scope check runs on every creation, cross-agency assignments are audit-logged, and client is authoritative for tenanting. No contradictions with 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?

The description is long but dense and front-loaded: it opens with the core purpose and required client, then dedicates a clear paragraph to decomposition/subtask rules. Each sentence earns its place by providing actionable guidance for a complex 22-parameter tool; the structure helps an agent parse requirements in priority order.

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 complex create tool with no output schema and minimal annotations, the description is sufficiently complete. It covers required fields, prerequisites, sibling alternatives, decomposition handling, cross-agency behavior, and the one-task-per-deliverable rule. The only omission is explicit return-value details, but the description's needs_decomposition guidance effectively tells the agent what to inspect in 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?

Despite high schema coverage, the description adds meaning beyond the schema: it clarifies that client is required for non-subtasks, assignee must be set to self or a teammate, goal and definition_of_done should always be provided, and subtasks should be used for multi-deliverable asks. It also explains the operational consequence of allow_cross_agency and the decomposition response flag.

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 action and object ('turn any client ask into a task') and frames it as step 2 of a working agreement, which clearly distinguishes it from sibling create/update/delete tools. It even names the workflow position and the core rule 'ONE TASK PER DELIVERABLE', leaving no doubt about what this 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?

The description gives explicit when-to-use rules ('before you start work'), required preconditions (call list_client_team first, ask for client if unknown), and names alternatives (call request_decomposition for decomposition). It also states behavioral prohibitions: do not begin work on a decomposition-flagged task and do not over-split.

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=false and destructiveHint=false, and the description adds meaningful context beyond them: key custody model (Tango holds the signing key and signs receipts in delegated mode), the follow-up workflow required for attested mode, and the ephemeral-sandbox use case. This is valuable behavioral disclosure for a write operation.

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

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

Four sentences with no filler: purpose first, then conditional mode guidance, then optional scoping, then prerequisite. Every sentence earns its place and the most important decision (key_mode selection) is front-loaded right after the core purpose.

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 tool with nested objects and no output schema, the description covers purpose, mode selection, follow-up tools, and prerequisites comprehensively. The main gap is that it never describes the return value (e.g., worker id/handle), which matters more here because no output schema exists to fill that role.

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 89%, so the schema carries most of the load. The description adds decision-level meaning beyond the schema: when to pick each key_mode value, that clients is an optional scoping dimension, and that whoami reveals valid values for organization and clients. Only the undocumented 'capabilities' object is left without any explanation.

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 ('Provision a new worker (agent identity)') and states the purpose ('so you can claim, lease, and hand off tasks'). It is clearly distinguishable from lifecycle siblings like archive_worker, delete_worker, and register_worker_key, and the title adds the 'for myself' self-provisioning scope.

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

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

Provides strong conditional guidance: use 'delegated' in ephemeral sandboxes, 'attested' only with durable keys, followed by explicit next steps (request_key_challenge, register_worker_key). Also directs the agent to call whoami first to discover organizations and clients. Lacks an explicit 'when not to use this tool' exclusion, but the context is clear and actionable.

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

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

The annotations already mark destructiveHint true, and the description adds important behavioral context: the operation is irreversible and requires a confirm acknowledgment. It also explains the permission model, which is valuable beyond the structured 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 concise sentences deliver purpose, usage context, permissions, and destructiveness without filler. The most important warning ('destructive and irreversible') is placed at the end but is clearly surfaced.

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

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

For a destructive delete operation with a confirm parameter, the description covers the essential what, when, prerequisites, and consequences. The schema handles parameter details, and no output schema is needed for a void-like destructive action.

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 task_id and confirm are already fully documented, including the const true requirement and the URL option for task_id. The description adds no parameter-specific detail, 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?

The description opens with a specific verb and resource: 'Permanently delete a Tango task.' It also names the intended use case (removing duplicates or bare tasks superseded by fully-specified ones), which distinguishes it from related tools like update_task or complete_task.

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 context for when to use the tool and states a precondition: the caller must have RLS permission as owner, agency admin, or task creator. It does not explicitly name alternatives or say when not to use it, so it falls just 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 set destructiveHint=true and readOnlyHint=false, and the description adds crucial behavior beyond that: deletion is hard/permanent, it is rejected with 409 if any history exists, and the reason is to preserve the audit trail via archive_worker. This clearly communicates the destructive semantics and consequence of misuse.

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 compact and front-loaded: the core action ('Hard-delete a worker') comes first, followed immediately by the precondition, error behavior, and alternative. Every sentence carries necessary information and there is no fluff.

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

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

For a destructive single-parameter tool with no output schema, the description covers the action, the exact precondition, the failure mode, and the fallback tool. An agent has everything needed to decide when to call this and what to expect on rejection.

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

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

Schema description coverage is 0%, so the description carries the burden for parameter meaning, but it never mentions worker_id. The parameter name and UUID format are fairly self-evident, yet the description adds no parameter-specific guidance such as how to obtain the ID or what values are valid. With only one parameter this is a minor gap, but the burden was not met.

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 and resource: 'Hard-delete a worker.' It also distinguishes itself from archive_worker by stating that workers with history must be retired instead, so an agent can clearly identify this as the permanent, history-free deletion path.

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 explicitly states when this tool is permitted ('only when the worker has never been assigned a task and holds no receipts, leases, or handoffs'), when it is not ('Anything with history returns 409'), and names the exact alternative ('must be retired with archive_worker instead'). This is actionable routing guidance with no ambiguity.

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?

Beyond the readOnly/destructive annotations, the description discloses meaningful runtime behavior: results are ranked, an needs_disambiguation flag fires for semantically ambiguous top hits, handles are returned for pass-back, and active_agency is always present so callers know which org was in effect. This materially shapes how an agent interprets and chains the response, and it does not contradict the readOnlyHint=true annotation.

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 earning its place: purpose, when-to-use, return contract, and the active_agency guarantee. The core purpose is front-loaded in sentence one, with supporting behavioral detail following in logical order and no filler.

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

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

For a read-only search tool with 5 parameters and no output schema, the description covers the essential return contract an agent needs: ranked candidates, passable handles, the needs_disambiguation flag, and agency context. Limit behavior and the exact ambiguity threshold are left unspecified, a minor gap given limit is self-explanatory and the schema covers it numerically.

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% (4 of 5 params documented; only limit is bare), so the schema carries most parameter meaning. The description adds only marginal parameter context — 'fuzzy' qualifies how query is matched, and the active_agency remark relates to scope/agency_id — so the 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 opens with a specific verb and resource ('Fuzzy-search for a worker, teammate, or client') and enumerates the searchable keys (name, handle, email). It clearly differentiates from sibling tools like search_tasks by naming the downstream consumers (create_task/handoff_task), so an agent cannot confuse it with task search or creation 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?

'Use this to disambiguate a plain-language reference (e.g. 'Merrilee' or 'Avalore') before create_task/handoff_task' is explicit when-to-use guidance with concrete examples and named downstream tools. It does not state an explicit when-not-to-use condition (e.g., skip if you already hold a canonical handle/ID), which keeps this at 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?

With only minimal annotations, the description carries behavioral disclosure well: it marks the task, blocks claiming until resolved, and runs the Tango PM reviewer to generate a brief, questions, and possible subtasks. It also clarifies that a human applies the result, managing expectations. It does not mention reversibility or permission requirements, but the main side effects are disclosed.

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 longer than average but every sentence carries useful routing or behavioral information. It is front-loaded with the primary use case and then explains effects and follow-up steps. Slightly dense, but not wasteful.

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

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

The description covers when to use the tool, what the tool does, what happens next, and where to retrieve the proposal. There is no output schema, but the follow-up guidance to use `get_task_review` compensates. A small gap is that the return value or success behavior of the call itself is not described, but this is not blocking for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents both `task_id` and `reason`. The description adds little beyond calling the task 'under-specified', which aligns with the schema. Baseline 3 is appropriate since the schema does the parameter documentation work.

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: flag a task as missing information by marking it `needs_more_info`. It also distinguishes this from guessing and places it in a clear workflow alongside `get_task_review`, so an agent can tell what the tool is for without inspecting siblings.

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

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

It gives explicit when-to-use criteria: vague goal, no checkable definition of done, unclear scope, and tells the agent to use it INSTEAD of guessing. It does not enumerate alternatives like `ask_human` or `request_decomposition`, but the trigger conditions are specific enough to route the agent correctly.

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 mark the tool read-only and non-destructive; the description adds behavior beyond that: binary artifacts return a short-lived download_url instead of text, and get_task's inlined bodies can be truncated, making this the way to get the full text. This is useful operational context, though auth and error behavior are not addressed.

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 earning its place: the core operation, the get_task alternative and its limitation, binary handling, and the synthesizer requirement. The key differentiator 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 read-only fetch tool with no output schema, the description covers return behavior (text vs short-lived download_url), lookup modes, the relationship to get_task, and truncation semantics. Nothing esseential is missing for an agent to select and invoke it correctly.

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

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

All four parameters are already fully documented in the schema, so the baseline is 3; the description adds meaningful relationship guidance by presenting the two lookup modes (artifact_id vs task_id + name) and explaining the truncation situation that max_bytes controls. This helps an agent choose the right parameter combination.

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

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

The description names a specific verb and resource: read the actual text/body of an artifact attached to a task. It also distinguishes itself from get_task, which lists artifacts and inlines small bodies, so the agent can tell the tools apart.

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 explicitly states when to use this tool: when a body was truncated or omitted, or to fetch one artifact by id or task_id + name. It names get_task as the alternative that inlines small bodies, and it adds a role-specific mandate for synthesizers.

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 context about the bundle being shared ground truth but does not disclose additional behavioral traits such as auth requirements, rate limits, or error behavior.

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

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

Two tight sentences: the first states the resource and contents, the second gives the usage trigger. There is no filler or redundant repetition of schema details.

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

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

With no output schema, the description still tells the agent what the returned bundle contains: brief, structured facts, reference links, and recent decisions log. It also explains why and when to call it, which is sufficient for a read-only fetch 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?

The schema already describes `client` and `decision_limit` reasonably well. The description does not add parameter-level meaning, and `client_id` remains semantically unexplained beyond format/pattern, so the description does not compensate for that 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?

The description starts with a specific verb-resource pair ('Fetch the shared context bundle for a client/workspace') and enumerates the bundle's contents: brief, structured facts, reference links, and recent decisions log. The 'task tied to a client' phrasing clearly separates it from project-context or task-context siblings.

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

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

It gives an explicit trigger: 'Call this before working on any task tied to a client so you inherit the same ground truth every other agent/human has.' This tells the agent when to use the tool, though it does not name alternatives or state 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, and the description does not contradict them. It adds behavioral context beyond annotations: output is ready-to-run snippets (cron/launchd/shell) and the tool is positioned as setup information rather than an action, plus a system-trigger scenario ('Tango tells you you are unreachable').

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 with zero waste: the first front-loads what the tool returns and its components, the second gives the call timing. Every clause earns its place.

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

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

Complete enough for a simple read-only tool with zero required parameters: purpose, content, and timing are covered. Since there is no output schema, slightly more detail on the return structure would help, but naming the cadence and snippet components provides an adequate preview.

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 is well described but platform has only an enum with no description. The tool description never names either parameter, though 'cron/launchd/shell' indirectly implies platform's role (launchd=macOS, cron=Linux). Useful but relies on inference rather than explicit parameter guidance.

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 — 'Return ready-to-run instructions' — and enumerates concrete content (in-session check_in cadence for chat agents, cron/launchd/shell heartbeat snippets). It is clearly distinguishable from the sibling check_in, which performs a check-in rather than returning setup guidance.

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 invocation timing: 'Call this once when you connect, or whenever Tango tells you you are unreachable.' No explicit exclusions or named sibling alternatives, but the trigger conditions are concrete enough for an agent to decide when to call.

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, covering the safety profile. The description adds value by disclosing the exact contents returned (goal, brief, structured facts, reference links, decision log) and prescribing a recommended usage order (read before task work). This goes beyond what the annotations alone provide.

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

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

Two sentences, each earning its place: the first states precisely what the tool returns, and the second states when to use it. There is no redundant wording, filler, or vague abstraction.

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

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

The description covers purpose, return contents, and usage timing, and annotations cover the safety profile. However, with 5 parameters and no output schema, the description leaves ambiguity around ID-based addressing, client scoping, and decision_limit semantics—an agent may not know how to parameterize the call in less common cases.

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%, yet the description provides no parameter guidance. It does not explain the distinction between client/client_id and project/project_id, how IDs may be used instead of names, or the meaning of decision_limit. The only hint of a parameter is the word 'project' in the resource name, so the description fails to compensate for the low schema coverage.

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

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

The description uses the specific verb 'Fetch' with a clearly bounded resource ('shared context bundle for a project') and enumerates the exact contents: goal, brief, structured facts, reference links, and recent decision log. This clearly distinguishes it from sibling tools like get_client_context and get_task, which target different resources.

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

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

The second sentence gives an explicit when-to-use directive: 'Read this before working a task' and explains the rationale (alignment with project intent over task title). It does not explicitly name alternatives or exclusions, so it falls short of a 5, 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 and non-destructive behavior; the description adds useful behavioral detail by listing the returned context pieces and the activity timeline boundary. The internal mismatch of '7-part spec' followed by only five named parts is a small transparency gap.

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

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

The description is two dense sentences with no filler: the core action comes first, the return contents are structured as a list, and the imperative usage note is separated. Every sentence earns its place.

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

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

For a read-only tool with one parameter and no output schema, the description does well to explain what is returned and to point to get_task_activity for older entries. It is slightly incomplete because it promises a '7-part spec' but lists only five parts, leaving the full response shape somewhat ambiguous.

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 single task_id parameter is fully documented in the input schema, including accepting an 8-character reference or pasted URL, so the schema bears the semantic load. The description only repeats 'by id' and adds no new parameter detail.

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

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

The description states a precise action ('Fetch') and resource ('a Tango task by id') and enumerates what the return bundle contains, so an agent immediately knows this is the by-id task context reader. It also distinguishes itself from get_task_activity by routing older entries to that 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?

It gives explicit when-to-use guidance: 'Always read activity before starting work,' and calls out get_task_activity as the alternative for older entries, which tells the agent when not to rely on this tool for deep history. The 'full context bundle the next agent needs' framing makes the intended use case 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, and the description is consistent with them. It adds genuine behavioral context beyond the annotations: results are merged and newest-first, the timeline spans six entry kinds, and it is the shared write surface for teammates. The only unaddressed behavior is return shape, which is minor for a read tool.

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

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

Three sentences with zero filler: core function is front-loaded in sentence one, usage guidance in sentence two, ecosystem context in sentence three. Every sentence earns its place and nothing important is buried.

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

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

For a read-only list tool with four schema-documented parameters and safety annotations, the description covers purpose, ordering, content scope, and selection conditions — a complete picture for invoking it correctly. Minor gaps: it doesn't hint at the return shape (no output schema exists) or explain whether combining multiple `types` values is AND or OR filtering.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by enumerating the entry kinds the `types` filter accepts (progress notes, comments, status changes, handoffs, artifacts, escalations), which goes beyond the schema's generic 'e.g.' example, and it motivates filtering by saying the tool can 'filter to a single kind of entry.'

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 ('the merged, newest-first activity timeline for a task'), then enumerates the exact content types: progress notes, comments, status changes, handoffs, artifacts and escalations. This distinguishes it from the sibling get_task, whose limited 30-entry activity window is explicitly called out, and from 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 names the alternative and the switching condition: 'Use this when get_task's `activity` window (30 entries) isn't enough, or to filter to a single kind of entry.' It also identifies the write-side siblings (add_progress_note, add_comment) whose output lands on this surface, giving the agent a sense of the tool's ecosystem role.

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 substantial behavioral context: it lists the exact data returned, including quality-gate status, PM proposal components, and open questions. Since there is no output schema, the description carries the full burden of explaining return content, and it does so clearly.

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 dense but well-structured: it opens with the core return value, lists the specific components, and closes with a practical usage tip. Every sentence earns its place with no repetition or 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?

Given a single simple parameter, no output schema, and read-only annotations, the description is complete. It tells the agent what will be returned, when to use it, and why it is preferable to asking the human, leaving no critical gap for invocation.

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

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

Schema description coverage is 100%: the single `task_id` parameter is documented as 'Task id or task URL.' The description does not add meaning beyond this, but the schema already fully covers the parameter semantics, so the baseline score 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?

The description immediately states the tool returns whether a task is blocked by specific quality gates and the latest PM proposal. It enumerates the exact contents (missing information, goal, definition of done, open questions, proposed subtasks), clearly distinguishing this read-only review tool from task mutation or question-asking tools.

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

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

The description gives an explicit usage directive: 'Read this before asking the human anything.' It explains why the tool should be used first—the reviewer has usually already written the questions worth asking—effectively telling the agent to consult this before falling back to asking the human directly.

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 enumerating the response fields (useful given no output schema) and explaining a non-obvious behavioral rule: a suspended webhook receives no deliveries until set_webhook is called again. No contradiction with 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 with zero waste. The first sentence front-loads the verb and the full return-value list; the second adds a genuinely useful behavioral note about suspension semantics. Every word earns its place.

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

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

For a one-parameter read tool whose safety profile is already carried by annotations and which has no output schema, the description is complete: it enumerates the response fields and explains the one non-obvious behavioral rule. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 0%, so the description carries the burden, but it adds only minimal meaning: 'for one of your workers' clarifies ownership scoping of worker_id. The single parameter is well-named and strongly typed via uuid format and pattern, so the schema largely speaks for itself; the description modestly compensates 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?

The description states a specific verb ('Return') and resource (a worker's webhook settings) and enumerates the exact fields returned, making the purpose unambiguous. However, it does not explicitly differentiate itself from sibling webhook tools like get_webhook_deliveries or set_webhook — the distinction is inferred from the field list rather than stated.

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: an agent can tell this is the tool for inspecting current webhook configuration, and the suspension sentence references set_webhook as the remedy, offering indirect routing. But there is no explicit when-to-use vs alternatives guidance — nothing tells the agent to prefer get_webhook_deliveries for delivery history or set_webhook/clear_webhook for mutations.

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; the description adds behavioral context by positioning the call as a no-database-access diagnostic and specifying exactly what fields the response contains. It does not disclose retention limits or pagination traits, but those are not critical for this read-only list tool.

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

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

Two dense sentences, front-loaded with the purpose and followed by the use-case trigger. Every clause adds information and there is no filler.

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

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

For a simple read-only list operation with only two parameters and no output schema, the description provides enough context: what the tool returns, the fields returned, and when to use it. No critical missing information prevents an agent from calling it correctly.

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

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

The schema already documents `limit` (default 20, min/max) and `worker_id`'s UUID format. The description clarifies that `worker_id` refers to 'one of your workers' but does not elaborate on either parameter beyond that, so it only partially compensates for the missing worker_id 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?

The description states a specific purpose ('Debug webhook delivery') and a concrete resource ('returns the most recent delivery attempts for one of your workers') with a detailed field list. This makes it clearly distinct from siblings like get_webhook, set_webhook, or clear_webhook.

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 conditions for use: 'Use this when a worker is not receiving events or its webhook has been suspended.' It lacks when-not-to-use or named alternatives, so it stops short of full routing guidance.

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

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

Annotations already convey read-only and non-destructive behavior, so no credit is needed for restating that. The description adds genuinely useful behavioral context: content is versioned, should be cached by version, and must be re-read when the version changes, plus it names the canonical source.

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

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

Three dense sentences carry purpose, usage, caching, and provenance with no filler. The most important information is front-loaded before usage details.

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

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

For a simple, optional-parameter lookup tool with readOnly annotations, the description covers invocation modes, version/caching behavior, and content source. No output schema exists, but the return value (terms and definitions matching the listed vocabulary) is sufficiently inferable.

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

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

The schema already fully documents the single optional `term` parameter (100% coverage), including examples and omit-for-everything semantics. The description adds minor color ('resolve one word', 'whole versioned glossary'), but no material parameter information beyond the schema.

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

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

The description opens with a specific verb and resource ('Look up Tango vocabulary'), lists representative terms, and makes the tool's scope obvious. It is immediately distinguishable from the many get/list siblings because it is the only vocabulary-resolution tool.

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 explicitly instructs how to invoke the tool: no arguments for the whole glossary, `term` for a single word, and when to refresh cached results. It does not name excluded alternatives, but none of the siblings compete for this 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 only provide readOnlyHint=false and destructiveHint=false, leaving the description to carry the behavioral burden. The description does so strongly: it reveals audit requirements, the failure mode of "rejected with 422 and nothing is written," and the rule that the actor is never guessed from the assignee. It also clarifies how attribution can be satisfied via lease, acting_worker_id, or human/org-owner status.

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 dense sentences with the core action front-loaded and no redundant filler. Every sentence earns its place by adding a necessary constraint, failure behavior, or identity rule.

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

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

For a 9-parameter mutation tool with no output schema, the description covers the highest-risk elements: cross-agency auditing, attribution prerequisites, and failure behavior. It leaves minor gaps around recipient disambiguation and lease timing, but those are secondary to safe and 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 only 44%, so the description adds important meaning beyond the schema, especially for allow_cross_agency and acting_worker_id. However, it leaves some parameter relationships underspecified, such as to_id versus to, to_kind, and lease_seconds. Overall it substantially compensates for sparse schema coverage but not completely.

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 the action verb "Reassign" and the resource "a task" with the recipient scope: "another worker or human with a required note." This clearly distinguishes it from generic task updates and from claim-related tools. The title reinforces the same transfer semantics.

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

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

Provides clear context for use: cross-agency handoffs require allow_cross_agency and are audited, and attribution prerequisites are explicitly described, including the 422 rejection when they are missing. It does not explicitly name alternative tools or say when not to use this tool, 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?

The description adds significant behavioral context beyond the sparse annotations: the raw key is returned exactly once, it must be handed to the worker process, and it should not be repeated in chat. It also discloses the ownership requirement. This is especially valuable for a credential-issuing tool, and it does not contradict 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 tight sentences: the first front-loads the action and purpose, the second covers the critical one-time-exposure security behavior, and the third covers ownership and lifecycle alternatives. Every sentence earns its place with no redundancy or filler.

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

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

For a simple two-parameter, no-output-schema tool, the description covers everything an agent needs: what the key enables, that it is shown only once, what to do with it, who may request it, and where to go for lifecycle changes. Nothing critical 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 schema already documents worker_id and label well. The description reinforces that the worker must be owned/administered by the caller, but this largely mirrors the schema's 'Must be yours.' Therefore it adds only marginal semantic value beyond the schema, matching the baseline for full schema coverage.

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

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

The description states a specific verb ('Mint') and resource ('tng_ bearer key') and clearly identifies the purpose: letting a worker call Tango's HTTP worker API outside MCP. It also distinguishes itself from sibling lifecycle tools by naming rotate_worker_key/revoke_worker_key as alternatives.

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

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

The description says exactly when this tool is appropriate: when a worker needs to call the HTTP worker API outside MCP. It explicitly names the lifecycle alternatives (rotate_worker_key/revoke_worker_key) and states the ownership prerequisite, leaving no ambiguity about when to choose this 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 the operation read-only and non-destructive, and the description adds useful behavioral detail: the returned roster includes both human and AI workers and exposes @handles intended for direct use with create_task or handoff_task. It doesn't cover edge behaviors like empty rosters or client not found, but those are minor for this tool.

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

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

The description is two sentences with no filler. It front-loads what the roster contains and immediately gives actionable guidance about when and why to use the 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?

For a simple read-only lookup with two optional parameters and no output schema, the description covers the essential return value (@handles) and the primary use case. The only notable gap is not explaining what happens when both client and client_id are omitted, or whether at least one is expected.

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

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

Schema description coverage is 100%, with both parameters clearly documented: client is fuzzy-resolved and client_id is for when it is already known. The description adds no extra parameter-level semantics beyond tying the roster to a client, so the baseline score 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?

The description clearly identifies the resource (a client's roster) and the specific contents (human teammates and AI/robot workers with @handles). It also implicitly differentiates this from find_people by warning against guessing assignees from find_people alone.

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

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

The description gives an explicit when-to-use instruction: call this before choosing an assignee. It also names an alternative (find_people) and explains why it is insufficient for routing work to the right client-access teammate.

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 mark this as read-only and non-destructive. The description adds meaningful behavioral context: it aggregates sources from both the organization and the client, returns curated view keys, and implies the views are usable only through query_context_source. It does not mention output structure or edge cases, but given the annotations, this is solid.

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 concise, purposeful sentences: the first states the core scope, the second explains the output's key use, and the third gives the when-to-use trigger. No filler or repetition of schema/annotation data.

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 listing tool with two optional parameters and no output schema, the description covers what is returned (sources and curated views), how the return is used (view keys for query_context_source), and when to invoke it. The only meaningful gap is the parameter-selection ambiguity, but that is already reflected in parameter_semantics.

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

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

Schema description coverage is only 50%: client has a short description, but client_id only has format/pattern with no semantic explanation. The tool description never addresses how to choose between client and client_id, whether either is sufficient, or what each resolves to. Since coverage is low, the description needed to compensate and did 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?

The description states a specific verb ('List') and a distinct resource: external data sources connected to a client, including the organization's sources plus the client's own. It also clarifies that the tool exposes curated views with keys for query_context_source, which clearly separates it from the sibling query_context_source and get_client_context 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 tells the agent when to use it: 'when the shared brief is not enough and the answer likely lives in the agency's own systems.' It also points to the related query_context_source tool for the next step. It stops short of enumerating when-not-to-use cases or naming all alternative tools, so it earns 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 already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: the tool only returns authorized integrations and guarantees that unlisted tools are unreachable, which goes beyond the annotation metadata.

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

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

The description is two sentences with no wasted words. The main purpose and examples are front-loaded, and the second sentence gives essential routing guidance. It is appropriately sized for a simple list 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?

For a read-only list tool with no required parameters and no output schema, the description conveys enough: what will be shown, when to call it, and why it matters. It could be marginally more explicit about the exact shape of the return value, but overall the essential context 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%: the 'client' parameter has a description, but 'client_id' does not, and the description provides no parameter-level guidance. It does not explain whether one or both parameters are expected, how they relate to each other, or what happens if neither is supplied. The description fails to compensate for the incomplete 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 states a specific verb and resource: 'Show the external systems a client workspace has connected' and explicitly names examples (Slack, Linear, GitHub, Notion, Jira, Asana). It also differentiates itself from call_integration by framing this as the prerequisite listing tool, so an agent can distinguish it from siblings.

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

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

The description gives explicit usage guidance: 'Call this before call_integration so you act in a system the client has actually authorized.' It also states a hard constraint — 'you can never reach a tool that is not listed here' — which tells the agent when this tool is required before other actions.

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. The description adds meaningful operational context: it reports which roles are switched on and whether the executing runtime is healthy, and warns that the role slug must be picked up to be effective. Missing return-format/error details are less critical given the read-only annotation.

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 with no filler: the first states what the tool returns and the second states when to call it and why it matters. The main value 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 simple read-only list with one optional parameter and no output schema, the description covers the output scope, status dimensions, and usage rationale. The only minor gap is the exact shape of the returned role objects, but enough context is present for an agent to call and interpret it correctly.

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

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

The single optional parameter client_id is fully described in the schema (100% coverage), and the description adds no additional parameter-specific semantics. Baseline 3 is appropriate when the schema already carries the weight.

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 title and description clearly state this lists micro-worker roles and their operational status. It distinguishes itself from worker lifecycle siblings (create_worker, archive_worker, delete_worker) by focusing on available roles and health rather than managing worker entities.

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 'Call this before delegating specialist work' and explains how the result feeds into create_task's `role` parameter. This gives an agent a concrete when-to-use signal and ties it to an actionable downstream step.

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 annotations: the global cross-agency default and the guarantee that each row includes agency_id and agency_name. This helps callers understand scoping behavior.

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

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

Three sentences with no filler. The purpose is front-loaded, then filter capabilities, then a practical row-level detail. Every sentence earns its place.

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

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

For a read-only list call with 15 optional parameters and no output schema, the description gives essentials: scope, default behavior, available filters, and a useful note about returned columns. It does not enumerate all filters or return fields, but the high schema coverage fills most gaps, making this sufficiently complete.

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

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

Schema description coverage is 73%, so the schema carries most parameter meaning. The description names several key filters (status, role, client_id, agency_id) and clarifies the global default, adding some semantic value. However, it does not compensate for all the less-documented parameters or explain interactions such as mine versus role.

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 pair ('List Tango tasks visible to the signed-in user') and clarifies the global, cross-agency scope. It clearly communicates what the tool does, though it does not explicitly differentiate itself from the sibling search_tasks tool.

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

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

The description gives clear context on when this is the right tool: to list tasks visible to the current user globally by default, with optional filters. It also tells callers not to rely on active-agency state because every row carries agency_id and agency_name. It does not name alternatives explicitly, so it does not reach 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?

The description claims the list comes 'with any human answers,' but include_answered defaults to false, meaning answered questions are excluded by default. This can mislead an agent about what the tool returns. Annotations cover read-only safety, but the description does not clarify the open-question filtering behavior.

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

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

Two tight sentences with no filler; the core action is front-loaded and the usage guidance is immediate.

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 listing tool this covers purpose and a concrete workflow, but the default exclusion of answered questions is only recoverable from the schema. Without an output schema, the description should be unambiguous about what is returned, and it currently is not.

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 descriptions already cover task_id and include_answered; limit has type/min/max but no prose meaning. The description adds no parameter-level detail and doesn't clarify how limit applies, so it neither compensates for the missing limit description nor conflicts with 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?

Uses a specific verb ('List'), names the resource ('questions raised on tasks you can see'), and states that it returns human answers. The 'after ask_human' context clearly separates it from the asking/answering 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?

Explicitly instructs agents to call this after ask_human to poll for a human reply before resuming work. It does not name explicit alternatives or when-not-to-use scenarios, so it stops 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. The description complements this by clarifying what kind of data is returned (significant dated events with examples), which adds behavioral context beyond the annotations. No contradiction exists.

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

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

Two sentences, front-loaded with the core purpose, followed by a practical usage hint. No filler or repetition of structured data.

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

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

For a read-only list tool with 7 optional parameters and no output schema, the description covers the what and when but leaves some gaps. It does not mention output format, ordering, default limit, or how to choose among client/project/client_id/project_id. The schema covers some of this, but the overall picture is adequate yet incomplete.

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 43%, so the description should compensate. It mentions a 'date range', aligning with the to/from parameters, but does not explain limit, client, client_id, or project_id. The schema already documents project's fuzzy resolution, so the description adds little parameter-level meaning beyond what is already 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?

The description uses a specific verb and resource ('Read the dated timeline of significant events on a project') and lists concrete event types (changes, launches, incidents, external shifts, milestones). This distinguishes it from write tools like log_project_event and update_project_event.

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

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

The description gives a clear usage context: 'Use this to explain what analytics are showing over a date range before drawing conclusions.' It does not explicitly state when not to use it or name alternatives, but the context is strong enough for an agent to select it appropriately.

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), and the description's 'Read' verb is consistent with them. It adds useful context about data scope (blockers from external systems) and returned fields (severity, status, fixing tasks). It does not disclose pagination or limit defaulting, but the status default is already documented in the schema.

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

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

Two sentences with zero waste: the first states purpose and return scope, the second gives the usage rationale. The action verb is front-loaded and every clause earns its place.

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

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

The description partially compensates for the missing output schema by naming the returned fields (severity, status, fixing tasks) and for the read-only annotation coverage by explaining the operational purpose. However, with six parameters and no output schema, the unexplained limit/client/client_id parameters and the name-vs-id targeting ambiguity leave clear gaps for an agent invoking 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 only 33% (status and project have descriptions; limit, client, client_id, and project_id have none). The description does not compensate: it never mentions limit, client, or the ID parameters, and gives no guidance on when to use a name versus an ID. An agent cannot tell how 'project' and 'client' interact or how limit behaves.

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/resource ('Read the known issues recorded on a project') and clarifies scope via the em-dash: 'blockers found in external systems, their severity, status and the tasks fixing them.' This differentiates it from the write-siblings log_project_issue and update_project_issue, but it doesn't explicitly distinguish it from similar list tools like list_project_events, which are discoverable in the sibling list.

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

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

Provides an explicit when-to-use directive: 'Read this before you start work so you do not re-discover or duplicate a known problem.' The timing (before starting work) and rationale (avoid duplicating known problems) are clear. It stops short of naming alternatives or exclusions, 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, covering the safety profile. The description adds the domain invariant that every task belongs to exactly one project and the prerequisite role, but doesn't disclose return format, pagination, or archived-project behavior. This is adequate given the annotation coverage.

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 with no filler. The first sentence provides examples of project names, and the second explains the domain rule and the call-time instruction. Every word earns its place.

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

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

For a simple read-only list tool, the description plus annotations cover the main use case: call before create_task. However, the include_archived parameter is unexplained, there is no output schema, and the description doesn't mention what fields are returned, leaving a moderate gap.

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

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

Only client has a schema description (fuzzy-resolved); client_id and include_archived are effectively undocumented, and the description adds no parameter-level meaning. With schema coverage at 33%, the description should compensate but doesn't, leaving an agent unsure what include_archived controls.

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 the verb 'List', the resource 'projects', and the scope 'for a client', with concrete examples like Website and Google Ads. It clearly identifies what the tool does, though it doesn't explicitly differentiate it from sibling list tools such as list_my_tasks or search_tasks.

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

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

The description gives an explicit usage rule: every task belongs to exactly one project, so call this before create_task and ask the human which project the work belongs to. This is strong when-to-use guidance, though it doesn't discuss alternatives or when not to use the 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 the safety profile is covered. The description adds useful behavioral context beyond that: it says the result includes full conversation history and staff replies, and that ticket_id selects a specific thread. This helps the agent understand what kind of data it will receive, even without an output schema.

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

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

Two concise sentences with no redundant wording. The primary purpose is front-loaded, and the ticket_id usage note is included without extra fluf. Every sentence earns its place.

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

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

For a simple read-only list tool, the description covers the main action and the special case of fetching a single thread. It does not describe the status filter, but the schema provides the enum and default, so an agent can still use it correctly. Missing pagination or response format details are minor given the low 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 description coverage is 50%: ticket_id already has a schema description, and the description echoes that with 'Pass ticket_id to fetch one thread.' The status parameter has no description in the schema and is not mentioned in the description, though its enum values are self-explanatory. The description adds modest value for ticket_id but does not fully compensate for the undocumented status 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?

The description begins with a specific verb and resource: 'List your Tango support tickets and read the full conversation.' It clearly distinguishes this from support-related siblings like reply_to_support_request and submit_support_request by framing it as a read/list operation. It also explains the key mode distinction: passing ticket_id fetches one thread.

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

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

The description gives clear context for when to use the tool: for listing support tickets and reading full conversations. It also gives within-tool guidance by saying 'Pass ticket_id to fetch one thread,' which helps the agent choose the right invocation mode. It does not explicitely discuss alternatives, but the read-only framing makes the usage context 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?

The description goes beyond the annotations by revealing that entries are durable, appended, and visible to all future agents and humans. This is valuable behavioral context. It does not disclose edge behaviors like idempotency or failure semantics, but the append-only nature is the key behavioral trait and is clearly stated.

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

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

Three tight sentences deliver the core purpose, usage boundary, and why it matters. The key scoping instruction ('not routine progress updates') is placed early, and there is no filler or repetition of schema fields.

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 logging tool with six parameters and no output schema, the description provides enough context to invoke it correctly: what to log, where it goes, who sees it, and which sibling to use instead. It does not explain the response format, but that is rarely critical for an append-style 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 67%, with descriptions already covering client, detail, summary, and task_id, plus an enum for kind. The description reinforces the kind categories and adds the general 'rolling decisions log' framing, but it does not add meaningful parameter-level detail beyond the schema. A 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 opens with a clear verb and resource: 'Append a durable note to a client's rolling decisions log.' It enumerates the accepted content types (decisions, learnings, preferences, constraints) and differentiates itself from add_progress_note and implicitly from project-scoped logs like log_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?

The description explicitly states when to use this tool ('decisions, learnings, preferences, or constraints') and when not to use it ('not routine progress updates'), naming add_progress_note as the alternative. It does not explicitly address project-level decision logging via log_project_decision, but the 'client's rolling decisions log' wording makes the client scope reasonably 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 establish readOnlyHint=false and destructiveHint=false, and the description is consistent with both. The description adds that logged items are inherited by future teammates, implying persistence, but it does not disclose side effects like deduplication, overwriting, or whether the record is editable later.

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

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

The description is two tight sentences with no wasted words. The core 'what to record' is front-loaded, and the use case is stated immediately.

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

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

For a tool with 8 parameters, no output schema, and low parameter-level schema coverage, the description gives strong purpose and usage context but not enough operational detail to confidently populate optional fields or understand how this relates to update_project_decision and memory_save. It is functional but leaves gaps.

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

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

Schema description coverage is only 25%, so the description must compensate, but it adds little param-level meaning. It does clarify the semantics of 'kind' by naming the four categories, yet leaves 'client', 'client_id', 'project_id', 'detail', and 'task_id' without explanatory guidance beyond the sparse schema text.

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

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

The description states a specific action ('Record') and names the exact resource: things future teammates must inherit, enumerating decision, learning, preference, and constraint. It is clear enough to distinguish from log_project_event and log_project_issue even though it does not explicitly name 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?

The description gives a direct and useful usage rule: use this whenever you make a judgement call that a later agent would otherwise re-litigate. It does not list exclusions or directly compare with sibling tools like memory_save or update_project_decision, but the when-to-use guidance is concrete and actionable.

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 this is a non-read-only, non-destructive write (readOnlyHint=false, destructiveHint=false), and the description's 'Record/Log' verbs align with that. The description adds genuine value beyond annotations by disclosing the downstream behavioral consequence: events are overlaid on analytics and affect how future numbers are interpreted. It does not, however, disclose editability (an update_project_event sibling exists), idempotency, or what a successful log returns.

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, roughly 70 words, with zero filler: action + examples, purpose, then the when-to-log trigger. The concept is front-loaded and every sentence earns its place. This is exemplary conciseness for a tool of this 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?

Given no output schema, 12 parameters, and a fuzzy-resolved 'project' parameter, the description covers the conceptual 'what/why' well but leaves invocation gaps. It does not clarify how to select among the relational identity parameters, what a good title vs description looks like, or what confirmation the agent should expect. Adequate at the concept level, incomplete at the call level.

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 only 33% schema description coverage across 12 parameters, the description bears a heavy duty to compensate, and it only partially does. The examples map usefully onto the category enum (outage→incident, campaign launch→launch, external algorithm update→external) and 'happened on a date' mirrors occurred_on, but the required title parameter is never explained, and the overlapping identity params (client/client_id, project/project_id, task_id) are left to the agent to disambiguate.

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 action and resource ('Record something significant that happened on a date') backed by concrete examples (budget change, site migration, outage). It also explains the underlying purpose ('overlaid on analytics later so the data can be read correctly'), which goes well beyond a tautology. However, it never explicitly distinguishes itself from sibling logging tools like log_project_issue or log_project_decision, so the differentiation is implicit rather than stated.

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

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

Provides a clear positive trigger condition: 'Log one whenever you make or observe a change that will show up in future numbers.' This tells an agent when to act without ambiguity. It lacks the other half of strong guidance — explicit when-not-to-use and named alternatives — 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 only say readOnlyHint=false and destructiveHint=false. The description adds meaningful behavioral context: the issue is persisted so it survives dismissal, and the tool also creates a task to fix it. It does not disclose every side effect, but it goes beyond 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?

The description is only two sentences and front-loaded with the core purpose. The examples and the detail/task guidance earn their place, though the second sentence packs in a lot and could be slightly more structured.

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 11-parameter tool with no output schema, the description explains the key scenario and the most important action, but it does not clarify many optional parameters, the mechanics of task creation, or what the agent can expect after invocation. It is adequate but leaves notable gaps.

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

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

Schema description coverage is 64%, and the description adds useful semantics for detail ('Paste the exact wording ... so it survives') and hints at task creation. However, several parameters like url, client, source, severity, and client_id are left to the schema alone, and the description does not fully 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?

The description states a specific verb and resource: 'Record a significant issue you discovered while working a project.' It also gives concrete examples (Google Ads policy warning, GA4 tagging error, broken feed) and clarifies this is for discovered issues, distinguishing it from generic project event logging.

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 clearly explains when to use the tool: for significant issues, especially those living in external systems that may disappear once dismissed. It also gives a concrete workflow instruction: paste exact wording into detail and create a task to fix it. However, it does not explicitly name alternatives or say when not to use this 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?

Beyond the readOnlyHint=true annotation, the description discloses that memory content is unreviewed, authored by another agent or person, and should be verified against authoritative sources. This is valuable behavioral context that helps the agent handle the returned data safely.

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 compact and front-loaded: it states the action, the trigger condition, and the trust caveat in three short sentences. Every sentence adds information necessary for correct and safe 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?

For a simple one-parameter read tool with no output schema, the description fully covers what the tool does, when to use it, where the id comes from, and how to treat the returned content. 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 description coverage is 100%, and the sole parameter memory_id is already documented as returned by memory_search or memory_save. The description adds no additional parameter semantics beyond 'by id,' 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: reading a single memory from the shared vault by id, including the full body. This clearly distinguishes it from the related memory_search tool, which returns truncated matches, and from memory_save, which writes.

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 'Use after memory_search returns a truncated match,' giving the agent a concrete trigger condition. The reliability warning further guides responsible use by telling the agent not to treat recalled content as instructions.

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 provide readOnlyHint=false and destructiveHint=false. The description adds meaningful behavioral context beyond those: memory is unreviewed context, readers must verify claims, nothing is visible outside the workspace, and memory persists across harnesses. This is valuable transparency not available in structured metadata.

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 with no filler. It front-loads the core action, then gives use cases, scoping guidance, a trust caveat, and alternatives—each sentence earns its place.

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

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

Given the tool has 9 parameters, no output schema, and is a cross-agent write operation, the description covers the essential context: what is stored, who consumes it, how to scope it, the trust boundary, and when to use a different tool. Nothing critical an agent needs to invoke it correctly is missing.

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

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

Schema coverage is high at 89%, so the schema itself documents most parameters. The description adds extra meaning by explaining how to scope memories ('Scope it to a client and, where relevant, a project or task') and by tying the handoff concept to harness and cross-agent visibility, which helps an agent interpret fields like client, project_id, task_id, source_harness, and target_harness.

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

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

The description clearly states the verb and resource: 'Write a durable note to the shared Tango memory vault.' It also distinguishes itself from siblings by emphasizing persistence across harnesses and sessions, and explicitly names alternatives (update_client_context, log_project_decision) for different use cases.

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

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

The description gives concrete when-to-use scenarios: handoffs between tools, context that outlives one session, and anything a teammate would need to re-derive. It also provides explicit exclusions by directing durable team standards to update_client_context or log_project_decision 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?

The annotations already establish readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context beyond that: result bodies are truncated, and recalled memories are unreviewed context that must be treated as data to verify, not instructions to follow. This is meaningful guidance for an agent deciding how to trust results.

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 three tight sentences with no filler. It front-loads the core purpose, then lists the search dimensions, then provides necessary usage caveats. Every sentence earns its place.

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

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

For a read-only search tool, the description covers the essential context: what is searched, how to filter, the truncation behavior, and the trust boundary on results. There is no output schema, so a bit more detail about the returned fields would be beneficial, but the existing caveats are sufficient for safe invocation.

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

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

Schema description coverage is 71%, so the schema documents most parameters. The description adds a helpful mapping from 'workspace' to client/client_id and from 'harness' to target_harness, but it does not add detail about the undocumented client_id and project_id formats beyond what the schema already provides.

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 ('Find') and names a concrete resource ('durable notes and handoffs another agent left behind') with scope ('across harnesses'). It clearly differentiates the tool from memory_read by noting that bodies are truncated and full text requires memory_read.

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

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

The description provides clear context for when to use this tool: searching shared memory for durable notes and handoffs. It names the alternative memory_read when full bodies are needed, though it does not explicitly enumerate exclusions or compare against other search-like siblings such as search_tasks.

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 indicate this is a write operation and not destructive. The description adds meaningful behavior beyond annotations: it releases the lease, returns the task to the queue, and preserves a checkpoint for clean resumption. No contradiction with the annotations was found.

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

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

The description is two concise sentences, front-loads the primary action, and includes the most important side effects without filler. Every sentence earns its place.

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

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

The description provides enough context to invoke the tool correctly: purpose, checkpoint contents, lease release, and queue return are all stated, while parameter details live in the schema. It does not describe the return value or explicitly point to resume_task as the follow-up, but those are not required for correct invocation.

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

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

The input schema already documents all three parameters with 100% coverage: task_id, checkpoint, and note. The description reinforces that the checkpoint is a structured working state, but it does not add new parameter-level meaning, so the baseline score 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?

The description uses a specific verb and resource: 'Pause work on a task and save a structured checkpoint.' It also clarifies the outcome—releasing the lease and returning the task to the queue—which distinguishes pause_task from siblings like resume_task, complete_task, and claim_task.

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 context for when to use the tool: pausing work so another coworker can resume cleanly, with lease release and queue return. It does not explicitly name alternative tools or state when not to use it, which prevents a 5 but the intended use is still 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; the description confirms this with 'Read-only: nothing is recorded' and adds substantial beyond-annotation behavior: the exact signing protocol (Ed25519 over ASCII bytes, base64url), the signature format `<protected_header>..<signature>`, and the fields that must be passed through verbatim. No contradiction with 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?

Four sentences with zero filler, and the highest-value facts come first: audience, then return values, then signing steps, then the read-only guarantee. Every sentence carries a distinct piece of the calling protocol.

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 bears the full burden of explaining return values, and it names all three outputs plus the exact downstream complete_task parameters. Minor gaps — where worker_kid originates and the precise JSON shape of the returned object — keep it from a perfect 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% (task_id and summary have prose; outcome has only an enum; acting_worker_id and evidence_artifact_ids have none), yet the description adds no per-parameter guidance and never mentions acting_worker_id or evidence_artifact_ids at all. The workflow context implies that task_id/outcome/summary feed the payload, but with low coverage the burden to compensate was higher than what this description delivers.

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 (prepare) and resource (a signable completion payload), and is immediately concrete: it returns the JCS-canonicalized payload, JWS protected header, and signing input. The workflow framing around complete_task distinguishes preparation from the actual submission step, so an agent can tell the two apart.

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?

Opens with an explicit audience constraint ('Attested workers only (you hold your own Ed25519 private key)') and closes with an explicit exclusion: 'Delegated workers do not need this — Tango signs for them.' It also routes the follow-up step to complete_task with exact field names, so when to use it versus the alternative path is fully 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?

The annotations already signal readOnlyHint=false and destructiveHint=false. The description adds meaningful behavioral context: atomicity of the claim, lease semantics ('Returns the leased task'), and a limitation ('call get_task next for the full context bundle'). This goes beyond the annotations without contradicting them.

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 workflow step, then the core behavior, then the next-step instruction. Every clause earns its place; there is no filler or repetition.

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

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

Given the tool has no output schema and only two optional parameters, the description appropriately explains what the call returns and what to do next. It does not cover failure cases or concurrency behavior, but for its complexity level the operation is adequately specified for an agent to invoke 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 description coverage is 100%, so the schema fully documents both worker_id and lease_seconds. The description adds no parameter-specific detail beyond the schema; this is the expected baseline when the schema carries 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?

States a specific verb ('claim') and resource ('next queued task matching one of the caller's registered workers'). It conveys the atomic behavior and return value. However, it does not explicitly distinguish itself from the sibling tool claim_task, which is a very close name and likely overlapping purpose, so it misses the top score for sibling differentiation.

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

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

Provides clear procedural context ('Step 3 of the Tango working agreement (own it)') and prescribes the immediately following action ('call get_task next...'). This is strong usage guidance, though it does not name alternatives such as claim_task or state when not to use this 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?

The annotations already declare readOnlyHint=true and destructiveHint=false. The description adds meaningful behavioral context beyond that: the view is 'pre-approved', the query is read-only, and access is strictly limited to what the view exposes. This helps an agent understand safety and scope 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 with no filler. The purpose leads, the prerequisite workflow follows, and the key constraint is stated last. Every sentence earns its place and the description remains compact despite covering purpose, usage, and limitations.

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

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

For a tool with seven parameters, a nested filters object, no output schema, and a dependency on list_context_sources, the description provides enough context to call it correctly: it identifies the prerequisite, explains the central 'view' concept, and sets expectations on scope. It could optionally mention how results are returned or clarify the relationship between `client`, `client_id`, and `source`, but the description is largely complete for effective use.

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 71%, but the description adds important semantic context not fully captured by individual parameter descriptions: the concept of a 'view key' and 'filterable columns' directly clarifies the `view` and `filters` parameters. It also explains that `source` may be needed when keys collide, reinforcing the schema. A small amount of additional per-parameter elaboration (especially for `limit`) would make it stronger, but the description substantially aids interpretation.

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

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

The description clearly states the operation: running one pre-approved, read-only view against an external data source. It distinguishes itself from siblings by explicitly referencing list_context_sources as the companion tool for discovering view keys, and by emphasizing the read-only, scoped nature of the query.

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

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

The description provides explicit workflow guidance: call list_context_sources first to discover available view keys and filterable columns. It also states a clear limitation ('You cannot reach anything the view does not expose'), which helps an agent decide when this tool is appropriate. It stops short of explicitly listing when not to use it or naming alternative query tools, so it does not earn 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?

The description reveals server-side verification of proof of possession, a public publication URL (/.well-known/tango-worker-keys/{worker_id}.json), and rejection of private-key submissions. These behaviors go well beyond the annotations (readOnlyHint=false, destructiveHint=false) without contradicting them.

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 dense sentences, each carrying distinct information: flow position, required payload, verification/publication behavior, and mode-selection guidance. It is front-loaded with the most important constraint ('Submit ONLY your ... PUBLIC JWK').

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?

It covers the main protocol flow, security constraints, and the choice between attested and delegated mode, which matters for correct invocation. It omits a description of return responses or error cases, but there is no output schema and the parameter schema fills most remaining 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?

The description reinforces that public_key_jwk must be public-only (no private key) and ties signed_nonce to the request_key_challenge nonce, which is useful beyond the schema's 'base64url Ed25519 signature' text. Worker_id is only implied through the URL, but schema coverage is already 75%, so the description need not restate every field.

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 identifies a concrete action ('register'), a resource ('my public signing key'), and its role in a larger flow ('Step 2 of attested mode'). It distinguishes itself from sibling key tools by specifying the public JWK submission and proof-of-possession verification, so an agent won't confuse it with issue/rotate/revoke.

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 explicitly frames when the tool applies ('Step 2 of attested mode') and gives a when-not condition: 'Only register an attested key if you can persist the private key across sessions; otherwise use delegated mode'. It also warns against private-key submissions, providing a clear safety boundary.

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