twenty

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

The destructiveHint annotation already signals mutation. The description adds only that 'name is required' (already in schema) and the REST endpoint. It does not disclose return values, idempotency, or other side effects of creation, so transparency is limited beyond annotations.

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

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

The description is a single, front-loaded sentence plus a compact REST endpoint reference. Every word earns its place; there is no fluff 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?

With no output schema, the description should at least hint at the return value or post-creation behavior, but it does not. It also leaves the nested 'extra' passthrough and URL transformation semantics entirely to the schema. For an 8-parameter create tool with no output schema, the description is under-specified.

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

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

Schema description coverage is 100%, so the schema fully documents all 8 parameters including the required 'name'. The description adds no extra meaning beyond noting 'name' is required, which is already present in the schema. 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 states 'Create a new company' with a specific verb+resource, clearly distinguishing it from sibling create tools like twenty_create_note or twenty_create_person. Mentioning the REST endpoint adds further precision.

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

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

Usage is implied: use this when you need to add a new company. However, there is no explicit guidance on when to prefer this over related tools (e.g., update_company or list_companies), nor any exclusions or prerequisites.

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

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

There is a direct contradiction: the description states the tool 'creates' a note (a non-destructive operation), while annotations declare destructiveHint=true. This misalignment is misleading and severely undermines trust. Additionally, the description provides no behavioral details such as side effects, permissions, or return behavior.

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

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

The description is two sentences, front-loaded with the core action, and includes the REST endpoint for reference. Every sentence adds useful information without unnecessary verbosity.

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

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

The tool has no output schema and the description does not explain what the tool returns (e.g., the created note object) or what errors might occur. The destructiveHint contradiction further confuses the expected behavior. For a create operation, the description is underspecified.

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

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

The input schema already provides descriptions for all three parameters (100% coverage), so the description adds little on top. It does restate that title is required and body holds content, and mentions noteTargets is out of scope, but the latter is not a parameter. Since schema coverage is complete, the description's marginal semantic addition keeps this at 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?

The description clearly states 'Create a note' with a specific verb and resource, and distinguishes this tool from sibling create tools for other entities (company, opportunity, person, task). It also mentions that attaching to records via noteTargets is out of scope, further clarifying its capabilities.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives. The only contextual hint is the out-of-scope note about noteTargets, but it does not name any alternative tool or state conditions for use. The tool name implies its purpose, but the description offers no actionable selection criteria.

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

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

