Teamleader Focus MCP by usefulapi

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

Annotations already declare readOnlyHint=false, destructiveHint=true, openWorldHint=true and idempotentHint=false, and the 'WRITE:' prefix is consistent with them. Beyond that, the description adds genuine context: the optional colleague notification side effect and the fact that it returns the new note's id, which the annotations do not state.

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

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

A single compact sentence with the mutation flag, the resource scope, an example, the side effect, and the return value — all front-loaded with zero filler. The trailing API mapping ('notes.create') is cheap but useful grounding.

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 discloses the return value (new note id), and the annotations cover the safety profile. It is nearly complete; only the absence of explicit usage boundaries keeps it short of 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 every parameter is already documented, giving a baseline of 3. The description's subject enumeration loosely mirrors the subject_type enum but adds no format, UUID, or notify-list semantics beyond what the schema 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 opens with a specific verb and resource ('WRITE: add a note'), then enumerates the concrete attachable subjects plus an example ('a call summary'). Nothing in the sibling list does the same thing, so an agent can distinguish it immediately 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 is implied by the subject list ('add a note to a contact, company, deal...'), which tells the agent what situations the tool fits. However, there is no explicit when-to-use/when-not guidance and no named alternative (e.g., whether to use a task or note for follow-ups), so a 3 rather than 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?

Annotations already flag readOnly=false, destructive=true, idempotent=false and openWorld=true, so the bar is lower; the description still adds real value by noting that entries spanning midnight are split into two, that the new entry's id is returned, and by naming the underlying API call. It does not warn about duplicate creation despite idempotentHint=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 write intent and the example are front-loaded, followed by the required inputs and optional inputs in a logical order. It is dense but nearly every clause carries information; the redundant "Teamleader: timeTracking.add" trailer earns 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 9-parameter creation tool with no output schema, the description covers the required input combination, optional inputs, a notable side effect (midnight split) and the return value (new entry's id). That is enough for an agent to call it correctly without further documentation.

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

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

Schema coverage is 78%, giving a baseline of 3, and the description improves on it by stating the mutual exclusivity of duration_minutes and ended_at, the subject (customer/ticket/task) pairing, and the invoiceable flag. It still leaves user_id, work_type_id and the subject_type enum semantics 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?

Opens with a specific verb+resource ("WRITE: record time spent") plus a concrete example, and the WRITE marker distinguishes it from the read-only sibling teamleader_list_time_tracking. An agent can identify it without opening the schema.

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

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

"Give started_at plus duration_minutes or ended_at" spells out the required invocation combination, and it lists what is optional (work type, description, subject, invoiceable). It gives clear context for how to call it, though it never explicitly says when to prefer this over teamleader_list_time_tracking or what to do if a duplicate already exists.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=true and openWorldHint=true. The description usefully adds that completion is reversible ('can be reopened in Teamleader'), which softens the destructive framing, but it says nothing about permissions/access requirements or what an already-completed task returns.

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

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

Three short fragments with the mutation marker front-loaded, so an agent gets the mode and action immediately. The 'Teamleader: tasks.complete' tag is auxiliary rather than essential but costs almost 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 one-parameter state-change tool with no output schema, the description covers what happens, the mutation mode, reversibility and the backend method. Only the preconditions (permissions, how to source the id) are absent, which is minor at 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?

There is a single required parameter with 100% schema description coverage (UUID pattern plus 'The task id (a UUID)'), so the schema carries the full burden. The description adds no meaning beyond it, so the baseline of 3 is correct.

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

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

States a specific verb and resource ('mark a task (to-do) as complete') and maps to the underlying API method (tasks.complete), so it is unambiguously distinct from create_task and list_tasks. It stops short of explicitly naming any sibling, which keeps it out of the top band.

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

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

