Tookan MCP by usefulapi

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

Annotations flag destructiveHint=true and idempotentHint=false, and the description explains exactly why: it replaces the previous agent (destructive) and re-notifies on repeat calls (non-idempotent). This corroborates and enriches the annotations with concrete consequences an agent needs 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?

A single dense sentence with the operation type and the most consequential behavior (replacement) front-loaded, followed by the notification caveat and endpoint. No filler or restatement of the title.

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

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

For a write tool with no output schema, it covers what gets overwritten, notification side effects, idempotency, and the endpoint. It does not mention permission or auth requirements or what happens on invalid job/team combinations, which keeps it below a 5.

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

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

Schema description coverage is 100%, so all four parameters including notify are already documented, which sets the baseline at 3. The description adds only marginal detail — that notify=false suppresses the notification and that repeats re-notify — but gives no extra meaning for job_id, fleet_id, or team_id beyond the schema.

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

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

States a specific verb and resource ('assign (or reassign) a task to an agent of a team') and adds the key semantic that it replaces any previous agent. The 'WRITE:' prefix and the underlying POST endpoint make the operation type unambiguous, and no sibling tool performs assignment so there is no confusion to resolve.

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 use condition clear: this is the tool for assigning or reassigning, and it overwrites prior assignments. It also warns that repeating the call re-notifies, which is practical guidance for avoiding accidental duplicate notifications. No explicit 'when not to use' or alternative is named, though none of the listed siblings competes for this job.

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

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

Annotations only declare destructiveHint=true, so the description carries real weight and delivers: it declares the write operation, the return values (job_id and tracking link), and the forced ignore_customer_lat_long=1 behavior so the agent knows a stored address will not be used. It omits side effects such as notifications fan-out and whether duplicate submissions create duplicate jobs.

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 verb and required inputs, then layers optional assignment and return behavior, all in a dense paragraph with no filler. The trailing endpoint/flag metadata ('POST /v2/create_task (has_pickup 0, has_delivery 1, layout_type 0)') is low-value for an agent and slightly clutters the close.

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 15 parameters, no output schema, and minimal annotations, the description covers the essentials: what is created, what is required, how assignment works, address precedence, and what is returned. Missing only duplicate-handling and notification side-effect notes, which are secondary for a create call.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by explaining the interaction between fleet_id, team_id, and auto_assignment, and by clarifying that the address parameter overrides any saved customer location. Parameter-level detail for the remaining fields is left to the schema, which is appropriate.

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

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

States a specific verb and resource ('create a delivery task (job) for a customer address') plus the scheduling constraint, immediately distinguishing it from every sibling, which are all read, list, assign, or status-update operations. An agent knows exactly what this tool produces.

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?

Explains the creation-time assignment options (fleet_id, team_id, or auto-assign within a team), which is genuine when-to-use guidance for the branching paths. It does not explicitly say when to prefer tookan_assign_agent_to_task afterwards or when not to use this tool, so it stops short of full alternative 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?

readOnlyHint=true already declares the safety profile, so the description only needs to add context. It contributes the underlying endpoint (POST /v2/find_customer_with_phone), which is mildly useful, but says nothing about auth, rate limits, or whether a missing customer yields an empty result or an error.

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

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

Two short sentences, front-loaded with the purpose and followed by the endpoint. Nothing is padded, though the raw endpoint path is arguably metadata noise rather than decision-relevant content.

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

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

Simple one-parameter, read-only tool, but there is no output schema, so the description should say what comes back (single customer vs. list, empty result or error on no match). That gap is noticeable given the plural 'customers'.

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 one parameter and 100% schema coverage the baseline is 3, but the description genuinely adds semantics the schema lacks: matching is on the exact phone number, so partial or formatted variants won't work. The schema only shows example formats, not the matching rule.

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 ('Find customers') and adds a scope qualifier ('exact phone number') that separates it from the broader list_customers and get_customer siblings. It never names a sibling or states when one should be preferred, 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: the agent can infer 'use this when you have a phone number' and that partial/fuzzy matches are excluded by 'exact'. There is no explicit guidance on choosing between this, list_customers, and get_customer, and no note on what to do when no customer matches.

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?

