Twenty MCP by usefulapi

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

Annotations supply only destructiveHint=true, so the description carries nearly the whole behavioral burden. It discloses nothing about duplicate-name handling, whether creation is idempotent, what the response contains (no output schema exists), or auth/scope requirements; the REST endpoint note is mildly useful but not behavioral.

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, front-loaded with the verb+resource and the required field; nothing is padded. It is efficient but so terse that structure is doing little work.

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

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

For an 8-parameter create with a nested passthrough object and no output schema, the description omits the return shape (id/handle?), duplicate behavior, and any auth context. The fully documented schema covers the field-level gaps, keeping this at minimum-viable rather than deficient.

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

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

Schema description coverage is 100%, so the baseline is 3. The description only restates that `name` is required and never explains the non-obvious semantics of the `extra` passthrough object or the flattened address/link fields, so it adds nothing beyond the schema.

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

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

States a specific verb and resource ("Create a new company") that maps cleanly onto the sibling set (get/list/update variants are obviously different operations). It stops short of 5 because it adds no differentiation beyond what the tool name already conveys, and does not say how it relates to twenty_create_person/opportunity or when a company should be created first.

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

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

There is no when-to-use guidance, no prerequisites (workspace, auth, whether the company must already exist for opportunity linking), and no alternative or exclusion mentioned. The only actionable steer is the required-field note, which is already schema information.

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

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

With destructructiveHint present in annotations, the description adds the meaningful scope exclusion (no noteTargets linkage) and the REST mapping, both of which are behavioral context beyond the annotation. It does not reveal auth requirements, side effects, or the response shape, but those gaps are minor for a create operation.

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

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

Three tight sentences, front-loaded with the purpose, then the key fields, then scope and endpoint. Every clause earns its place; the parenthetical aside is the only slightly awkward element.

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

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

There is no output schema, so return values need not be explained. For a 3-parameter create tool with full schema coverage it covers the essentials and adds a useful scope note, though it omits any auth or side-effect context.

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

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

Schema description coverage is 100%, so the schema already documents title, body, and extra. The description merely restates that title is required and body holds content, adding no syntax, format, or constraint detail the schema lacks — the baseline 3.

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

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

States a specific verb+resource ('Create a note'), which inherently distinguishes it from the create_company/person/task siblings. It is clear and unambiguous, but it does not explicitly call out its difference from any named sibling tool the way the highest-scoring examples do.

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 parenthetical '(Attaching to records via noteTargets is out of scope.)' gives a clear when-not constraint, useful because an agent might otherwise expect to link a note to a record on creation. It stops short of naming an alternative tool or describing the full context in which note creation is preferred.

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 supply only destructiveHint=true, so the description carries most of the burden. It does add real value by disclosing the payload transformation (amountMicros + currencyCode collapse into a nested amount object) and the underlying POST /rest/opportunities endpoint, but it says nothing about idempotency, error behavior, auth requirements, or what happens to unknown fields routing through `extra`.

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 clauses, correctly front-loaded with the purpose before the field mechanics. Minor redundancy with the schema on the amount composition, but nothing wasted at the sentence level.

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

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

