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

Beyond the annotations, the description discloses idempotency, the exact response shapes for fresh and repeated links, and that Capsule's 422 error is caught and converted internally. This is substantial behavioral context that helps an agent predict side effects and interpret results.

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

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

The description is compact and front-loaded. Every sentence adds useful information: the action, the relationship to main-party setup, idempotency, and the response shape. No redundant or filler content is present.

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 does well to document the response behavior in detail. It also covers idempotency and error conversion, which are the main behavioral hazards. Combined with the schema's enum and parameter descriptions, the tool is adequately specified 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 schema already describes 'entity' and 'partyId', and the description reinforces that the party must be existing and that the target is an opportunity or project. However, the required 'entityId' parameter is not described in either the schema or the description, leaving its meaning to be inferred 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?

The description opens with a specific verb and resource: link an existing party as an additional secondary party on an opportunity or project. It also distinguishes this operation from setting the main party, which is handled by update_opportunity / update_project, so it is clearly differentiated from sibling tools.

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

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

The description explicitly states where the main party is set via update_opportunity / update_project and clarifies that this tool adds additional parties beyond the main one. This gives the agent a clear decision rule for when to use this tool versus the relevant 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 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 already establish that this is not read-only and not destructive. The description adds useful behavioral detail: the operation is atomic and maps to a single PUT to Capsule, and 'append' implies additive rather than replacing semantics. This goes beyond the boolean 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?

Two sentences with no filler. The core action is front-loaded, and the sibling-routing guidance is delivered in a single, direct sentence. 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?

For a simple append-mutation tool, the description covers purpose, atomicity, and usage guidance, supplemented by rich country-validation details in the schema. Minor gaps remain (e.g., return value, permission prerequisites), but these are not critical for correct invocation of this straightforward operation.

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

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

Schema description coverage is only 29% (2 of 7 parameters documented). The description itself provides no parameter-level guidance beyond the schema's country-field validation details. With this low coverage, the description should compensate by explaining key parameters, but it 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 and resource ('Append a single postal address to a party') and immediately distinguishes itself from update_party.addresses. An agent can tell exactly what this tool does and how it differs from related operations.

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 this tool: 'Use this instead of update_party.addresses for single-entry adds.' This gives a clear decision rule and names the alternative, so an agent knows both when to invoke this tool and when to prefer the 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses 'Atomic — one PUT to Capsule,' revealing atomicity and the underlying transport operation, which the annotations do not convey. It also clarifies the append-only, non-replacing semantics versus the bulk alternative. A small gap remains: no mention of error behavior or idempotency, but the disclosed traits add real value 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, each earning its place: the core action, the atomicity/transport trait, and the routing guidance against the sibling. The most decision-relevant information is front-loaded in the first sentence, and there is no filler or restatement of the tool name.

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

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

For a simple 3-parameter append operation with no output schema, the description covers the key decision factors: operation semantics, atomicity, and when to prefer it over update_party. The main omission is the response shape on success or failure, but with annotations already establishing the mutation/safety profile and the operation being low-complexity, nothing an agent needs to select or invoke it correctly is materially missing.

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

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

Schema description coverage is only 33% (only `type` has a natural-language description), so the description carries some burden. It contextualizes `address` as a single entry and the operation as append-only, but it does not elaborate on `partyId` or the label semantics of `type` beyond the schema. The parameter names are self-evident, which softens the gap, but the description only partially compensates for the low schema coverage.

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+resource: 'Append a single email address to a party.' The word 'single' scopes the operation precisely, distinguishing it from bulk array updates and from the sibling add_party_phone_number/add_party_address tools, which target different resources. No ambiguity about what this tool does.

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

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