The description says 'Create a new opportunity', implying a non-destructive operation, while annotations declare destructiveHint: true. This is a direct contradiction. Additionally, no further behavioral context is provided (e.g., side effects, auth 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?

One concise sentence, front-loaded with the core purpose, no redundant text. However, it is slightly dense with backticks, but still efficient.

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

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

Despite having 8 parameters and a nested object, the description is minimal and fails to explain return behavior or consequences. The annotation contradiction further reduces completeness, as the agent receives conflicting signals about the tool's safety.

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

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

Schema coverage is 100% with detailed parameter descriptions. The tool description adds a note about amountMicros+currencyCode combining into amount, but that is already present in the schema. No meaningful additional semantics.

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

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

The description clearly states the action ('Create') and the resource ('opportunity (deal)'), distinguishing it from sibling create tools for other entities. It also mentions the required `name` field, which is helpful.

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 use this tool versus alternatives like update_opportunity, or any context about prerequisites or exclusions. The description is purely declarative.

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

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

The description adds behavioral context beyond the destructiveHint annotation by explaining that all fields are optional and that firstName/lastName are combined into a nested name object. It also discloses the underlying REST method and path. While it does not discuss error conditions or permissions, it provides useful transformation details.

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 short sentences front-loaded with the core purpose. It wastes no words and includes only essential information: the action, the field optionality, a key transformation, and the REST endpoint.

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

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

For a tool with 10 optional parameters and no output schema, the description is reasonably complete. It explains the endpoint and the name combining behavior. It does not describe what the creation response contains, but the absence of an output schema lowers that expectation. The schema covers the parameter 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 100%, with each parameter already described in detail, including mapping conventions like 'xUrl sent as xLink:{primaryLinkUrl}'. The description's note that all fields are optional is also implicit in the schema (no required parameters). Thus the description adds minimal new parameter-level meaning beyond the schema.

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

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

The description opens with 'Create a new person (contact)', a specific verb and resource that clearly distinguishes it from sibling tools like create_company or create_note. It also includes the REST endpoint, reinforcing the precise action.

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 context is clear: this tool is for creating a person. Sibling tools target different entities (company, note, etc.), so the resource name makes the usage context obvious. However, it does not explicitly state when not to use it or mention alternatives, which would warrant a 5.

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

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

Annotations already include destructiveHint=true, indicating this is a mutation. The description adds only the REST endpoint, which is implementation detail rather than behavioral context such as what is created, return format, or permissions. No additional transparency beyond the annotation is provided.

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 exceptionally concise: a single sentence with the core action plus a REST endpoint hint. No word is wasted, and the most important information is front-loaded.

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

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

Given the absence of an output schema and the presence of six parameters including a nested 'extra' passthrough, the description is too terse. It does not explain what the tool returns, how 'extra' should be used, or any other operational context necessary for complete understanding.

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

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

Schema has 100% description coverage with meaningful per-parameter descriptions. The description's note that 'title is required' is redundant with the schema's required field and adds no extra semantic value. The baseline of 3 applies because schema carries the parameter details.

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 'Create a task' with a specific verb and resource, which distinguishes it from sibling tools like create_company or create_note. It also provides the underlying REST endpoint for clarity.

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 does not provide any guidance on when to use this tool versus alternatives, nor does it mention prerequisites or exclusions. The only usage hint is the implied context from the tool name and the required 'title' field.

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 read-only nature is known. The description adds the REST endpoint but no further behavioral details (e.g., error handling, depth behavior). It does not contradict 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?

A single, succinct sentence that fully conveys the tool's purpose. 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 simple get-by-id tool with full schema coverage and a readOnly annotation, the description is complete. No output schema exists, but the return value (the company) is implied by the operation.

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 id and depth well-described. The description adds no additional parameter semantics beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool 'Get a single company by id', using a specific verb and resource, and distinguishes from sibling list/create/update tools. It also provides the REST endpoint for clarity.

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

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

The description gives clear context: use this when you need a single company by ID. It does not explicitly name alternatives like twenty_list_companies for multiple records, but the usage is obvious from the wording.

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 known. The description adds the REST endpoint (GET /rest/notes/{id}) which aligns with the read-only nature, but does not disclose additional behavioral traits like error handling or authorization. With the annotation present, this is adequate baseline transparency.

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

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

The description is a single sentence that immediately conveys the core purpose, followed by the REST endpoint. It is front-loaded and every word contributes value.

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

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

For a simple read-only get-by-id tool, the description, combined with strong schema and annotations, provides sufficient context. It does not mention the depth parameter or error behavior, but those are either in the schema or low-risk for this operation. A slightly richer description might mention return format, but it's not critical.

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

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

Schema description coverage is 100% for both parameters (id and depth), so the schema fully documents them. The description adds no extra parameter context, but the baseline for high schema coverage is 3.

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

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

The description clearly states the verb (Get), the resource (note), and the scope (by id). It is specific and distinguishable from sibling get tools for other entities. The REST endpoint reinforces the exact 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?

The phrase 'Get a single note by id' clearly indicates when to use this tool (when you have a note id). It does not explicitly mention alternatives or exclusions, but the purpose is straightforward and the sibling list tools imply the distinction.

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 discloses that this is a safe read operation. The description adds the REST GET method and the fact that it fetches by id, but it does not disclose additional behaviors such as error handling, authentication requirements, or return format. The bar is lower due to the annotation, and the description provides minimal extra context beyond it.

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

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

The description is a single, focused sentence that front-loads the core purpose and includes the REST path. Every word earns its place, with no redundancy or filler. It is highly concise and well-structured.

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

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

For a simple read-only single-object retrieval tool with 100% schema coverage and a readOnlyHint, the description covers the essential purpose. There is no output schema, but the response is implicitly the opportunity object. It could add a note about the response shape or error conditions, but this is a minor gap for such a straightforward GET tool.

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

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

The schema descriptions cover both parameters (id and depth) with clear meaning, so the description does not need to add parameter details. The description only mentions 'by id', which is already in the schema. With 100% schema coverage, a baseline of 3 is appropriate; the description adds no extra semantic value beyond the schema.

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

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

The description clearly states that the tool retrieves a single opportunity by its id, using a specific verb ('Get') and resource ('opportunity'). It also provides the exact REST endpoint, which unambiguously distinguishes it from sibling tools like twenty_list_opportunities and get tools for other entities.

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

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

The description implies that this tool should be used when you have an id and need one specific opportunity, but it does not explicitly mention alternatives or when not to use it (e.g., for listing multiple opportunities). No exclusions or sibling comparisons are provided, so guidance is only implicit.

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

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

Annotations already declare readOnlyHint=true, so the description's mention of 'REST: GET' is consistent but adds no new behavioral traits like error handling, auth requirements, or depth parameter effects. It provides minimal added context beyond the annotations.

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

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

The description is two concise, front-loaded sentences: 'Get a single person (contact) by id. Twenty REST: GET /rest/people/{id}.' Every word earns its place, with no unnecessary details.

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

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

For a simple get-by-id tool with annotations covering read-only and schema covering parameters, the description is nearly complete. It omits mention of the optional depth parameter's effect on the response or any error behavior, but these are partially covered by the schema and implied by the tool's simplicity.

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 'id' and 'depth' documented in the schema. The description repeats 'by id' without adding semantic details beyond the schema, so baseline 3 applies.

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

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

The description clearly states 'Get a single person (contact) by id', identifying the specific action (GET), resource (person/contact), and scope (single by id). This distinguishes it from sibling tools like list_people (multiple) and update_person (modification).

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

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

The description implies usage when a specific person's ID is known, and the REST endpoint reinforces this. However, it does not explicitly compare against alternatives like list_people for searching or other get tools for different entities, though the 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, and the description's mention of GET /rest/tasks/{id} is consistent. It adds minimal extra behavioral context beyond the endpoint, but no further details about return format or side effects. With annotations present, a 3 is appropriate.

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

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

The description is a single concise sentence that is front-loaded with the primary purpose. It includes the REST endpoint for reference without unnecessary verbosity.

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

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

For a simple get-by-id tool with no output schema, the description sufficiently conveys the operation. It does not explain return values, but the purpose implies a task object. The lack of explicit alternatives slightly reduces completeness compared to an exemplary description.

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

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

Schema description coverage is 100%, so the schema already documents both 'id' and 'depth'. The description mentions 'by id' but adds no extra parameter semantics beyond what the schema provides, 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?

The description clearly states 'Get a single task by id' with a specific verb (get), resource (task), and scope (single by id). This distinguishes it from sibling tools like twenty_list_tasks (multiple) and twenty_get_company (different resource).

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

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

The description clearly implies the use case: use this tool when you need one task by its id. However, it does not explicitly mention alternatives or when-not-to-use, so it falls short of a 5 but provides clear 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, so the agent knows this is a safe read operation. The description adds the REST endpoint (GET /rest/companies) and capability notes (pagination, filter, depth), but does not disclose additional behavioral traits such as return format, pagination loop behavior, or any side effects. Given the annotation coverage, this is adequate but not rich.

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

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

The description is three short sentences, front-loaded with the primary purpose. Every sentence adds value: stating the function, noting key capabilities, and providing the underlying REST endpoint. There is zero redundancy or filler.

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

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

Given the moderate complexity (6 parameters, all well-documented in schema) and the presence of readOnlyHint, the description is sufficiently complete. It conveys the endpoint, core capabilities, and purpose. Lacking an output schema, it doesn't describe the response shape, but for a list tool this is not a critical omission. The schema covers parameter behavior, and the annotations cover safety.

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 detailed descriptions for all 6 parameters including examples, syntax, and comparators. The description only mentions 'raw filter/order_by, and relation depth' generically, adding no value beyond the schema. The baseline of 3 is appropriate because the schema already does the heavy lifting.

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

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

The description opens with 'List/filter companies', a specific verb+resource combination that clearly states the tool's function. It distinguishes itself from sibling tools like twenty_get_company (single record) and twenty_create_company (write operation) by explicitly mentioning list/filter and pagination/filtering capabilities.

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

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

The description provides clear context for when to use this tool by highlighting its unique capabilities (cursor pagination, raw filter/order_by, relation depth) absent from other sibling tools. It implies this is the tool for listing/filtering multiple companies, though it doesn't explicitly state exclusions or alternatives like 'Use get_company for a single record.'

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 read-only nature is covered. The description adds functional context: it lists both standard and custom objects, includes fields, and mentions the underlying REST endpoint. This goes beyond the annotation by explaining the scope and output focus, though it doesn't detail pagination or response format.

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

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

Two sentences with no fluff. The first sentence states the action and scope, the second gives the use case and an endpoint reference. Every word earns its place.

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

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

With no output schema, the description indicates the return content ('objects (standard + custom) and their fields'). Given zero parameters and a simple list operation, this is adequate. The REST endpoint adds an extra anchor for agents familiar with Twenty's API. Minor gap: no mention of response format or potential pagination, but complexity is low.

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?

Tool has zero parameters, so the baseline is 4. The description appropriately notes that it lists everything ('all objects') and includes the REST endpoint, which is sufficient context for a parameterless operation.

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?

Description uses a specific verb 'List' and clearly identifies the resource: 'all objects (standard + custom) and their fields from the Twenty schema'. This distinguishes it from sibling list tools that target specific record types (companies, people, etc.) by focusing on metadata schema objects.

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 states when to use: 'use this to discover custom objects/fields and valid field names'. This gives clear context for schema discovery. It doesn't explicitly exclude alternatives, but the sibling tools are clearly for record listing, so the intended usage 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?

The description adds behavioral context beyond the readOnlyHint annotation by mentioning support for cursor pagination, raw filter/order_by, and relation depth. This informs the agent about advanced query capabilities. It does not describe auth requirements or rate limits, but the annotation already establishes the safe read-only nature.

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 concise sentences, front-loaded with the purpose, followed by feature highlights and the REST endpoint. Every sentence earns its place with no redundant or unnecessary wording.

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

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

Given that there is no output schema, the description should hint at return behavior. 'List/filter notes' implies a list result, and pagination cursors referencing pageInfo suggest the response structure. The description covers the tool's main capabilities well, though it could be slightly more explicit about the response format.

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 mentions cursor pagination, raw filter/order_by, and relation depth, which map to parameters like starting_after/ending_before, filter/order_by, and depth. However, this adds no new syntax or meaning beyond what the schema already provides; it only summarizes the existing parameter descriptions.

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

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

The description clearly states the tool's purpose as 'List/filter notes', which is a specific verb+resource. It distinguishes from siblings like twenty_get_note (single note retrieval) and twenty_create_note (creation) by explicitly mentioning listing and filtering. The added details about cursor pagination and raw filter/order_by further specify its function.

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

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

The description implies usage for listing/filtering notes but does not explicitly contrast with alternatives such as twenty_get_note for single-note retrieval. It provides no explicit 'when to use' or 'when not to use' guidance, though the resource name and behavior make the intended use reasonably clear.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces this with 'GET /rest/opportunities'. It also adds behavioral context about pagination (cursor-based), raw filter/order_by support, and relation depth—traits not fully captured by annotations alone. No contradictions with annotations.

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

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

The description is two sentences, front-loaded with the core purpose, and includes only relevant technical details. No redundant words or filler.

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

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

The tool has 6 optional parameters and no output schema, so the description should explain the return shape and pagination mechanics. It mentions cursor pagination but does not describe the response structure (e.g., records array, pageInfo). Given the complexity of raw filters and relation depth, the description is adequate but leaves gaps for an agent to infer behavior.

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

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

The input schema provides 100% parameter description coverage, with each parameter's format and constraints documented. The description adds only a high-level summary (e.g., 'cursor pagination', 'raw filter/order_by') that doesn't meaningfully enhance the schema semantics. Baseline 3 applies since the schema does the heavy lifting.

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

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

The description starts with 'List/filter opportunities (deals)' which clearly states the verb and resource, and distinguishes it from sibling list tools for other entities like companies, people, and tasks. The additional capabilities (cursor pagination, raw filter/order_by, relation depth) further specify the tool's scope.

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

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

The description makes it clear this is the tool for listing/filtering opportunities, and the mention of pagination and raw filters implies when you need those features. It does not explicitly name alternatives (e.g., twenty_get_opportunity for a single record), but the purpose is clear enough for an agent to select it appropriately among siblings.

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

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

Annotations already include readOnlyHint: true. The description adds that this is a REST GET endpoint and discloses support for cursor pagination, raw filter/order_by, and relation depth—non-obvious behaviors beyond the annotation. No contradiction with annotations.

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

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

Three short sentences, front-loaded with the core purpose. Each sentence adds distinct value: purpose, capabilities, and endpoint. No redundant or extraneous content.

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

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

For a read-only list endpoint with a fully documented schema and no output schema, the description covers key behaviors: listing, filtering, pagination, ordering, relation depth, and the REST endpoint. Given the readOnlyHint annotation and standard GET semantics, return value expectations are obvious, so no additional detail is needed.

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

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

Schema coverage is 100% with detailed parameter descriptions (e.g., limit range, cursor fields, filter syntax examples). The description's mention of pagination/filter/depth is a high-level summary that adds no new specifics beyond the schema, so baseline 3 applies.

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

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

The description begins with 'List/filter people (contacts)' which clearly states the verb and resource. It distinguishes itself from sibling list tools (companies, notes, opportunities, tasks) by specifying 'people'. The additional mention of filtering and pagination clarifies its scope.

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

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

The description provides context about supported features (cursor pagination, raw filter/order_by, relation depth) but does not explicitly say when to use this tool versus alternatives like twenty_get_person for a single record. Usage is implied by the resource name and capabilities, but no exclusions or alternative tools are named.

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 establishes safety, so the description appropriately adds behavioral details beyond that: cursor pagination, raw filter/order_by support, and relation depth. This gives the agent useful context about capabilities without contradicting 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?

The description is a single, information-dense sentence followed by the REST endpoint. It is front-loaded with the core purpose, contains no fluff, and every phrase adds value.

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

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

The tool is simple and the schema already documents parameters thoroughly. The description covers core functionality and the pagination-related params reference pageInfo, providing enough context for an agent to use the tool effectively. It could explicitly state the response shape, but the absence of an output schema is mitigated by the schema's pagination hints.

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 provides 100% coverage with detailed descriptions for all six parameters, including syntax examples and defaults. The description only summarizes these features ('cursor pagination', 'raw filter/order_by'), adding no new semantic information beyond the schema.

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

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

The description begins with 'List/filter tasks,' which is a specific verb+resource pair that clearly distinguishes it from sibling list tools for other entities. The inclusion of the REST endpoint 'GET /rest/tasks' further anchors the tool's purpose.

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

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

The intended usage is strongly implied by the name and description, but there is no explicit guidance on when to use this tool versus alternatives like twenty_get_task for single records. No exclusions or contrasting sibling tools are mentioned, 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 include destructiveHint:true, and the description adds the HTTP method PATCH and the partial-update behavior. It does not contradict the destructive hint; it reinforces that this is a write operation. No further behavioral details are provided, but the annotation covers the main risk.

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 extremely concise: one sentence explaining the update semantics and another giving the REST endpoint. Every word adds value, with no redundancy or fluff.

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

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

Despite having no output schema, the description provides the essential context: it is an update (PATCH) for an existing company, with partial-update semantics. Combined with full parameter schema and annotations, it is sufficient for an update tool, though it omits return value and error behavior.

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

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

Schema description coverage is 100%, with each parameter having a descriptive text (e.g., 'X/Twitter URL (sent as xLink:{primaryLinkUrl})'). The tool description itself adds no parameter-level details beyond the schema, so a 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 clearly states the action ('Update fields') and resource ('existing company'), and specifies the REST endpoint 'PATCH /rest/companies/{id}', distinguishing it from create/get/list siblings which use different verbs and resources.

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

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

The phrase 'Only provided fields change' explicitly communicates a partial-update semantic, telling the agent when to use this tool (update existing company with specific fields). It does not explicitly mention alternatives, but sibling names like 'create_company' and 'get_company' make the use case clear without extra guidance.

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

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

The annotation destructiveHint=true already signals mutation, but the description adds the key behavioral detail that only provided fields are modified, preventing assumptions of full replacement. Mentioning 'Twenty REST: PATCH' also provides HTTP method context. This goes beyond the annotation without contradicting it.

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 composed of two short, information-dense sentences. The action is front-loaded, and every phrase ('Update fields', 'existing opportunity', 'Only provided fields change', 'Twenty REST: PATCH') adds value without 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?

Given full schema coverage and a clear partial-update statement, the description covers the essential behavior for a mutation tool. It does not describe return values or error handling, but no output schema exists and the schema handles parameter details. The core ambiguity (partial vs full update) is resolved, making it adequately complete.

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

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

Schema description coverage is 100%, so all parameters are individually documented. The description adds no extra parameter-specific meaning beyond the global 'Only provided fields change' behavior, which is already a general update trait. Baseline 3 is appropriate given the schema's completeness.

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

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

The description clearly states the action with a specific verb and resource: 'Update fields on an existing opportunity.' It distinguishes from create/get/list siblings by the word 'update' and the reference to an existing record. The additional clause 'Only provided fields change' further clarifies the partial-update semantics.

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

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

The description makes clear this tool is for updating an existing opportunity, not creating one, and the clause 'Only provided fields change' signals partial updates. It does not explicitly name alternatives like 'use create_opportunity to create a new record', but the context and wording imply the appropriate usage.

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

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

With destructiveHint=true already indicating the operation is destructive, the description adds valuable context by stating that only provided fields change, preventing unintended overwrites. It also includes the REST endpoint for technical clarity. No contradiction with annotations.

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

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

The description is three concise sentences, front-loaded with the primary purpose. Every sentence provides useful information: the action, the patch behavior, and the REST endpoint. No wasted words or irrelevant details.

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

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

The tool is straightforward, and the description covers the key patch semantics that prevent data loss. It lacks details about return values or error behavior, but given the rich schema and annotations, it is sufficiently complete for a basic update operation.

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

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

Schema description coverage is 100%, so parameters are fully documented in the schema itself. The description does not add additional parameter-specific meaning 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 clearly states the tool updates an existing person, using the verb 'Update' with the resource 'person'. It distinguishes from create/get/list tools by specifying 'existing' and the PATCH method. The note 'Only provided fields change' clarifies the update semantics.

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

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

The description implies usage for modifying existing person records, but does not explicitly mention alternatives like twenty_create_person or when not to use it. There is no direct comparison to sibling tools, so the usage context 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?

With annotations declaring destructiveHint=true, the description adds valuable behavioral context: 'Only provided fields change' clarifies partial-update semantics, and the REST method PATCH is disclosed. This goes beyond the annotation without contradicting it.

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 short sentences, front-loaded with the main action, and includes the essential REST endpoint. Every word earns its place; there is no fluff 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 7-parameter update tool with 100% schema coverage and a destructiveHint annotation, the description is adequately complete. It covers the core action, partial-update behavior, and API method. It does not mention return value, but no output schema exists and this is typical for an update tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds the key semantic that only provided fields change, which clarifies that omitted parameters are left untouched. This is useful parameter-level insight beyond the schema's per-field descriptions.

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

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

The description clearly states the verb 'Update' and the resource 'existing task', making it distinct from sibling tools like create, get, or list tasks. It also specifies the REST endpoint (PATCH /rest/tasks/{id}), which further anchors its purpose.

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

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

The description 'Update fields on an existing task' provides clear context for when to use this tool (to modify an existing task). It does not explicitly mention alternatives or exclusions, but the distinction from create/get/list tools is implicit and easy to infer.

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