readOnlyHint=true already covers the safety profile; the description adds the concrete return shape (which fields come back) and the underlying endpoint POST /v2/get_user_details. No auth or rate-limit context, but for a zero-param read that's minor.

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: what comes back first, then the usage cue and endpoint. Every clause carries information, though the raw endpoint string is of marginal value to an agent.

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

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

No output schema exists, but the description compensates by enumerating the returned fields. With no parameters and annotations covering read-only safety, an agent has everything needed to call and interpret it; only error/empty-case behavior is 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?

Zero parameters, so there is nothing to disambiguate and the description correctly spends no words on arguments. Baseline 4 applies.

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

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

States a specific verb+resource: retrieves the connected Tookan account's admin user details, enumerating the fields (user_id, email, name, company name, address). The qualifier 'connected ... (admin user)' distinguishes it clearly from siblings like tookan_get_agent, tookan_get_customer, and tookan_list_agents.

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

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

'Good first call' gives explicit situational guidance for when to reach for this tool, useful since it takes no parameters. It stops short of naming alternatives or exclusions (e.g., use tookan_get_agent for other users), so it doesn't reach a 5.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered; the description still adds real value by naming the returned field set, stating that current tasks are included, and guaranteeing that app tokens and password hashes are never returned. It also discloses the underlying call (POST /v2/view_fleet_profile), which usefully explains why a read operation is a POST. Return shape for tasks is not described.

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

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

Two tight sentences: the payload/field list comes first, the security guarantee second, the endpoint last. No filler sentences and nothing redundant with the schema.

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

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

With no output schema, the description correctly compensates by enumerating returned fields and disclosing the excluded sensitive fields, which is what an agent needs for this one-parameter read. Minor gap: the structure/format of the 'current tasks' list and units for rating are unspecified.

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

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

Schema coverage is 100% and the single parameter fleet_id is already documented as 'Agent id (fleet_id from tookan_list_agents)', including its origin. The description adds no further semantics about the id, so the baseline 3 applies.

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

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

Specific verb+resource: fetches a single agent's profile and enumerates exactly which fields come back (name, email, phone, tags, transport, location, rating, active state) plus current tasks. "One agent's profile" implicitly contrasts with the list-style sibling tookan_list_agents, but no sibling is named explicitly.

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

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

Usage is only implied: needing details or current tasks for one known agent. There is no explicit statement of when to prefer this over tookan_list_agents or tookan_get_agent_location; the alternative routing hint ('fleet_id from tookan_list_agents') lives in the schema, not the description.

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

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

readOnlyHint=true already declares the safe-read profile, so the description only needs to add context. 'Last known' is a genuinely useful signal that the data may be stale or cached, but it says nothing about behavior when the agent is offline or how fresh the fix typically is.

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

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

Two compact fragments with zero filler and the key fact (last known coordinates) front-loaded. The endpoint path is arguably low-value for an agent but consumes little space.

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 fully documented parameter and no output schema, the description covers the essentials but doesn't indicate what else comes back (timestamp, accuracy, agent status) or what happens for an agent with no location. Slightly under-specified for an output-schema-free tool.

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

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

Schema coverage is 100% and the single fleet_id parameter is fully documented, including its source (tookan_list_agents). The description adds no semantics beyond that, which is the expected baseline when the schema does the work.

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

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