The description explicitly names the alternative ('update_party.emailAddresses'), states the condition that selects this tool ('when you want to add exactly one entry'), and explains the behavioral difference ('the bulk array on update_party is append-only and won't replace'). This is textbook when-to-use/when-not-to-use routing with zero 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?

The annotations already indicate this is a non-read-only, non-destructive operation. The description adds useful behavioral context by stating the operation is atomic and performs a single PUT to Capsule, and by framing it as an append rather than an update. It does not cover error handling or duplicate behavior, but the added atomicity context goes 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?

Two tight sentences with no filler. The core action is front-loaded, and the routing guidance is stated immediately after the behavior. 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?

For a simple three-parameter operation with no nested objects or enums, the description covers the action, atomicity, and the key alternative. It does not describe return values, but there is no output schema and the operation is simple enough that this omission is not critical. A minor gap is the lack of any prerequisite note, such as the party needing to exist.

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%, so the description should compensate. It clarifies that 'number' is a phone number and that the operation appends a single entry, but it does not explain partyId or type beyond what the parameter names and the existing schema description for type already provide. The parameter meanings are recoverable, but the description adds limited per-parameter 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 states a specific verb and resource: 'Append a single phone number to a party.' It also differentiates itself from update_party.phoneNumbers, making the tool's distinct purpose immediately clear. The sibling tools include add_party_email_address and remove_party_phone_number_by_id, so this precise action is well separated.

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 instead of update_party.phoneNumbers for single-entry adds' explicitly names the alternative and the condition under which this tool should be chosen. This gives an agent clear routing guidance without needing to inspect update_party's schema.

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

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

The annotations only say the tool is not read-only and not destructive. The description adds meaningful behavioral context: 'Append' indicates it does not replace existing data, and 'Atomic — one PUT to Capsule' reveals the underlying operation's scope and side effect. It does not cover duplicate handling or authorization, but what it adds goes clearly 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?

Three sentences carry a large amount of useful information with zero filler. The core action is front-loaded, followed by the atomicity detail and the routing instruction, and then the address semantics. Nothing is extraneous.

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

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

For a simple, single-resource append with a fallback to the schema for parameter details, the description covers action, scope, alternative, and parameter semantics. It does not mention the return value or error behavior, but the lack of an output schema makes a small gap. Overall, the information provided is sufficient for correct invocation.

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

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

Schema description coverage is 67%, which already documents 'address' and 'service' in detail. The description restates the address semantics (URL vs. handle) but adds no new parameter-level information beyond what the schema provides. PartyId remains documented only by type, not by purpose.

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'), a clear resource ('a single website / social handle to a party'), and immediately distinguishes itself from update_party.websites. An agent can tell exactly what this tool does and how it differs from similar party-update tools.

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

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

The description explicitly routes the agent: 'Use this instead of update_party.websites for single-entry adds.' This names the alternative and defines the exact condition that selects this tool, so no inference is 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 declare readOnlyHint=false and destructiveHint=false. The description adds crucial behavior beyond that: resolve-or-create semantics, case-insensitive matching with canonical-casing preservation, and explicit idempotency ('re-attaching an already-attached tag is harmless'). No contradiction with annotations; the creation-on-miss side effect is surfaced clearly.

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?

Every sentence earns its place: core purpose is front-loaded, followed by resolution behavior, case-sensitivity nuance, duplicate-avoidance guidance, idempotency, and the detach alternative. The length is justified by the genuinely non-obvious matching behavior and sibling routing; 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 3-param tool with a rich description and 100% schema coverage, the definition is nearly complete: it covers what the tool does, side effects, idempotency, and alternatives. The only gap is that, with no output schema present, the description never states what the tool returns (e.g., whether it returns the resolved tag or a success indicator), which the rubric implies the description should cover.

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's tagName description is nearly a verbatim copy of the tool description, so the schema already carries full parameter meaning. The description adds marginal value for entity/enum and entityId, which the schema documents adequately. Baseline 3 is appropriate since the description does not compensate for any schema gap (there is none).

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+resource: 'Attach a tag to a party, opportunity, or project by NAME.' It clearly distinguishes this tool from the sibling cluster (remove_tag_by_id, delete_tag_definition, batch_add_tag, list_tags) by emphasizing attach-by-name semantics, so an agent can select it without opening schemas.

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 routing: 'call list_tags first and reuse the exact name' to avoid near-duplicates, and 'To DETACH a tag, use remove_tag_by_id with the tag's id (read via get_party/get_opportunity/get_project with embed="tags")'. This names the alternatives and the conditions that select them, leaving nothing to inference.

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

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

The description goes well beyond annotations by warning that the operation is NOT IDEMPOTENT, explaining that duplicate applications create duplicate instances/tasks, and detailing how startDate drives dueOn computation. It also discloses a subtle source of noise (auto-applied tracks from board rules). Annotations only indicate it is not read-only and not destructive, so the description carries and fully satisfies the transparency burden.

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?

Every sentence earns its place: main action, side effects, date calculation, template discovery, idempotency warning, and pre-check guidance. The most critical behavioral warning (non-idempotency) is bolded and placed prominently.

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 purpose, side effects, date logic, idempotency, discovery, and pre-check workflow. The only minor gap is that it does not describe the return value, and there is no output schema to fill that void; for a create-style tool this is a small omission.

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

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

Schema descriptions already cover entity, startDate, and trackDefinitionId. The tool description adds meaningful semantics by explaining how startDate defaults to today and how it combines with each task's daysAfter offset, and that trackDefinitionId auto-creates task definitions. entityId lacks a schema description and is not elaborated in the tool description, but its purpose is self-evident.

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+resource: 'Apply a track definition to an opportunity or project.' It goes on to clarify the outcome (creates a track instance and auto-creates tasks), which clearly differentiates it from sibling operations like update_track or remove_track and positions it relative to list_track_definitions.

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 tells the agent to use list_track_definitions to discover templates and to call list_entity_tracks first if single application is desired. The added caveat about board-stage auto-applied tracks provides nuanced guidance about when the pre-check may be unreliable.

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 readOnly/destructive annotations, it discloses parallel fan-out, the default concurrency cap (CAPSULE_MCP_BATCH_CONCURRENCY=5), cache invalidation per entity type, and the exact result/summary shape. These are non-obvious side effects the annotations alone would not convey.

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 purpose, then gives usage shape, runtime behavior, return value, and cache side effect in a few sentences with no filler. Each sentence carries distinct information.

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

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

With no output schema, the description compensates by specifying the returned { results, summary } shape. It also covers item count limits, concurrency behavior, per-item equivalence to add_tag, and cache invalidation, which is complete for the tool's 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?

The input schema already documents the item structure fully (100% coverage), so the baseline is 3. The description adds value by showing the exact array shape inline, tying it to realistic mass-tagging examples, and explaining that each item behaves like a standalone add_tag call, going slightly beyond the schema baseline.

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

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

The description opens with a specific verb and resource ('Attach tags to many entities in parallel'), supported by concrete scenarios and an explicit comparison to the single add_tag call. This clearly distinguishes batch_add_tag from siblings like add_tag and batch_remove_tag_by_id.

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 examples (RSAC26 conference tagging, layoff batches) define when batch tagging is appropriate, and the 1–50 item cap plus 'each item is processed identically to a single add_tag call' grounds the usage model. It does not explicitly say to use add_tag for a single item, but that alternative is strongly implied.

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

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

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?

Discloses idempotent handling of already-detached tags, parallel fan-out with a default cap of 5, and the exact return shape. Annotations only mark not-read-only and not-destructive, so the description supplies all crucial behavioral context 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?

Three compact sentences front-load purpose, then input format, then behavior and return value. Every sentence earns its place without duplicating schema details or adding 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?

Covers what the tool does, how to invoke it (items shape, 1–50 limit), parallel execution cap, idempotency semantics, and output structure – essential because there is no output schema. For a batch mutation tool, this is comprehensive and sufficient for safe 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 already fully describes the items array with min/max and field constraints. The description adds value by showing the concrete input shape and clarifying that each item is processed identically to a single remove_tag_by_id call, plus mapping output results back to individual items.

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 opens with 'Detach tags from many entities in parallel' – a specific verb, resource, and scope. It explicitly positions itself as 'cleanup counterpart to batch_add_tag' and contrasts with the single 'remove_tag_by_id call', making it clearly distinguishable 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?

Names both the counterpart batch tool (batch_add_tag) and the single-operation equivalent (remove_tag_by_id), giving clear context for when batch removal is appropriate. It doesn't explicitly state exclusion conditions, but the implied usage is strong and unambiguous.

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, the description discloses parallel fan-out, a default concurrency cap of 5, the response shape, the possibility of partial failures, and that Capsule has no rollback. These are significant behavioral details that an agent needs to set expectations and handle errors.

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 information-dense with no filler. It front-loads the core capability, then explains when to use it, how it behaves, and what it returns, all in a compact set of 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?

Given there is no output schema, the description does the necessary work by specifying the return shape, summarizing success/failure counts, and warning about partial failures and lack of rollback. It also explains the relationship to update_opportunity and the practical limits of the batch operation.

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

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

Schema description coverage is 100%, and the schema already documents the items array, the 1–50 cap, that each item matches update_opportunity, and that only id is required. The tool description reinforces this but does not add meaningful parameter-level detail beyond what the schema provides.

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

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

The description states a specific verb and resource: 'Update 1–50 opportunities in parallel.' It explicitly distinguishes itself from update_opportunity by noting the same input shape wrapped in an `items` array, making its role clear relative to the sibling 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 explicitly says to use this tool 'not N sequential update_opportunity calls' and names concrete use cases: mass stage transitions, owner reassignments, and value adjustments. This gives an agent clear conditions for choosing this tool over the alternative.

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 only state that the tool is neither read-only nor destructive, but the description goes much further: it discloses that the connector fans out parallel HTTP requests, the configurable concurrency cap of 5, the exact return shape, and critical partial-failure semantics with no rollback. This is far beyond what the annotations or schema reveal and is essential for correctly handling results.

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

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

Despite being information-dense, every sentence earns its place: purpose, usage scenario, implementation detail, return format, and failure semantics are all covered without repetition. Key facts are front-loaded, with the single-record comparison and usage guidance appearing immediately after the first sentence.

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

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

For a batch mutation tool with no output schema, the description is remarkably complete. It specifies the return structure, the possibility of partial failures, the absence of rollback, and the need to inspect per-item results for follow-up. Combined with the fully documented items schema, an agent has all the information required to invoke the tool and interpret its response 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% and the items parameter is thoroughly documented in the schema. The description adds value by pointing out that each item is 'the same shape as update_party,' which lets the agent reuse its knowledge of the single-update tool rather than studying the full nested schema. It also explains the 50-item cap in terms of rate-budget protection, giving rationale beyond the schema's validation rules.

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 precise verb, object, and range: 'Update 1–50 parties in parallel.' It immediately distinguishes itself from update_party by explaining the items-array wrapper and explicitly names the sibling it replaces for bulk writes. An agent can tell this apart from update_party and the other batch_update_* tools without examining 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 instructs when to use this tool: 'Use this — not N sequential update_party calls — for any homogeneous multi-record write,' with concrete examples like mass owner reassignment and bulk metadata corrections. This provides both the condition and the alternative, leaving no ambiguity about when to prefer batch over sequential calls.

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 say readOnlyHint=false and destructiveHint=false, so the description carries the burden of behavioral disclosure. It does this well by revealing parallel HTTP fan-out, a default concurrency cap of 5 (with env var), the return shape, possible partial failures, and the absence of rollback. This is exactly the kind of operational context 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?

The description is dense but every sentence contributes: identity, usage guidance, sibling parity, concurrency behavior, return shape, and failure semantics. It is front-loaded with the core action and scopes the tool before diving into operational details.

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

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

For a batch mutation tool with no output schema, the description is unusually complete: it covers the input contract, when to use it, how it executes, what it returns, partial-failure behavior, and lack of rollback. There is no critical operational gap that would prevent 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 the baseline is 3, but the description adds meaningful semantics about the items array: it wraps update_project inputs, is capped at 50 for rate-limit reasons, and mirrors sibling batch tools' shape. This goes beyond the schema's structural definition and explains why the constraint exists.

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 ('Update 1–50 projects in parallel'), names the resource, and explicitly contrasts itself with update_project and sibling batch tools. An agent can immediately distinguish this from sequential project updates and from batch_update_party/batch_update_opportunity without inspecting schemas.

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

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

It gives explicit when-to-use guidance: mass stage transitions, bulk owner reassignments, batch closures — and explicitly says to use this rather than N sequential update_project calls. It also names the sibling batch tools it mirrors, which helps an agent generalize the fan-out shape across entity types.

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 non-read-only and non-destructive behavior. The description adds valuable context by explaining what state it sets, which fields are populated, and that the task is preserved in history. This clarifies the impact beyond the basic 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?

The description is compact and front-loaded with the action, then efficiently provides behavioral details and sibling relationships. Every clause contributes useful 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?

For a single-parameter mutation tool with no output schema, the description covers the action, side effects, and usage context well. The only minor gap is not describing what the tool returns or explicitly confirming that id refers to the task being completed.

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 explain the 'id' parameter at all. While the parameter name is self-evident, the description fails to compensate for the missing schema-level documentation, and there is no explicit statement that id is the task identifier.

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 action and resource: 'Mark a task as done / completed / finished' and further specifies the exact state change (status=COMPLETED, completedBy, completedAt). It also differentiates itself from delete_task and update_task, making its purpose unmistakable.

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 tells the agent when to use the tool ('whenever a user says mark done, complete, finish') and identifies the alternative (update_task with status:COMPLETED) and the contrasting tool (delete_task). This gives clear routing guidance beyond the schema.

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

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

Annotations already declare this is a non-read-only, non-destructive write, and the description does not contradict that. It adds one behavioral nuance (pipeline inferred from milestone) and the value/currency coupling, but does not mention creation side-effects such as milestone automation mutating owner/team or the default-owner behavior (those live only in the schema, not the tool description).

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 the main action first, followed by the key constraint and the workflow pointers. No filler or repetition of the full schema; 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 13-parameter creation tool with no output schema, the definition plus detailed schema gives enough to call it correctly: required fields, cross-parameter validation, discovery steps, and a follow-up sibling for multi-party deals. The only real gap is that the description doesn't state what the successful create returns, which would be useful when there is no output schema.

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

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

Schema coverage is moderate (~69%), and the description mostly restates what the schema already documents — partyId and milestoneId are required, milestone determines pipeline, currency must accompany amount. It does add the concise discovery workflow and multi-party follow-up, but does not compensate for undocumented parameters like name, description, or probability.

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

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

The description opens with 'Create a new opportunity linked to a party' — a specific verb and resource that clearly distinguishes create_opportunity from update, search, get, and delete siblings. It also states the key linkage requirements (partyId, milestoneId), so an agent can tell what this tool is for before looking at 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 tells the agent to discover valid milestone ids via list_pipelines/list_milestones first and to use add_additional_party for multi-party deals, giving concrete pre- and post-steps. It does not explicitly state when not to use it or contrast it with update_opportunity, but the creation intent 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?

With only readOnlyHint=false and destructiveHint=false in annotations, the description carries the full burden of behavioral disclosure—and it does so extensively. It details silent field ignoring, owner defaulting, country dictionary rejection (422), BOOLEAN two-state semantics, NUMBER read-back as strings, audit-log noise on null writes, and append-only merges for nested collections. All of this exceeds what annotations reveal and directly helps an agent predict outcomes.

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 long but each section earns its place; it is front-loaded with the core purpose and type contract, then methodically walks through nested behaviours vice top-level. The structure is readable (bolded parameters, clear sentences) and avoids redundancy. Slightly overpacked for a reviewer, but not bloated for an agent needing exact behaviour.

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 has 16 parameters, no output schema, and multiple hidden caveats (country dictionary, BOOLEAN two-state, append-only merges), the description is remarkably complete. It covers error cases, defaults, side effects, and creation-time shortcuts. The only omissions are minor (e.g., response shape), and the description is sufficient for a competent agent to call the tool correctly in the vast majority of scenarios.

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 56%, and while the schema itself documents many parameters, the description adds materially: it explains the type-specific requirements for name vs firstName/lastName, the 404 condition for organisationId, the creation-only nature of trackDefinitionIds, and the append-only semantics for nested arrays. It clearly compensates for the coverage gap and clarifies edge cases that the schema alone would miss.

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 the precise action 'Create a new person or organisation in Capsule CRM' and immediately explains the two type-specific contract rules (required name vs firstName/lastName, silently ignored fields). It also flags a non-obvious 404 for organisationId pointing to a non-organisation, which clearly differentiates this from update_party and other party tools. No ambiguity about what the tool does.

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

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

The description gives targeted when-to-use vs when-not guidance: it points to atomic add/remove/replace for websites/addresses/phones/emails, notes trackDefinitionIds is a creation-only shortcut vs apply_track, and instructs to use update_party after creation for team-owned parties without an owner. It does not have an explicit 'when not to use' blanket statement, 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?

Annotations already signal a non-read-only, non-destructive write. The description adds useful observable behavior by stating the return value ('Returns the created project including its assigned id') and the effect of stageId on board placement. However, it does not disclose side effects such as board automations mutating owner/team, the owner-or-team requirement, or failure modes; those live only in parameter descriptions. 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 compact and front-loaded: core creation action, required/optional inputs, conditional board-pinning behavior, ID discovery, and return value. Every sentence earns its place, and there is no padding or needless repetition of the schema.

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

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

Given 11 parameters and no output schema, the description covers the high-level call contract: what is created, required inputs, optional board placement, and the returned project with its id. The schema's property descriptions provide the deeper caveats (ownership requirements, board automations, custom-field quirks). A small gap is that the description calls owner/team 'optional' without warning that at least one is required, though the schema covers this.

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 high (82%), so the baseline is 3. The description largely restates information already present in the schema: 'Requires partyId and name' mirrors the required array, and 'stageId uniquely identifies a stage within a board' matches the stageId property description. It adds minimal value beyond pointing to both list_boards and list_stages for ID discovery.

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

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

The description states a specific verb and resource: 'Create a new project in Capsule CRM linked to a party.' It clearly distinguishes create_project from sibling creation tools like create_party, create_opportunity, and create_task, and from update_project/get_project by framing the operation as creation with a returned 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 gives clear context: required parameters ('Requires partyId and name'), optional parameters, and conditional guidance for pinning to a board ('To pin a project to a specific board+stage on creation, pass stageId'). It also names discovery tools (list_boards + list_stages). It does not explicitly contrast with update_project or other create_* siblings, so it stops short of full when/when-not guidance.

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

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

Annotations 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 goes well beyond the destructiveHint annotation by explicitly stating that deletion is irreversible, requires confirm=true, and is idempotent on retry. It even discloses the exact two response variants, so the agent knows what to expect whether the entry existed or was already gone.

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 dense and economical: the warning is front-loaded, the precondition is stated in one short sentence, and the idempotency behavior is summarized with concrete response examples. 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 destructive delete tool with no output schema, the description is unusually complete: it covers what happens on success, what happens when the entry is already deleted, and the required confirmation flag. No critical operational detail is missing.

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

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

Schema description coverage is 100%, so the schema already documents both id and confirm. The description reinforces confirm's role but adds no parameter-level meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description names a specific verb ('permanently delete'), a specific resource ('a note (or other entry)'), and the means ('by its ID'). This clearly differentiates it from sibling delete tools like delete_party, delete_project, or delete_task by scoping it to entries.

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

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

The description gives clear context: this is the destructive deletion tool for entries and requires confirm=true as a precondition. It does not explicitly compare itself to sibling tools, but the entry scope and confirm requirement provide enough guidance for correct 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?

Beyond the destructiveHint annotation, the description adds irreversibility, the confirm=true requirement, retry idempotency, and the exact response shape for both fresh deletes and already-deleted cases. This is rich behavioral context that the annotations alone do not 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?

Three compact sentences: the destructive warning is front-loaded, followed by required preconditions, and then retry behavior. Every sentence earns its place with no filler or repetition.

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

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

For a destructive two-parameter tool with no output schema, the description provides the essential workflow, confirmation requirement, return values, and idempotent retry behavior. Nothing critical is missing 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?

The schema already documents confirm well. The description reinforces confirm=true and implies id targets an opportunity, but it does not add substantial new meaning for id beyond what the schema's name and constraints convey. Schema coverage is 50%, so this is adequate but not exceptional.

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: 'permanently delete an opportunity.' It is immediately distinguishable from read tools like get_opportunity, update_opportunity, and list_deleted_opportunities, and it emphasizes the destructive nature clearly.

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 preconditions: read the opportunity first with get_opportunity, confirm with the user, and set confirm=true. It clearly tells the agent when and how to invoke the tool safely, including the required confirmation step.

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 signal destructive intent, and the description goes far beyond them by disclosing irreversibility, cascading deletion of linked records, the organisation-vs-person exception, orphaned track instances, and exact retry responses. This is rich, non-contradictory behavioral 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 long but every sentence carries essential safety, side-effect, or workflow information. The destructive warning and main action are front-loaded, and the detailed caveats are organized in a logical sequence.

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 appropriately covers return values, idempotency, prerequisites, side effects, exceptions, and cleanup alternatives. It gives an agent everything needed to invoke this dangerous operation safely and 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 documents confirm's const=true and some cascade effects, but the description adds the silent clearing of organisation fields, orphan track behavior, and the idempotent response shape. The id parameter is not explicitly redefined, though the get_party-first workflow makes its role clear.

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: permanently delete a party (person or organisation), and names the exact cascading consequences. This clearly distinguishes it from sibling delete tools like delete_opportunity, delete_project, and delete_task.

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

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

It explicitly instructs to read the party first with get_party and confirm with the user before calling. It also tells the agent when to use remove_track instead of proceeding with deletion, and notes that retries are safe due to idempotent behavior.

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 destructiveHint=true and readOnlyHint=false, but the description goes beyond them by disclosing irreversibility, the confirm=true requirement, and exact idempotent response shapes for fresh versus already-deleted projects.

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 the destructive warning, and every sentence adds operational value: alternative, required flag, precondition, and retry behavior. No filler.

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

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

For a destructive two-parameter mutation with no output schema, this is complete: it covers safety, prerequisite workflow, alternative, and even the exact response contract. Nothing an agent needs to call it safely 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?

The description reinforces the confirm parameter with 'Requires confirm=true' and the destructive consequence, complementing the schema's const=true description. It does not add new meaning for id, but the role of id as the project to delete is unambiguous from the tool name and the get_project-first instruction.

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 'DESTRUCTIVE & IRREVERSIBLE: permanently delete a project,' giving a specific verb, resource, and scope. It explicitly contrasts with update_project status='CLOSED' so an agent can distinguish this tool from the close-preserving-history path.

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

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

States when to prefer update_project with status='CLOSED' and mandates a read-then-confirm workflow: 'Always read the project first with get_project and confirm with the user before calling.' There is no ambiguity about prerequisites or 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 declare destructiveHint=true, and the description goes well beyond them: it discloses the tenant-wide blast radius, irreversibility (re-creating mints a new id), idempotency on retry with exact return shapes for both fresh-delete and already-deleted cases, and that the 404 is caught. No contradiction with annotations – all added context is consistent.

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

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

Front-loaded with the critical warning ('DESTRUCTIVE & TENANT-WIDE') before anything else, then proceeds through scope, contrast, use case, workflow, irreversibility, and idempotency. Every sentence earns its place for an operation this dangerous; the only borderline clause (endpoint verification) is a single parenthetical that adds confidence.

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

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

For a destructive tenant-wide mutation with no output schema, the description covers everything an agent needs: operation, scope, prerequisites, alternatives, return values for both success paths, and error handling. The input schema covers parameters at 100%, and return behavior is spelled out in the description since no output schema exists.

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

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

Schema coverage is 100% and the schema itself is already rich (tagId is clarified as NOT an entity id; confirm's description is detailed). The description adds value beyond that by providing workflow context: reading the tag first via list_tags, confirming with the user, and the return payloads tied to tagId/entity. It reinforces rather than merely repeats.

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

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

States a precise verb+resource: 'permanently delete a tag DEFINITION from an entity type's tag namespace', and immediately distinguishes itself from the sibling tool remove_tag_by_id. An agent can tell exactly what this tool does and what it does not do, without needing to open 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?

Gives explicit when-to-use ('clean up stray / mistyped / test tag definitions'), explicit when-not-to-use ('if you only want to untag one record, use remove_tag_by_id instead'), and a required precondition workflow ('Always read the affected tag first via list_tags and confirm with the user'). This is fully actionable 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=true), the description adds the precise idempotency contract with example response payloads for fresh vs already-deleted tasks. It also warns irreversibility and requires confirm=true, giving the agent full behavioral expectations. No contradiction with annotations.

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

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

Three sentences with the destructive warning and primary purpose front-loaded, followed by the alternative, the precondition, and the idempotency contract. No filler or repetition of schema information that is already present.

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 provides the complete response contract for both fresh and repeated deletes. It covers the core action, the safer alternative, the required flag, and retry semantics, making it self-sufficient for an agent to invoke 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 only documents confirm (50% coverage) while id lacks a description. The description compensates by establishing the confirm requirement and defining the response uses id, making the id's role clear. The schema's numeric constraints on id remain the reference for validation, and the description adds just enough semantic 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?

The description opens with 'DESTRUCTIVE & IRREVERSIBLE: permanently delete a task,' naming the exact verb, resource, and consequence. It explicitly contrasts with complete_task, which marks a task done while preserving history, so it is easily distinguishable from the sibling that looks most similar.

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 'Prefer complete_task to mark a task done while keeping it in history,' giving a clear when-not-to-use condition and naming the alternative. It also states the mandatory confirm=true precondition and documents idempotent retry behavior, leaving no doubt about invocation.

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 genuinely useful behavior beyond annotations: Capsule's API does not support ad-hoc sort, IDs are monotonic, and 'most recent X' can be approximated by filtering on a date field and taking the highest ID. This is non-obvious and valuable context.

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

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

The description is two sentences with no wasted words. The purpose is front-loaded, and the second sentence packs a high-value sorting workaround with a concrete example. Every clause earns its place.

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

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

For a read-only filter tool with a well-documented schema and no output schema, the description covers the key non-obvious pitfalls: no sort support and how to get newest records. It doesn't describe the return shape or restate AND semantics, but those are either obvious for a filter or already in the schema. Overall, it is complete enough for correct invocation.

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

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

Schema description coverage is 50%: conditions and embed are thoroughly documented, while page and perPage are left to their self-explanatory names. The description adds a concrete condition example and summarizes possible condition fields, but the schema already carries most of the semantic weight for conditions. It doesn't compensate for the undocumented pagination params, though those are conventional.

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: 'Filter opportunities by structured conditions (milestone, value, close date, tags).' It clearly enumerates the condition dimensions and explicitly contrasts with search_opportunities, so an agent can tell them apart without inspecting schemas.

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 'Use this — not search_opportunities —' and gives concrete example questions ('last won deal', 'opportunities closed this month', 'pipeline X at milestone Y'). It even provides a workaround for the API's lack of ad-hoc sorting, so the agent knows exactly when and how to use this 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 mark this as read-only and non-destructive. The description adds valuable behavioral context beyond annotations: the API does not support ad-hoc sort, Capsule IDs are monotonic, and the recommended workaround for 'most recent X' queries. This helps the agent predict result semantics accurately.

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 dense sentences with no filler. The purpose is front-loaded, routing guidance follows, and the sort workaround is delivered efficiently with a concrete example. 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 filtering tool with no output schema, the description covers the essential use cases, limitations, and workaround strategy. It doesn't explain pagination or response shape, but those are largely inferable from the schema and the tool's role as a filter operation. The main gap is minimal and non-critical.

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

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

The description adds meaningful semantic guidance beyond the schema by showing an actual condition object for date-range filtering and explaining how to derive the newest record. Given the schema already documents field/operator/value options thoroughly, the description supplements rather than repeats, which compensates reasonably for the moderate schema coverage.

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 'Filter parties by structured conditions (date ranges, tags, fields)', a clear verb-resource-mechanism statement. It also explicitly contrasts itself with search_parties, making the tool's purpose and differentiation immediately obvious.

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

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

It directly says 'Use this — not search_parties — for questions like...' and provides concrete example queries. This is explicit when-to-use guidance with a named alternative, leaving no ambiguity about tool selection.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds important non-obvious behavior beyond annotations: Capsule's API does not support ad-hoc sort, Capsule IDs are monotonic, and the highest-id row after a date-filtered query is the newest record. This is exactly the kind of behavioral context an agent needs to use the tool correctly.

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 information-dense sentences with no filler. The purpose and key differentiator are front-loaded, and the no-sort workaround is packed efficiently into the second sentence 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?

For a read-only filter tool with a detailed conditions schema and a clear sibling context, this description is complete. It covers the main API limitation, gives a concrete workaround, and tells the agent when not to use list_projects. The return concept is clear from the tool name and sibling set, so the lack of an output schema is not a critical gap.

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

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

Schema coverage is 50%: conditions and embed have descriptions, while page and perPage rely on defaults and type constraints. The description adds meaningful value by explaining the conditions-based strategy for achieving 'most recent' without sort, but it does not compensate fully for the un-described pagination parameters. This is a solid improvement over the schema baseline, though not exhaustive.

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 ('Filter projects by structured conditions') and names the kinds of filters supported: date ranges, status, tags, owner. It explicitly distinguishes itself from list_projects with 'Use this — not list_projects', so an agent can route correctly.

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 when-to-use direction with concrete examples ('most recent project', 'projects opened this month') and names the sibling to avoid (list_projects). It also provides a practical strategy for the no-sort limitation, making the usage guidance 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?

The description discloses detailed behavioral traits beyond the readOnlyHint and destructiveHint annotations: image/* returns native image content, text/* and application/json return decoded text, other binary types return metadata + base64, and files exceeding maxSizeBytes return truncated metadata only. This is exactly the kind of response behavior an agent needs to handle results correctly.

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

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

Two sentences, front-loaded with the core action and resource, followed by a compact breakdown of return formats for different MIME families. No filler or redundancy; the brief mention of maxSizeBytes default in prose contextualizes the truncation flag without bloating the description.

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 carries the burden of explaining return values, and it does so across all relevant cases: images, text/JSON, binary types, and oversize truncation. Parameter semantics are fully covered by the schema, so nothing an agent needs to call the tool correctly is missing.

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

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

Schema description coverage is 100%, and the schema already documents both parameters, including maxSizeBytes' default (5242880), maximum (26214400), and truncation behavior. The description repeats the default but adds no new parameter semantics beyond what the schema provides. The baseline 3 is appropriate.

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

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

States a specific verb and resource: 'Download an attachment by id.' The type-specific return details reinforce that this is a retrieval tool, not a mutation. It clearly distinguishes itself from the upload_attachment sibling by its download focus.

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

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

The description makes the tool's purpose unambiguous: retrieve attachment content by id. It doesn't explicitly name alternatives or when-not-to-use conditions, but the only related sibling (upload_attachment) is the inverse operation, so there is no genuine alternative for downloading. This provides clear context without needing explicit exclusions.

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

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

Annotations already declare readOnlyHint=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 safety profile is established. The description adds that this returns a definition rather than a value, but it does not disclose behavior like not-found responses or authorization requirements. Given the annotations cover the main behavioral concerns, a neutral score is appropriate.

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

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

Two short sentences with no filler. The primary action and object are front-loaded, and the discovery instruction is placed second. 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?

For a low-complexity read-only tool with two fully documented parameters, the description is complete. It states what the tool does, how to get the required id, and the annotations cover side-effect safety. No output schema exists, but the return value is implied by 'show' and the definition focus.

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

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

Schema description coverage is 100%, with both id and entity already described in the input schema. The description only repeats the notion of field ids and adds no new parameter semantics. Baseline 3 is appropriate when the schema fully documents 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 action: show a single custom field definition by id. It explicitly uses 'single' and 'by id', which distinguishes it from listing tools. The uppercase 'DEFINITION' reinforces that this returns the field metadata, not values.

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 instructs to use list_custom_fields first to discover field ids, providing a clear precondition and workflow. This effectively differentiates the tool from its sibling list_custom_fields and tells an agent when to call it.

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 known. The description adds meaningful behavioral detail by specifying what kind of payload is returned depending on entry type, which goes beyond the annotations and helps the agent set expectations.

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 action, then gives return-value detail, usage context, and sibling alternatives, each sentence earning its place. The enumeration of payload types is relevant because there is no output schema to communicate this otherwise.

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 compensates by explaining return payload variations for different entry types. It also covers when to use the tool and which sibling to choose for mutations, making it complete for an agent to select and invoke 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 50%, so the description carries some burden. It does clarify that id is a numeric timeline-entry id and that ids come from list_*_entries calls, which adds context beyond the schema. However, the embed parameter is not mentioned in the description, and the id semantics are only lightly supplemented beyond its integer type.

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 a specific verb and resource: 'Fetch a single timeline entry by its numeric id.' It clearly distinguishes itself from siblings by explaining that it returns full content for notes, emails, and completed tasks, and contrasts with update_entry and delete_entry.

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: 'when you have an entry id from one of the list_*_entries calls and want the full content.' It also identifies alternatives and their use cases: use update_entry to modify, delete_entry to delete. This leaves no ambiguity about routing.

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

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

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 declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: it returns the full record, lists the included components (value, milestone, owner, party), and explains how embedding affects round-trip behavior. 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?

Three sentences, each earning its place: the first states the core action, the second summarizes return content and embedding tip, the third routes to the batch sibling. Information is front-loaded with the primary purpose, and no filler or redundancy exists.

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-record read tool, the description is complete: params are covered by the schema plus description, the return payload is summarized (relevant since there is no output schema), safety is in annotations, and the sibling alternative is named. No critical missing information 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 coverage is only 50%: 'embed' is documented but 'id' is not. The description compensates by clarifying that 'id' is numeric and shows a concrete usage example for 'embed' ('tags,fields'), which adds meaning beyond the raw schema. It doesn't enumerate all valid embed tokens, but the schema already lists them, so the combination is sufficient.

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

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

States a specific verb ('Fetch') and resource ('a single opportunity') with a clear scope qualifier ('single', 'by its numeric id'). It names the sibling 'get_opportunities' as the batch alternative, making the distinction explicit.

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 vs the sibling: single fetch here, batch of up to 50 with get_opportunities. It also gives a usage tip for embedding tags/fields in one round-trip. The guidance is direct and leaves no ambiguity about which tool to pick for single-record retrieval.

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 indicate readOnlyHint=true and destructiveHint=false, so the safe-read profile is known. The description adds valuable behavioral specifics: it enumerates the fields returned and explains that embed='tags,fields' includes those in a single round-trip. It does not cover not-found behavior or rate limits, but those are not critical for a simple read tool.

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, each earning its place: primary action, return contents, and batch alternative. The most important information is front-loaded, and there is no redundancy or filler.

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

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

For a single-resource read operation with no output schema, the description compensates by listing the returned fields and explaining embed usage. It also routes the batch case to the correct sibling. The guidance is sufficient for an agent to call the tool correctly in the common scenarios.

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 meaning beyond the schema by explaining that embed='tags,fields' fetches tags and custom fields in one round-trip, and that id is the numeric party ID. This helps an agent choose parameter values more effectively than 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 operation: 'Fetch a single party (person or organisation) by its numeric id.' It also specifies the resource scope and differentiates from the batch sibling get_parties. The returned record contents are listed, leaving no ambiguity about what the tool does.

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

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

The description explicitly names the alternative for batch scenarios: 'For batch fetches of up to 50 parties at once, use get_parties instead.' It also gives practical guidance on using embed to avoid multiple round-trips, making the when-to-use context clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context beyond the annotations: it lists the returned fields, explains the status values, describes the embed effect, and clarifies what this tool does not provide (timeline data), which is a meaningful distinction.

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 four concise sentences with no filler. It front-loads the core purpose, then covers return values, embed usage, and alternative tools in a logical order. Every sentence earns its place and contributes to correct tool invocation.

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 one required parameter and one optional embed parameter, the description is complete. It states what the tool returns, how to enrich the response, and when to use sibling tools instead. The absence of an output schema is mitigated by the explicit list of returned fields.

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% because the required id parameter lacks a description. The description compensates by calling it a 'numeric id' and explicitly tying it to the project. For embed, the description adds semantic meaning by explaining that tags and fields include attached tags and custom field values, going beyond the schema's token list. It doesn't fully describe all embed tokens, but the schema lists them.

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: 'Fetch a single project by its numeric id.' It clearly distinguishes this from sibling tools by naming get_projects for batch fetches and list_project_entries for timeline data, making its scope 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 explicitly provides when-to-use alternatives: use get_projects for batch fetches of up to 50 projects, and list_project_entries for the project's timeline. It also gives practical guidance on using embed='tags,fields' to include related data in one round-trip, leaving no ambiguity about tool selection.

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

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

Annotations already declare readOnlyHint=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 this as read-only and non-destructive. The description adds useful behavioral context: it returns specific fields, may return tasks not attached to any entity, and treats standalone tasks as valid. This goes beyond the structured 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 with no filler. The primary purpose and return contents come first, and the batch alternative is presented in one clear follow-up sentence.

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

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

With no output schema, the description compensates by listing the key returned fields and clarifying the attached-entity behavior. It could have said more about the optional embed parameter's effect on the response, but that is already covered in the schema, so the definition is sufficiently complete 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 description coverage is 100%, with id and embed fully described in the schema. The description itself adds little parameter-level meaning beyond confirming the id is numeric, so baseline 3 is appropriate.

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

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

The description clearly states the tool fetches a single task by numeric id, listing the returned fields. It explicitly distinguishes itself from get_tasks by noting batch fetching is the sibling's job, so an agent can select it unambiguously.

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 says to use get_tasks instead for batch fetches of up to 50 tasks. This gives a direct when-to-use versus when-not-to-use directive, which is exactly what an agent needs.

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 and destructiveHint, the description discloses important behavioral traits: it returns a minimal Capsule projection, omits trackDefinition and entity references, and lacks a completion field. It also explains the semantic workaround for completion checks, which is genuinely useful context an agent would not otherwise know.

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?

Every sentence earns its place: purpose first, then the exact return projection, then explicitly what is absent and how to handle those gaps through sibling tools. The description is information-dense but not bloated, and the structure makes the critical caveat about missing fields front and center.

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 carries the burden of explaining return values, and it does so clearly by naming the fields and the exclusions. It also covers the practical follow-up actions for entity lookup and completion checks, making it complete for an agent to decide whether and how to call this 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 0%, so the description must compensate for the id parameter. It does, by clarifying that id is a track instance id used in the GET /tracks/{id} endpoint. For a single integer parameter this is sufficient semantic guidance, though it could have added a brief note on id validity or error behavior.

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

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

The description opens with a specific verb and resource: 'Fetch a single track instance by id.' It explicitly lists the returned fields (id, description, trackDateOn, direction, tasks), which makes the tool's purpose and scope unmistakable, and it distinguishes itself from sibling tools by stating what the response does NOT include and routing to list_entity_tracks for entity lookup.

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

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

The description gives clear when-to-use guidance and explicit alternatives: use list_entity_tracks to find the entity a track is applied to, and rely on task statuses to check completion. This tells an agent exactly how to choose between get_track and related tools rather than leaving that decision to inference.

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

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

Annotations already declare readOnlyHint=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 readOnlyHint and destructiveHint annotations already establish this as a safe read operation, so the description does not need to re-state that. It adds useful conceptual context about what additional parties are, but it does not disclose pagination behavior, embed expansion, or response characteristics beyond the tool name.

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 compact and front-loaded with the core action, then adds a clarifying distinction and a direct instruction for the key parameter. No filler is present, though the third sentence partly repeats enum information already in the schema.

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

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

For a basic call, the required parameters and entity choices are sufficiently described, and annotations cover the safety profile. However, with no output schema, the tool does not explain what the returned secondary-party links look like, nor does it mention pagination defaults or embed usage, so an agent may lack enough detail for more advanced invocations.

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 documents entity, entityId, and embed. The description reinforces that entity selects the container and entityId identifies the specific opportunity/project, but it does not add meaning for page or perPage, which lack schema descriptions. With 60% schema coverage, the description only partially compensates for the undocumented 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 uses a specific verb and resource: 'List secondary party links on an opportunity or project.' It also clarifies the distinction from the main party and gives concrete examples (partners, consultants, referrers), which effectively differentiates this tool from related party-listing 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 clearly indicates when to use the tool: when you need secondary party links on an opportunity or project, and it explains how to select the target entity via 'opportunities' or 'projects'. It does not explicitly name alternative tools, but the main-versus-additional distinction provides enough routing 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 the safety profile is covered. The description adds useful behavioral context beyond annotations: the return shape matches list_projects, results are filtered to one opportunity, and the association direction is clarified. It does not discuss pagination behavior, but the schema covers page/perPage parameters.

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 and front-loads the core purpose before contextual details. Each sentence adds distinct value: purpose, return shape, and sibling/direction routing. It is slightly dense 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?

For a read-only list tool with annotations covering safety, the description provides the essential decision-making context: what it does, what shape results take, and when to prefer alternatives. The lack of an output schema is mitigated by the reference to list_projects' record shape. Some parameter semantics are left to inference, but the core call parameters are evident from the schema.

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

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

Schema description coverage is only 25%, so the description must compensate for the 4 parameters. It only indirectly clarifies opportunityId via 'given opportunity' and does not explain page, perPage, or embed beyond what the schema already provides. This is insufficient compensation for the low schema coverage.

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: 'List projects associated with a given opportunity.' It further distinguishes itself by stating it returns the same shape as list_projects but filtered to one opportunity, and clarifies the directionality versus list_party_projects and the project's own opportunity field.

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

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

Usage guidance is explicit and actionable: the description states this tool is 'only needed for opportunity → projects discovery' and directs the agent to 'use list_party_projects for party → projects.' It also notes the inverse direction is available directly on each project's opportunity field, preventing unnecessary calls.

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 declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context about the filtering relationship via the `organisation` field, but it does not disclose other behaviors such as pagination behavior, result limits, or what fields are returned. This is adequate but not particularly rich.

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

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

The description is three short sentences, all of which earn their place. It front-loads the core purpose, follows with the exact filtering behavior, and ends with practical usage guidance. There is no redundant or vague 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 list tool with one required parameter, the description gives enough to call it correctly: the target partyId, the meaning of the result, and a use case. It lacks explicit mention of pagination or output shape, but the schema provides defaults and the absence of an output schema lowers the burden on the description. Overall it is sufficiently complete for the tool's 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 only 50%, yet the description mostly restates what the partyId schema already says: returns parties whose `organisation` field references the partyId. It adds no meaningful documentation for the undocumented pagination parameters `page` and `perPage`, leaving a noticeable gap. The description does not compensate for the incomplete schema coverage.

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

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

The description states a specific verb and resource: 'List the people who work at a given organisation party.' It also clarifies the exact mechanics by saying it returns parties whose `organisation` field references the given partyId. This clearly distinguishes it from generic party listing tools like get_parties or filter_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 tells the agent when to use this tool: 'Use this to answer who works at X?' It also provides an exclusion by saying 'rather than enumerating all parties.' However, it does not name specific sibling alternatives or give explicit when-not-to-use scenarios beyond that one contrast.

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 operation as read-only and non-destructive. The description adds meaningful behavioral detail by warning that results may include both manually-applied and automation-applied tracks, and explains how to distinguish them using trackDefinition.id. This 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 efficiently front-loaded with the core purpose, then gives a sibling distinction and a high-value caveat about auto-applied tracks. Every sentence contributes useful information without padding.

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 provides key return semantics by mentioning track instances and trackDefinition.id. It covers the main ambiguity around auto-applied tracks. Some additional details such as pagination or full item shape are missing, but for a non-destructive list tool the description is largely complete.

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

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

The schema describes entity via an enum and a short description, but entityId has no schema-level description. The description adds domain context by mapping the call to 'this opportunity / project / party', which partially clarifies the parameters, but it does not explain how entityId should be obtained or what it represents beyond a 'specific record'.

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

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

The description uses a specific verb and resource: 'List track INSTANCES on a specific record' and explains what those instances mean. It explicitly differentiates from list_track_definitions, 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?

It explicitly names the sibling alternative list_track_definitions and clarifies that this tool returns applied instances, not templates. It also provides important context about auto-applied tracks, helping the agent reason about when and how to interpret results.

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.