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

Annotations are minimal (readOnlyHint=false, destructiveHint=false). The description adds significant behavioral context: idempotence, response shape for both fresh and duplicate links, and internal handling of Capsule's 422 error. This fully compensates for the lack of annotation 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?

Two sentences, highly efficient. The first sentence states the core purpose, the second adds idempotency and response details. No wasted words.

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

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

For a tool with 3 parameters and no output schema, the description covers the essential: purpose, scope, idempotency, response format, and error handling. It is sufficient for an agent to use correctly.

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

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

Schema description coverage is 67% (two of three parameters described). The description does not add any new parameter-level information beyond what the schema already provides. It meets the baseline but does not exceed it.

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

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

The description clearly states the action ('Link an existing party as an additional party') and the target resources ('on an opportunity or project'). It distinguishes itself from siblings like update_opportunity which sets the main party, and from add_party_* tools which add different types of data.

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 explains when to use this tool: for adding secondary parties beyond the main one (set by update_opportunity/update_project). Also mentions idempotent behavior, guiding the agent on safe re-use.

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 indicate readOnlyHint=false and destructiveHint=false. The description adds critical behavioral detail: note attribution is forced to the API-token owner with no override, explicitly explaining why creatorId is not exposed (security rationale). It also discloses that entryAt persists across updates while updatedAt advances, and that content is treated as markdown. This goes well beyond the schema and 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 slightly lengthy but every sentence conveys necessary information: core purpose, constraint, attribution rationale, and parameter behavior. The most critical constraint (exactly one target) is front-loaded. No redundant filler; just a dense, well-organized paragraph.

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 create operation with no output schema, the description covers all parameters, usage constraints, and key edge cases (backdating, markdown, attribution). It doesn't mention response format, but that's acceptable given no output schema is present. Minor gaps like error handling are not critical for initial invocation. The tool is complete enough for an agent to call correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds nuance not present in the schema alone: the mutual exclusivity of the three ID parameters is reinforced but also clarifies the attribution rule for entryAt (preserved across update_entry) and the markdown handling. These are meaningful additions for correct usage, earning a 4.

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 clear verb-resource-target relationship: 'Add a note to a party, opportunity, or project.' It immediately distinguishes from sibling tools (e.g., add_party_email_address) by specifying the resource type and the three possible attachment targets. No ambiguity remains.

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

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

It provides a hard constraint ('Provide exactly one of partyId, opportunityId, or projectId') and explains when to use optional parameters (entryAt for backdating, activityTypeId for categorization). It doesn't explicitly contrast with other note-related tools, but the tool is unique enough that the constraint suffices.

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 indicate a non-read, non-destructive write. Description adds behavioral context: atomic PUT operation and detailed validation behavior for the country parameter (rejection on invalid entries, normalization). However, no mention of side effects on existing data.

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

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

Two concise sentences: first states purpose, second gives usage guidance. No extraneous information, front-loaded and 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?

Covers primary purpose, usage alternative, atomicity, and country validation. Missing details on optionality of parameters (though schema shows none required), return value, and error cases beyond country.

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 low (29%). The country parameter description is exceptionally detailed, adding validation rules and examples. Other parameters like street, city, state, zip lack any description in the schema or tool description, leaving gaps.

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 it appends a single postal address to a party, distinguishing itself from update_party.addresses by explicitly recommending its use for single-entry adds.

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

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

Provides when-to-use guidance (single-entry adds instead of update_party.addresses) and mentions atomicity, but does not explicitly exclude scenarios like adding multiple addresses or state prerequisites such as party existence.

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 are minimal (readOnlyHint=false, destructiveHint=false), so the description carries the burden. It adds that the operation is atomic and uses a single PUT to Capsule, which provides some insight. However, it does not disclose error handling, idempotency, or whether duplicates are allowed. Still, it adds meaningful context 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 two sentences: the first states the action and a technical detail (atomic PUT), the second provides usage guidance. It is front-loaded, no filler, and 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 tool with low schema coverage, no output schema, and minimal annotations, the description should cover more: no explanation of return values, no parameter details, and no error scenarios. It is adequate for purpose and usage but incomplete for a fully self-contained 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 only 33% (only 'type' has a description). The description does not elaborate on any parameter; it doesn't explain 'partyId' or 'address', nor does it provide examples. Given low coverage, the description should compensate but fails to add any 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?

The description clearly states the action ('Append a single email address to a party'), specifies it's atomic, and explicitly distinguishes it from the sibling tool update_party.emailAddresses by explaining when to use each. This provides specific verb+resource+scope with differentiation.

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 explicit guidance: 'Use this instead of update_party.emailAddresses when you want to add exactly one entry; the bulk array on update_party is append-only and won't replace.' It clearly states context but does not mention other alternatives like add_party_address, which are for different resource types, so it's sufficiently focused.

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 indicate readOnlyHint=false and destructiveHint=false. The description adds that the operation is 'Atomic — one PUT', which confirms a single, non-destructive write. No contradictions.

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, no wasted words. The first sentence states purpose, the second gives usage guidance. Well 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?

While the tool is simple, the description lacks details about phone number format validation, behavior on duplicate numbers, or return value. Given no output schema and low parameter coverage, more context would be beneficial.

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

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

Only 33% of parameters have schema descriptions (type has a description). The description does not elaborate on partyId or number beyond 'single phone number'. For low schema coverage, the description should compensate but does not.

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

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

The description uses a specific verb 'Append' and resource 'single phone number to a party', clearly differentiating from sibling 'update_party.phoneNumbers' for single-entry adds.

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 that this tool should be used instead of update_party.phoneNumbers for single-entry adds, and that it is atomic with one PUT call. No exclusions or when-not conditions beyond that, but clear context for the main use case.

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 indicate non-readonly and non-destructive. The description adds 'Atomic — one PUT to Capsule', revealing the atomic nature and underlying API call. It does not contradict annotations and adds behavioral context beyond the structured fields.

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

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

Three sentences with no fluff. Each sentence adds value: purpose, usage guidance, and parameter clarification. Front-loaded with the most important 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?

Covers the essential purpose, usage, and parameter hints. However, it does not describe return values or error behavior, and there is no output schema. For a simple append operation, this is adequate but could be slightly more 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 67%. The description adds value by clarifying the 'address' parameter with examples ('URL when service='URL' or a handle like '@acmeco'') and specifies that 'service' defaults to 'URL' if omitted, which is not in the schema description.

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

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

The description states 'Append a single website / social handle to a party' with a specific verb and resource. It also distinguishes from the sibling 'update_party.websites' by explicitly stating 'Use this instead of update_party.websites for single-entry adds.'

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

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

Provides clear guidance: 'Use this instead of update_party.websites for single-entry adds.' This indicates when to use this tool vs the alternative. It does not mention any further exclusions or prerequisites, but the guidance is sufficient.

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

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

Annotations indicate non-read-only and non-destructive. Description adds idempotency, case-insensitive matching, and automatic tag creation, providing full behavioral context 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?

Well-structured with key information front-loaded. Every sentence is useful, though slightly verbose. Could condense without losing meaning, but still effective.

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

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

Covers all essential aspects: entity types, tag resolution, case sensitivity, idempotency, and cross-reference to related tools. No output schema needed; behavior is fully described.

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 baseline is 3. Description reinforces the tagName parameter's behavior but does not add significant new meaning beyond the schema's own description.

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

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

The description clearly states the action ('Attach'), the resource ('tag'), and the target entities ('party, opportunity, or project'). It distinguishes from sibling tools like remove_tag_by_id and batch_add_tag.

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

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

Explicitly tells when to use this tool (attach by name) and when to use alternatives (remove_tag_by_id for detachment, list_tags first to avoid near-duplicates). Also explains idempotency.

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?

Clearly discloses non-idempotent behavior ('applying the same trackDefinitionId twice creates two independent instances'), task auto-creation and due date computation via startDate + daysAfter offset. Adds significant context beyond annotations (readOnlyHint: false, destructiveHint: false).

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

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

Dense single paragraph with front-loaded purpose and behavioral notes. Could benefit from bullet points for readability, but no superfluous sentences.

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

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

Adequately covers discovery and idempotency concerns given sibling tools. No output schema, but expected behavior (creation) is implied. Complete for a 4-parameter tool with no nested objects.

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?

