TaScan

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

The description discloses meaningful runtime behavior beyond annotations: it explains that each completed 'number' set 'stores its value and timestamp, giving per-set timing for progression tracking' and clarifies response_type semantics. Annotations only say the call is not read-only and not destructive; the description adds the important data-capture behavior. It doesn't cover idempotency or bulk edge cases, but the safety profile is already covered.

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

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

Three sentences, front-loaded with the core action, then the typed-response taxonomy, then a worked example. No filler; the example earns its place by making the response_type semantics concrete.

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

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

With only two required parameters and a fully described schema, the description plus schema is enough to construct a correct call: task_id, subtasks with title, optional sort_order/description/response_type/response_config. It lacks an explicit note about the return value or bulk limits, but no output schema exists and the interactions are simple, so this is a minor gap.

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

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

Schema has 100% coverage with descriptions for task_id and subtasks, so baseline is 3. The description adds value by giving concrete examples of response_type values ('number' for per-set data like reps/weight/distance, 'choice' for options) and illustrating the set-logging scenario, which goes slightly beyond the bare schema.

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

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

States a clear verb+resource: 'Add one or more subtasks to a task (bulk)' – specific and distinct from tascan_add_tasks and other sibling mutation tools. It also names the key domain feature (typed responses), further narrowing the purpose.

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

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

Provides a concrete use case (set-logging with Bench Press / Set 1/2/3 and response_type 'number') that tells an agent when bulk subtask creation is the right pattern. It doesn't explicitly state when not to use alternatives like tascan_update_subtask or tascan_delete_subtask, but gives clear context for the primary scenario.

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 cover the safety profile (readOnlyHint=false, destructiveHint=false), and the description adds genuinely non-structured context: a permission gate with a specific refusal outcome and a conditional scope rule for CODE:/SHELL: titles. It does not explain partial-failure behavior for bulk creation, which is the main remaining behavioral unknown.

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?

Purpose is front-loaded in the first sentence and each following sentence carries routing or permission information. The response_type paragraph is verbose and overlaps the enum description, but nothing is purely 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 bulk mutation with no output schema, the description never says what a successful call returns (created task IDs? per-item errors?) or how partial failures in the tasks array are handled. Permissions and response_type are well covered, but that gap is material for retry logic alongside an idempotency_key.

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's own response_type description already enumerates text/photo/checkbox with the same examples, so the description's "IMPORTANT: Set response_type correctly" block largely restates structured data rather than adding new semantics. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ("Add one or more tasks to an event (task list)") and adds scope via "Supports bulk creation." It differentiates from the dispatch sibling by name, but does not distinguish itself from tascan_add_subtasks, which an agent could easily confuse with bulk task 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?

Gives clear routing guidance ("To dispatch tasks to an AI agent use tascan_dispatch_to_agent instead") plus a precondition: writing to an agent inbox requires agent:dispatch / agent:dispatch:code and the call is refused otherwise. Missing only guidance versus tascan_add_subtasks and tascan_create_event.

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 idempotent, non-destructive, and readOnlyHint false. The description adds valuable context by disclosing that server_side_ai triggers a POST to the Anthropic API, explaining why the tool is not purely read-only and highlighting potential external side effects. No contradiction with annotations 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?

Three sentences each contribute useful information: protocol context, retrieval details, and the server-side AI capability. It is efficient, though the protocol framing at the start delays the core verb; overall it is appropriately sized and 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?

With no output schema, the description gives a reasonable summary of the returned data (worker info, message thread, project history, similar issues) and explains the behavior for both default and server_side_ai modes. It covers the tool's complexity well, though exact response formatting is not detailed.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the server_side_ai parameter's behavior (raw data vs. direct AI analysis) but does not introduce new semantic meaning 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 explicitly states the tool retrieves full issue context, listing specific data types (worker info, message thread, project history, similar issues), and also mentions the server-side AI analysis option. It clearly distinguishes itself from sibling tools like list_issues or auto_resolve by framing it as Step 1 of the Closed-Loop Autonomous Operations Protocol.

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

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

The description provides usage context by labeling it as 'Step 1 of the Closed-Loop Autonomous Operations Protocol' and states its intended purpose ('Use this data to reason about the root cause and generate a remediation plan'). However, it does not explicitly mention alternatives or when not to use this tool, so it lacks full exclusion guidance.

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

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

Goes well beyond the annotations by disclosing hard limits (content ≤32 KB, no data: URL, only text turns), observable side effects (message_count and preview update, GET reads back in order), and an audit guarantee (a receipted ledger event with hashed content is written first). None of this is derivable from the schema or the write-tier hints, and it does not conflict with readOnlyHint=false / idempotentHint=false / destructiveHint=false.

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 action is front-loaded and the dense single sentence packs the endpoint, constraints, side effects, and receipt without filler. The colon/semicolon chaining makes it harder to scan than it needs to be, and 'the way the portal helper saves each exchange' is slightly ornamental, but nothing is wasted.

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

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

With no output schema, the description adequately covers what changes and how results are observed (message_count/preview, GET readback, ledger receipt), which is what an agent needs before writing. It leaves unstated whether the call returns the created message objects or ids, and it does not name the permission needed as an admin, so it is strong but not exhaustive.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds semantics the schema lacks by constraining content to plain text of at most 32 KB with no data: URL and by implying the 1-2 turn cap and ordering. It does not fully specify role ordering rules (e.g., whether a lone assistant turn is valid), so it stops short of a 5.

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

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

States a specific verb and resource (append 1-2 text turns to a chat thread) plus scope details (admin of your org, POST endpoint) that let an agent distinguish it from thread-creating (tascan_save_chat_thread), thread-listing, and thread-deleting siblings. The 'turns' framing and the reference to the portal helper make the intent unmistakable.

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

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

Usage is implied through 'the way the portal helper saves each exchange' and the thread_id pointer to tascan_list_chat_threads / tascan_save_chat_thread, so an agent can infer it persists an exchange into an existing thread. However, there is no explicit when-to-use statement or exclusion (e.g., do not use for a new thread, do not use for >2 turns), so the guidance remains inferential.

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 non-read-only, idempotent, non-destructive, closed-world behavior; the description adds useful behavioral context: org ownership constraint, null clearing, and write-tier classification. It does not add permission details or return behavior, but the annotation coverage lowers the burden.

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

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

Front-loads the core action and mode distinctions in one dense sentence, then adds two short constraints. Parenthetical endpoint details are compact and no sentence is wasted.

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

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

Covers both operational modes, clearing behavior, org ownership, and write-tier semantics for a tool with no output schema. Some schema gaps remain around conditional requiredness and return behavior, but the description is substantially 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?

With 0% schema description coverage, the description compensates well by explaining qr_style_id null-clears, target+id for item assignment, and target purpose with purpose values. It still leaves id requiredness for non-purpose targets and exact purpose enum values implicit.

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: applying a saved QR look, with explicit distinction between item-level application and purpose-level defaulting. It also names the relevant targets, so the agent can distinguish it from save_qr_style, list_qr_styles, and generate_qr.

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

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

Gives clear usage contexts: project/list/task/site with id, or purpose with purpose values. It does not explicitly compare with sibling tools or state exclusions, but the target-based routing is concrete enough for correct selection.

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 non-readOnly, non-idempotent, non-destructive operation. The description adds that it 'adds all template tasks', confirming an additive effect, but it does not disclose potential duplication on re-application or error behavior. Little is added 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 a single, concise sentence that is front-loaded with the verb and clearly states the action and target. No unnecessary words or repetitions.

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 mutation with annotations and full schema coverage, the description is mostly complete. It clearly communicates the core functionality but could add context about whether existing tasks are preserved or if applying twice duplicates tasks. However, the non-destructive hint partially covers this.

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 (list_id and template_slug) with examples in the template_slug description. The tool description reinforces their role but does not add additional semantic meaning beyond what the schema already provides. Baseline of 3 is appropriate given 100% 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 clearly states the action 'apply' with a specific resource 'pre-built template to a task list' and the outcome 'adding all template tasks'. This distinguishes it from sibling tools like tascan_add_tasks, which focus on adding tasks individually rather than through a template.

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 the tool is used when a template_slug is available, but it does not explicitly state when to use this tool over alternatives (e.g., tascan_add_tasks) or mention any prerequisites like listing templates first. Usage is inferred but not directly guided.

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

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

The description adds behavioral context beyond the annotations by explaining that the model uses 'the asset's full assessment history in context' and returns specific outputs (delta score, defects, wear indicators, recommendations, trajectory). It does not contradict the annotations (readOnlyHint=false, destructiveHint=false) and provides meaningful insight into how the tool operates.

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

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

The description is two sentences long, with the first sentence front-loading the core purpose and the second efficiently describing the return values and behavioral context. There is no redundant or unnecessary information; every phrase 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?

With no output schema, the description carries the burden of explaining return values, which it does thoroughly (delta score, defects, wear indicators, recommendations, trajectory). It also explains the use of historical context. However, it does not address edge cases (e.g., no previous assessment) or response format specifics, leaving a small gap. Overall, it is nearly complete for a tool of this complexity.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the input schema. The description adds some contextual relationship (e.g., history context for asset_id) but does not provide additional parameter-level details beyond what the schema offers, resulting in a baseline score of 3.

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

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