For an 8-parameter create tool with a fully documented schema, the description covers the essentials. The remaining gap is that with no output schema defined, it never indicates what the call returns (e.g. the created opportunity's id), which a caller needs to chain into follow-up calls.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's parameter notes (`name` required, amount composition) largely restate what the schema property descriptions already say, so it adds little beyond the structured 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?

The description states a specific verb and resource ("Create a new opportunity (deal)") and the alias "deal" helps map to domain language. It clearly separates this from the get/update/list opportunity siblings via the verb, but never names or contrasts an alternative explicitly.

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

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

Usage is only implied by the verb: you call it when you want a new opportunity record. There is no statement of prerequisites, when to prefer update_opportunity instead, or any exclusion — a caller must infer everything from the tool name.

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

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

Annotations only carry destructiveHint=true, so the description carries most of the burden; it does disclose real behavior beyond the schema (field-combination rules like firstName/lastName into name, and the link-shape rewrites for xUrl/linkedinUrl/primaryEmail/primaryPhone) plus 'all fields optional'. It does not mention auth requirements, duplicate handling, or what a successful create 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 compact clauses with no filler: purpose first, then the key optionality/mapping caveat, then the endpoint. Every sentence earns its place and nothing 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?

No output schema exists, so the description would ideally state what a successful create returns (e.g. the new record id) and how duplicates are treated; neither is covered. For a 10-parameter create tool with minimal annotations, the definition is adequate but leaves the agent guessing about the response contract.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds a little value by restating the name-combination rule, but the per-field mapping details (xLink, linkedinLink, emails, phones) already live in the schema descriptions, so the description does not substantially extend parameter meaning.

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

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

States a specific verb and resource ('Create a new person (contact)') and pins it to the underlying endpoint (POST /rest/people). The resource noun alone distinguishes it from the nineteen siblings (create_company, create_note, update_person, etc.) without ambiguity.

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 create verb: it is clearly for creating, not updating or fetching. But there is no explicit guidance on when to use this versus twenty_update_person (e.g. upsert semantics) or how it relates to twenty_create_company for linked records, and no prerequisites 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 only supply destructiveHint=true, which the description neither explains nor contradicts; it is genuinely unclear why a create operation is flagged destructive. The description does add the REST endpoint and flags the required field, but says nothing about auth, idempotency, or what the call returns. Minimal added value over the annotation.

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

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

Three short front-loaded fragments with no filler sentences. The REST endpoint mention is arguably noise for an agent invoking the tool, but nothing is padded or 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 6-parameter mutation tool with a nested passthrough object and no output schema, the description covers only the required field. Because the schema itself is fully described, an agent can still call it correctly, but the destructiveHint goes unexplained and the `extra` passthrough behavior is left entirely to 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 all six parameters (body, dueAt, extra, title, status, assigneeId) are already fully documented. The description only repeats that `title` is required, which the schema's required array and field description already state, adding no new 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 and resource ('Create a task') and even the backing endpoint (POST /rest/tasks), which clearly separates it from the get_/list_/update_ siblings. It lacks explicit sibling naming, but the create verb is unambiguous within this tool family.

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 guidance on when to create a task versus using twenty_update_task or other create tools, and no stated prerequisites (permissions, workspace membership, required fields beyond title). The agent must infer usage from the verb alone.

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 readOnlyHint annotation already declares this is a safe read, so the description only needs to add context, and it does contribute the REST endpoint mapping (GET /rest/companies/{id}) which helpers integrating with the REST API. However, it says nothing about behavior on a missing/invalid id, nor what the 'depth' hydration actually 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?

Two short, front-loaded sentences with zero waste: the core action leads, the endpoint follows as supporting detail. Nothing needs to be trimmed or reordered.

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 full parameter coverage and a readOnly annotation covering the safety profile, the essentials are present. But there is no output schema, and the description does not say what a returned company record contains — a gap it could have filled given that omission.

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

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

Schema description coverage is 100%: both 'id' and 'depth' (with 0-2 bounds and its hydration meaning) are fully documented in the schema. The description adds no parameter detail beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description names a specific verb and resource ('Get a single company by id') and adds the underlying REST route, so an agent knows exactly what it does. It implicitly distinguishes itself from twenty_list_companies by saying 'single ... by id', though it never names or contrasts 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?

The phrase 'by id' implies the precondition (you must already have a company id), which is the minimum viable usage signal. There is no explicit when-to-use versus twenty_list_companies or twenty_list_metadata_objects, and no exclusion guidance.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the underlying REST endpoint (GET /rest/notes/{id}), which reinforces the read semantics, but says nothing about hydration behavior or error cases when the id does not exist.

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. The REST path second sentence is low-value for an agent that never issues raw HTTP calls, so it is mild filler rather than 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 low-complexity single-record read with full parameter documentation and a readOnly annotation, the description is sufficient. With no output schema, the note's return shape is unexplained, but that is a minor gap for a standard entity 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?

Schema description coverage is 100% — both 'id' and 'depth' (including the 0-2 hydration range) are documented in the schema. The description adds nothing beyond it, so the baseline 3 applies.

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

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

States a specific verb+resource+scope: 'Get a single note by id,' which an agent can distinguish from twenty_list_notes. It does not name a sibling explicitly, but the singular 'single note by id' framing makes the boundary 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?

Usage is only implied: use this when you have a note id and want one record. There is no explicit when/when-not guidance or pointer to twenty_list_notes for lookup-by-filter, which is the main alternative an agent would weigh.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered structurally. The description's only added behavioral detail is the REST endpoint mapping (GET /rest/opportunities/{id}), which is minor; nothing is said about not-found/error behavior or what the depth hydration actually 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?

Two short sentences, front-loaded with the core purpose and with zero filler. Every clause earns its place.

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

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

With no output schema and full parameter documentation in the schema, the description is adequate for selecting the tool, but it omits the `depth` hydration behavior's practical effect and any error case for a missing id, leaving a modest gap.

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

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

Schema description coverage is 100%, so both `id` and `depth` are already documented in the schema, including the 0-2 hydration range. The description repeats only 'by id' and adds no format or semantic detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get a single opportunity by id'), which cleanly separates it from the create/update/list/modify siblings. It does not explicitly name those siblings or contrast itself with twenty_list_opportunities, so it falls short of a 5.

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

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

There is no guidance on when to use this versus twenty_list_opportunities or the other twenty_get_* tools. The intended use (fetch one record when you already have its id) must be inferred entirely from the name.

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

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

readOnlyHint=true already establishes this as a safe read, so the description's main addition is the REST endpoint mapping, which is mildly useful context. It does not disclose error behavior for a missing id, whether related hydration counts against limits, or the return shape. Adequate against existing annotations but not rich.

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

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

Two short sentences, zero waste, with the core purpose front-loaded before the endpoint detail. Nothing to trim.

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 single-record read with full schema coverage, annotations marking it read-only, and no output schema, the description covers what an agent needs to invoke it. Only marginal gaps remain, such as error behavior for a non-existent id.

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

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

Schema description coverage is 100%, so both id and depth are already documented in the schema; the description only reinforces 'by id'. The depth parameter (hydration level 0-2), which is the more interesting one, gets no additional explanation 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 (Get), resource (person/contact), and scope (single, by id), which cleanly separates it from twenty_list_people and the other get_* siblings. The REST endpoint mapping (GET /rest/people/{id}) further pins down exactly what it does.

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

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

The 'single ... by id' phrasing implies usage versus list_people, but the description never explicitly states when to use this over alternatives such as twenty_list_people or twenty_get_company, nor any prerequisites. Usage is implied 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, so the safe-read profile is covered by structured data. The description adds the underlying REST endpoint as a traversal hint but says nothing about not-found behavior, error modes, or how the 'depth' hydration affects the response.

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, zero filler, with the core purpose front-loaded and the endpoint detail trailing. Nothing to trim.

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 single-record read this is mostly sufficient, but with no output schema the description does not hint at the return shape or what hydration depth yields, and it is silent on missing-id behavior. Complete enough to invoke, not complete enough to predict the result.

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

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

Schema description coverage is 100%: 'id' and 'depth' (including the 0-2 range meaning) are fully documented in the schema. The description adds no additional parameter meaning 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?

States a specific verb ('Get') with resource ('a single task') and scoping ('by id'), which cleanly separates it from the sibling twenty_list_tasks and from the create/update task tools. The REST endpoint mapping reinforces exactly what the tool retrieves.

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 is implied by the singular 'by id' phrasing and the sibling set (lists vs. single gets vs. updates), but there is no explicit statement of when to use this over twenty_list_tasks or what to do when an id is unknown. Adequate inference, no explicit guidance or 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?

readOnlyHint=true already tells the agent this is a safe read. The remaining content — cursor pagination, verbatim filter/order_by, hydration depth, and the REST mapping GET /rest/companies — is almost entirely restated from the parameter schema, so the description adds little behavioral context beyond it (no rate limits, no response shape).

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

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

Two compact sentences: the primary purpose is front-loaded, the capability list follows, and there is no filler. 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 low-complexity, zero-required-parameter list tool with fully documented parameters and a readOnly annotation, this is nearly sufficient — the cursor pagination model is hinted at and the REST endpoint disclosed. It is slightly short of complete because no output schema exists, yet nothing describes the returned payload (data array, pageInfo) that pagination depends on.

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

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

Schema description coverage is 100%, and the schema already documents comparators, cursor semantics, the 1-60 limit cap, and depth values in more detail than the description. The description's mention of filter/order_by/depth therefore adds no meaning beyond the schema, which makes the baseline 3 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?

"List/filter companies" states a specific verb and resource, and the name/verb pair makes it immediately distinct from twenty_get_company (single record) and twenty_create_company (write). It stops short of naming any sibling or contrasting scope, so it is clear but not fully differentiated in the text itself.

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

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

The description enumerates capabilities (cursor pagination, raw filter/order_by, relation depth) but never states when to reach for this tool versus twenty_get_company or twenty_list_people, nor any prerequisites. Usage is only implied by the verb "List/filter".

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

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

readOnlyHint=true already declares the safety profile, so the description only needs to add context. It does: it discloses that the result includes both standard and custom objects with their fields, and names the underlying REST endpoint (GET /rest/metadata/objects). No pagination or response-shape details, but for an unpaginated metadata listing that is minor.

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

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

One sentence that front-loads purpose, then the discovery use case, then the endpoint reference. No filler; 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?

With no params and no output schema, the description carries the burden of describing the return content, and it does so at a high level (objects plus fields, standard and custom). It stops short of describing the object/field shape an agent will parse, but that modest gap is acceptable for a discovery tool.

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

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

The tool takes no parameters, so there is nothing for the description to disambiguate. Baseline for a zero-parameter tool.

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

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

States a specific verb (List) and resource (metadata objects / schema fields), and explicitly scopes the result to standard + custom objects. It is trivially distinguishable from the sibling CRM entity tools (create/get/list company, person, etc.) which operate on records, not schema metadata.

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

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

Gives a clear when-to-use: 'use this to discover custom objects/fields and valid field names.' That is actionable context an agent needs before writing filters or payloads. It does not name a specific alternative or state when not to use it, but the guidance 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, so safety is covered. The description adds that results are cursor-paginated and can be hydrated to a relation depth, which is genuine behavioral context, but it omits the 60-item cap behavior and what pageInfo/return shape the caller receives.

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 core action and then the notable capabilities and endpoint. No filler, though the REST endpoint reference is mildly redundant with the tool name.

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 a fully documented schema and no output schema, the description covers scope, pagination, filtering, and ordering adequately. The only real gap is that result-shape and default-paging behavior are left to the schema annotations.

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

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

Schema description coverage is 100%, so every parameter (depth, limit, filter, order_by, both cursors) is already documented with syntax examples. The description's mention of "raw filter/order_by" and "relation depth" merely mirrors the schema and adds no new semantics, making the baseline 3 appropriate.

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

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

States a specific verb and resource ("List/filter notes") and discloses the underlying REST operation, which cleanly separates it from twenty_get_note and the create/update siblings. It is clear without explicitly naming an alternative tool.

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

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

The description only asserts capability (pagination, raw filter/order_by, depth) and never says when to reach for this list tool versus twenty_get_note or how to narrow results. No prerequisites or exclusions are given, leaving usage entirely to inference from the name.

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

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

readOnlyHint=true already declares the safety profile, so the description only needs to add context. It does add the REST endpoint (GET /rest/opportunities) and confirms pagination/filtering behavior, but says nothing about result caps, default paging, or what the returned payload looks like.

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 with the core purpose front-loaded and capability list following. No filler or redundancy.

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

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

For a read-only list tool with a fully documented six-parameter schema and readOnlyHint annotation, the description covers purpose and capabilities adequately. The lack of output schema means the response shape is undefined, but that is a minor gap for a list endpoint.

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

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

Schema description coverage is 100%, so the schema already documents every parameter including filter syntax and comparator lists. The description merely names filter/order_by/depth/pagination generically, adding essentially nothing beyond the schema — the baseline 3 is warranted.

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

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

"List/filter opportunities (deals)" gives a clear verb and resource, and the parenthetical disambiguates the domain term. It does not explicitly contrast itself with the get/create/update siblings, but the list verb is self-evidently distinct.

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 notes the supported capabilities (cursor pagination, raw filter/order_by, relation depth), which implies when the tool is useful. It never states when to prefer it over twenty_get_opportunity or twenty_list_metadata_objects, so usage is only implied.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds that filters/order_by are passed verbatim and that cursors come from a previous page's pageInfo, but the cursor mechanics are already documented in the schema and nothing is said about the returned page shape or auth scoping.

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

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

Two short, front-loaded sentences with no filler; the verb+resource leads and capabilities follow. Slightly telegraphic, but 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 read-only list tool with no output schema, the description covers filtering and pagination but says nothing about the response envelope (pageInfo, total count) that an agent must handle. Adequate but with a clear gap.

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

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

Schema description coverage is 100%, so all six parameters are already documented in detail (comparators, cursor meaning, depth range, limit cap). The description only names filter/order_by without adding syntax or constraints beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource ('List/filter people') and clarifies the resource synonym ('contacts'), which an agent can distinguish from get_person. It does not explicitly differentiate itself from the other twenty_list_* siblings, 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?

Usage is implied by 'List/filter people' plus the capability list, but there is no guidance on when to prefer this over twenty_get_person for a single record or over a list tool for another entity. No exclusions or prerequisites 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 carry the readOnlyHint=true safety profile, so the bar is lower. The description adds genuinely useful context beyond that: cursor pagination support, raw filter/order_by passthrough, relation-depth hydration, and the underlying REST endpoint (GET /rest/tasks). It omits rate limits, defaults, and what the response envelope contains, so it adds value but not rich behavioral detail.

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 purpose and then the capability summary. No filler. The REST endpoint mapping is arguably extra, but it is short and useful for debugging/URL reasoning, so the slight redundancy is tolerable.

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

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

For a read-only list tool with no output schema, the description should hint at the return shape — particularly the pageInfo cursors that the starting_after/ending_before parameters depend on. It mentions cursor pagination but never names pageInfo as the cursor source, leaving a small but real gap for correct chained calls.

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

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

Schema description coverage is 100%, so all six parameters are already documented in the schema with ranges, defaults and filter syntax examples. The description only repeats the categories (pagination, filter, order_by, depth) without adding syntax or default information beyond the schema. Baseline 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 clear verb+resource combination ('List/filter tasks') that a reader can distinguish from twenty_get_task, twenty_create_task and twenty_update_task by inference. It doesn't explicitly name those siblings, but the list-vs-single distinction is unambiguous from the wording.

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

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

The description implies when to use it (listing/filtering many tasks) but gives no explicit 'use this instead of twenty_get_task when...' guidance or exclusions. Usage is only implied by the verb, leaving the agent to infer the boundary with the single-record getter.

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

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

Annotations only carry title and destructiveHint=true, so the description must add behavioral context – and it does, via partial-update semantics and the concrete PATCH endpoint. It says nothing about reversibility, permission requirements, or that custom fields must be routed through the 'extra' passthrough, which are material for a mutation.

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

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

Three short front-loaded sentences, no filler, and the partial-update rule appears before the API detail. Every sentence earns its place.

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

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

For a 9-param destructive mutation with no output schema, the description covers purpose, update semantics, and endpoint, and the 100%-covered schema handles field-level detail. The main omission is signaling that non-schema/custom fields go through 'extra'.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds only the partial-update rule; it does not explain the 'extra' passthrough or the link-flattening behavior that the schema itself describes.

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 ('Update fields on an existing company') and the word 'existing' separates it from twenty_create_company. It stops short of naming a sibling alternative or clarifying overlap with twenty_list/get tools, but the purpose 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?

'Only provided fields change' tells the agent this is a partial/PATCH-style update rather than a full replace, which is a genuine usage cue. However, there is no explicit when-to-use guidance, no prerequisite/permission note, and no mention of how to add fields not in the schema.

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

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

Annotations only supply destructiveHint=true and a title, so the description usefully adds that this is a PATCH-style partial update where unspecified fields are untouched, plus the raw endpoint. It says nothing about reversibility, permissions, or any error/not-found behavior for a destructive mutation, leaving real gaps.

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

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

Three short sentences, front-loaded with the action, then the partial-update rule, then the endpoint. Every sentence carries information and there is no filler.

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

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

For a destructive partial-update tool with no output schema, the description covers the essential mechanics: what it mutates and that omitted fields are preserved. It omits permission requirements and failure/return behavior, which are the remaining meaningful gaps.

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

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

Schema coverage is 100%, so the schema already documents all nine parameters including stage examples, micros/currency semantics, and the extra passthrough object. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb (update) and resource (opportunity) plus the partial-update behavior and the underlying endpoint (PATCH /rest/opportunities/{id}). The verb alone distinguishes it from create/get/list/update siblings, but it never names an alternative explicitly.

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

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

Usage is implied by 'update fields on an existing opportunity' and 'only provided fields change,' which tells the agent this is a partial rather than full replacement. There is no statement of when to prefer this over create_opportunity, and no prerequisites such as required permissions or a prerequisite that the record exist.

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

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

Annotations declare destructiveHint=true; the description adds the partial-update semantics ('Only provided fields change'), which is useful behavioral context. But it doesn't disclose reversibility, required auth scopes, or what happens for missing/invalid ids.

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

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

Three short sentences, front-loaded with the action and mutation semantics; nothing wasted.

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

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

Adequate for a partial-update tool with full schema coverage and annotations, but for a destructive mutation it should say more about side effects, error handling, or return shape (no output schema).

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

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

Schema coverage is 100%, so the schema already documents every parameter including the unusual extras passthrough and link-combination behavior. The description adds little param-specific detail beyond saying which fields change.

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 ('Update fields on an existing person'), distinguishes partial-update semantics ('Only provided fields change'), and names the underlying endpoint. Clearly differentiable from twenty_create_person and twenty_get_person.

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

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

States context is an existing person and that it's a partial update, which implies when to use, but names no alternative (create vs update) and no prerequisites (permissions, existence of 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?

The annotations supply destructiveHint=true, so the safety profile is largely covered; the description adds the meaningful behavioral detail that updates are surgical (only supplied fields change) and names the PATCH endpoint. It does not elaborate why the operation is flagged destructive, does not state auth/permission requirements, and says nothing about error behavior for a nonexistent 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?

Three short sentences with zero filler, front-loaded with the core action and followed by the key behavioral rule and the API mapping. Every sentence earns its place and the reader can stop after sentence one if that is all they need.

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 mutation tool with a nested passthrough object and no output schema, the description covers the essentials: the resource, the partial-update rule, and the endpoint. It stops short of noting the required id, authentication expectations, or what happens to omitted fields at the API level, but nothing essential to invoking it correctly is missing.

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

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

Schema description coverage is 100%, so every parameter (including the "extra" passthrough object and the id) is already documented in the schema; the baseline for this dimension is therefore 3. The description adds no parameter-level detail beyond what the schema provides, but it also introduces no confusion.

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

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

States a precise verb and resource ("Update fields on an existing task") and pins the underlying operation to PATCH /rest/tasks/{id}, so an agent immediately knows this is a mutation on the task resource rather than a create/get/list. The verb+resource pairing distinguishes it from the create/get/list siblings in the family, though no sibling is named explicitly.

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

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

"Only provided fields change" communicates partial-update semantics, which is useful context for choosing to call this rather than rewriting the whole record. However, there is no explicit when-to-use statement, no prerequisite (e.g. the task must already exist, required id), and no routing to alternatives such as twenty_create_task or twenty_get_task.

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