Adds meaning beyond schema: explains entity enum options, startDate default and scheduling use, trackDefinitionId role. Schema coverage is 75%, description compensates with extra context, though entityId is not elaborated.

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 clearly states 'Apply a track definition to an opportunity or project' with specific verb and resource. Distinguishes from sibling tools like list_track_definitions and list_entity_tracks.

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 advises using list_track_definitions to discover templates and warns about non-idempotency. Suggests checking existing instances via list_entity_tracks, but does not explicitly state when not to use the tool.

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 detail beyond annotations: parallel HTTP requests with configurable concurrency cap (5), cache invalidation per entity type, and exact return format. Annotations only indicate it's not read-only and not destructive, so the description significantly enriches 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 compact paragraph that efficiently conveys purpose, usage example, parameter format, behavioral traits, and return structure. Every sentence 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 the single-parameter schema with good documentation, lack of output schema, and simple annotations, the description thoroughly covers behavior (parallelism, concurrency, caching, return format). It leaves no significant questions unanswered for an AI agent.

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

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

Schema coverage is 100% and the schema description already explains the items array and its shape. The tool description adds concurrency behavior, return format, and purpose context, but the schema description also mentions mass-tagging and cache invalidation. Thus, moderate added value.

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

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

The description clearly states it attaches tags to many entities in parallel with concrete examples (RSAC26, Departed). It distinguishes from siblings like 'add_tag' (single) and 'batch_remove_tag_by_id' (removal) by emphasizing batch addition and parallel execution.

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 use cases (mass-tagging after events) and implicitly indicates when to use this over 'add_tag' (for multiple items). However, it does not explicitly mention when not to use it (e.g., for single tags) or list alternatives, leaving some gap.

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?

Discloses parallel execution, concurrency cap (5), per-item failure handling for already completed/deleted tasks, and return format. Annotations only state it's not read-only and not destructive; description adds significant behavioral context.

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

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

Concise, front-loaded with action, then usage, then technical details, then return format. Every sentence adds value, no 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 single-parameter tool with no output schema, description fully covers usage, behavior, return format, and error handling. No 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 fully covers 'ids' parameter. Description adds context about parallel execution, caps, and error handling, but does not change parameter meaning. High schema coverage gives baseline 3; added value justifies 4.

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 clearly states the action ('Mark...COMPLETED'), resource ('tasks'), and scale ('1–50 tasks'). It distinguishes from sibling 'complete_task' by specifying batch parallelism.

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

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

Provides explicit usage scenarios ('end-of-week catchups', 'close all...') and implies when to use the singular alternative (complete_task). No explicit when-not, but context makes it 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 declare readOnlyHint=false and destructiveHint=false. The description adds details about parallel HTTP requests with default cap of 5, idempotent handling of already-detached tags, and the response structure. This significantly expands on the annotations, providing full behavioral context.

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

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

Four sentences, each serving a purpose: purpose, syntax, idempotency, parallelism. No fluff. Front-loaded with the key action.

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

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

With only one parameter fully described by schema, and no output schema, the description fully compensates by specifying the return shape ({ results, summary }). No gaps remain for a tool of this complexity.

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

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

Schema description coverage is 100%, so baseline is 3. The description repeats the parameter shape ('items: [{ entity, entityId, tagId }, ...]') and constraints (1–50 items) but adds little beyond the schema's own descriptions (e.g., maxItems, minItems, description).

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

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

The description states 'Detach tags from many entities in parallel' with verb 'detach' and resource 'tags from entities'. It distinguishes from sibling 'batch_add_tag' by calling it the 'cleanup counterpart', making purpose clear and specific.

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 explicitly positions it as the batch removal counterpart to batch_add_tag, and explains the input format and idempotent behavior. While it doesn't enumerate when not to use it, the context is clear enough for an agent to decide.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false, leaving the description to carry the behavioral burden — and it delivers. It discloses concurrency behavior with a configurable cap ('default cap 5 (CAPSULE_MCP_BATCH_CONCURRENCY)'), the exact return shape, and critically the failure semantics: 'Partial failures possible; Capsule has no rollback.' For a batch mutation, this is precisely the risk information an agent needs.

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

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

Five sentences, zero fluff, and the core action is front-loaded. Each subsequent sentence adds a distinct piece: shape relation, use case, concurrency behavior, return contract, failure mode. It earns a 4 rather than a 5 because the single dense paragraph could be slightly more scannable — the concurrency and failure-semantics details could be visually separated — though nothing approachable is wasted.

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

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

Given there is no output schema, the description correctly documents the return contract ({ results: [...], summary: {...} }), the input-shape relationship to the single-update sibling, the 1-50 cardinality, and idempotency-adjacent safety info (no rollback). This is complete for a batch utility whose error contract matches its single sibling. Minor deduction: the contents of the per-item `ok` object are left undefined, and there's no note about whether a single malformed item aborts the batch or gets reported inline.

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

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

Schema coverage is 100% and the items parameter already carries a rich description explaining the 1-50 bound and the rationale ('so a single tool call can't burn an outsized share of Capsule's hourly per-token rate budget'). The main description complements this by documenting the return shape. Slight deduction because the 'same shape as update_opportunity' reference assumes the agent cross-references another tool's schema, and field-level semantics are delegated entirely.

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

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

Opens with 'Update 1–50 opportunities in parallel' — a specific verb, resource, and scope qualifier in one breath. It then names the sibling it is not ('Same input shape as update_opportunity but wrapped in an items array'), making the single-vs-batch distinction unmistakable against siblings like update_opportunity, batch_update_party, and batch_update_project.

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 this — not N sequential update_opportunity calls — for mass stage transitions (e.g. move a milestone batch to Won), owner reassignments, or value adjustments' is an explicit when-to-use directive that names the alternative and gives concrete example scenarios. This is the gold standard the rubric calls for.

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

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