The description clearly states the tool's function: 'Run an AI condition assessment of an asset from a photo.' It goes beyond a simple statement by specifying unique outputs like 'Condition Delta Score' and 'degradation trajectory,' which distinguishes it from sibling tools like tascan_condition_history or tascan_recommend_fix.

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 the tool: when you need a photo-based AI condition assessment with historical context. It implies the use case but does not explicitly name alternatives or exclusions, which prevents a 5. However, the context 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?

The description adds behavioral context beyond the annotations by detailing the server-side AI analysis, creation of a task list, and dispatch to a worker, including physical-world instruction delivery. This complements the annotations (readOnlyHint=false, destructiveHint=false) and provides a clear picture of the multi-step side effects 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?

The description is three sentences and not overly long, but it contains marketing-like phrasing such as 'FULL Closed-Loop Autonomous Operations Protocol' and a patent claim reference that may be unnecessary for practical understanding. The core behavior is present but could be stated more directly and front-loaded.

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

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

There is no output schema, yet the description does not explain what the tool returns or the outcome after dispatch, such as a confirmation, task list, or status update. It also omits prerequisites like the issue being in a resolvable state, leaving the agent without a full understanding of result handling.

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 covers issue_id with 100% description coverage, so the schema documents the parameter adequately. The description does not add extra meaning about the parameter format, source, or constraints, leaving the baseline score of 3 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 indicates the tool performs a full autonomous resolution workflow: analyzing the issue, generating remediation tasks, creating a task list, and dispatching to a worker. This goes beyond simply saying 'auto-resolve' and distinguishes it from sibling tools like tascan_analyze_issue or tascan_add_tasks by emphasizing the complete closed-loop behavior.

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

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

The description implies usage when full autonomous resolution without human intervention is desired, but it does not explicitly state when to use this tool versus alternatives. It lacks exclusions or a direct comparison with sibling tools, such as suggesting tascan_analyze_issue for only analysis or tascan_dispatch_instruction for only dispatch.

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 annotations, the description discloses that non-pending rows are refused with 409 and that sent messages cannot be recalled. This adds meaningful behavioral context to the destructiveHint and idempotentHint annotations. It does not contradict any 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 concise sentences deliver the action, the precondition, and the key error condition without repetition or filler. The most important 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 single-parameter mutation with no output schema, the description covers the valid target state, the invalid states, the error behavior, and the fundamental limitation. Combined with the annotations, an agent has everything needed to invoke the tool correctly.

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

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

Schema coverage is 100% and the single id parameter is already fully described as the scheduled_sms row id from tascan_schedule_sms / tascan_list_scheduled_sms. The description adds no additional parameter-level meaning, so the baseline score 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 names the exact operation (cancel) and the target resource (a scheduled text/SMS row) and specifies the relevant state (pending). This clearly distinguishes it from scheduling, sending, and generic deletion tools 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?

It states an explicit precondition — the text must be pending — and explicit forbidden states: sending, sent, failed, or cancelled. It also makes the hard limitation clear with 'a sent text cannot be recalled,' so an agent knows exactly when to use this tool and when not to.

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?

Without this description, the annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false) would leave behavior opaque. The description fills the gap richly: it explains the admission check, the refusal reasons (seat_not_yours, not_routable), the 404-vs-403 security policy, the required permission (agent:dispatch:code), and the fact that it does not itself mint a receipt. This is exactly the context annotations cannot carry.

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

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

The description is dense but well-structured, with the core claim operation and admission rule front-loaded, followed by refusal semantics and permission requirements. Every clause carries specific information. It is slightly long for a tool definition, but the density is justified by the non-obvious behavior being explained.

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's complexity—a state-mutating claim operation with strict identity and routing rules—the description covers entry criteria, failure modes, permissions, and the relationship to subsequent tools. No output schema exists, but the description clarifies that the tool 'opens the run' and that receipts come later, which is sufficient context 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%, so the schema already documents each parameter clearly (agent_id prefix rule for 'instance', TTL range for 'ttl_seconds', source of task_id). The description reinforces the instance requirement but adds no syntax or format details beyond what the schema provides. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description opens with a specific verb+resource ('Claim a fan-out seat task as a LOCAL subagent run') and immediately names the mechanism and sibling relationship ('POST /runs/claim -> claim_agent_run(p_runner='local')'). It distinguishes itself from adjacent tools like tascan_create_fanout and tascan_finish_run by describing exactly which phase of the workflow it occupies.

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

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

Explicit conditions for invocation are given: only admitted when the instance prefix matches the seat's coord.agent_id, never for cloud (research) seats. It also directs the reader to tascan_heartbeat_run for extending leases and tascan_finish_run for completion, so the agent knows what to use instead.

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

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

Annotations only establish write/non-destructive/non-idempotent. The description goes well beyond: all-or-nothing single transaction with rollback semantics, automatic next project number, and default naming convention. These are behavioral facts the annotations cannot convey.

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

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

Front-loaded with the core action and the copied/not-copied distinction, then the naming and transaction guarantees. The enumeration is dense but every clause carries distinct information; only the tier label at the end is marginal.

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

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

For a 2-parameter tool with a well-documented schema and no output schema, the description covers scope, side effects, defaults, and atomicity. It does not say what identifier or object the caller receives back, which would close the last gap.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the default naming and the fact the copy receives the next project number, though the name default is largely duplicated from the schema's own 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?

States a specific verb ('Duplicate'), resource ('a project's STRUCTURE'), and endpoint, and immediately clarifies it copies structure rather than creating a fresh project. An agent can distinguish it from create_project or apply_template without opening either schema.

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

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

Explicit about what is and isn't copied ('task lists, not a work order's own lists', 'tasks, never coordination cards', 'nothing that happened is copied'), which effectively tells an agent when this tool fits. It stops short of naming an alternative tool for the opposite need, so not a 5.

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

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

Annotations already indicate a non-read-only, non-idempotent operation. The description adds valuable behavioral detail beyond this: each completion is timestamped, per-set durations are derivable from consecutive completions, and the returned progress includes the all_subtasks_complete flag. This helps the agent understand the timing semantics and downstream implications.

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 focused sentences with no wasted words. The core action is first, then the optional parameter behavior, then progress/return behavior and the related parent-completion step. Important operational details are front-loaded.

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

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

The description adequately covers the operation's purpose, optional behavior, return key, and next action. While an output schema is absent, the description provides the most relevant return information (all_subtasks_complete and timestamping). Some details like error behavior or what happens when all_subtasks_complete is false are not spelled out, but are reasonably 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?

Schema coverage is 100%, so the schema already documents all parameters. However, the description enriches response_value by explaining its purpose with a concrete example ('weight or reps') and indicating it applies to number/text/choice subtasks. This goes beyond what the schema alone communicates.

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 specific action ('complete a subtask') and the optional response_value for typed data. It also distinguishes the tool from tascan_complete_task by explicitly mentioning that completing the parent task is a separate step once all subtasks are complete.

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

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

The description provides clear usage context: use this tool to complete a subtask and optionally record a typed response value. It also gives explicit guidance on the next step after completion (calling tascan_complete_task when all_subtasks_complete is true), which is a direct alternative-routing instruction.

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

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

Annotations already declare this is a non-readonly, non-idempotent, non-destructive, closed-world write; the description goes far beyond by naming the exact 403 error codes (worker_not_key_owner, on_behalf_requires_owner_key), the permission tiers required, and the fact that actor and worker are both recorded on completion. None of this repeats the structured data and it is exactly the behavioral context needed to avoid a silent failure.

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 core action plus side effects are front-loaded, then the exclusion rule, then the key-tier rules – a sensible order. It is a single dense paragraph with heavy jargon, and a break between 'what it does' and 'authorization rules' would improve scanability, but every sentence carries information an agent needs.

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

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

For a write tool with annotations, full schema coverage, and no output schema, the definition covers side effects, authorization, and refusal modes well. It says nothing about re-completion of an already-completed task despite idempotentHint=false, and gives no hint of the returned handle, which is a minor remaining gap.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning about the two most ambiguous parameters: worker_id must be omitted or be the key's own worker for an agent key, while on_behalf_of requires an owner/admin-tier root key and is recorded separately. That interpretation is not derivable from the schema alone, so a 4 is warranted.

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 ('Complete an ORDINARY task'), plus concrete side effects ('Inserts a completion record and timer event'). It sharply separates itself from coordination-cycle work (CODE:/REVIEW: builds, decisions, questions, integrations, parked cards), which is the main confusion axis. It never distinguishes itself from the close sibling tascan_complete_subtask, so a small gap remains.

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 excluded case ('Coordination-cycle tasks ... are refused with 403') and says who handles them instead ('builds and reviews are completed by their runner, decisions only by the human on the worker page'). It also spells out which key tiers may call it, giving the agent a clear when/when-not decision rule with named alternatives.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is clear. The description adds value by detailing the output: score trend, grades, deltas, findings, and assessor. This goes beyond the annotations by describing the return structure. It does not mention edge cases (e.g., empty history) or response limits, but the annotations cover the core behavior adequately.

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 zero filler. The first sentence is front-loaded with the verb and resource, then lists specifics. Every word earns its place; no redundancy or 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?

With one parameter and no output schema, the description covers the core purpose and return contents. However, it lacks details on response ordering (chronological?), pagination (if many assessments), and error handling for missing assets. The annotations (openWorldHint=false) hint at limited results, but completeness is adequate but not fully fleshed out.

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 has one parameter (asset_id) with description 'Asset ID', and schema coverage is 100%. The description does not add type or format details for asset_id (e.g., is it a UUID or serial number?), but the phrase 'per-serial-number condition ledger' weakly implies asset_id corresponds to a serial number. This adds marginal meaning beyond the schema, keeping the score at baseline 3.

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

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