The description names the specific resource (an agent's last known coordinates) and specifies latitude/longitude, which distinguishes it from the broader tookan_get_agent sibling. It lacks a verb phrase, but the resource and returned data are unambiguous.

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

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

There is no statement of when to use this versus tookan_get_agent, tookan_list_agents, or the team/fleet siblings. The agent must infer from the name alone that this is the location-only lookup.

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, so the description is not needed for safety. It nevertheless adds real context the annotations don't: the underlying endpoint (POST /v2/view_customer_profile) and, more importantly, the payload contents, which matters because there is no output schema.

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

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

Two short fragments with the resource front-loaded and no filler. The endpoint string is arguably noise but is defensible as a traceability aid; the phrasing is telegraphic rather than a complete 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 one-parameter read tool with no output schema, the description does the important extra work of enumerating what comes back (contact details, address, coordinates). Missing only routing guidance versus the phone-lookup and list siblings.

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 and a single required integer parameter that even cites its provenance (tookan_list_customers), the schema carries the semantics. The description adds nothing about the id format or constraints, so the baseline 3 applies.

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

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

States a specific resource and scope: a single customer's profile, with the fields returned (contact details, address, coordinates) named explicitly. It is distinguishable from tookan_list_customers by the singular 'one customer', though it never names that sibling directly.

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 when-to-use or when-not-to-use guidance appears in the description. The nearest alternatives, tookan_find_customer_by_phone and tookan_list_customers, are never referenced, and the only hint (customer_id 'from tookan_list_customers') lives in the schema rather than the description.

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

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

Annotations only declare readOnlyHint=true, so the description carries most of the burden and does add real context: the 100-task batch cap, the HTTP endpoint (POST /v2/get_job_details), and a full status-code legend that an agent cannot get from structured fields. It stops short of noting rate limits, auth requirements, or what happens with invalid job ids.

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 return fields are front-loaded in a single dense clause, and the status-code legend is compact and high-value. The first sentence is a long run-on that would be more scannable as structured lines, but little of it 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 correctly enumerates the returned fields (customer, addresses, agent, timestamps, tracking link, custom fields) and the status-history option, which is what an agent needs to interpret results. It omits error behavior and the contents of 'additional info', which are minor gaps for a read tool with readOnlyHint.

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 three parameters, making 3 the baseline. The description adds a little ('optionally the status history' maps to include_task_history, 'up to 100' restates maxItems) but never mentions include_additional_info, so it does not go beyond the schema meaningfully.

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

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

The description states a specific verb and resource ('Full details of up to 100 tasks by job id') and enumerates the returned fields, so the agent knows exactly what comes back. The 'by job id' qualifier subtly separates it from sibling lookups like tookan_get_tasks_by_order_id, but it never names an alternative explicitly.

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

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

Usage is implied rather than stated: the agent can infer this is the lookup-by-job-id path, but there is no explicit 'use this when...' or exclusion against tookan_list_tasks or tookan_get_tasks_by_order_id. The alternative routing is left to inference.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description adds that results are 'full details' rather than summaries, which is a useful distinction from list-style siblings, but says nothing about behavior for unknown or partial order ids, batching semantics, or ordering of results.

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

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

A single front-loaded sentence identifying the returned resource, the filter key, and the parenthetical clarification, plus the underlying endpoint. No filler; slight redundancy between the parenthetical and the noun phrase.

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

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

No output schema exists, so the description carries the burden of describing what comes back, and beyond 'full details' it does not characterize the payload. It also omits what happens when an order id matches nothing, which matters for a batch lookup with up to 100 ids.

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 earns a bump by glossing 'order id' as 'the reference you set when creating a task', which resolves the ambiguity of what an order id actually is beyond the schema's bare example value.

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

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

States a specific verb and resource ('full details of the tasks') qualified by the lookup key ('carrying the given order ids'), so the operation is unambiguous. It does not distinguish itself from siblings like tookan_get_tasks or tookan_list_tasks, which also return tasks.

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

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

Usage is implied: use this when you already hold order ids and want complete task records. There is no explicit when-not guidance and no mention of when to prefer tookan_get_tasks or tookan_list_tasks instead, leaving the agent to infer the selection rule.

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?

readOnlyHint=true already covers the safety profile, so the lower bar applies. The description still adds real context: it discloses the return semantic (counts grouped by status), the full status-code legend, and the underlying POST endpoint. Minor gap is no mention of pagination/response shape.

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

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

Front-loads the purpose (counts per status), then the decoding legend, then the endpoint. The long code list is dense but earns its place by filling the schema gap; no filler sentences.

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

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

For a read-only aggregation tool with no output schema, it conveys that the result is per-status counts and which filters apply. Without an output schema the exact response shape remains slightly underspecified, but it's adequate to call 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%, but the schema's job_status only says "e.g. [2, 3]" without explaining codes. The description's status legend (0 assigned ... 10 deleted) fills that genuine gap, adding value beyond the schema rather than repeating it.

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

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

States a specific verb+resource: returns task COUNTS per status, with optional filtering. This is clearly an aggregation tool, distinct in intent from list_tasks/get_tasks which return task records. It doesn't explicitly name those siblings, keeping it from 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?

"optionally for one task type, one team and a date range" implies the filtering scenarios it serves, but it never states when to prefer this over tookan_list_tasks or tookan_get_tasks, nor any exclusions. Usage is implied, not 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?

Adds real behavioral context beyond the readOnlyHint annotation: the upstream API returns the entire list and the tool imposes a window (limit/offset with next_offset), which is essential for correct iteration, plus it notes the underlying POST /v2/get_all_fleets so the agent is not confused by a write-shaped verb on a read. No mention of rate limits, error behavior, or empty-result handling, keeping it short of a 5.

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

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

Three dense sentences, front-loaded with what is listed and what comes back, then filtering, then pagination and endpoint. No filler, no restatement of the title.

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

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

With no output schema, the description carries the burden of describing returns and does so by naming the returned fields and explaining the status encoding, plus the next_offset continuation convention for a 9-parameter, zero-required listing tool. Response envelope shape and failure modes are not described, so it stops just short of 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 coverage is 100%, so the baseline is 3, but the description earns above baseline by mapping the response 'live status' values (0 available, 1 offline, 2 busy), which resolves an ambiguity the schema leaves open — the status filter parameter only accepts 0/1 while live status is three-valued. The filter summary (name, tags, availability, fleet ids) also orients the agent before consulting parameter docs.

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

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

States a specific verb and resource ('List agents'), immediately glosses the domain terminology ('Tookan calls them fleets'), and enumerates the fields returned (fleet_id, name, phone, tags, team, live status). This clearly separates it from the singular tookan_get_agent and from tookan_list_teams/tookan_list_customers without the agent needing to open a schema.

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

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

The description implies usage by naming the filter dimensions (name, tags, availability, fleet ids) and by explaining the paging window, so an agent can infer this is the browse/enumerate path. However, it never says when to prefer a sibling — e.g. use tookan_get_agent for a single agent or tookan_get_agent_location for positions — and gives no exclusions or 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 declare readOnlyHint=true, so safety is covered; the description adds real value by disclosing pagination semantics ('one Tookan page per call', page defaults to 1) and enumerating the returned fields, which the agent needs to plan iteration. It stops short of stating page size, how to detect the last page, or rate limits.

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

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

Two sentences, front-loaded with the core action and result fields, followed by search and pagination behavior plus the endpoint. No filler and nothing important buried.

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

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

With no output schema, listing the returned fields in the description is the right compensation, and pagination behavior is explained. The only remaining gap is how an agent knows it has reached the last page, which matters for a paginated list tool but is a minor omission.

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 schema, including the page default and the fixed page size. The description restates the same facts (name/phone as optional search, page default 1) without adding syntax or format guidance, so the baseline 3 applies.

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

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

States a specific verb and resource (list customers), names the returned fields, describes the optional name/phone search, and identifies the underlying endpoint. It does not, however, differentiate itself from the sibling tookan_find_customer_by_phone, which overlaps with the phone-search behavior described here, so an agent still has to guess which one to pick for a lookup.

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: 'optionally searched by name or phone' suggests when to pass filters, and the pagination note suggests when to page. There is no explicit when-to-use or when-not-to-use statement, and no routing guidance versus tookan_get_customer or tookan_find_customer_by_phone, which is the most likely point of confusion.

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

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

Annotations only supply readOnlyHint=true; the description adds real behavioral detail on top: the hard 31-day date-window restriction, that each call returns exactly one page of a fixed page size, and the underlying endpoint. It omits return shape (total count, whether page size is discoverable), which keeps it from a 5.

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

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

Front-loaded with purpose and the date-window constraint, then filters, then status legend, then endpoint — a sensible ordering. The status-code list is duplicated from the schema's job_status description, which is the one clearly redundant clause.

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

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

No output schema exists, so the description must carry the return semantics — it discloses the page-per-call model and pagination entry point, which is the critical piece. It still leaves unanswered what a returned page contains and whether the caller can tell it has reached the last page.

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

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

Schema description coverage is 100%, so every parameter already carries its own documentation, including the status-code legend and job_type meanings. The description largely restates the status codes verbatim from the schema and adds no new semantics such as default-vs-explicit behavior or how multiple filters combine (AND vs OR). 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?

Names a specific verb and resource ('List tasks', clarified as Tookan 'jobs'), scopes it to one task type within a task-date range, and gives the endpoint (POST /v2/get_all_tasks). It stops short of naming the nearest sibling (tookan_get_tasks / tookan_get_tasks_by_order_id), so an agent must infer the boundary itself.

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?

Useful operating context is given: at most a 31-day window that must fall within the last 31 days, and pagination is one Tookan page per call. However, it never says when to prefer this over tookan_get_tasks, tookan_get_tasks_by_order_id, or tookan_get_task_stats, even though it advertises order-id and job-id filtering that overlaps those siblings.

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

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

Annotations already establish readOnlyHint=true, and the description adds real context beyond that: results are paginated as a window with next_offset, and include_agents produces a larger reply and switches the underlying endpoint. It does not mention ordering guarantees or a total count, but the key behavioral traits are 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 short, front-loaded clauses with no filler: returned fields first, then the include_agents behavior, then pagination and endpoint. Every sentence carries information the 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?

With no output schema, the description supplies the shape of the return (field list, pagination window, next_offset). For a simple read-list tool this is nearly complete; only ordering or total-count behavior 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 coverage is 100%, so the baseline is 3, but the description goes further by explaining what include_agents does to the response size and endpoint, and by tying offset to the previous call's next_offset. That adds meaning beyond the schema's own per-parameter text.

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

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

States a specific verb and resource ('List teams') and enumerates the returned fields (team_id, name, address, tags), plus the endpoint variant used. The resource is clearly distinct from siblings like tookan_list_agents, though it doesn't explicitly contrast with 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?

Usage is implied rather than stated: 'With include_agents, each team also lists its agents' tells the agent how to expand results, and the offset explanation says to reuse next_offset. There is no explicit when-to-use-this-vs-sibling guidance or when-not-to-use conditions.

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

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

Annotations only declare destructiveHint=true; the description goes well beyond by disclosing the override of the agent app, that status 2/3/9 close the task and trigger notifications per account settings, and that a user confirmation is required. It also flags the excluded status 10, which is exactly the kind of behavioral context annotations cannot carry.

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

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

The destructive warning and confirmation requirement are front-loaded, and the status-code list is compact and necessary given the numeric API. The single dense paragraph bundles purpose, effects, and parameter enumeration, which costs a little readability but wastes nothing.

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 destructive write with no output schema, the description covers safety, side effects, and allowed values thoroughly. It doesn't mention what the response contains or error/retry behavior, but nothing needed to select or invoke it correctly is missing.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds real meaning beyond the schema by enumerating what each settable code (0,1,2,3,4,6,7,8,9) denotes and which ones close/notify. It stops short of 5 only because the job_id parameter gets 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+resource ('force a task's status') plus scope (overriding the agent app) and the exact endpoint POST /v2/update_task_status. It is clearly distinguishable from siblings like tookan_assign_agent_to_task or tookan_create_delivery_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?

Gives explicit operational guidance: 'confirm with the user first' and 'Deleting (10) is not offered,' which rules out a tempting but invalid action. It doesn't name a sibling tool as the alternative for non-forced status changes, so it falls short of a 5.

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