Annotations already indicate write (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds rich behavioral context: parallel HTTP requests, concurrency cap, return structure with per-item results, partial failure handling, and no rollback. 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?

Four sentences, front-loaded with purpose, followed by usage guidance, technical behavior, and return/error handling. Every sentence is informative with no 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 the tool's complexity (batch update with concurrency, partial failures) and the absence of an output schema, the description fully equips the agent: it explains the input shape, parallelism, concurrency settings, return format, and how to handle partial failures. No gaps remain.

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 a detailed schema comment on the 'items' parameter. The description adds value by clarifying the input is the same shape as update_party wrapped in an array, and reinforces the 50-item cap. This enhances understanding beyond the schema alone.

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', resource 'parties', and scope '1–50 in parallel'. It distinguishes itself from sibling update_party by noting the batch pattern, making its purpose 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?

Explicitly advises to use this instead of N sequential update_party calls for homogeneous multi-record writes, with concrete examples (mass owner reassignment, bulk metadata corrections). Also covers technical details (concurrency cap, configurability) that help the agent decide when to invoke.

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

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

Goes beyond annotations by explaining concurrency limit (default cap 5), return structure with results and summary, and partial failure behavior with no rollback. 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?

Four focused sentences with no redundancy. Front-loads purpose, then usage guidelines, then technical details. Every sentence provides 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?

Covers behavior, parallelism, return format, and failure handling. No output schema, so description compensates well. Minor gap: no mention of specific error handling beyond partial failures.

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

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

Schema coverage is 100%, so baseline is 3. Description adds context by comparing to update_project input shape, but does not add new parameter-level details beyond 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?

Description clearly states the verb (update), resource (projects), and scope (batch of 1-50). It distinguishes from sibling update_project by specifying parallelism and same input shape wrapped in array.

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

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

Explicit use cases are given: mass stage transitions, bulk owner reassignments, batch closures. It advises using this instead of sequential calls. Does not explicitly state when not to use, but context is strong.

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?

Description adds details beyond annotations: sets status=COMPLETED, populates completedBy/completedAt, preserves in history unlike delete_task. This enriches the agent's understanding.

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 focused sentences, no fluff. Front-loaded with key action and alternatives. 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?

Lacks return value or confirmation details (no output schema). Agent knows what the tool does but not what to expect back (e.g., updated task object vs success status). Adequate for a simple mutation but could be more complete.

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

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

With 0% schema description coverage, the description should clarify the 'id' parameter meaning. It only implies it's a task ID, but doesn't confirm it's required or provide constraints. Agent may need to infer from context.

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 clearly states the verb ('mark as done/completed') and the resource ('task'). Distinguishes from delete_task and update_task by explaining behavioral differences.

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

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

Gives explicit usage triggers ('mark done', 'complete', 'finish') and notes it's a discoverable alternative to update_task. Does not explicitly state when not to use, but clear enough for most cases.

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 readOnlyHint=false and destructiveHint=false, so the description carries the transparency burden and does substantial work: it discloses that tenant automation rules can mutate owner/team post-create, that pipeline is inferred rather than set directly, and notes wire-verified behaviors. No contradiction with annotations — 'create' aligns with readOnlyHint=false and non-destructive intent. Strong behavioral disclosure well beyond the minimal 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 three-sentence description is efficient and front-loaded: purpose first, then core constraints (partyId/milestoneId, value/currency coupling), then discovery and alternative tool routing. No wasted sentences at the top level; the verbosity lives in the schema's per-parameter descriptions, which is appropriate placement.

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

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

For a 13-parameter tool with nested objects and no output schema, the description covers the essentials (party linkage, stage pinning, value rules, discovery path, multi-party handling) but has two gaps: the 'requires partyId and milestoneId' claim conflicts with the schema's required:[name], which could mislead an agent about mandatory inputs, and there is no statement about what the call returns on success. These prevent full callability confidence for a tool of this complexity.

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

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

Schema coverage is 69%, placing the baseline at 3. The description adds value on partyId and milestoneId (pinning stage, pipeline inference) but partially repeats the schema's own rich descriptions (currency-required-when-amount, list_pipelines discovery). A notable discrepancy: the description asserts 'Requires partyId and milestoneId' while the schema marks only name as required — a factual mismatch that weakens the otherwise helpful parameter guidance.

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 (Create), resource (opportunity), and linkage scope (linked to a party), clearly distinguishing it from siblings like update_opportunity, delete_opportunity, and batch_update_opportunity. The description goes further by naming the two key inputs (partyId, milestoneId) and explaining the milestone→pipeline inference, so an agent knows exactly what this creation tool is for.

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

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

Provides concrete guidance: discover milestone ids via list_pipelines + list_milestones first, and use add_additional_party for multi-party deals — explicitly routing to a sibling. It also notes the chained batch_update_opportunity workaround for milestone automation side-effects. It doesn't enumerate when to favor update_opportunity or batch_update_opportunity for modifications, but the creation-vs-alternative guidance is present and actionable.

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 state readOnlyHint=false and destructiveHint=false, so the description carries full behavioral disclosure. It reveals silently ignored fields per type, 404 on mismatched organisationId, owner defaulting to the API-token user, no default for teamId, and append-only semantics—far beyond what annotations could convey. 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 front-loaded with the core purpose and then delivers dense, decision-relevant specifics in five sentences. Every sentence earns its place: type rules, error behavior, ownership defaults, and alternatives are packed without fluff or repetition of schema 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 16-parameter create operation with no output schema and minimal annotations, this description covers the highest-risk semantics: required-field rules, ignored fields, error responses, ownership defaults, and partial/list update behaviors. It is sufficiently complete for an agent to call the tool correctly without guessing.

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

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

With only 56% schema description coverage, the description adds critical meaning: firstName/lastName vs name requirements per type, silently ignored title/jobTitle, organisationId lookup-type filtering, and owner/team default behavior. It compensates for schema gaps and clarifies real API behavior rather than just restating types.

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

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

Opens with a specific verb-resource statement: 'Create a new person or organisation in Capsule CRM.' This is differentiated from sibling create tools (create_opportunity, create_project, create_task) by clearly scoping to parties, and the type-specific handling is immediately anchored.

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

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

Provides explicit conditional usage by party type, and names concrete alternatives for edge cases: use update_party to clear/team-own after creation, use apply_track for existing records, and use add/remove_party_* for atomic list mutations. An agent can decide when create_party is the right tool or when to route elsewhere.

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 signal readOnly=false and destructive=false. The description adds behavioral context: stageId pins the project to a board+stage at creation, IDs come from list_boards/list_stages, and the call returns the created project including its assigned id. It does not mention defaults or automation caveats, but the create verb and annotation make the safety profile sufficiently clear.

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 five focused sentences: core action, required/optional fields, stage pinning, ID discovery, and return value. It is front-loaded and contains no filler or repetition of schema detail.

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 11-parameter creation tool with no output schema, the description plus the rich schema jointly give the agent nearly everything needed to call it correctly, including a return-value summary. The main gap is the inaccurate required-fields statement, which could lead an agent to prepare the call incorrectly.

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

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

Schema coverage is high (82%), so the baseline is 3. The description adds a useful high-level summary and explains the stageId/board relationship, but it also states 'Requires partyId and name' while the schema only lists name as required. This contradiction undercuts some of the semantic value the description otherwise provides.

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

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

The description opens with a specific verb and resource: 'Create a new project in Capsule CRM linked to a party.' This clearly distinguishes it from update_project, delete_project, and create_opportunity. The scope is unambiguous.

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

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

The action is clear and there is no competing sibling tool for creating projects, so the intended use is obvious. The description also adds a useful preparation step: 'Discover valid ids via list_boards + list_stages.' It does not explicitly list exclusions or alternatives, but none are really needed here.

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 indicate a non-readonly, non-destructive mutation, but the description adds key behaviors: the connector rejects multi-target inputs, repeat.on is derived from dueOn when omitted, and ownerId cannot be cleared once set. These go beyond the annotation hints.

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

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

Three paragraphs, each with a distinct purpose: core action, exclusion rule, and standalone usage. The most critical constraint (mutual exclusion) is prominent. No wasted words.

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

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

For a 9-parameter tool with a nested repeat object and no output schema, the description covers linking constraints, repeat derivation, owner behavior, and the connector's validation. It lacks return-value details, but that's typical without an output schema and not critical for invocation.

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

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

The description clarifies the mutual exclusivity of partyId/opportunityId/projectId, explains the standalone-task behavior when all are omitted, and adds detail about repeat.on and ownerId limitations, enriching the schema's parameter descriptions (coverage 78%).

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 task', and mentions optional links to party, opportunity, or project. Clearly distinguishes from sibling tools like update_task or complete_task by the creation 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?

Explicitly states the mutual-exclusion rule (pass at most ONE of the three IDs) and notes that omitting all is valid, creating a standalone task. It also mentions the rejection before HTTP call. While it doesn't directly compare with alternatives like update_task, the guidance is concrete and scenario-specific.

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 significant behavioral context beyond the destructiveHint=true annotation: it emphasizes irreversibility, requires confirm=true, and details the idempotent response format. 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 extremely concise—two sentences with clear structure and emphasis. It front-loads the critical warning and uses formatting (bold, code blocks) to highlight key points without 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?

Despite lacking an output schema, the description thoroughly explains the response format for both fresh delete and retry scenarios. It covers all necessary context (destructiveness, idempotency, required parameter) for a delete 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?

The input schema already covers both parameters with descriptions (100% coverage). The description reinforces that confirm must be true and provides response semantics for idempotency, adding 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 explicitly states it permanently deletes a note or other entry by ID, using strong language 'DESTRUCTIVE & IRREVERSIBLE'. It clearly distinguishes from sibling delete tools that target specific entity types (e.g., delete_opportunity, delete_party) by using the generic 'entry' term.

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 specifies the requirement for confirm=true and explains idempotent behavior, guiding the agent on correct usage. It does not explicitly contrast with alternative deletion tools, but given the clear purpose, the guidance is sufficient for selection.

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

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

Annotations already indicate destructiveHint=true. The description adds crucial details: irreversibility, need for confirm=true, idempotent behavior on retry, and the exact response format including 'alreadyDeleted' field. 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?

Two sentences, no wasted words. Front-loaded with critical warning and requirement. Second sentence efficiently covers idempotency and response.

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

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

Despite no output schema, the description fully covers response format, required parameter behavior, and safe usage pattern. Complements annotations well.

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 50% (only confirm has description). The description adds meaning by stating 'confirm=true' requirement and explaining idempotent responses, but does not elaborate on the 'id' parameter beyond what schema provides.

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

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

The description starts with 'DESTRUCTIVE & IRREVERSIBLE: permanently delete an opportunity.' The verb 'delete' and resource 'opportunity' are clearly stated, distinguishing it from sibling tools like delete_party or delete_project.

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 instructs to 'Always read the opportunity first with get_opportunity and confirm with the user before calling.' Also specifies that confirm must be true, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate destructiveHint=true. The description adds extensive context: cascading effects, organization-specific behavior (clearing organisation field), orphan track instances, idempotency, and response format. No contradiction.

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

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

The description is somewhat long but every sentence provides essential behavioral details. It is front-loaded with a warning. Could be slightly more concise but still effective.

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

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

Given the tool's complexity (cascading, irreversible, special cases) and no output schema, the description covers all critical aspects for safe usage, including idempotency and orphan handling.

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

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

Schema coverage is 50% (only confirm has description). The description adds significant context to the confirm parameter (must be true, irreversible, cascading effects). For id, no additional semantics beyond 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 it permanently deletes a party (person or organisation) and cascades to linked items. It distinguishes from sibling delete tools by focusing on party-specific behavior.

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

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

Explicitly instructs to read the party first with get_party and confirm with user before calling. Also provides guidance on when to use remove_track first if orphan accumulation matters.

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

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

Annotations already indicate destructiveHint=true; description adds idempotency details and response format. No contradiction, though annotations cover destructiveness primarily.

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

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

Four sentences all essential: warning, alternative recommendation, prerequisite, and idempotency. Front-loaded with critical info.

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

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

Covers purpose, usage, behavioral traits, parameter constraints, and response format. No output schema, but response is described. Complete for a destructive tool with 2 params.

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 50%; the description explicitly requires confirm=true and implies id from get_project. However, the id parameter lacks description in both schema and description beyond implicit reading. Response format clarifies parameter effects.

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 deletes a project permanently and contrasts with update_project for non-destructive closure. It uses specific verb 'delete' and resource 'project', distinguishing it from siblings like update_project.

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 advises using update_project with status='CLOSED' as an alternative, and instructs to first read the project with get_project and confirm with user. Provides clear when-not-to-use guidance.

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

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

Annotations already mark destructive=true. Description adds: irreversible, idempotent on retry, tenant-wide effect, response shape (deleted/alreadyDeleted), and endpoint verification (DELETE returns 204, 404 caught). Goes well 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?

Single dense paragraph, front-loaded with key constraints (DESTRUCTIVE & TENANT-WIDE). Every sentence earns its place: purpose, alternative, prerequisite, idempotency, response, endpoint. No wasted words.

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

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

Covers every aspect needed for a destructive operation: what, when, prerequisites, irreversibility, idempotency, response, and endpoint behavior. No output schema, but description fully explains return values.

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%—all 3 params have descriptions. Description adds extra context: tagId 'NOT an entity id' and confirm's idempotent retry behavior. Baseline 3 elevated due to these clarifications, though the description doesn't document every param exhaustively 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?

Starts with 'DESTRUCTIVE & TENANT-WIDE: permanently delete a tag DEFINITION'—a specific verb and resource. Explicitly distinguishes from sibling remove_tag_by_id by contrasting scope (definition vs. one record). Lists entity types (parties/opportunities/projects).

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

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

Provides explicit when-to-use ('clean up stray/mistyped/test tag definitions'), when-not-to-use ('if you only want to untag one record, use remove_tag_by_id'), and a prerequisite ('Always read the affected tag first via list_tags and confirm with the user'). Also mandates confirm=true.

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 set destructiveHint=true. Description adds irreversibility, idempotency on retry, and the exact response format including alreadyDeleted field. No contradictions.

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

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

Two sentences front-load the core purpose and key details. Each sentence adds critical information 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?

With 2 parameters and no output schema, the description explains both parameters and the exact return object. It also covers retry behavior, making it self-contained for a delete 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 coverage is 50% (confirm has description, id lacks description). Description explains confirm's role and response semantics but does not elaborate on id beyond what schema implies. Compensates partially.

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 'permanently delete a task' and contrasts with complete_task for marking done. It uses strong wording like 'DESTRUCTIVE & IRREVERSIBLE' to reinforce 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?

Explicitly says when to use this tool (permanent delete) and when to use complete_task instead. Also explains confirm=true requirement and idempotent behavior, giving clear 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 and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it discloses that Capsule's API does not support ad-hoc sort and provides a workaround based on monotonic IDs. This goes beyond annotations without contradicting them.

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

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

The description is a bit lengthy but each sentence carries weight: purpose, differentiation, and the sorting workaround are all essential. It front-loads the purpose and usage guidance, then provides the advanced tip. 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 tool with multiple conditions and a known sorting limitation, the description covers the most critical missing piece (sorting workaround) and gives a concrete example. It doesn't mention pagination or return format, but since there is no output schema and readOnly annotations cover side effects, this is adequate. The 'all conditions ANDed' is already in the schema.

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

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

Schema description coverage is 50%; the schema itself has detailed descriptions for the conditions array (field, operator, value). The description adds an explicit example of a date filter for 'most recent X' and clarifies the field-name mapping (e.g., response.createdAt vs filter-side 'addedOn') indirectly via the example. This compensates for the partial coverage and adds practical semantics.

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

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

The description clearly states the tool filters opportunities by structured conditions, listing the key fields (milestone, value, close date, tags). It explicitly differentiates from search_opportunities by naming the sibling and giving example queries that should use this tool, making its purpose unambiguous and 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 directly says 'Use this — not search_opportunities — for questions like ...', providing explicit when-to-use guidance and naming the alternative. It also explains how to handle the lack of ad-hoc sorting, which is a practical usage note beyond basic selection.

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

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

The description reveals non-obvious behaviors: email uniqueness validation, type must match name fields, and the 'read-only' hint for validation. These go beyond the schema and annotations, which only state destructive hints are false. Missing error handling details, but the key validation trap is exposed.

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?

Compact and dense with information — three sentences cover all key points. The text is not overly verbose, though the 'use read-only when validation' phrase is somewhat cryptic. Overall it imparts maximum value per word.

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

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

Covers the primary decision points (person vs org, email uniqueness, field mismatches) and gives an outline of what to provide. Does not mention pagination or response format, but for a create tool, the crucial context is validation constraints.Client's expectation of the created object is likely understood.

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?

Clarifies the conditional parameters (lastName/organisationName based on type), explains that firstName/lastName are ignored for organisations, and specifies the 'value' for tags. Not every parameter is described, but the critical ones (type, name fields, uniqueness) are covered. The schema already provides structure for address/contact objects.

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 a new party') and distinguishes between person and organisation subtypes. It does not name an alternative create tool (none exists), but the purpose is unambiguous. Could be tightened, but the verb+object is specific.

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

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

Provides explicit instructions for person vs. organisation creation, notes the ignored fields for organisations, and ties the 'type' field to name-field requirements. The email-uniqueness validation is also a crucial usage constraint. It doesn't compare against other create tools, but as the only create-party tool, the guidance is sufficient.

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

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

Annotations already establish readOnly=true and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: the API does not support ad-hoc sort, and Capsule IDs are monotonic so newest id = newest record. This tells the agent about a real API quirk and how to compensate. 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?

Two sentences, front-loaded with purpose, then usage guidance and the sort workaround. The second sentence is dense but every clause earns its place; no filler or repetition of schema 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 filter tool with a rich schema and safety annotations, the core usage, sibling routing, and the key API limitation are all covered. The only minor gap is the absence of any mention of the return shape, but for a filter tool the response (matching project records) is predictable and the schema already documents pagination caps.

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 50% — conditions, field, operator, and value are richly documented in the schema, while page and perPage rely on defaults. The description adds strategic guidance for crafting conditions (date-range filtering plus highest-id selection as a sort substitute), but it does not compensate for the undocumented pagination parameters or explain embed usage beyond the schema's token list.

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 ('Filter projects') plus the condition dimensions ('date ranges, status, tags, owner'), and explicitly distinguishes itself from list_projects. An agent can tell exactly what this tool does without opening the schema.

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

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

It names the alternative explicitly ('Use this — not list_projects') and gives concrete query examples ('most recent project', 'projects opened this month'). It also explains the API's no-sort limitation and the recommended workaround, so selection logic is fully specified.

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 mark it as a safe read operation, but the description adds rich behavioral details: how different MIME types are handled, the size limit, and the 'truncated' flag for large files. 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?

Two sentences that front-load the core purpose and then efficiently detail the conditional behaviors. Every sentence contributes necessary information 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?

Despite lacking an output schema, the description thoroughly covers return types for various MIME categories, the truncation mechanism, and size limits. It addresses edge cases and leaves no gap in understanding what the tool returns.

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 each parameter described. The description adds context beyond the schema by explaining the behavior for files exceeding maxSizeBytes (truncated flag) and the default value, and clarifies that image/* types return image content. This adds meaningful nuance.

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 starts with 'Download an attachment by id' – clear verb+resource. It distinguishes download from its sibling 'upload_attachment' and specifies handling per MIME type.

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 explicitly states when to use the tool: to download an attachment. Although it does not list alternatives or when not to use it, the context is clear given the sibling tools and the straightforward nature of the operation.

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 destructiveHint=false. The description adds context about the specific endpoint ('/users/current') and mentions it is a read operation, which is consistent with annotations. No contradictions.

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

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

The description is two sentences long, front-loaded with the core purpose and use cases, followed by endpoint specificity. Every sentence adds value, and there is no unnecessary 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?

For a zero-parameter read-only tool with annotations, the description is complete. It covers what the tool does, when to use it, and the underlying endpoint, leaving no ambiguity.

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

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

The input schema has no parameters, so the description does not need to add parameter details. It provides enough context about the tool's function without needing to clarify parameters.

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

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

The description clearly states the tool shows the user owning the API token, with specific use cases (audit, token rotation confirmation). It distinguishes itself from sibling tools like list_users by focusing on the current authenticated user.

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 explicitly mentions when to use it (audit, confirming token rotation) but does not explicitly state when not to use it or mention alternatives like list_users. However, the context is clear enough.

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 destructiveHint=false, so the safe read nature is covered. The description adds that it shows the 'DEFINITION' (schema) rather than field values, which is useful behavioral 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 a single, front-loaded sentence followed by a brief, actionable suggestion. Every word serves a purpose with no 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?

For a simple read tool with clear annotations, the description is largely sufficient. However, it does not describe the output shape (e.g., what fields the definition includes), which would be helpful given no output schema is provided.

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 input schema already documents both parameters (id and entity) with full descriptions. The description does not add additional meaning beyond stating 'by id,' making baseline score 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 'Show a single custom field DEFINITION by id,' clearly indicating the verb (Show) and the resource (custom field definition). It distinguishes itself from sibling tools like list_custom_fields by focusing on a single definition retrieval.

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 explicitly advises to 'Use list_custom_fields first to discover field ids,' providing clear context for when to use this tool versus alternatives.

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

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

Annotations already provide readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable context that the return payload varies by entry type (note, email, completed-task), which is not in the annotations. It doesn't add extra disclosures like rate limits, but for a read-only fetch that's acceptable. Score reflects added value beyond 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 three tight sentences: first states the core action, second explains the variable payload, third gives usage context and alternatives. It is front-loaded, without redundant phrases 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?

Since there is no output schema, the description's breakdown of the return payload by entry type is crucial and provided. It also covers when to use the tool and points to alternatives. The only minor gap is that it doesn't explicitly address the 'embed' parameter's effect on the response, but the schema already documents it. Overall it is sufficiently complete for a simple read 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?

The schema already describes the 'embed' parameter with valid tokens, and the 'id' parameter is typed as integer with range. The description confirms id is numeric but doesn't explain the effect of 'embed' beyond the schema's own description. With 50% schema coverage, the description adds minimal new semantics, so it meets the baseline without enhancing.

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 (fetch/single entry) and resource (timeline entry by numeric id), and distinguishes from list_*_entries by focusing on a single item and full content. It also names related sibling tools for modification and deletion, making the purpose 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?

Explicitly describes when to use it ('when you have an entry id from one of the list_*_entries calls and want the full content') and names alternatives for modification and deletion (update_entry and delete_entry). This gives clear routing and 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?

Beyond the readOnlyHint/destructiveHint annotations, the description reveals internal behavior: native endpoint for 1–10 ids, transparent chunking and parallel requests for 11–50, and merged results. It also explains the return record fields (value, milestone, owner, party), giving the agent a solid model of side effects and output.

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

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

The description is three sentences with zero filler. It front-loads the primary purpose, then covers behavioral nuance and the alternative in a logical order. Every sentence earns its place 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 the read-only annotations, the full parameter schema, and the absence of an output schema, the description covers everything needed: purpose, limit, chunking behavior, return contents, and routing to the singular alternative. Nothing critical is missing for correct invocation.

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

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

Schema coverage is 100%, so both parameters (ids and embed) are already documented. The description adds the return-record contents (value, milestone, owner, party) and the explicit batch-size breakdown, which gives the agent a fuller understanding of what the ids parameter yields. However, the core parameter meaning is already in the schema, so this is a 4 rather than a 5.

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

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

The description states a specific verb and resource ('Batch-fetch up to 50 opportunities by id') with clear scope and even names the alternative for single-id use. This distinguishes it immediately from get_opportunity, search_opportunities, and filter_opportunities 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?

It explicitly says 'For a single id, use get_opportunity instead,' which is direct routing guidance. It also implies use for multiple ids by describing the batch behavior, leaving no doubt about when to pick this tool over its 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 provide readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds behavioral context beyond the annotations: the tool returns the full record and lists its fields, and clarifies that embedding avoids multiple round-trips. It doesn't mention rate limits or auth, but for a read-only fetch that's acceptable—the added round-trip and content specifics justify a 4.

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, both loaded with useful information. The scoping constraint (single vs batch) is front-loaded, and the alternative tool is named. 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 simple read-only tool with two parameters alerts, the description fully covers what an agent needs: what it returns, how to use embed, and when to use the sibling tool. Return format is described via the field list, and annotations cover safety. No critical 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 50%: the id parameter has no description in the schema, and embed has a token list. The description adds meaning by specifying 'id' is numeric (consistent with schema) and giving a concrete usage example ('embed='tags,fields'') plus the round-trip benefit. It clarifies the purpose of the embed beyond just listing tokens, though it doesn't fully explain each token. This exceeds 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?

The description states exactly what the tool does: fetch a single opportunity by numeric id, and enumerates the fields included (value, milestone, owner, party, tags, custom fields). It contrasts with get_opportunities, making the purpose unmistakable and distinguishing it from its sibling.

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

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

Explicitly instructs when to use the embed parameter ('Use embed='tags,fields'') and when not to use this tool ('For batch fetches of up to 50 opportunities, use get_opportunities instead'). This gives the agent clear routing guidance with no inference required.

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 provide readOnlyHint=true and destructiveHint=false. The description goes well beyond that by disclosing the internal behavior: for 11-50 ids the connector splits into 10-id chunks and fans out parallel Capsule requests, with results merged. This level of behavioral detail is valuable and not implied by 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?

Three sentences, zero filler. The core purpose is front-loaded in the first sentence, followed by behavior and usage guidance. Every sentence earns its place, and there is no redundant elaboration.

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 batch-fetch tool with no output schema, the description is complete: it states the limit, explains the round-trip behavior for different id counts, and specifies that results are merged. Combined with readOnly annotations, it gives an agent everything needed to call it correctly.

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

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

The schema already describes both parameters in full detail (ids with min/max and the chunking behavior; embed with valid tokens). The tool description adds no additional meaning beyond what the schema provides – it mostly repeats the chunking information. With 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description opens with 'Batch-fetch up to 50 parties by ID' – a specific verb, resource, and limit. It clearly distinguishes itself from the sibling get_party by explaining the batching and parallel fan-out behavior, so an agent can tell them apart without opening the schema.

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

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

Explicitly states when to use this tool: 'Use this whenever Claude has several party IDs', and names the alternative (get_party) and the problem it avoids (N sequential round trips). It also describes behavior for different ID counts, which helps the agent decide.

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 and destructiveHint, so safety is covered. The description adds behavioral context by listing the return payload (type, name fields, emails, phones, addresses, websites, embedded tags/custom fields) and the effect of the embed parameter. It doesn't cover error handling or pagination, but for a single-read fetch this is not critical.

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

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

Two concise sentences. The core action and resource are stated first, followed by embed usage and sibling routing. Every sentence earns its place; 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 simple read-only tool with two parameters, no output schema, and annotations, the description is complete: it says what the tool returns, how to request additional embeds, and when to prefer the batch alternative. The only minor note is that the schema marks id as optional (required=0), but the description implies id is essential.

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

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

The schema already describes both parameters (id and embed) with 100% coverage. The description adds value by clarifying that id is numeric, and by explaining embed with the example value 'tags,fields' and a rationale for using it. This goes beyond the schema's terse description.

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

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

The description uses a specific verb ('Fetch'), identifies a single resource ('a single party'), and specifies the key identifier ('by its numeric id'). It also distinguishes itself from the batch sibling get_parties by explicitly noting the single-party 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 clearly states when to use which tool: 'For batch fetches of up to 50 parties at once, use get_parties instead.' It also advises using embed='tags,fields' to include related data in one round-trip, giving practical usage 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 and destructiveHint=false. The description adds valuable behavioral context by listing the full record fields returned (name, status, owner, stage, board, etc.) and explaining the embed='tags,fields' round-trip optimization. This goes beyond the annotations without contradicting them.

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

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

Four sentences with no redundancy: main action and scope first, then return fields, then embed tip, then alternatives. Front-loaded and every sentence serves a purpose.

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

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

The description covers the essential call information: what to pass, what you get back, how to enrich results, and which sibling to use for other use cases. Minor gap: id is implied but not explicitly stated as required, and the schema doesn't mark it required either, which could confuse an agent. Overall adequate for a simple read tool.

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

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

Schema coverage is only 50% (embed has a description, id does not). The description compensates by clarifying that id is a numeric project identifier and gives a concrete embed example ('tags,fields') that maps to actual semantics. It adds meaning beyond the schema for the key parameter.

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

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

The description states a specific verb ('Fetch') and resource ('a single project') scoped by numeric id, and explicitly differentiates from get_projects (batch) and list_project_entries (timeline). This clearly distinguishes it from many sibling project tools.

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

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

Provides explicit, actionable alternatives: 'For batch fetches of up to 50 projects at once, use get_projects instead' and 'For the project's timeline ... use list_project_entries'. This gives the agent clear routing conditions and prevents misuse.

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 destructiveHint=false, so the agent knows this is a safe read. The description adds substantial behavior beyond annotations: the transparent chunking into 10-id requests, parallel fan-out for 11–50 ids, and the merged result view presented as a single tool call. This is exactly the kind of hidden complexity that needs disclosure.

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

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

Two sentences, zero waste. The cap and the chunking behavior are front-loaded. Every sentence earns its place by describing non-obvious behavior.

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?

Complete for a read-only batch tool. The description covers the cap, the internal chunking, and the merged behavior; the schema handles parameters; annotations handle safety. This is effective as written.

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 parameters. The description repeats the ids chunking behavior but does not add meaning beyond what the schema already states — the ids parameter description in the schema already mentions the 10-id cap and transparent splitting. Baseline 3 is appropriate because the schema does the heavy lifting, and the description adds no new parameter semantics.

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

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

States a specific verb (batch-fetch) and resource (projects by ID) with an explicit cap of 50, and distinguishes it from the singular get_project by describing the batch behavior. An agent immediately knows it is the bulk variant of get_project.

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 clarifies the batch context (fetching multiple projects by ID) and the transparent chunking behavior, which implies when to use it over get_project. It does not explicitly name alternatives or say 'use get_project for a single ID', but the batch-fetch framing is clear enough. Lacks an explicit when-not-to-use statement.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false. Description adds specific return fields (subdomain, display name, URL) and diagnostic purpose, enhancing transparency 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?

Two concise sentences, front-loaded with purpose, no wasted words.

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

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

For a parameterless, read-only diagnostic tool with no output schema, the description fully covers what it returns and its purpose, making it complete.

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

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

Input schema has zero parameters with 100% coverage, so description doesn't need to add parameter details. Baseline of 4 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 returns the Capsule account (subdomain, display name, URL) the connector is authenticated against, and positions it as a diagnostic tool. It distinguishes itself from get_current_user, which returns the PAT owner's identity.

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

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

Explicitly says 'Diagnostic for which Capsule account is this?' and directs to get_current_user for PAT owner identity, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already mark the tool as read-only (readOnlyHint: true, destructiveHint: false). The description adds behavioral detail about the returned fields (description, due date, owner, completion state, attached entity) and the possibility of standalone tasks, which goes beyond the annotations by outlining the response content, though it does not cover error cases or side effects.

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 concise and well-structured: two sentences that state the purpose, the response contents, and the alternative for batch operations. There is no unnecessary detail or repetition, making it efficient for an agent to parse.

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 schema covers both parameters and the description addresses purpose, usage, and return content, the tool definition is complete for an agent to invoke correctly. It does not need to explain return formats or error handling since no output schema is present and the context is straightforward.

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

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

The schema descriptions cover both parameters adequately: 'id' is described as 'Task ID' with integer type, and 'embed' as 'Comma-separated embeds' with valid tokens listed. The description adds little beyond what the schema provides, so the schema coverage is effectively 100%, warranting the baseline score of 3.

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

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

The description clearly states the tool's purpose: 'Fetch a single task by its numeric id.' It specifies the resource (task) and action (fetch), and explicitly distinguishes it from the batch variant get_tasks, making it easy for an agent to select the correct 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 provides explicit usage guidance: use this tool for a single task, and use get_tasks for batch fetches of up to 50. This directly tells the agent when to choose this tool over its sibling.

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 destructiveHint=false, so safety is covered. The description adds valuable behavioral context: it explains the underlying Capsule API limit of 10 per request, the transparent splitting for larger batches, parallel fan-out, and that the caller sees merged results. This goes beyond the annotations and helps the agent understand performance and consistency implications. 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 a single, focused sentence that front-loads the primary behavior (batch-fetch up to 50 tasks) and then provides the important edge-case detail about splitting. It is neither too long nor verbose, with each clause earning its place. It could be slightly more structured with a bullet or two, but the current format is efficient and clear.

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

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

Given the tool's low complexity (2 params, no output schema, no nested objects), the description covers the essential behavioral aspects: batch limit, splitting behavior, and network round-trip implications. The annotations already provide safety context. The description does not mention error handling or rate limits, but these are not explicitly required for this simple read operation. It is largely complete for an agent to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds depth by explaining the 10-id chunking behavior in relation to the 'ids' parameter, which is beyond what the schema says. It also mentions the 'embed' parameter's purpose implicitly through the schema, but the description reinforces the batch context. Since schema coverage is high, a 3 is baseline, but the added chunking detail justifies a 4.

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

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

The description clearly states the tool fetches up to 50 tasks by ID, using a specific verb ('batch-fetch') and resource ('tasks'). It distinguishes itself from get_task (which likely fetches a single task) by emphasizing the batch capability. However, it does not explicitly name a sibling alternative, so it loses a point for not being as explicit as possible.

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

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

The description explains the behavior for different batch sizes (1-10 vs 11-50) and mentions the splitting mechanism, giving the agent clear context on what to expect. It does not explicitly state when to use this tool vs alternatives (e.g., get_task for single fetch), but the batch emphasis implies the use case. The lack of explicit exclusions means it's a 4, not a 5.

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

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

Beyond the annotations (readOnlyHint: true), the description adds context that the API does NOT include a trackDefinition link, entity reference, or completion field. This discloses important behavioral traits that affect how agents interpret 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?

Three sentences: first states purpose, second lists return fields, third explains exclusions and alternatives. No wasted words, highly 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 simple 1-parameter tool with annotations and no output schema, the description covers purpose, return projection, exclusions, and cross-references to relevant siblings. It is complete for an agent to use effectively.

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

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

The schema has a single 'id' parameter with 0% description coverage. The tool description reinforces that the tool fetches 'by id', but does not detail format or constraints beyond what the schema provides. The clarity is adequate, hence 4.

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 it fetches a single track by ID and lists the exact fields returned (id, description, trackDateOn, direction, tasks). It also explicitly distinguishes itself from sibling tools like list_entity_tracks by noting what is not included.

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

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

The description provides explicit guidance on when to use alternative tools: 'to find the entity a track is applied to, use list_entity_tracks; to check completion, the track-tasks' own statuses are the proxy.' This directly helps the agent choose the correct tool.

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 destructiveHint=false, so the description adds substantial behavioral context: it specifies ordering (newest first), the content of rows (typed, acting user, apiClient, refs), pagination support, and a critical caveat that this is an undocumented Capsule endpoint 'could change without notice'. This far exceeds 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?

Multi-line but dense and purposeful, front-loading the core definition and then layering filters, use cases, and the caveat. Every sentence contributes value; the caveat at the end is appropriate. Slightly long but not wasteful.

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 fully specifies expected return content (typed rows, user, apiClient, refs), ordering, pagination, and filtering semantics. It also discloses the undocumented nature of the endpoint, which is essential for safe use. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is only 33% (only `since` is described). The description compensates by explaining `since` as an ISO-8601 server-side filter and mentions pagination generically. It does not detail perPage/page specifics but the schema already provides defaults and bounds, so the description adds semantic 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?

States a specific verb and resource: 'Global cross-entity ACTIVITY FEED: everything that happened across the tenant, newest first' — it clearly lists the content and distinguishes itself from per-entity list tools by emphasizing the cross-entity scope and the explicit note that there is no per-entity server-side filter.

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

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

Provides explicit example queries ('what happened this week across the book', 'what did <user> touch today', 'which emails came in') and explains when this is the right choice ('one call instead of per-record entry fan-outs'). Does not name specific sibling tools as alternatives, but clearly implies that per-entity filtering is not supported, which routes to other list tools.

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

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

Annotations already declare readOnlyHint true and destructiveHint false, so the description's role is to add beyond that. It explains that the tool returns each type's id and name and that the values are account-configured. It does not contradict annotations and provides useful context, though it could mention pagination behavior more explicitly.

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

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

The description is two sentences with no wasted words. The first sentence states the core purpose, and the second provides usage context. It is front-loaded and every sentence is valuable.

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 with two optional parameters and no output schema. The description covers purpose, usage context, and output fields (id and name). Annotations are present. It lacks explicit pagination behavior, but overall it is fairly complete for a read-only reference data tool.

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

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

Schema coverage is 50% because the 'page' parameter lacks a description; only 'perPage' is described. The description does not elaborate on the parameters (page and perPage) beyond the schema. It mentions 'list all' but doesn't explain how pagination works. Given the low coverage, the description should compensate but fails to do so.

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 lists all configured activity types, gives examples (Call, Meeting, Email), and explains that it returns id and name. It distinguishes itself by noting these are account-configured, not a fixed enum, and that they are used in add_note, which differentiates it from siblings.

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

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

The description explicitly tells when to use the tool: before referencing an activityType in entry creation via add_note. It explains that the set is account-configured, so calling this is necessary to discover valid values. It does not explicitly mention alternatives or when not to use it, but the context is clear enough.

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

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

The annotations already declare readOnlyHint=true and destructiveHint=false, which is consistent with the 'List' action. The description adds context about main vs. additional parties, but it doesn't describe the response format or pagination behavior. However, given the read-only nature, the transparency is sufficient, and the description adds value 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 concise, consisting of two sentences that immediately convey the purpose and key parameter. It avoids unnecessary detail and stays focused on the essential 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?

The description provides sufficient context for a list operation: it identifies the resource, the parent entities, and gives examples of additional party types. It does not mention response structure, but that is not strictly required for a read-only list. The missing parameter descriptions are a minor gap, but overall the description covers the necessary 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?

Only the 'entity' parameter is described in the schema, and the description reiterates its allowed values. The parameters 'page', 'embed', 'perPage', and 'entityId' lack descriptions, though their names suggest common semantics (pagination, embedding, filtering). The description does not clarify 'entityId' or the meaning of 'embed' tokens, leaving gaps for an agent.

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 ('List'), the resource ('secondary party links'), and the target entities ('opportunity or project'). It also specifies the required parameter 'entity' and its allowed values. This makes the tool's purpose unambiguous and distinguishable from related tools like list_opportunities or list_projects.

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

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

The description explains that the tool lists additional parties, contrasting them with the main party on the entity itself. It also instructs the user to set the 'entity' parameter to 'opportunities' or 'projects'. While it doesn't explicitly name alternative tools, the context and examples make the appropriate usage clear. The lack of explicit 'when not to use' is a minor gap.

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 destructiveHint=false, so safety is covered. The description adds behavioral context: it returns the same record shape as list_projects and is filtered to one opportunity. It also notes the inverse relationship. This goes beyond annotations but doesn't cover pagination or potential edge cases, which is acceptable given the 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?

Two sentences with high information density. The core purpose is front-loaded, the alternative is mentioned, and there is no fluff. Every phrase earns its place.

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

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

With no output schema, the description's reference to 'same record shape as list_projects' is helpful but not a full specification. It also omits that opportunityId is effectively required for meaningful use (though not marked required), and doesn't mention pagination defaults or error behavior. For a read-only list tool with 4 params, more detail on required inputs and response shape would be expected.

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 only 25% (only embed has a description). The description mentions 'given an opportunity' but doesn't explicitly tie that to the opportunityId parameter, nor does it explain pagination (page, perPage) or their defaults. Since the schema leaves most parameters undocumented, the description should step in, and it largely doesn't.

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

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

The description states a specific verb and resource ('List projects associated with a given opportunity') and clarifies that it returns the same record shape as list_projects but filtered, which distinguishes it from sibling tools like list_party_projects. This is precise and actionable.

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

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

It explicitly says when to use this tool ('only needed for opportunity → projects discovery'), when not needed (inverse direction is available directly on the project's opportunity field), and names the alternative for party → projects (list_party_projects). This is exemplary routing guidance.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds that it returns board id, name, and stages, and that boards are stable. No contradictions; the added context is helpful but does not cover pagination behavior or other traits.

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

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

The description is three sentences, each serving a purpose: stating the action, defining the resource, and providing usage context. No redundant words; efficient 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?

Given no output schema, the description does specify return fields (id, name, stages), which is adequate. Pagination is supported but not mentioned. The tool is simple and the context provided is sufficient for selection and basic use.

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

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

Schema description coverage is 0%, and the description does not mention the pagination parameters (page, perPage) at all. While the parameters are standard and optional, the description misses the opportunity to explain their role, leaving the agent to infer from the schema only.

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 lists all project boards, explains what a board is (a grouping of stages), and specifies the returned fields (id, name, stages). It differentiates from sibling tool list_pipelines by calling boards the project equivalent of opportunity pipelines.

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

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

The description provides explicit guidance to use this tool to discover boardId when creating a project, and then to use list_stages for stage selection. It notes that boards are stable per account. No explicit when-not-to-use, but 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?

The description adds behavioral context beyond annotations by noting that the set is account-configured rather than a fixed enum. Annotations already declare readOnlyHint=true and destructiveHint=false, so the description doesn't need to repeat that, but it adds useful information about dynamic data.

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

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

The description is three sentences, no redundancy. It starts with the core action and then provides context and purpose. Every sentence 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?

For a simple read-only list tool, the description covers the return format (id, name, colour) and purpose. However, it does not mention that the list is paginated (as per schema), which is a minor gap. Overall, it's fairly 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?

The input schema has two parameters (page, perPage) with 50% description coverage (only perPage has a description). The description does not mention any parameters, leaving page undocumented. It should at least indicate that pagination is available.

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 lists configured entry/task categories with their colours, IDs, and names. It distinguishes itself from sibling list tools by specifying the resource (categories) and provides examples of categories.

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

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

The description explains when to use this tool: to discover valid category IDs before using them in add_note or create_task, and for labeling and filtering. It doesn't explicitly state when not to use it, but the usage context is clear.

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

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

Annotations already declare readOnly/destructive=false, so the description adds meaningful extras: the complete one-shot listing (no pagination), the exact row count (250), and that the data is cached reference data. This rises above the annotation baseline.

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

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

Dense but not bloated: it packs the row count, field list, usage condition, and error behavior into a single tight sentence. A minor over-elaboration on the exact reject message is acceptable, so a 4, not a 5.

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

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

Covers the data set size, field schema, usage trigger, and failure mode. An agent can decide and call this tool correctly without opening the schema or consulting anywhere else.

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

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

The tool takes zero parametersthority, so the schema fully covers it. The description adds no parameter explanations because none are needed — a baseline 3 is appropriate; there is simply nothing further to clarify.

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 (

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

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

Explicitly says when to use it: tie to party addresses, and notes the exact spelling requirement (anything else → 422). It also names an alternative class (add_party_address) where this dictionary is the prerequisite.

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

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

Beyond the read-only annotation, the description discloses that the data is cached (reference data) and that the complete list is returned in one response (no pagination). This gives the agent a clear expectation of the tool's behavior and performance characteristics.

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 concise yet information-dense, covering all essential aspects in a single sentence. It is well-structured, starting with the action, then the content, purpose, and behavioral notes, with no wasted words.

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

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

Given the tool's simplicity (no parameters, no output schema), the description is fully complete. It explains what the data contains, its intended use, and its delivery characteristics, leaving no ambiguity for the agent.

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 has no parameters, and the description correctly does not attempt to describe any. Since there are zero parameters, the baseline of 4 is appropriate; the description adds no parameter-related 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?

The description clearly states the tool lists Capsule's currency dictionary, specifying the exact fields (ISO 4217 code, symbol, name) and row count (80). It also explains its purpose as providing valid codes for the opportunity's `value.currency` field, which is unambiguous.

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

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

The description implies when to use it: whenever valid currency codes are needed for `value.currency`. It also mentions that it is cached reference data, suggesting it can be called infrequently. However, it does not explicitly state 'use this when...', so a small gap remains.

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 provide readOnlyHint true and destructiveHint false. Description adds that it returns schema and not values, clarifying behavior 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?

Two concise sentences, front-loaded with purpose, then clarification. No unnecessary words.

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

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

Simple tool with one parameter and good annotations; description fully explains input, output, and boundaries. No output schema 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 has 100% coverage with enum for entity types. Description repeats the entity types but adds no additional semantic meaning beyond schema.

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

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

The description clearly states the tool lists custom field definitions for an entity type, returning schema (name, type, options) not values. It distinguishes from sibling tools like get_custom_field or get_party.

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

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

Explicitly says when to use (to get definitions) and when NOT to use (for values on a record), directing to get_party/get_opportunity/get_project with embed=fields.

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

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

Annotations already indicate read-only and non-destructive behavior. The description adds transparency by mentioning the `restrictedOpportunities` key in the response, which goes beyond what annotations provide.

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

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

The description is brief and front-loaded with the tool's purpose. Every sentence adds value without unnecessary detail.

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

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

Covers the required parameter and a notable response field, but lacks information about pagination parameters (`page`, `perPage`), which are part of the input schema and important for usage.

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

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

Only the `since` parameter is described in the tool description, but it already has documentation in the schema. The `page` and `perPage` parameters lack any description, and with low schema description coverage (33%), the description does not compensate adequately.

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?

Clearly states it lists deleted opportunities on or after a timestamp. The phrase 'Audit feature' distinguishes it from other listing tools and indicates a specific use case.

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 that the `since` parameter is required, which is a key usage instruction. However, it does not provide guidance on when to use this tool versus siblings like `filter_opportunities` or `delete_opportunity`.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds value by noting that the `since` parameter is mandatory and that the response includes a `restrictedParties` key for partially inaccessible records. This behavior is not implied by annotations alone.

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

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

The description is two sentences long, front-loaded with 'Audit feature', and contains no superfluous information. Every sentence provides essential context 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 the absence of an output schema, the description helpfully mentions the `restrictedParties` key. It covers the main purpose and a notable response detail. However, pagination behavior (e.g., sorting, maximum results) is not described, which would be useful 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 coverage is only 33% (only `since` has a description). The description reinforces that `since` is required and explains it is an ISO-8601 timestamp. However, it does not add meaning for `page` and `perPage` beyond their schema constraints (defaults and ranges), so the burden of compensating for low schema coverage is only partially met.

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 it is an 'Audit feature: list parties deleted on or after a given timestamp.' It uses a specific verb ('list') and specific resource ('deleted parties'), and it distinguishes from sibling tools like 'list_deleted_opportunities' by focusing on parties.

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 explicitly states that the `since` parameter is REQUIRED and that the Capsule API rejects the call without it. It also explains the `restrictedParties` key, which helps the agent understand response behavior. However, it does not explicitly state when to use this tool versus alternatives like 'filter_parties'.

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?

Consistent with annotations (readOnlyHint=true, destructiveHint=false). Adds value by revealing the `restrictedProjects` key in responses, informing the agent about potential partial data access. No contradictions.

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

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

Two sentences, front-loaded with purpose. Every sentence adds unique value with no redundancy. Highly 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?

Covers purpose, required parameter, and a notable response feature. Lacks details on pagination behavior and full response structure, which would aid agent invocation. Adequate but incomplete for a list tool.

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

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

Adds meaning for the `since` parameter (required, ISO-8601 format) beyond the schema. However, it provides no explanation for `page` or `perPage`, which lack schema descriptions, leaving a gap for the agent.

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 identifies this as an audit feature for listing deleted projects by timestamp, distinguishing it from general listing tools like list_projects. However, it could further differentiate from sibling tools list_deleted_opportunities and list_deleted_parties.

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 that the `since` parameter is required, providing a clear usage constraint. Does not indicate when to avoid this tool or suggest alternatives, leaving some room for confusion about appropriate 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 indicate read-only and non-destructive. The description adds the key behavioral detail about the filtering logic (organisation field references partyId). It doesn't disclose pagination or embedding behavior, but given annotations cover safety, this is acceptable 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 sentences, front-loaded with the action and purpose. No filler. 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?

The description, combined with the schema and annotations, provides enough for an agent to call this correctly for the main use case. It lacks explicit mention of pagination defaults or embed usage, but these are in the schema. Given the low complexity, it is 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?

Description does not add information beyond the schema. partyId is described in schema, embed is also described. It does not clarify pagination parameters. With 50% schema coverage, the description fails to compensate for the undocumented parameters, resulting in insufficient parameter guidance.

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

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

States the operation precisely: listing employees of an organisation. It explicitly notes the return condition (parties referencing the given partyId) and distinguishes from enumerating all parties. Clear and specific.

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 use-case ('answer who works at X') and tells to avoid using it to enumerate all parties. It doesn't name specific alternative tools but implies the distinction, which is sufficient for the agent to choose appropriately.

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

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

Annotations already mark it as read-only. The description adds transparency about the source of tracks (manual vs. auto-applied from board rules) and hints at how to distinguish them. This exceeds annotation disclosure.

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

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

The description is concise with two sentences and a note, all front-loaded. Every sentence adds value without superfluous words.

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

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

For a read-only list tool with no output schema, the description explains scope, distinguishes from a sibling, and covers behavioral nuance. It lacks detail on the entityId parameter but is otherwise 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 50% (entity has description, entityId does not). The description mentions entity types but does not explicitly tie to the 'entity' parameter or clarify 'entityId'. It adds marginal value over the schema.

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

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

The description clearly states the tool lists track instances on a specific record and explicitly distinguishes it from the sibling 'list_track_definitions', which lists templates. Verb and resource are specific and unambiguous.

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

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

The description implies when to use (when needing track instances on an entity) and distinguishes from list_track_definitions. It does not explicitly state when not to use or list alternatives, but the guidance is clear. The note about auto-applied tracks adds useful 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 and destructiveHint=false, so an agent knows it is a safe read. The description adds valuable behavior context: pagination is supported, default order is most-recent-first, and it covers multiple record types. It omits specifics like pagination response format or embed details, but given annotations cover the safety profile, this is strong.

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

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

The description is a single, compact sentence that front-loads the purpose, states the ordering, and then gives the usage guidance. Every sentence earns its place; no fluff.

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

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

Given no output schema, the description could explain return format, but the tool is a paginated list—an agent can infer the response structure from the schema parameters. The description covers scope, ordering, and alternatives. It doesn't mention embed tokens or pagination details, but that is slightly beyond the minimum for a read-only list tool.

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

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

Schema description coverage is only 33% (only 'embed' is described in schema; 'page' and 'perPage' are not). The description does add context by mentioning pagination and the default ordering, and it hints that this is a global feed. However, it doesn't explain the exact semantics of the three parameters beyond what schema provides for 'embed'; but the description's mention of pagination compensates somewhat. Given the description adds some meaning beyond the bare parameter names and types, a 4 is justified.

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 is specific: 'Global timeline feed: every note, captured email, and completed-task record across the whole Capsule account, paginated.' It defines the resource, the verb (list), the scope, and the content type, which clearly distinguishes it from sibling tools that list entries per party/opportunity/project.

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

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

It explicitly states when to use this tool ('what activity happened today/this week across the company?') and points to sibling alternatives that should be used instead for scoped lists, naming them explicitly. This is the optimal pattern for usage 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?

Discloses empty list behavior for accounts not using Goals feature, adding value beyond readOnlyHint and destructiveHint annotations. No contradictions.

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 efficient sentences, no fluff, front-loaded with purpose. Every sentence 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?

Covers resource, scope, and edge case. Pagination details are in schema. No output schema needed for a list tool. Minor gap: no example or mention of sorting.

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 50% (only perPage described). Description adds no parameter-specific info beyond schema, meeting baseline but not compensating for missing 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?

Clearly states the verb 'list' and resource 'goals', specifying scope as per-user or per-team revenue or activity targets. Distinct from siblings as no other tool lists goals.

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

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

Implies usage for retrieving goals but lacks explicit guidance on when to use vs alternatives or when not to use. No mention of pagination or filtering beyond schema.

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