The description uses a specific verb ('Get') and explicitly identifies the resource ('asset's longitudinal condition history'), detailing what it returns: score trend, assessments with grade, delta, findings, and assessor. It distinguishes itself from sibling tools like tascan_get_scan_history and tascan_get_report by focusing on condition history, and the 'per-serial-number condition ledger' clarifies scope by serial number.

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 by specifying 'longitudinal condition history' and listing the contents (grades, trends, findings), so an agent knows to use this when needing historical condition data. However, it does not explicitly state when not to use it or name alternative tools (e.g., tascan_get_report for summaries). The context is strong enough for a 4.

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

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

Goes well beyond the annotations: it discloses that every action records a signed control completion as the system worker of this org (never another org identity), the exact idempotency replay semantics including the subtle 'replayed resume after a later pause stays paused' case, the fanout_closed refusal condition, and the required agent:dispatch:code permission. These are precisely the destructive/auth/replay details an agent needs.

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

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

Purpose and action semantics are front-loaded, and each sentence carries information (refusals, replay, auth, identity). It is dense and somewhat run-on in the middle, but there is little waste for the amount of behavior it must convey.

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 no output schema, the description explains observable outcomes (replayed:true on replay, enumerated refusal reasons like fanout_closed and not_synthesizing) and the permission requirement. An agent has everything needed to invoke and interpret results correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning over the terse schema: it explains what each enum action does to seats and tasks, clarifies exclude_seats as 'named exclude_seats' for close_barrier, and elaborates idempotency_key replay behavior. The added semantics exceed what the schema documents.

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

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

States a specific verb+resource ('Control a running fan-out') with the underlying endpoint, and enumerates exactly what each of the five actions does (pause holds seats, resume releases, cancel supersedes, close_barrier forces the synth, retry_synth mints a revision). This clearly distinguishes it from sibling lifecycle tools like create_fanout and get_fanout.

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 per-action conditions for use and explicitly rules out others ('No amend or answer yet'; retry_synth 'refused otherwise' with enumerated refusal reasons). It lacks an explicit routing statement toward siblings, but the action-level conditions are detailed enough for correct invocation.

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

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

Annotations only mark read/write/idempotent/destructive hints; the description far exceeds that by disclosing side effects (minting tasks, parking cycles, revision limits), duplicate-prevention behavior, preflight limitations (unchecked[]), and error codes. No statement contradicts 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 front-loaded with the core action, but it is a single extremely dense paragraph with long parenthetical enumerations of validation codes and edge cases. It earns its place content-wise, yet poor visual structure makes it harder for an agent to parse quickly.

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 no output schema, the description covers side effects, preflight validation, failure modes, duplicate handling, revision/review behavior, optional panels, permissions, and tracking. A caller has the information needed to decide on dry_run versus a real create and to interpret the cycle afterward.

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 applies; the description largely repeats semantics already present in the schema (kind=review_only, dry_run, artifact_bytes, idempotency_key). It adds protocol-level context like build_ref sha256 and DUPLICATE root_id, but not enough new per-parameter meaning to rise above the high-coverage baseline.

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

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

Opening sentence names a specific verb and resource: 'Start an unattended build-review-decide cycle' and immediately spells out concrete behavior (queues T1 CODE:/T2 REVIEW:). This clearly distinguishes it from the many create_* and list_* siblings; it is unmistakably the cycle-creation 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 invocation context: dry_run performs a PREFLIGHT-only validation, a real run queues multiple tasks, and tracking is routed to tascan_get_cycle_report(root_id). It also states the required permission (REQUIRES agent:dispatch:code), though it does not explicitly enumerate when-not-to-use alternatives.

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

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

Annotations already declare this is a non-idempotent, non-destructive write, so the description adds genuine value with the hard constraint 'team_mode and multi_instance cannot both be true' and semantic explanations of what each mode does (shared vs. isolated copies). It does not mention permission requirements tied to access_level or agent_assignee, which would have pushed this higher.

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

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

Three sentences, front-loaded with the core action, then the two important flags, then the constraint. No filler and nothing restated from the title alone.

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

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

For an 8-parameter creation tool with full schema descriptions and no output schema, the description covers the ambiguous behavioral choices an agent must get right. The remaining gaps (access_level semantics, assignment side effects) are documented in the schema, so 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 coverage is 100%, so the baseline is 3; the description earns above baseline by clarifying that multi_instance means each worker gets an isolated copy and naming real scenarios, plus the mutual-exclusivity rule the schema does not state. It still leaves access_level (open/assigned/secured) and agent_assignee meaning entirely to the schema.

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

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

States a specific verb and resource ('Create a new event') and immediately disambiguates the domain term by glossing 'event' as '(task list) within a project'. An agent can distinguish this from tascan_create_project, tascan_update_event, and tascan_list_events without opening any schema.

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

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

Gives concrete usage guidance for the two mode flags, including when multi_instance is the right choice ('surveys, onboarding, info collection'). It stops short of naming alternative tools for related intents (e.g., tascan_apply_template or tascan_create_cycle), so it is clear but not exhaustively routable.

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

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

Annotations only declare readOnlyHint=false, openWorldHint=true, idempotentHint=false and destructiveHint=false, but the description adds substantial non-obvious behavior: budget is consumed BEFORE create, refusals visible only to the DB still consume units, the specific failure codes (cap_below_plan, fanout_ceiling_unset, over_ceiling, idempotency_body_mismatch), the 24h replay window, and that every seat, synth and roll-up leaves a signed completion.

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?

It is a dense single paragraph, but it is front-loaded with the core action and scoping constraint and nearly every sentence carries operational payload (auth, budget, failure codes, dry_run, idempotency, tracking). A long run of parenthetical failure codes makes it slightly hard to scan, keeping it just short of 5.

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

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

For a 13-parameter, nested-object, no-output-schema tool this covers the operational essentials: auth prerequisite, budget side effects, validation path, failure modes, idempotency and where to track the result. The one gap is that the successful-create return payload is only partially implied (fanout_id appears only in the idempotency replay branch), so an agent cannot fully anticipate the normal response without an output 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 already 100%, so the baseline is 3, but the description adds genuine semantics beyond the schema for dry_run (returns dry_run/plan_sha256/seats/problems without spending budget), idempotency_key behavior, and the budget-consumption path around cap. It does not restate the remaining nested seat/synth/seat_defaults fields, which the schema already handles well.

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

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

States a specific verb and resource ('Create a fan-out: 1-30 seats ... plus one synthesizer under ONE cycle root') and pins the endpoint POST /coord/fanouts. It also distinguishes the artifact from its siblings by naming the tracking tool (tascan_get_fanout) and clarifying what the operation does NOT do relative to the wider coordinator tree.

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

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

Gives clear conditions for using dry_run as a preflight and for supplying idempotency_key, and states the required auth scope (agent:dispatch:code, with the note that an admin session has none). It does not explicitly contrast against sibling creation tools such as tascan_create_cycle or explain when a fan-out is preferred over delegating individual tasks, so it stops short of full 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?

It goes well beyond the annotations by revealing non-obvious behavior: auto lines come only from VERIFIED work, lists with no completions are skipped, billing is quarter-hour from first to last verified completion, and single-list invoices also mint a linked Service Report. Annotations only supply read/destructive/idempotent hints, so the description carries the behavioral burden and succeeds.

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

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

Three sentences, front-loaded with the core purpose, and every clause earns its place — including the illustrative line format. It is dense but not padded.

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

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

Despite 17 parameters and no output schema, it names the key decision inputs and the return package (invoice number, totals, url, work billed). The remaining parameter details are already in the schema, so nothing needed for a correct call is missing.

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

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

With schema coverage at 88%, the schema documents individual fields, but the description explains parameter interactions: line_items bypasses auto-billing, project_id/task_list_ids plus hourly_rate or flat_rate_per_list drives generated lines, and attach_service_report behavior is exposed. This adds meaning the schema alone does not convey.

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

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

Opens with an explicit action and resource — 'Create a client invoice and get its shareable link' — and immediately distinguishes the two billing paths. This differentiates it from sibling update/list/request tools even without naming 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 provides explicit conditional guidance for choosing explicit line_items vs project_id/task_list_ids auto-billing, including the rate options. It does not explicitly route to sibling tools such as tascan_update_invoice, so it stops short of full alternative guidance.

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

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

Annotations declare the write/creation safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the description carries a lower burden. It adds genuinely useful behavior beyond annotations: the next P-number is auto-assigned when 'number' is omitted, and a duplicate number is refused with 409. It does not mention auth requirements or the shape of the created object.

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

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

Three tight sentences, front-loaded with the core action and entity role, then the optional-parameter default/conflict behavior, then the external_refs purpose. No redundant restatement of the tool name or 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 write annotations present and no output schema, the description covers the essentials for a create tool: default value behavior, the 409 conflict case, and the semantics of the non-obvious parameter. Missing only the return payload and permission/scope requirements, which are minor gaps for this complexity 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?

Schema description coverage is 100%, so the baseline is 3. The description still adds meaning over the schema for two parameters: it explains that 'number' is optional with a server-assigned default and that 'external_refs' links customer job numbers, an intent not captured in the schema text. That is value beyond what the structured fields 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?

States a specific verb and resource ('Create a new TaScan project') and immediately clarifies the entity's role ('top-level container for events'), which distinguishes it from the sibling tascan_create_event. An agent can tell what this tool produces 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?

Usage context is implied by the 'top-level container for events' framing, which tells the agent this is the parent object to create before events. However, there is no explicit when-to-use statement, no mention of prerequisites (e.g. org membership), and no named alternative, so guidance remains inferred rather than stated.

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

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

Annotations already declare readOnly=false and destructive=false; the description adds meaningful context beyond them: external_key uniqueness causes a 409 refusal, and lat/lng must be sent together. It does not cover permissions or what the response returns, but the core write behavior and failure mode 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?

A single front-loaded sentence that identifies the operation first and then enumerates constraints. It is dense but every clause carries useful information; minor readability cost from cramming all parameters into one sentence.

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 write tool with annotations covering safety, the description covers purpose, required name bounds, paired coordinates, and the key duplicate-refusal behavior. Missing is any mention of authentication requirements or the created object's return shape, but the essentials for invoking it are 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 67%, so the schema carries much of the parameter documentation. The description adds the 409 consequence for duplicate external_key and reinforces lat/lng pairing, but address and client_company are only named with no added semantics.

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

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

States a specific verb and resource: 'Create a site (a job location) in the organization.' The parenthetical defines 'site' and the write framing clearly distinguishes it from read siblings like get_site, list_sites, update_site, and link_site.

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 never says when to choose this tool over alternatives such as list_sites, find, or create_project, nor does it advise checking for an existing site before creating. It provides behavioral constraints (409 on duplicate external_key) but no usage routing.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the agent knows this is a non-destructive write. The description adds the 'taskee' alias and organizational scope, but does not disclose any additional behavioral traits such as validation rules, uniqueness constraints, or required permissions. It is consistent 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 a single focused sentence with no filler, front-loading the operation ('Create') and resource ('worker'). It 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?

While the schema is well-documented and annotations cover the safety profile, the description lacks information about return values (no output schema) or any preconditions. For a simple create operation, this is a minor gap, but it's not fully complete.

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

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

Schema description coverage is 100% (name, email, phone each have descriptions). The description adds no additional meaning beyond the schema, which meets the baseline for high 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 'create' and resource 'worker' (with alias 'taskee'), clearly distinguishing from sibling tools like tascan_update_worker and tascan_list_workers.

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 states what the tool does but gives no explicit guidance on when to use it vs alternatives (e.g., tascan_register_agent may be an alternative for adding agents, or tascan_list_workers to check existing). Usage is implied by the action 'create' but no exclusions are provided.

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 annotations, the description discloses that zones perform GPS-based task-list routing and that enforce_on_list locks the task list to workers inside the radius. It does not cover return values or auth, but annotations already establish this as a non-read-only, non-idempotent mutation. There is no contradiction with the annotations.

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

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

The description is two sentences with the core action first and the enforcement option second. It avoids repeating schema content and contains no filler. The geo.html URL detail is specific but earns its place by clarifying the routing mechanism.

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 22-parameter creation tool, the schema carries most of the burden, and the description supplies the essential zone-routing mental model plus a key behavioral toggle. It does not state the return value, but no output schema exists and the annotations already convey the side-effect profile. This is sufficiently complete for an agent to call the tool correctly.

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

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

The schema already documents all 22 parameters with 100% coverage, so the baseline is high. The description adds meaning by connecting lat/lng/radius/task_list_id to the routing behavior and by explaining why a caller would set enforce_on_list=true. It does not document parameter syntax, but the schema already does that thoroughly.

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 'Create a geofenced work zone,' a clear verb-direct object pair that identifies the resource and distinguishes this from other create_* tools. It then adds the zone's routing behavior, so an agent knows what a zone is for. No ambiguity 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 explains what created zones do and highlights the enforce_on_list behavior, giving useful context. However, it never explicitly says when to use this tool versus update_zone or list_zones, and it offers no exclusions or alternatives. The selection cue is mostly carried by the tool name and the verb 'create.'

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

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

Annotations only supply generic hints (readOnlyHint=false, destructiveHint=false, idempotentHint=false); the description goes far beyond, disclosing TTL defaults and dual clamping (range and grantor expiry), tier subsetting rules, one-time-only raw key display with no server storage (I-10), and cascade revocation on ancestor revoke. This is exactly the behavioral context annotations can't carry.

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

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

The key action is front-loaded and every clause carries substantive policy (scope refusals, TTL clamps, tier subset, one-time key, cascade revoke). It is dense and studded with internal references (I-6, I-10, roadmap #11, migration 249) that add noise for an agent, keeping it from a 5.

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

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

For a non-idempotent, open-world=false mutation with 8 params and no output schema, the description covers the critical unknowns: the raw key is returned exactly once and cannot be retrieved again, plus lifecycle and inheritance behavior. It stops short of describing any other response shape, but nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic context: the scopes array is constrained to read/write with everything else refused by name, and resource_constraints is described as inheriting the parent's projects when omitted. Minor added value beyond the schema's own descriptions.

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

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

Opens with a precise verb+resource+qualifier: 'Mint a time-limited, NARROWER child API key'. This clearly separates it from siblings like tascan_revoke_delegation, tascan_list_delegations, and tascan_dispatch_to_agent, and the API route (POST /delegations) pins the operation.

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

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

States the precondition (requires the delegate permission, owner-only to grant, requires full) and enumerates which scopes are always refused by name (full, agent:dispatch, device:admin, delegate, webhooks:manage), which tells the agent when this tool is applicable. It does not explicitly contrast with a named alternative sibling, 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 already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds real value beyond that: cascading deletion of messages and an audit-side-effect ('a receipted ledger event is written first'), which an agent would not know from the annotations alone.

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

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

One compact sentence with the operation and endpoint front-loaded, followed by the important side-effect. 'The way the Simple page does' is the only filler clause that doesn't inform an agent decision.

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 destructive tool with no output schema and full annotation coverage, the description supplies the missing pieces an agent needs: cascade scope and the ledger write. Only the provenance of thread_id is left unstated.

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 thread_id. The endpoint path implies the parameter is a thread identifier, but there is no guidance on its format or where to source it (e.g. via tascan_list_chat_threads), leaving a gap.

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

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

States a specific verb and resource ('Delete a chat thread and its messages') and even names the underlying endpoint DELETE /chat/threads/:id. That scope statement (thread plus its messages) is enough to distinguish it from tascan_list_chat_threads, tascan_save_chat_thread and the other delete_* 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?

Deletion is implied by the verb, and 'Write tier' hints at the write class of operation, but nothing tells the agent when to prefer this over save_chat_thread or how to obtain a valid thread_id first. Usage is only inferable, not stated.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds critical context: the cascade deletion of tasks/completions and irreversibility, which are not inferable from annotations alone. It doesn't contradict 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 no redundancy. Every phrase adds value: the resource, cascade scope, and irreversibility.

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 simple one-parameter schema and no output schema, the description adequately covers purpose, effect, and irreversible nature. It is complete enough for an agent to select and 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?

The only parameter list_id is fully described in the schema as 'Task list (event) ID to delete' (100% coverage). The description does not add additional parameter-level details, so baseline 3 applies.

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

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

The description clearly states the action (delete), the resource (event/task list), and the scope (all tasks and completions), distinguishing it from sibling delete tools for tasks and projects.

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 lacks explicit 'when to use' guidance or named alternatives, but the scope 'all its tasks and completions' implies a cascading delete, differentiating it from tascan_delete_task. It provides clear context but no exclusions or alternatives.

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

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

Annotations declare destructive=true and idempotent=true, and the description goes well beyond them: it discloses the 409 refusal semantics with counts, the pre-delete receipted audit event, the transactional locking behavior, the 3-second lock timeout with 503/retry, and that the operation is irreversible. None of that is in the structured fields.

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

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

Front-loaded with the core purpose and precondition, and every sentence carries operational information. It is dense — the long second sentence chains several guarantees together — but 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?

For a destructive, irreversible tool with no output schema, the description covers refusal conditions, audit side effects, transaction/locking semantics, retry behavior, and the alternative path. An agent has everything needed to call it safely and interpret failure codes.

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 still adds real meaning: confirm_name must equal the project name exactly (with the 400 confirm_name_mismatch code) and audit notes are stored verbatim in the audit event, which is more than the schema conveys.

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 (delete), resource (project), and a hard precondition (NO history, name confirmation). It also names the sibling alternative (tascan_update_project status archived), so an agent can distinguish it from update/archive paths without opening the schema.

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

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

Explicitly says when the call is refused (409 project_has_history with counts) and what to do instead (archive via tascan_update_project). It also covers the 503 busy retry path and the exact-match requirement for confirm_name, leaving no routing or retry 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?

The description adds that the deletion cascades to completions and is irreversible, which is valuable beyond the annotations' destructiveHint and idempotentHint. It does not contradict the provided annotations and gives clear context about what gets destroyed.

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, direct sentences contain all essential information. The primary action is front-loaded and the irreversibility warning is immediate, with no unnecessary content.

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

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

For a simple destructive operation with one clearly documented parameter, the description sufficiently covers the object being deleted, the cascading effect, and permanence. It does not describe return values, but there is no output schema and the tool's purpose is straightforward.

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 100% schema description coverage, the schema already fully describes the single 'subtask_id' parameter. The description does not add parameter-level details, but none are needed given the schema's clarity.

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 specific action 'Delete a subtask and its completions' with a clear verb and resource, and explicitly notes the irreversible nature. It clearly distinguishes itself from sibing delete_task by targeting subtasks and their associated completions.

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

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

No explicit guidance on when to use this tool instead of alternatives such as tascan_update_subtask or tascan_complete_subtask. The resource name implies the usage, but the description does not state conditions, exclusions, or alternative selection 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 already declare destructiveHint=true and readOnlyHint=false. The description adds value beyond annotations by explicitly noting the cascade effect ('and its completions') and the irreversible nature of the operation, which is not fully captured by the annotations alone.

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

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

The description is two short sentences that immediately state the primary action and a key consequence. Every word is purposeful, with no redundancy or 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?

Given the small parameter surface, the lack of an output schema, and the presence of annotations (destructive, idempotent), the description covers the essential functional context. It explains what is deleted and the irreversible nature, which is sufficient for an agent to invoke it correctly. It could mention edge cases like non-existent tasks, but that is not critical.

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 provides 100% coverage for the single parameter 'task_id' with a clear description. The tool description does not add additional parameter-level context, 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 uses a specific verb 'Delete' with a clear resource 'a specific task and its completions', which distinguishes it from sibling delete tools for events and projects. The additional note that the action is irreversible further clarifies the 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?

The description implicitly indicates when to use this tool (when deleting a task) but does not explicitly contrast with alternatives like deleting events or projects. No exclusions or prerequisites are mentioned, so usage guidance is minimal but not misleading.

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?

Even though annotations already mark the tool as destructive, the description adds meaningful behavioral detail: it is a soft delete (is_active=false), it refuses under certain conditions, and it never hard-deletes. This goes well beyond the annotations and clarifies exactly what 'delete' means.

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

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

The description is compact and front-loaded, with the core operation stated first, followed by the key exception and the correct alternative. Every sentence adds value; 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 single-parameter tool with no output schema, the description covers the operation, the safety guardrail, the alternative path, and the soft-delete behavior. Nothing essential is missing for an agent to decide 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 description coverage is 100%, and the worker_id parameter is already described as 'Worker ID to delete.' The description reinforces that the target is a worker record but does not add significant new semantics beyond the schema, so a baseline score is appropriate.

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

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

The description states a specific action ('Tombstone a worker record'), identifies the exact resource, and clarifies the operation sets is_active=false. It also distinguishes itself from tascan_merge_workers, so an agent can tell which tool handles which scenario.

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 the condition under which the tool refuses ('any task/subtask completions or payments') and names the alternative tool to use in that case (tascan_merge_workers). This gives clear when-to-use and when-not-to-use 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?

Beyond the annotations (which only mark it a non-read, non-destructive write), the description discloses concrete side effects ('Mints a completed task + completion under the Chief of Staff worker and a dispatcher_action ledger event on the root'), the auth requirement ('Requires agent:dispatch'), and a conditional path for kind=deploy. This is exactly the behavioral context the rubric credits.

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 core purpose is front-loaded and every clause earns its place — kinds, side effects, deploy exception, auth. However, it is a single dense multi-clause sentence mixing protocol jargon ('protocol v0.2 D6'), conditional logic, and side effects, which makes parsing slightly harder than a structured two- or three-sentence form would.

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 mutation tool with no output schema, the description covers purpose, kinds, side effects, auth, and the deploy-specific composition. The remaining gaps are the unauthorized branch of the deploy path ('when the root is authorized' but no behavior stated for the unauthorized case) and no indication of the response shape.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds cross-parameter meaning beyond the schema: it ties kind=deploy to evidence.deploy_id as a required conditional, and maps root_id to the cycle root via the endpoint path. The per-parameter descriptions in the schema already carry the format details, but the description frames the kind/evidence interplay.

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 ('Record'), resource ('chief-of-staff dispatcher action on a coordination cycle'), and outcome ('as a receipt'), then enumerates the seven valid kinds. It distinguishes itself from siblings by citing the POST endpoint and explicitly clarifying its relationship to coord_record_integration ('one call that does both records').

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 use — recording dispatcher actions as receipts, with the seven kinds enumerated — and explicitly flags the deploy case where it composes coord_record_integration. However, it does not explicitly state when not to use it or contrast it with the dispatch siblings (tascan_dispatch_instruction, tascan_dispatch_to_agent), 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?

The description discloses the tool's multi-channel effects (thread message, notification, feed update, SMS, task creation), which goes beyond the annotations that only indicate non-read-only and non-destructive. This gives the agent critical context about side effects such as SMS delivery and optional task creation, enhancing behavioral transparency.

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

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

The description is two sentences, front-loaded with the purpose and then detailing the specific channels. Each element earns its place; the channel list is necessary and concise. 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 7-parameter dispatch tool with no output schema, the description covers the main behavior and side effects. It lacks information about return values or error conditions, but these are not typically required in a tool description. The protocol context adds completeness, though it could explicitly mention what happens after dispatch.

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 7 parameters have descriptions in the schema (100% coverage), so the baseline is met. The tool description adds context about remediation_tasks ('optional remediation task list creation') and send_sms ('SMS if phone on file'), but these are also covered in the schema descriptions. The description does not significantly clarify parameter formats or relationships 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 clearly states the tool dispatches remediation to a worker via multi-channel delivery, with a specific verb and resource. It distinguishes from sibling tools like tascan_dispatch_to_agent by explicitly specifying 'to the worker' and listing concrete delivery channels.

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 context as 'Step 3 of the Closed-Loop Autonomous Operations Protocol,' implying it is used after analysis and recommendation, but it does not explicitly state when to use it over alternatives like tascan_dispatch_to_agent or tascan_send_task_email. No exclusions or alternatives are mentioned, so guidance is implied rather than explicit.

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

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

Goes substantially beyond the annotations: describes automatic pickup/execution, exact routing behavior, cloud agent refusal of CODE/SHELL/PLAN/MCP, default fallback when the local PC agent is dead, and the requirement for agent:dispatch permission. These are non-obvious behaviors an agent must know before invoking.

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

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

Dense but well-structured: purpose first, then permissions, routing, fallback, agent targeting, and tracking. Every sentence carries load-bearing operational information; there is no filler or redundancy.

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

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

For a 3-parameter tool with no output schema, this description is remarkably complete: it covers invocation, permissions, routing rules, error behavior, default agent, and how to monitor the dispatched task via tascan_get_task. An agent has everything necessary to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds high-value semantics beyond the schema: the full routing-prefix system, the default agent value, permission nuances per task type, and the pointer to tascan_list_agents for valid agent IDs. This pushes it above baseline.

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

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

States a specific verb and resource: dispatches work to an AI agent's inbox for automatic execution. The 'PREFERRED tool for sending work to an AI agent' framing and routing details clearly set it apart from sibling tools like tascan_dispatch_instruction and tascan_send_task_email.

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 operational context: when to target an agent, how routing prefixes select the destination, permission requirements, and how to discover agents or track progress. It does not explicitly state when NOT to use this tool versus alternatives like tascan_dispatch_instruction, so some exclusion guidance is missing.

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 annotations, the description discloses important behavioral nuance: it is one route with two methods, action=set has two distinct modes (author vs. pin), and it adds concrete validation rules such as require being a non-empty array and min_count constrained to require.length. It also clarifies what action=get evaluates. This adds substantial context beyond the idempotent/destructive hints.

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 and front-loaded with the core purpose before expanding into action-specific detail. It is longer than the average tool description, but the length is earned because the tool genuinely has two operations and nested parameter semantics. Some protocol route detail could arguably be trimmed, but it remains relevant to explaining why one tool covers two methods.

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 five-parameter tool with a nested object and no output schema, the description covers most invocation concerns: action semantics, pinning vs authoring, validation constraints, and what get evaluates. It does not describe the response shape or error behavior, which would have made it fully complete given the absence of an output schema, but the core usage is well specified.

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?

Although schema coverage is 100%, the description adds meaning beyond the schema by explaining the behavioral difference between providing and omitting definition, the pinning workflow, the version-ignored-when-pinning rule, and the validation constraints on definition fields. This goes well above the baseline 3 for fully covered schemas.

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

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

The description opens with a specific verb and resource: 'Read or author a task's evidence policy.' It then separates the two operations into action=get (evaluate) and action=set (author/pin), which distinguishes this combined read/write tool from the many sibling get/update tools. This is far from a tautology and gives an agent a precise mental model.

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

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

The description clearly explains when each action applies: use action=get to evaluate the pinned policy; use action=set to author/update or pin. It also gives conditional guidance for definition omission versus provision. It does not explicitly name sibling alternatives or exclusions, but the dual-action structure makes the intended usage contexts 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, idempotentHint=true, openWorldHint=false, and destructiveHint=false, so safety is covered. The description adds useful behavior by noting ids and parent context are returned for disambiguation, but it does not mention pagination, result limits, or ordering.

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

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

The definition is two sentences, front-loaded with the core capability, and contains no filler. The dense enumeration of entity types and matching fields is appropriate for a cross-entity search 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?

Given the simple two-parameter schema and the absence of an output schema, the description is nearly complete: it explains scope, entity coverage, matching fields, and that results include ids/parent context. Only minor search-result details such as limits or ordering are omitted.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description still adds meaningful semantics by explaining what can be searched per entity type, including project number/customer job number via external_refs and site matching by address or client company.

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 (cross-entity search) and enumerates exactly which resources can be found, including the fields used to match each type. It distinguishes this from sibling list/get tools by emphasizing one-call lookup across projects, lists, tasks, workers, assets, sites, and work orders.

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 says to use this instead of walking projects→lists→tasks or guessing ids from display names. That gives clear when-to-use guidance and directly addresses the main alternative behavior an agent might otherwise choose.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds meaningful behavioral context beyond these annotations: it discloses that matches are candidate-level, that detail is per-signal, and that the output is a candidate list intended for the merge process. This goes beyond simply restating 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 two sentences with the core function front-loaded and the workflow significance in the second sentence. It is appropriately sized, though the parenthetical 'Patent 4 §6.25(b)' reference is cryptic and adds little agent-facing value; the text is still concise overall.

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, idempotent tool with fully documented optional parameters, the description covers the essential context: what it finds, what signals it uses, and how the output relates to the merge workflow. It does not spell out the exact return shape, but the absence of an output schema and the 'per-signal match detail' phrasing provide sufficient orientation.

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 descriptions already explain each parameter well, including the preferred worker_id anchor, the threshold default, and the orphan flag behavior. The description does not add much parameter-level detail beyond the schema, 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 opens with a specific verb and resource: 'Find candidate same-person worker records', which is much more specific than a generic list or search. It also names the concrete signals (phone reuse, name similarity, GPS pattern correlation) and explicitly positions the tool as feeding the merge workflow, distinguishing it from merge_workers and list_workers without needing to open schemas.

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

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

The description provides clear context for when this tool is appropriate: it surfaces duplicate candidates for identity resolution and feeds the merge workflow. It does not explicitly name alternatives or state when not to use it, but the workflow cue is strong enough for an agent to infer the intended usage.

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

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

Goes far beyond the annotations: it discloses that document is hashed into build_ref, that a task_completions row and a signed receipt are minted, that the completion releases the next held seat and feeds the fan-out synthesizer/rollup, and that failed runs store nothing. It also states the required permission and the 404/not_live refusal conditions, none of which are derivable from readOnlyHint/idempotentHint/destructiveHint.

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

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

Front-loaded with the action and endpoint, and each subsequent clause carries distinct information (storage, hashing, receipt, fan-out side effects, auth, failures). The prose is dense with run-on parentheticals and emphasis, which slightly hurts readability but wastes little.

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

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

For a mutation tool with no output schema, the description covers the side effects, the authorization requirement, the failure semantics, and points to tascan_get_receipt for the returned artifact. Nothing an agent needs to invoke it correctly appears missing.

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

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

Schema coverage is 100%, so baseline would be 3, but the description adds real meaning: it stresses that document IS the hashed deliverable ('send the real content, not a summary') and clarifies verification becomes the seat's second artifact_path. The cost_micro_usd default rationale is left to the schema.

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

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

States a specific verb+resource ('Finish a claimed local run') plus the underlying endpoint (POST /runs/:run_id/finish), and its two outcome branches are fully spelled out. An agent can distinguish this from tascan_claim_run or tascan_heartbeat_run without opening any schema.

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

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

Gives clear context for each outcome: 'completed' stores artifacts and mints a receipt, 'failed' finishes with error text and stores nothing, and it names a prerequisite (requires agent:dispatch:code) and refusal cases (404 / not_live). It never explicitly names tascan_claim_run or heartbeat_run as the alternative operations, so the when-not guidance is inferred rather than stated.

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

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

Annotations already flag idempotent, non-destructive, closed-world behavior, and the description adds real value beyond them: the QR is drawn in-house, returned as an SVG and a data: URI in qr_image_url, and no third-party service sees the link (a privacy guarantee). It doesn't explain what the non-readOnlyHint generation persists, but the output-format and privacy disclosure is strong.

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: capability first, then a concrete behavioral detail, with zero waste. Everything is front-loaded and 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?

With no output schema, the description usefully explains what is returned (SVG plus a data: URI), and annotations cover the safety profile while the schema covers both params. It could say a bit more about the non-read-only side effect, but nothing critical is missing for correct invocation.

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

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

Schema coverage is 100%, so both parameters (list_id and the reserved/ignored style) are already documented in structured data. The description only implicitly maps to list_id via 'task list (event)' and adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb (Generate) plus resource (QR code) plus target (task list/event) and the outcome (workers scan to access tasks). No sibling tool deals with QR generation, so an agent can immediately tell this apart from the rest of the catalog.

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 conveys the scenario (giving workers scannable access to a task list), which implies when to use it, but it names no alternatives or exclusions and gives no preconditions such as requiring an existing list_id.

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 idempotency and non-destructiveness, and the description adds useful behavioral context beyond them: links are stable, evidence reports require admin sign-in to view, service acknowledgments file into the list thread, and SMS delivery is optional. Nothing here contradicts the annotations.

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

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

The description is information-dense and front-loaded with the core action and output. The colon-delimited type list is readable, and every clause contributes meaning, though it is a single long paragraph and could theoretically be tightened without losing value.

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

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

With no output schema, the description still tells the agent the outcome ('get its link') and covers the main decision points: choosing a report type, required IDs, service customization, and optional SMS delivery. It does not exhaustively describe all 9 parameters, but the high schema coverage compensates, and the core calling decision is fully supported.

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 (89%), so the schema already documents most parameters. The description adds value by explaining what each report type semantically contains, clarifying that list_id vs project_id depends on type, and describing the purpose of service report branding and acknowledgment behavior beyond raw parameter names.

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 pair: 'Mint a shareable report and get its link.' It then enumerates four distinct report types with concrete contents, making the tool's purpose unmistakable and differentiating it from sibling get/list report 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 clear context for when each report type is appropriate (completion, service, project, evidence) and states which ID each requires via the schema and prose. It does not explicitly name alternatives like tascan_get_report, but the 'Mint a shareable report' framing strongly implies generation rather than retrieval, and no exclusions are needed beyond the type prerequisites.

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

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

Annotations already establish read-only, idempotent and safe, and the description layers meaningful domain behavior on top: task-level values win over list values, the floor rule for Decisions lists and passkey cards, and the inherited agent_assignee. The one gap is that it never says what happens when neither or both ids are supplied.

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

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

Front-loaded with verb and resource, but the single sentence is overloaded with stacked parentheticals and domain jargon, making it hard to scan. The information is relevant but poorly staged.

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

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

There is no output schema, and the description steps in to enumerate the returned fields (access_level, effective level, human assignees, agent_assignee, floor), which is exactly what's needed. Missing only the edge-case behavior when zero or two identifiers are supplied.

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 carry parameter meaning; it does identify list_id as a task list and task_id as a task and explains inheritance. It does not state whether the two are required, mutually exclusive, or which takes precedence when both are passed (the 'task-level wins' line describes the data model, not the parameters).

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

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

States a specific verb (Read) and resource (the access object) and scopes it to either a task list (list_id) or a task (task_id). The list-vs-task distinction is genuine disambiguation, though it never names the write counterpart tascan_set_access to complete the picture.

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

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

Usage is only implied: pass list_id to read a list's access or task_id to read a task's. There is no 'use this when…' framing, no mention that reads of access should go here while changes go to tascan_set_access, and no exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuine context beyond that: NULL limits or a missing budget row mean unlimited, and keys are strictly scoped to their own row. It does not discuss pagination or response shape beyond the counter list, so 4 is fair.

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

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

Front-loads the core action and result set, then adds the two constraints (NULL = unlimited, own-key-only) and the tier. Dense but every clause carries information; only the parenthetical rule reference (I-3) is arguably overhead.

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

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

With no output schema, the description carries the burden of explaining return values and it does so: it names the limit counters and the spend comparison, defines the NULL/missing-row unlimited semantics, and bounds visibility. An agent has everything needed to call it and interpret the result.

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

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

Zero-parameter tool, so the schema-based baseline is 4. The description usefully frames what the caller implicitly scopes to (this credential's key) and what the returned counters mean, which is the only parameter-like semantic that matters here.

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

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

States a specific verb (Read) and resource (THIS credential's per-key action budget), and enumerates exactly which counters are returned (sms, invites, payment-request cents, dispatch, human pages) plus today's spend. The emphasis on 'OWN' and 'never another key's' clearly separates it from generic usage/report siblings like tascan_get_usage.

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

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

Gives clear context for when this applies: it is a read-tier call returning this key's own budget, and it explicitly states the hard constraint that no key can read another key's row. It does not name an alternative tool or when-not-to-use it (e.g., vs. tascan_get_usage), 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by explaining the manifest is truncated at 12000 chars, computing build_ref (sha256 over the manifest), and that binary or over-cap files only store the sha. It also clarifies the discovery semantics, which goes beyond annotations. No contradiction.

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

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

The description is a single, dense paragraph that packs essential information: purpose, content, computation, truncation, and sibling distinction. Every sentence adds value, front-loading the semantic difference from file reads. No fluff 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's single parameter, clear annotations (read-only, idempotent), and that the output schema is not provided (but the description describes what the manifest contains), this is complete. An agent can call it correctly, understand what it returns, and know to use tascan_get_build_file for file content. The truncation limit and read semantics are stated.

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 build_ref's format (sha256:<64 hex>). The description adds context that build_ref is a SHA256 over the manifest and how to obtain it (from tascan_get_task or tascan_get_cycle_report), which is additional meaning beyond the schema. Slight deduction for not fully detailing the manifest's structure beyond what's listed, but it's adequate for a single 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 clearly states 'Manifest of a stored build bundle by build_ref' and details what the manifest contains (files with sha256, byte length, text content status), which precisely identifies the resource and scope. It distinguishes itself from siblings by specifying it is metadata/discovery, not a file read, and explicitly names the sibling for reading a file.

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 provides usage context: 'Use tascan_get_build_file to read a file', and clarifies that 'Reading the manifest is discovery, not a read of any file'. It explains the protocol version and that build_ref is derived from tascan_get_task or tascan_get_cycle_report, giving clear when-to-use guidance and when-not-to.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description adds valuable detail: the call is refused if build_sha256 does not match the artifact's stored hash, storing replaces the file's full content going forward, and agent:dispatch permission is required. 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?

The description is dense and front-loaded with the core action. Every clause carries useful context, though the long parenthetical about protocol internals and the repeated 'only writes one' could be trimmed without losing meaning.

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 write-only tool with no output schema and 7 fully documented parameters, this description covers what the tool does, why it exists, its validation rule, its destructive side effect, the lack of any read-back path, and its required permission. An agent has everything needed 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?

Schema coverage is 100% and each parameter already has a precise description. The prose adds the high-level constraint that build_sha256 must equal the stored artifact hash and repeats that the tool never computes a diff, but it does not materially extend the per-parameter meaning already present 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?

Opens with a specific verb and resource: 'Store an already-computed diff for one file of a build bundle against a base commit.' It also anticipates the misleading tool name by explicitly stating the route is write-only and that no GET path reads a stored diff back, distinguishing it from tascan_get_build/tascan_get_build_file.

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: the parser has no GET for this path, the deployer precomputes the diff, and this route only validates and stores it. It explicitly says there is no REST route that reads the stored diff back and that this tool only writes one, providing a firm when-not. It does not name alternative tools, but the endpoint references imply them.

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

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

Adds substantial behavior beyond the readOnly/idempotent annotations: per-call character cap, offset/limit paging with next_offset, sha256 and byte-length return values, truncation behavior for binary/over-cap files, and the binding semantics of header lines. An agent knows exactly what will happen on repeated or partial reads.

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

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

Dense but purposeful: the first clause names the operation, the middle explains limits and output, and the final sentence gives operational guidance for paging and record-binding. No filler; every sentence adds information needed to call or interpret the tool correctly.

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

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

Even without an output schema, the description covers the return payload, paging mechanics, sha256/byte-length metadata, binary/over-cap edge cases, and the reviewer-binding semantics. An agent has enough contextual detail to invoke the tool and handle partial or empty results correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds useful semantic context by framing limit/offset as paging over characters, explaining that truncated reads return next_offset, and emphasizing that path must refer to the exact build-listed artifact. This goes slightly beyond the bare schema definitions.

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

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

States a specific action ('Read one file'), a precise resource ('stored build bundle'), and the selection keys ('by build_ref and path'). It also differentiates itself from a working-tree read and from the related tool tascan_get_build, so an agent can tell exactly what this tool is for.

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

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

Gives clear context: this is the read tier for exact executor-produced build artifacts and is what the independent reviewer reads. It implicitly excludes working-tree reads and other list-style build tools, though it does not spell out a formal when-to-use vs. when-not-to-use against each alternative.

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

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

Beyond the readOnly/idempotent/destructive annotations, the description discloses important behaviors: 'Read tier,' default summary-only behavior, the effect of full=true, the 12000-char cap on the complete JSON, and the fact that a computed summary is returned first. These details significantly help an agent anticipate response size and shape 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?

The description is dense but every clause contributes: scope, contents, summary-first behavior, full mode, size cap, read tier, and notification uniqueness. The main purpose and identifier are front-loaded, and there is no filler or repetition within the description itself.

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

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

With no output schema, the description carries the burden of explaining what the agent will receive, and it does so thoroughly: it lists all report sections, the computed summary fields, the full-JSON option, the size cap, and the root_id resolution path. An agent has enough context to select and invoke the tool correctly even without knowing the exact JSON keys.

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 full and root_id well. The description reinforces the same semantics, including the root_id provenance and the full=true behavior, but does not add substantial new parameter-level meaning beyond the schema. 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-plus-resource framing: 'audit report of one coordination cycle by its root task id' and enumerates the exact contents (tasks, runs, completions, verdicts, decisions, ledger events, hash-chain verdicts, spend). It clearly differentiates this from general report/list tools by scoping it to a single cycle and calling it 'the ONLY per-cycle notification surface.'

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: when a per-cycle audit report or notification surface is needed. It also provides concrete invocation guidance for root_id: 'returned by tascan_create_cycle; a non-root cycle task returns its root_id in the error.' It lacks an explicit named alternative or when-not-to-use statement, but the 'ONLY per-cycle notification surface' claim effectively rules out sibling notification tools.

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

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

Annotations already declare readOnly, idempotent, non-destructive behavior, so the safety profile is covered. The description adds two genuinely useful behavioral facts beyond that: the return set is bounded to the last 20 evidence_event ids, and credential hashes are never returned — a meaningful security disclosure.

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 with zero filler; the verb and lookup key are front-loaded and the returned-field inventory follows immediately. Nothing is repeated from the schema or annotations.

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

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

With no output schema, the description carries the burden of describing the return payload and does so explicitly, including the 20-event cap and the credential-hash exclusion. An agent knows what it will receive before calling.

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

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

Schema description coverage is 100% for the single device_id parameter, so the schema already documents it. The description adds only the trivial clarification that lookup is by id, which is the baseline 3 when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Get one device by id') and then enumerates exactly what the response contains (kind, name, status, zone, rotation timestamps, revocation reason, last 20 evidence_event ids). The singular 'one device' also implicitly separates it from the sibling tascan_list_devices.

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 'by id' implies this is the point-lookup counterpart to the list operation, which is enough to infer intended usage. However, it never names tascan_list_devices as the alternative or states when not to use it, so the routing guidance is only implied.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds useful context that an 'event' is a 'task list' and that the response includes its tasks. This goes beyond the annotations to clarify the response scope.

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

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

The description is a single clear sentence that is front-loaded with the action and resource, and it includes the key behavioral note about including tasks. There is zero redundant content.

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

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

For a simple read-only operation with one fully documented parameter, rich annotations, and no output schema, the description sufficiently indicates what the tool returns (details plus tasks). No additional context is needed to use it effectively.

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 parameter list_id is fully documented in the schema ('Task list (event) ID') with 100% coverage. The description only reiterates the 'event/task list' relationship without adding syntax, format, or parameter-specific details 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 clearly states the verb ('Get'), the resource ('specific event'), and adds the crucial parenthetical '(task list)' to clarify terminology. It also notes 'including its tasks', which distinguishes it from siblings like tascan_list_events (listing many events) and tascan_get_task (fetching a single 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 phrase 'specific event' implies this is for fetching one event by ID, but there is no explicit guidance on when to use this versus tascan_list_events for enumeration or tascan_get_task for a task's details. Usage context is implied, not spelled out.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds genuinely new behavior: org isolation returns 404 never 403 ('another org's fan-out never even appears to exist'), the verify view recomputes rollup_ref server-side and reports ok/mismatches, and no dispatch permission is required (read tier). These are meaningful traits beyond the structured hints.

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

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

Dense but front-loaded: the core action and its view selector come first, then per-view detail, then the security/permission notes. Sentences are information-packed, though the view=verify sentence is long and the whole block is heavier than a single-purpose read tool strictly needs.

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

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

With no output schema, the description carries the return-value burden and does so view by view, including which fields appear (seat counts, spend, cap, poll_after_s; leaf path/sha256/completion_id). It also covers the auth/permission model and org-isolation edge case, leaving no obvious gap for correct invocation.

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

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

Schema coverage is 100% and the schema's enum description is terse ('status (default), report, rollup or verify.'), so the description meaningfully expands it by explaining what each view actually returns (state/counts/cap/synth_deadline_at/poll_after_s vs. leaves with path/sha256/completion_id). The fanout_id param is only restated as the T_F root UUID, so it stops short of a 5.

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

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

States a specific verb+resource (read a fan-out by id) and immediately scopes it with the four view modes, so the agent knows exactly what it retrieves. It also distinguishes itself from the related get_cycle_report by noting view=report returns that report inline, rather than leaving the agent to guess which sibling to call.

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 per-view selection guidance (status for state/counts, report for the full cycle, rollup for the response_value plus leaves, verify for recomputation) and a notable caveat: verify is 'a convenience, not a substitute' for scripts/verify-fanout.js. No explicit 'when not to use this tool' against a named sibling alternative, 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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds non-obvious behavior beyond that: the admin phone is masked to its last 4 digits and a tool never sees the full number, which an agent could not infer from the schema or annotations.

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

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

Three short sentences, front-loaded with the verb and resource, then the returned fields, then the boundary constraint. The parenthetical about masking is essential clarification rather than filler; nothing is wasted.

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

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

With no output schema and no parameters, the description carries the return-value burden itself and does so by enumerating the profile fields. Combined with the masking caveat and the write-path exclusion, an agent has everything needed to call and interpret this tool.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly implies no inputs are required and instead documents what the call returns, which is the relevant semantic information for this tool.

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

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

States a specific verb and resource (read the organization profile, GET /org) and enumerates exactly which fields come back (id, name, industry, logo, time zone, masked admin phone, tier). It also distinguishes itself from write operations by noting that editing happens in the portal, not via any 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?

Makes the usage context clear (read-only org profile, no parameters needed) and explicitly rules out the mutation path by stating that editing is done by an owner/admin in the portal and not by any tool. It does not name a sibling tool to prefer, but the zero-arg read scope 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, idempotentHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is fully covered structurally. The description reinforces read-only and adds that billing mutations are portal-only, but contributes little new behavioral detail (no auth requirements or response format notes).

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

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

A single front-loaded sentence carries the resource, endpoint, read-only nature, output fields, and the billing-mutation constraint with no filler. The trailing 'Read tier.' is a minor fragment but harmless.

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

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

With no output schema, the description compensates by naming the two values an agent gets back (plan tier and billing exemption). It omits whether the result is empty or errors for orgs without a plan, but is otherwise sufficient for a zero-parameter read.

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

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

Zero parameters, so the baseline of 4 applies. The description uses the space usefully by describing the returned fields rather than restating 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?

Names a specific verb+resource ('Your organization's plan') and enumerates what it returns: plan tier (free, pro, ...) and billing-exemption status. It doesn't explicitly contrast with nearby read siblings like tascan_get_org or tascan_get_budget, but the resource is narrow enough to be distinguishable.

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

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

States a clear constraint: 'Billing changes happen in the TaScan portal only,' which tells the agent not to attempt plan changes through this tool. It gives context without naming a sibling alternative, 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 declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds no extra behavioral context beyond restating the read-only nature. 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 a single concise sentence with no filler words. It directly states the tool's purpose without redundant information.

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

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

For a simple get tool with one parameter and rich annotations, the description is adequate. It does not explicitly define what 'details' includes (e.g., whether it returns tasks within the project), but the low complexity and clear scope make this an acceptable gap.

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

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

Schema coverage is 100% with the 'project_id' parameter clearly described as 'Project ID'. The description does not add additional meaning beyond the schema, so it relies on the structured definition.

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 ('Get') and resource ('project'), and clearly scopes to a single project via the project_id parameter. It distinguishes from sibling tools like tascan_list_projects (list all) and tascan_get_task (different resource).

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 usage is implied by the tool name and parameter: use when you need details for a specific project. However, there is no explicit guidance about when to prefer this over tascan_list_projects or any alternatives, nor any exclusions.

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

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

Annotations declare readOnlyHint, idempotentHint, and destructiveHint=false, and the description aligns with these (read operation). It adds significant behavioral context: explains the return contents (summary, JWS, verify URL), verification methods (offline/online), the distinction between outcome and verification.result, and the security caveat about not treating outcome=completed as success without a policy verdict. This goes beyond annotations to disclose how the tool behaves and what the results mean.

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 information-dense but not overly long. It front-loads the primary purpose and source of the required parameter, then covers verification, outcome interpretation, and the profile variant. While comprehensive, it is somewhat dense and could be slightly more scannable, but every sentence provides necessary context. Slight reduction could be made, but it remains focused.

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 rich annotations and fully described parameters, the description covers the essential aspects: what is returned, how to verify, the meaning of key fields, and the security caveat. It even references protocol sections for deeper context. Given no output schema, the description provides sufficient guidance on the return structure and interpretation. It is complete for an agent to use 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 provides descriptions for both parameters with 100% coverage. The description adds value by explaining the completion_id source (from tascan_get_task -> completions[].id) and elaborating on the profile enum's full vs. public distinction, clarifying the public profile's privacy implications. This enriches beyond the schema's own descriptions, though the schema already carries most 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?

The description clearly states the tool fetches a signed Action Receipt for a completed task by completion_id, with a specific identifier source (tascan_get_task -> completions[].id). It distinguishes its purpose from siblings by focusing on receipt retrieval for completed tasks, not creation, listing, or other operations.

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

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

The description explains when to use it (for a completed task's receipt) and how to obtain the completion_id, but does not explicitly contrast it with alternative tools for similar purposes (e.g., get_task). It provides context on the profile parameter and the protocol sections referenced, but no direct 'when not to use' guidance.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds genuinely useful context the annotations lack: the signed URLs are short-lived (~1h), and include_responses inflates the payload ('default false — keeps the payload light'). This helps an agent reason about freshness and response size.

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 get action, then the optional flag's effect. Dense but every clause (photo evidence, signed URLs, ~1h lifetime, payload weight) carries information; minor length cost from the parenthetical depth.

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

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

With no output schema and no nested objects, the description carries the return-value burden and does it adequately by listing report contents and the extra fields unlocked by include_responses. It could be more complete on pagination or report scope (all workers vs filtered), but nothing critical is missing for correct invocation.

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

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

Schema coverage is 100%, so baseline is 3, but the description goes beyond the schema by spelling out what include_responses actually returns (submitted numbers, text, choices plus a per-task photo list with fetchable signed URLs) rather than merely restating the field name.

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

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

States a specific verb+resource: 'Get completion report for a task list (event)' and enumerates report contents (task status, completions, workers, photos). It does not explicitly differentiate from close siblings like tascan_generate_report or tascan_list_reports, so it falls short of a 5.

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

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

Usage is only implied by the resource mentioned; there is no when-to-use/when-not or explicit alternative named against tascan_generate_report, tascan_list_reports, or tascan_get_event. The one piece of real guidance is the conditional 'Set include_responses to also return...', which is a parameter-level rather than tool-selection cue.

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 idempotentHint=true, so the safety profile is covered. The description adds valuable behavioral context beyond annotations by enumerating returned fields (GPS + IP + channel, scanner identity, scan→start delta) and explaining the 'sign-in-and-vanish' metric. 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?

The description is information-dense and front-loaded with the core purpose, then structured into two clear modes. However, it reads as a single long run-on sentence with many nested parentheticals, which slightly hurts scannability. No wasted words, but the structure could be cleaner.

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?

Since there is no output schema, the description correctly carries the burden of explaining return data, and it does so well: timestamp, GPS+IP, channel, scanner identity, and the delta metric. It does not explicitly state whether combining tag_id with task_list_id/project_id is invalid, and it omits ordering/pagination behavior, but the schema covers limit and filters, making this adequate for a read-only tool.

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

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

Schema description coverage is 100%, so the parameters are already self-documenting. The description adds some meaning by linking tag_id to mode 1 and task_list_id/project_id to mode 2, but this largely mirrors the schema's own parameter descriptions. It does not materially deepen parameter understanding 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 names a specific resource (scan accountability data) and immediately breaks it into two concrete modes: NFC tag scans and QR/link page-open stamps. It distinguishes itself from sibling tools by detailing the exact data returned (GPS, IP, channel, scanner identity, scan→start delta), so an agent can tell it apart from history/listing variants.

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 two-mode structure gives clear selection guidance: pass tag_id for registered NFC tag scans, or task_list_id/project_id for page-scan data. It does not explicitly name alternatives or state when not to use this tool, but the mode differentiation is strong enough for an agent to select 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 cover safety (readOnly, idempotent, non-destructive, closed-world), and the description adds substantial context beyond them: the bundle is self-contained and offline-verifiable, it enumerates the contents, it explicitly withholds signed URLs/phone/email, and it notes read tier and organization scoping.

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?

Purpose and the id's origin are front-loaded, followed by the return contents and a verification tip. The long field enumeration is justified because there is no output schema, though the sentence is dense enough to be slightly heavy.

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

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

With no output schema, the description compensates by detailing what the returned JSON contains and how to verify it independently. Access and safety semantics are also covered, leaving nothing an agent needs in order to call it correctly.

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

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

Schema coverage is 100% and the schema already explains the parameter as a UUID from the completion response of a signature task. The description largely restates that origin rather than adding new syntax or format guidance, 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 (Fetch) and resource (signature bundle) scoped to one signed document, identified by signature assertion id. It is readily distinguishable from generic siblings like get_receipt or get_task because it names the exact artifact and its auditor-verification purpose.

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

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

It states clearly where the required id comes from ('the signature_assertion_id inside the response value of a completed signature task'), giving a concrete precondition, and adds a verification command. It does not name an alternative tool or state when not to use this one, so it falls short of a full 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is fully covered structurally. The description only adds that related projects and task lists are included in the read, which is modest value and doesn't cover pagination 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 short sentences with the core action front-loaded and no filler. Every phrase contributes either the action or the return scope.

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-param read tool with rich annotations and no output schema, the description supplies the essential return scope (projects and task lists). The only gap is the ambiguous 'read tier' phrase and no indication of what happens for an invalid or missing site_id.

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

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

There is a single required parameter (site_id) with 100% schema description coverage, so the schema already carries parameter meaning. The description adds no format or sourcing guidance for the ID beyond the schema, fitting the baseline 3.

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

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

States a specific verb and resource ('Read one site') and adds scope detail about embedded projects and task lists, which differentiates it from list_sites and get_project. It does not explicitly name the sibling tools it contrasts with, keeping it below a 5.

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

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

'Read tier' is an opaque internal label that does not tell an agent when to prefer this over tascan_list_sites or tascan_get_project. There are no exclusions or prerequisites stated.

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