The 'WRITE:' prefix implies this is the mutation path for task state and 'It can be reopened' hints at the counterpart action, but there is no explicit when-to-use guidance versus update/delete, and no note on how to obtain the task_id (e.g., via list_tasks).

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=false and openWorldHint=true; the description corroborates the write nature with its 'WRITE:' prefix and adds useful return info ('Returns the new company's id') in the absence of an output schema. It does not, however, explain the surprising destructiveHint=true for a create, or any duplicate-detection side effects, rate limits, or permission requirements.

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

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

Four short sentences, front-loaded with the WRITE marker, then the required-parameter constraint, then the return value, then the raw API mapping. 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 10-parameter mutation tool with no output schema, the description covers the essentials (mutating, name-only required, returns id), but leaves the other nine fields uncharacterized and says nothing about permissions, error conditions, or duplicate 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 schema has 10 parameters at only 50% description coverage, and the description adds no meaning for the undocumented ones (remarks, website, vat_number, telephones shape, name constraints). It only restates that name is the sole required field, which the schema's required array already 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 and resource ('create a new company in Teamleader'), which is unambiguous against siblings like teamleader_list_companies or teamleader_get_company. It does not explicitly name a sibling to contrast with, but the create/list/get split is obvious from the name and description.

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

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

'Only name is required' gives a minimal calling hint, implying a bare-minimum invocation is valid. However, there is no guidance on when to create a new company versus reusing an existing one, no prerequisites (auth scopes, permissions), and no warnings about duplicate creation.

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

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

Annotations already declare the write profile (readOnlyHint=false, destructiveHint=true, idempotentHint=false, openWorldHint=true), so the 'WRITE:' prefix adds little. The description does contribute real value by stating the return value ('Returns the new contact's id'), but it omits the non-idempotent implication — no duplicate prevention — and any permission or failure context.

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

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

Three short, front-loaded clauses: write marker, required field, return value. The 'Teamleader: contacts.add.' line is marginally useful for traceability but is otherwise noise; nothing else is 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?

No output schema exists, and the description usefully discloses that the new contact's id is returned, which covers the return value. However, for a mutation tool with no idempotency and 8 loosely documented parameters, missing guidance on duplicate handling and on relating a contact to a company (via the sibling create_company tool) leaves an agent under-informed.

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 8 parameters and only 38% schema description coverage, the description is expected to compensate for undocumented fields like remarks, website, first_name and telephones. Instead it only repeats that last_name is required, which the schema already enforces via the required array. Nothing is added about field formats or the telephones structure.

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 contact (person)') plus the Teamleader API endpoint (contacts.add), which clearly separates it from teamleader_create_company and teamleader_add_note. An agent knows exactly what entity is produced 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?

Implies usage through the 'WRITE: create' framing and notes that only last_name is required, but never says when to prefer this over sibling tools like teamleader_create_company or when an existing contact should be looked up via teamleader_list_contacts first. Usage is inferable but not 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?

Annotations already declare write, destructive, non-idempotent, open-world behavior, so the barrier is lower; the description adds a genuine precondition ("for an existing contact or company") and the return value ("the new deal's id"), which matters given there is no output schema. It omits caveats like duplicate creation on retry, but that is already signalled by idempotentHint=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?

Three short sentences, front-loaded with the WRITE marker and the operation, then requirements, then return value. No filler and nothing buried.

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

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

For a 13-parameter mutation with no output schema, it covers the essentials: the write nature, the required fields, the phase cross-reference, and the returned id. It could have covered the company/contact-person relationship and the amount+currency coupling, which are the remaining non-obvious details.

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 85%, so the schema does most of the work; the description mainly restates which fields are required versus optional (customer, title vs. phase, value, probability, closing date). It adds little beyond that and omits notable parameters such as department_id, contact_person_id, source_id, summary, and the value/currency pairing rule the schema itself mentions.

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 an explicit verb+resource ("create a new deal") and immediately narrows scope to "an existing contact or company", which an agent can distinguish from teamleader_list_deals or teamleader_get_deal without consulting either schema. The trailing API mapping ("deals.create") removes any ambiguity about the underlying 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?

It states the required inputs and explicitly routes the agent to teamleader_list_deal_phases for the optional phase, which is a concrete alternative reference. It does not say what to do when the contact/company doesn't yet exist (create it first), so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true and openWorldHint=true, so the safety profile is carried; the description adds valuable behavior beyond that: the 'WRITE:' marker, the fact that it returns the new event's id, and the attendee-restriction constraint. It does not cover failure modes or permission requirements, keeping it below 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?

A compact, front-loaded block: write marker, action, required inputs, constraints, return value, API mapping. Every sentence carries information and nothing is 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?

For a 9-parameter write tool with no output schema, the description still tells the agent what is required, where to source the type id, how to attach relations, and that an id is returned. Only edge cases like timezone handling or validation failures are unaddressed.

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

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

With 67% schema coverage, the description compensates by explaining that activity_type_id comes from a companion list tool, that attendees are firm users only, and that links target customers or deals rather than free-text. That adds real meaning for the loosely documented optional fields.

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 ('put a meeting or call on the Teamleader calendar') and is clearly distinct from teamleader_list_events and the other create_* siblings. An agent can identify the operation immediately.

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 routes the agent to teamleader_list_activity_types for the required activity_type_id, and states that attendees must be firm users while customers/deals go in links. It gives clear context but does not state an explicit when-not-to-use condition.

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

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

Annotations already declare non-read-only, destructive, open-world, and non-idempotent behavior, so the safety bar is lower. The description still adds value beyond them: it discloses the required field set, that linkage fields are optional, and that the call returns the new task's id — a detail the annotations cannot supply.

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 paragraph front-loaded with the operation class and verb; every clause carries information (prerequisites, optional links, return value, source tool), with no filler.

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

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

With no output schema, the description correctly states the return value (the new task id), and it covers the three required parameters plus the linking axes. Minor gaps remain on the plain 'description' and 'estimated_duration_minutes' fields and on permission expectations for a destructive-hinted write.

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

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

Schema coverage is 75%, so the baseline is 3, but the description goes further by explaining that assignment is to 'a user or team' (clarifying the assignee_id/assignee_type pairing) and that a customer, deal, project or ticket may be linked. It omits the free-text description and estimated_duration_minutes fields, so it does not fully compensate.

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 task (to-do)'), flags the operation class up front ('WRITE:'), and names the companion tool (teamleader_list_work_types) rather than leaving the agent to guess among siblings like teamleader_list_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?

Gives concrete prerequisites (title, due date, work type id) and explicitly routes the agent to teamleader_list_work_types to obtain a work type id. It does not discuss when not to use it or alternative paths, but for a create-only tool with no sibling overlap that context is largely sufficient.

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 and openWorldHint=true, so safety profile is fully covered. The description adds the scope of the returned payload (relations, custom fields, remarks), which is useful, but says nothing about permissions, rate limits, or what happens for a missing/invalid id. The trailing 'Teamleader: companies.info' is an API mapping note rather than behavioral context.

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

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

A single front-loaded sentence enumerating the returned fields, plus a short API reference. Every clause earns its place; the API-name suffix is marginal 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 listing what the response contains, which is the key missing information for a getter. Auth/permission requirements and not-found behavior are the remaining gaps, but for a one-parameter read tool it is largely complete.

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

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

Only one parameter (company_id) with 100% schema description coverage including a UUID regex pattern, so the schema carries the full burden. The description adds no format, sourcing, or lookup guidance beyond what the schema already states.

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

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

Names a specific verb ('Fetch') and resource ('one company') and enumerates what 'in full' returns (addresses, VAT, responsible user, related contacts, tags, custom fields, remarks). It distinguishes itself from teamleader_list_companies by emphasizing a single company, though it never names that sibling 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 by 'Fetch one company in full' -- an agent can infer this is the detail lookup after a list operation -- but there is no explicit guidance on when to prefer this over teamleader_list_companies or the create/update siblings, and no prerequisites or error conditions are stated.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds real value by disclosing the return payload contents (linked companies with position, custom fields, remarks), which is the only return-shape information available since no output schema exists. It does not cover error/not-found behavior or permissions.

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

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

Two compact sentences, zero filler, with the payload enumeration front-loaded right after the verb. The trailing 'Teamleader: contacts.info' maps the tool to the underlying API method in a few words.

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 read with no output schema, the description is nearly complete because it enumerates what comes back. The only gap is what happens when the id does not exist or is inaccessible, which an agent may need to plan around.

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

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

Only one parameter with 100% schema description coverage including a UUID pattern, so the schema carries the semantics. The description implies lookup by a specific contact but adds nothing about the id format or behavior on invalid ids. Baseline 3 applies.

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

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

States a specific verb (fetch) and resource (one contact) and enumerates the payload scope: emails, telephones, addresses, linked companies with position, tags, custom fields and remarks. The 'one contact in full' framing makes it distinguishable from teamleader_list_contacts and teamleader_get_company 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?

Usage is implied by the required contact_id and the 'one contact' scope, so an agent can infer it is the lookup-by-id counterpart to the list tool. However, there is no explicit statement of when to prefer this over teamleader_list_contacts or what to do when the id is unknown.

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 safety (readOnly, idempotent, non-destructive), so the lower bar applies. The description adds real value by enumerating the payload fields returned (name, email, account id, language, time zone, teams) and flagging that the call is low-cost, which is the kind of context annotations cannot express.

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

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

Two short sentences, front-loaded with the purpose followed by the practical use case, with zero filler. Every clause carries information an agent would act on.

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

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

With no output schema, the description does the work of describing the return shape by naming the fields, and it notes the call is cheap. Minor gap: nothing about failure behavior when credentials are invalid, though "confirm the connection works" implies an error signal exists.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. It correctly says nothing about inputs rather than padding with irrelevant argument talk.

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 and resource ("Fetch the Teamleader user") scoped precisely to the authenticated identity ("the user the sign-in belongs to"), which distinguishes it from the sibling teamleader_list_users. It even names the underlying endpoint (users.me), removing any ambiguity about 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?

Gives a concrete use case: "A cheap way to confirm the connection works", which tells an agent when to reach for it. It stops short of explicitly stating the exclusion (use teamleader_list_users to enumerate other users), so the routing is implied by "the sign-in" rather than 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 readOnlyHint, idempotentHint, openWorldHint and non-destructive, so safety is covered. The description adds the valuable behavioral detail that this is the *full* record — including derived/related data such as phase history and linked quotations — which is not derivable from annotations or the one-parameter 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 sentences, front-loaded with the payload enumeration and finished with an API reference. 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 telling the agent what comes back, and it does so thoroughly for a read-only single-record fetch. What is missing is only secondary: error behavior for an invalid/unknown deal_id and the absence of an explicit pointer to the list tool.

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

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

Schema description coverage is 100% and the single deal_id parameter is documented in the schema as a UUID with a regex pattern. The description adds no parameter-level detail (e.g. how to obtain a deal_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 ("fetch") plus resource ("one deal") plus an enumeration of exactly what is returned (lead, value, probability, phase history, quotations, custom fields). The word "one" cleanly separates it from the sibling teamleader_list_deals, and the included-field list separates it from teamleader_create_deal or the contact/company getters.

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: it needs a known deal_id, so it is the single-record lookup rather than the list. However, no alternative is named explicitly (teamleader_list_deals is never mentioned), and there is no statement of when-not-to-use or what to do if you only have a name instead of a UUID.

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, so the safety profile is covered. The description adds genuine value by disclosing the content of the result (grouped line items, totals and taxes, payments received, Peppol status) and naming the underlying Teamleader endpoint (invoices.info), which no structured field provides.

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 sentence, front-loaded with the action and payload summary, followed by the API mapping. Nothing is wasted and nothing essential is buried.

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

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

With no output schema, the field enumeration is what tells the agent what a 'full' invoice contains, which is the key missing structured information. A brief note on failure behavior for an invalid or unknown UUID would make it 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?

There is a single required parameter whose schema description and UUID regex fully document its format (100% coverage). The description adds no syntax or format detail beyond that, so the baseline of 3 applies.

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

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

The description opens with a specific verb and resource ('Fetch one invoice in full') and enumerates the data domains returned, so the agent knows exactly what comes back. It only implicitly distinguishes itself from teamleader_list_invoices via the word 'one' rather than naming the sibling.

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

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

Usage is implied rather than stated: fetch a single invoice when you have an invoice_id. There is no explicit guidance on when to prefer this over teamleader_list_invoices, and no note about prerequisites such as needing a valid existing UUID.

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, and openWorld, so safety is covered. The description adds value by disclosing the full set of fields returned ('in full: code, description...'), compensating for the absence of an output schema. It doesn't discuss error behavior for missing products, so not a 5.

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

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

A single sentence, front-loaded with the verb and resource, with the field enumeration earning its place by standing in for a missing output schema. No waste.

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

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

For a one-parameter read with no output schema, the description is nearly complete: it lists what fields are returned and identifies the resource. Missing only explicit guidance on unknown-id behavior and the relationship to list_products.

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

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

Only one parameter and schema coverage is 100%, with the schema documenting the UUID format. The description's 'one product' confirms single-id lookup but adds no syntax or format 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?

States a specific verb (fetch) and resource (one product) and enumerates the returned fields (code, prices, tax rate, stock, category), which clearly differentiates it from the sibling list_products.

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?

'Fetch one product' implies a single-record lookup by id, distinguishing it implicitly from list_products, but the description never explicitly says when to prefer this over the list tool or that it requires a known product_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 declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds the scope of returned data ("in full: deal, grouped line items, discounts, totals, taxes, status and expiry"), but says nothing about error behavior, e.g. what happens with an unknown or missing quotation id.

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 front-loaded clause naming the resource and its payload, plus a terse API-mapping note. No filler; every fragment carries information.

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

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

With no output schema, the description usefully enumerates what a full quotation record contains, which is the main thing an agent needs. It stops short of failure semantics, but for a simple single-id read that 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?

Single parameter with 100% schema description coverage (UUID with a regex pattern), so the schema fully documents it. The description adds no extra detail about the id, which is acceptable given the 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?

States a specific verb and resource ("Fetch one quotation") and enumerates the returned content, which cleanly separates it from teamleader_list_quotations. An agent can tell immediately this is the single-record read.

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

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

The singular "one quotation" implicitly contrasts with the list sibling, but there is no explicit when-to-use/when-not statement or mention of alternatives. Usage is inferable rather than stated.

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

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds the useful detail that the response is the full record rather than a summary, but says nothing about not-found behavior, permissions, or expansion options.

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 sentence, front-loaded with the action and scope, followed by the returned fields and the API reference. Nothing redundant.

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

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

With no output schema, enumerating the returned fields is genuinely valuable and largely discharges the return-value burden. Only error/not-found semantics are left unstated, which is a minor gap for a read-only single-record fetch.

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 parameter and the schema documents it at 100% coverage (UUID pattern, 'The subscription id'). The description adds nothing about the id beyond what the schema already says, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Fetch one subscription in full') and enumerates the payload contents (invoicee, line items, totals, billing cycle, dates, payment term). It is distinguishable from teamleader_list_subscriptions only by inference from 'one'.

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

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

The single-record wording implies you call this when you already have a subscription id rather than browsing, but no alternative (e.g. the list tool) or precondition is named explicitly.

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 covered. The description adds real context beyond that: the result set is a fixed three-item enumeration and serves as a prerequisite for event creation. It stops short of describing the returned id/name shape or pagination behavior on a small list.

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

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

Three short sentences, each carrying distinct information: what the tool lists, what the values are, and why the agent needs it. Zero filler and the essential fact is front-loaded.

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

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

For a two-parameter, zero-required lookup with no output schema, the description plus annotations plus full schema coverage gives the agent everything needed to call it correctly. Only the concrete return shape (id/name fields) is left implicit.

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

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

Schema description coverage is 100%, with both page and page_size documented including the Teamleader default of 20, so the description needn't repeat them. It adds no parameter guidance of its own, which is the correct baseline 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 and resource ('List the activity types of calendar events') and immediately enumerates the domain values (tasks, meetings, calls), so the agent knows exactly what comes back. It also names the upstream Teamleader API endpoint, which disambiguates it from lookups like list_work_types or list_events.

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

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

Gives a concrete trigger: an activity type id is REQUIRED to create a calendar event, which tells the agent this is a prerequisite lookup before teamleader_create_event. It doesn't spell out when *not* to call it or mention alternatives, but for a small enum-like lookup the usage context is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds that filtering is possible across several facets but reveals nothing about result volume, default page size behaviour, or how multiple filters combine — the 'Teamleader: companies.list' line is an API reference, not behavioral context.

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

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

Two short sentences, front-loaded with the core action and the filter capabilities. The trailing 'Teamleader: companies.list' identifier is marginal overhead but negligible.

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 10-parameter, non-required listing tool with no output schema, the description covers the entry point but stays silent on pagination defaults, sorting, and what a company record contains. Annotations handle safety, and the schema handles most params, so the gaps are moderate rather than blocking.

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

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

Schema description coverage is 80%, so the schema already documents term, email, vat_number, tags, updated_since and paging. The description's filter list largely restates those fields and adds no syntax or format detail (e.g. that `term` is a broad multi-field search while `email` is exact). 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 or search companies (organisations)') and sketches the filter surface. It does not explicitly name the sibling it is not, so an agent must infer that single-record retrieval belongs to teamleader_get_company rather than being told.

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 'List or search' — the description never says when to prefer this over teamleader_get_company or how it relates to lookup-by-id. No prerequisites, no exclusions, no explicit routing advice.

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 openWorldHint, so the safety profile is covered. The description adds the available filter axes but says nothing about result volume, pagination behavior, or what happens when no filters 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?

Two compact sentences, front-loaded with the core action and followed by the filter inventory. The trailing 'Teamleader: contacts.list' endpoint tag is meta-information of limited 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?

For a read-only listing tool with 10 optional parameters and no output schema, the description plus rich per-parameter schema documentation covers enough to call it correctly. Sort options and pagination defaults live 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 description coverage is 80%, so the schema already documents term, email, tags, company_id, status, and updated_since precisely. The description's filter list mirrors the schema without adding format, defaults, or combination semantics, 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 and resource ('List or search contacts (people)') and disambiguates that contacts are people, not companies. It does not explicitly distinguish itself from siblings like teamleader_get_contact or teamleader_create_contact, so it stops short of a 5.

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

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

The filtering sentence implies when to use it (bulk retrieval/filtering) and the 'search term' phrasing hints at lookup use, but there is no explicit when-to-use vs. get_contact guidance or stated 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, and destructiveHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the return ordering (flow order) and that probability is included per phase — useful behavioral context a schema can't convey since 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 sentences with zero waste: the resource and ordering come first, followed by the practical usage hint. Nothing is redundant or 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?

For a simple read-only list tool with no output schema, the description covers what is returned (phases, order, probability) and how it's used. Pagination behavior is left entirely to the schema, a minor gap but adequate overall.

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 page, page_size, and deal_pipeline_id are fully documented in the schema. The description referencing "deal pipelines" loosely hints at the pipeline filter but adds no format or scoping detail 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?

Specific verb (List) plus resource (phases of deal pipelines) and adds distinguishing detail: flow order and probability. An agent can easily differentiate it from the sibling teamleader_list_deal_pipelines, which returns pipelines rather than their phases.

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

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

"Use a phase id when creating a deal" gives a clear downstream use case that motivates calling this tool before teamleader_create_deal. It lacks explicit when-not conditions or naming of alternatives, but the context is clear enough to guide 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 declare readOnlyHint, idempotentHint, and non-destructive, so safety is covered. The description adds value beyond the annotations by noting that the reply's meta names the default pipeline, which an agent could not infer from structured fields. It doesn't discuss pagination behavior, keeping it from a 5.

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

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

Three terse sentences, front-loaded with the core purpose and actionable follow-up. The trailing 'Teamleader: dealPipelines.list.' is a minor API-reference flourish but costs almost 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 simple read-only list tool with full annotation coverage, good parameter documentation, and no output schema, the description is nearly complete—it even explains the default-pipeline meta detail. Adequate to call correctly; only pagination semantics are unaddressed.

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

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

Schema coverage is 75%, with page, page_size, and term documented; only the status enum lacks a description. The description adds no meaning beyond the schema, so the high-coverage baseline of 3 is appropriate.

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

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

States a specific verb and resource ('List the sales pipelines') and distinguishes usefully from the sibling list_deal_phases by explaining how the pipeline id feeds that tool. An agent can tell exactly what this returns and how it differs from related listing tools.

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

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

Explicitly tells the agent to use a returned pipeline id with teamleader_list_deal_phases, giving a clear downstream use case. It stops short of explicit when-not conditions or alternatives for listing itself, so a 4 rather than a 5.

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

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

The annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is clear. The description adds filter context but does not explain pagination behavior, rate limits, result ordering, or other operational details beyond what the schema and annotations provide.

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

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

The description is two short sentences plus a compact API reference, with no wasted text. The core action and key filters 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?

For a 14-parameter read-only listing tool with no output schema, the description gives enough context to understand the resource and the major filter dimensions. The schema carries the detailed parameter semantics, though the description could mention pagination or return shape more explicitly.

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 93%, so the schema already documents nearly all parameters thoroughly. The description enumerates several filters, but it does not add meaning beyond the schema, such as clarifying how customer_id and customer_type interact or how date filters combine.

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

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

The description clearly states a specific verb and resource: list or search deals (sales opportunities). It does not explicitly distinguish this listing/search tool from get_deal or list_deal_pipelines, so it falls short of the top score.

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 implies usage by naming filter dimensions such as customer, phase, pipeline, status, responsible user, and dates, but it does not explicitly say when to use this tool instead of get_deal or how to choose among list tools. The guidance is adequate but incomplete.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds useful domain context about what a department represents and how ids are consumed elsewhere, but it does not disclose pagination behavior, return shape, or limits for a list operation.

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

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

The description is two focused sentences plus an API reference. The core purpose is front-loaded, the parenthetical definition is useful, and the dependency sentence earns its place by explaining why the tool matters.

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

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

For a simple read-only list tool with no output schema, the description covers what the resource is and how its ids are used downstream. It omits return fields and pagination, but given the annotations and optional filtering schema, an agent has enough to 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?

The description does not mention the status, sort_field, or sort_order parameters. Schema coverage is moderate at 67%: status and sort_order have brief schema descriptions, while sort_field is only inferable from its enum. The schema therefore carries most parameter meaning, and the description adds none, which is adequate but leaves a clear gap.

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

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

The description states a specific verb and resource ('List the account's departments') and defines what departments are in this system: company entities that issue invoices and quotations. This is more than a restatement of the name and gives an agent enough information to distinguish this tool from general company or invoice listing 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?

It explains why an agent would need this list: a department id is required to filter subscriptions and product categories or to create a deal for a specific entity. That is clear usage context, though it does not explicitly name alternative tools or when not to use this one.

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, openWorldHint and destructiveHint=false, so the safety profile is fully covered without the description. The description adds only that results are time-window scoped and that it maps to Teamleader events.list; it says nothing about pagination defaults, result ordering, or result volume.

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

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

Two tight sentences: the first front-loads what is listed and its time scope, the second enumerates the available filters. No filler, and the API mapping note is short.

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 13 all-optional parameters and 92% schema coverage, the description covers purpose, scope and filter surface adequately, and annotations cover safety. The only meaningful gap is pagination/result-set behavior (page, page_size, default 20) which the agent must read from the schema instead.

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 92%, so the schema already explains every filter precisely, including UUID patterns and ISO 8601 formats. The description's filter enumeration (user, activity type, term, attendee, link, task, done) largely restates the schema rather than adding semantics such as how link_id and link_type combine or how the time window pairs with starts_before/ends_after.

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 calendar events') and narrows the scope with '(meetings, calls) in a time window', so an agent knows exactly what entity is returned. It does not explicitly distinguish itself from siblings like teamleader_list_tasks or teamleader_list_activity_types, which keeps it at 4 rather than 5.

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

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

The enumerated filters imply when the tool is useful (find events by user, contact, deal, task, done state), but there is no explicit 'use this instead of X' guidance or statement of preconditions. Usage must be inferred from the filter list.

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 read-only and idempotent safety, so the description correctly spends its words elsewhere: it discloses what comes back ('totals, due date and paid state') and clarifies the otherwise cryptic 'matched' enum value as paid. It says nothing about pagination limits or total-result counts, which is the main remaining gap.

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

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

Three short sentences: purpose first, filter capabilities second, return shape third. No filler, no restatement of the title, and the backend method reference is compact and last.

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

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

No output schema exists, and the description compensates by naming the returned summary fields (totals, due date, paid state). For a 14-parameter, zero-required listing tool it covers what an agent needs to filter and interpret results; only result-count/pagination behavior is left implicit in the schema.

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

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

With 86% schema coverage the schema does most of the work, but the description adds real meaning by grouping filters by intent and, critically, translating 'matched = paid' — a mapping the enum alone does not convey. It does not add syntax for term or the customer_id/customer_type pairing beyond what the schema states.

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

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

States a specific verb and resource ('List or search outgoing invoices') plus the 'outgoing' scope qualifier, which is meaningful. It does not explicitly contrast with the sibling teamleader_get_invoice (single invoice), but the list/search framing makes the distinction obvious.

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 enumerated filter dimensions imply when to use this tool (browsing/searching invoices by status, customer, deal, project, dates), but there is no explicit statement of when to prefer it over teamleader_get_invoice or another listing tool. Usage is inferable rather than stated.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld). The description adds a return-content hint ('their text and date'), but says nothing about ordering, pagination behaviour or what happens with an invalid subject id.

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 front-loaded sentence that gets to the point quickly. Minor filler in 'and more' and the trailing 'Teamleader: notes.list.' API mapping, which an agent gains little from.

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

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

A simple read-only list tool with full schema coverage, complete annotations, and a return-content hint that substitutes for the missing output schema. The only real gap is that the description doesn't clarify that exactly one subject type/id pair is queried per 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 description coverage is 100%, so page, page_size, subject_id and subject_type are all documented in the schema. The description only loosely restates the subject types already enumerated and adds nothing about page/page_size semantics; 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 (list) and resource (notes) plus the set of attachable subjects, so an agent can tell it apart from teamleader_add_note. It does not explicitly name the write-side alternative, but the read/list framing is 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?

No statement of when to use this versus alternatives, no prerequisites (e.g. needing a valid subject id), no note about paging through results. Only implied usage from the resource list.

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 and openWorldHint=true, so the safety profile is covered. The description adds the useful 'ledger account' framing but says nothing about pagination, return volume, or ordering across an open-world backend.

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

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

Two tight sentences with the core purpose front-loaded and the optional filter immediately after. The trailing 'Teamleader: productCategories.list' API reference adds little for an agent but costs only a few tokens.

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-optional-parameter read tool with rich annotations and no output schema, the description covers what the tool returns conceptually (ledger-account categories). Only minor gaps remain: no hint on result size, pagination, or empty results.

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 optional parameter department_id is fully documented in the schema. The description's 'optionally for one department' restates rather than extends 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 the specific verb and resource ('List the product categories') and adds a clarifying gloss that each category is a ledger account, which meaningfully distinguishes it from sibling teamleader_list_products. It does not explicitly name the neighboring product/department tools as alternatives, but the resource is 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?

'Optionally for one department' implies the filtering use case and conveys that unfiltered listing is the default. However, it gives no explicit when-to-use guidance relative to sibling tools like teamleader_list_products or teamleader_list_departments, leaving selection to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and openWorld, so the safety profile is covered. The description adds only that this is the price-list resource; it says nothing about pagination behavior, total counts, or what a 'term' match does (prefix vs substring).

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 action and resource. The trailing 'Teamleader: products.list.' is API-reference filler but costs 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?

All parameters are optional and fully documented in the schema, and no output schema exists, so the description needn't explain every field. However, for a paginated list tool it gives no hint about the shape of the result (paged envelope, total count), leaving the agent to discover this after the 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 all four parameters are already documented with constraints and formats. The description's only added signal is that 'term' matches name or code, which the schema itself already states — 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+resource (list/search products) and clarifies the domain with '(the price list)', which disambiguates it from invoices, quotations and product categories. It doesn't explicitly contrast itself with teamleader_get_product or teamleader_list_product_categories, so sibling differentiation is only implicit.

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 'list or search ... by name or code' implies that the search path is used when you have a term, but there is no explicit guidance on when to use this versus get_product (single lookup) or list_product_categories, and no stated 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, idempotentHint and non-destructive, so the safety profile is covered. The description adds genuinely useful context by naming the fields returned (budget, time tracked, billed/unbilled, dates, owners), though it says nothing about pagination behavior or result volume beyond what the schema implies.

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: identity and module first, filters second, return payload third. No filler, no repetition of the title.

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

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

For a 7-parameter, zero-required, paginated list tool with no output schema, the description covers both the filtering surface and the return payload, which is what an agent needs to decide relevance. It could go further on pagination limits and on what happens when no filters 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 86%, so the schema already documents term, status, deal_ids, customer_id and pagination. The description's 'filter by term, status, customer or deal' merely restates the schema at a coarser grain, and notably omits the customer_type pairing rule that the schema does cover.

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 projects') and pins it to the projects module, which distinguishes it from the deal/contact/invoice list siblings. It stops short of explicitly contrasting with adjacent tools like teamleader_list_deals, but the resource is 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?

The description lists the available filter dimensions, which implies how to narrow results, but never states when to prefer this over alternatives such as teamleader_list_deals or teamleader_get_company, and gives no exclusions or prerequisites. Usage is inferable rather than 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 annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description's real added value is the API limitation that filtering works only by id — a genuine behavioral constraint absent from the schema. It says nothing about pagination behavior, result ordering, or what happens when ids exceed the 100-item cap.

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

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

Three short sentences, front-loaded with the purpose before the filtering caveat and the upstream-tool pointer. The trailing 'Teamleader: quotations.list.' endpoint note is marginal but harmless; nothing else is 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?

For a read-only list tool with full annotation coverage, no output schema and three well-documented parameters, the description supplies what matters: scope of filtering and source of ids. Pagination is handled by the schema, so no meaningful gap remains for correct invocation.

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

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

Schema description coverage is 100%, so the schema alone sets a baseline of 3. The description goes beyond it by explaining why only 'ids' exists as a filter and where those ids come from, which resolves the most likely agent error (trying to filter by deal).

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 quotations') and disambiguates the domain term with the alias '(offers)', plus names the payload fields (status, totals, deal). It is clearly distinct from the singular teamleader_get_quotation, though that sibling is never 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?

Gives actionable routing: 'Teamleader filters quotations only by id: to find a deal's quotations, take the ids from teamleader_get_deal.' That tells the agent both the constraint and the correct upstream tool. It does not state when to prefer teamleader_get_quotation for a single record or what to do when ids are unknown for a non-deal context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered and the description's job is lighter. The description adds the returned field set, but says nothing about pagination defaults, total counts, or whether results are paged by the Teamleader API — meaningful gaps for a 10-param list tool with 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 sentences plus a short API reference; the resource is front-loaded, the returned fields precede the filter list. 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?

Ten optional params and no output schema, but the description compensates by naming the fields returned, which is the most important missing piece. What remains unaddressed is pagination behavior and sort semantics, minor gaps that annotations and the schema largely fill in.

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

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

Schema description coverage is 80%, so the schema already documents page, page_size, customer_type and most filter params. The description restates the filter dimensions (customer, deal, department, status, invoice) without adding format, combinability, or array/single-value semantics beyond what the schema provides, so baseline 3 fits.

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

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

States a specific verb ('List') and resource ('subscriptions (recurring invoices)'), and enumerates the key fields returned (title, status, customer, billing cycle, next invoice date). The plural/list framing plus explicit filters clearly separates it from the sibling teamleader_get_subscription and from teamleader_list_invoices.

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

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

Names the filter dimensions (customer, deal, department, status, invoice), which implies when to reach for this tool, but gives no explicit when-not conditions or pointers to alternatives such as teamleader_get_subscription for a single record. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is fully covered structurally. The description adds only the API mapping ("Teamleader: tasks.list") and no extra behavioral context like result ordering or pagination behavior, which is acceptable given annotation coverage.

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

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

A single sentence with the core purpose front-loaded and filters following; no wasted prose. The trailing "Teamleader: tasks.list" is minimally useful API identification but borderline 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 12-parameter list tool with no output schema, the description covers filtering but says nothing about return shape, pagination behavior, or default page size beyond what the schema hints. Adequate to invoke, but not complete.

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

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

Schema coverage is 75% with good per-parameter descriptions, so the schema does most of the work. The description names several filters (user, completed, scheduled, due range, term, customer) that map onto real parameters but omits page/page_size/sort semantics, adding only modest 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+resource ("List tasks (to-dos)") and enumerates the filter capabilities, so an agent knows this is a query tool, not the mutating teamleader_create_task sibling. It stops short of naming any alternative explicitly, so it is clear but not fully differentiated.

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

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

The listing of filters implies when the tool is applicable (e.g., 'filter by assigned user, completed, scheduled...'), but there is no explicit when-to-use/when-not guidance and no pointer to alternatives such as retrieving a single task or listing users.

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, openWorld and non-destructive, so the safety profile is covered. The description adds value beyond that by previewing the returned fields, which matters since no output schema exists; it does not mention pagination limits, sort order, or default result size, which are left to the schema.

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

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

Two compact sentences with no waste, front-loading the resource and returned fields before the filtering note. Every clause carries 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 six-parameter, zero-required list tool with no output schema, the description covers the essential shape: what comes back and what can be filtered on. Minor gaps remain around result ordering, pagination behavior and whether closed/archived tickets are included, but nothing blocks a correct 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 83%, so parameters are largely self-documenting and baseline is 3. The description's 'filter by customer, project or assignee' maps onto customer_id, project_ids and assignee_ids but adds no syntax or constraints beyond what the schema already states, and it never mentions customer_type or the paging 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?

Specific verb ('List') plus resource ('support tickets') and an explicit enumeration of the fields returned (subject, status, assignee, customer, project, last message time). No sibling tool covers tickets, and the resource naming cleanly separates it from list_deals, list_invoices, list_projects, etc.

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?

'Filter by customer, project or assignee' implies when this tool is the right choice (narrowing a ticket set), but there is no explicit when-to-use/when-not guidance and no named alternative for, say, fetching a single ticket or listing all tickets unfiltered. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds genuine value by disclosing the response shape (who, when, duration in seconds, work type, subject, invoiceable flag, hourly rate), which matters since there is no output schema. It omits pagination defaults and sort behavior, which are only implied by the schema.

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

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

Two short sentences: the returned-field inventory is front-loaded, followed by the filtering summary. Nothing is repeated and every clause carries information the caller 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 read-only list tool with 8 fully documented optional parameters and no output schema, the description covers the essential gaps by naming the returned fields. It falls short of full completeness in not stating pagination behavior or the default sort, though those are partially recoverable from the schema.

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

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

Schema description coverage is 100%, so the baseline applies: every parameter is already documented, including the page/page_size defaults, the ISO 8601 formats and the subject_type enum. The description's filter sentence adds nothing about syntax or format beyond the schema and does not mention page, page_size, sort_order or subject_type pairing.

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

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

Opens with a specific verb+resource ("List tracked time entries") and then enumerates the returned fields, so the agent knows exactly what domain object is being fetched. No sibling tool covers time tracking, and the field list makes the boundary with list_work_types or list_users obvious.

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

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

The description says "Filter by user, start range or subject," which is effectively a restatement of the available filters rather than guidance on when to reach for this tool versus a sibling. There is no explicit when-to-use, when-not-to-use, or named alternative, leaving usage implied.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds account scoping and the downstream purpose, but says nothing about pagination limits, rate limits, or auth requirements beyond what the schema's page/page_size fields imply.

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 purpose front-loaded and the use case immediately after. The trailing "Teamleader: users.list." mapping is mildly redundant but harmless for traceability.

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 4-parameter, zero-required list tool with full schema documentation and read-only annotations, the description covers what the tool returns (users/colleagues) and why to call it. No output schema exists, but the return concept is adequately conveyed; only result shape details are absent.

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

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

Schema description coverage is 100%, with page, term, status and page_size all documented inline (including the Teamleader default of 20). The description adds no filter syntax or behavioral notes about the parameters, so the baseline of 3 applies.

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

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

The description uses a specific verb and resource ("List the users (colleagues) in the Teamleader account") and clarifies that 'users' means colleagues, removing ambiguity. It does not, however, distinguish itself from teamleader_get_current_user or teamleader_get_contact, which an agent could reasonably confuse it with.

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

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

It gives a concrete use case: "find a user id to assign deals or tasks to", which tells the agent when this tool is the right choice. It stops short of naming alternatives (e.g. get_current_user for the caller's own record) or exclusions, so it is clear context without routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds useful details beyond annotations, namely alphabetical ordering and the dependency on task creation, but it does not describe return shape, pagination behavior, or rate-limit/auth context.

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

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

The description is three compact clauses with no wasted wording, and the core purpose is front-loaded. The API reference is short and does not distract from the operational guidance.

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

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

For a simple read-only list tool with full schema coverage and clear annotations, the description is complete enough to support correct selection and invocation. It gives ordering and task-creation dependency, though it could explicitly mention pagination or that results are paginated.

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 page, term, and page_size are already documented in the input schema. The description does not add any parameter-specific meaning beyond noting alphabetical ordering, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource (list work types), gives concrete examples, and specifies alphabetical ordering. It also distinguishes the resource by noting that a work type id is required to create a task, which helps an agent separate this lookup tool from task-creation tools.

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

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

The description gives clear usage context by stating that a work type id is REQUIRED to create a task, implying this tool should be used before task creation. It does not explicitly name teamleader_create_task as the alternative or say when not to use it, but the practical guidance is strong.

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