Split (creator affiliate platform)

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

Annotations already indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds that this is a write action and requires confirmation, which usefully reinforces the non-destructive but mutating nature. However, it doesn't detail side effects like what happens to the gift after activation or any potential irreversible changes.

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 return value, followed by critical usage guidance. No wasteful words; every sentence carries essential information for correct 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 two-parameter tool with no output schema and minimal annotations, the description covers the key operational context: it's a write action requiring confirmation and returning a URL. It doesn't specify error handling or failure modes, but given the low complexity and that the schema provides the parameter descriptions, this is sufficient.

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% (only 'confirmed' has a description). The description clarifies the 'id' parameter by explaining that the URL returned corresponds to the creator's shopping URL for the gift, though it doesn't explicitly map 'id' to a gift identifier. The 'confirmed' parameter is well-covered in the schema, and the description emphasizes the need for confirmation, adding semantics beyond the raw boolean.

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 ('Activate a shopping-reimbursement gift') and explicitly mentions the return value (creator's personal shopping URL). It clearly distinguishes this from other tools by noting it is the only write action in the group, making its purpose unambiguous.

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

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

The description provides explicit when-to-use guidance: it is the only write action, and it tells the agent to confirm the brand and cap with the creator before using it, and to return the URL. It also implicitly contrasts with read-only siblings like split_get_reimbursement, clarifying this is a state-changing operation.

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

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

The annotations provide almost no behavioral signal beyond non-read-only and non-idempotent. The description adds important behavior: exact-prefix platform detection, fallback to 'Other', and normalization before sending. It doesn't mention duplicate handling or return values, but the disclosed behavior is genuinely useful.

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

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

Three sentences with no filler. The core action is front-loaded, followed by the parsing rules and a practical instruction for the agent.

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

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

For a single-parameter add operation, the description covers what counts as a known platform, what happens otherwise, and how input is normalized. It omits edge cases like duplicate social links or error responses, but nothing essential is missing for selecting and invoking the 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 100%, so the baseline is 3. The description adds meaning beyond the schema's example by explaining exact URL prefixes, the 'Other' fallback, and normalization rules, which helps the agent format account_url correctly.

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 ('Add') and resource ('social link') and immediately gives recognizable URL patterns. It is clearly distinguishable from sibling tools like split_remove_social_link and split_list_social_links.

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 useful input-construction guidance, such as normalizing bare handles and passing what the creator gave you. However, it never explicitly says when to prefer this tool over siblings or when not to use it, so usage context is implied rather than stated.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive. The description adds useful context beyond those hints: the GET-only constraint, the trailing-slash requirement, and the reason writes must be routed elsewhere. No contradiction with annotations.

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

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

The description is three concise sentences with the main purpose front-loaded. Every sentence earns its place: the scope, the method/routing rule, and the path formatting tip are all essential.

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 generic raw-read fallback, the description plus annotations adequately cover safety, path prefix requirements, and method. The lack of an output schema means return-value details are unstated, but the raw-read nature makes this acceptable; query semantics remain the main 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?

The schema documents the path parameter but not the query parameter, and schema coverage is only 50%. The description adds a concrete path example and reinforces the trailing-slash rule, but it does not explain the query object's role or format, which would help an agent use it correctly.

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 ('Read'), a resource ('any Split API path'), and a clear boundary ('not covered by a dedicated tool'), while adding the method constraint 'GET only'. This distinguishes it from the many get/list sibling tools as the generic fallback.

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

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

It explicitly says when to use the tool: any path not covered by a dedicated tool. It also gives a negative rule by stating that writes must go through the specific tool so confirmation rules apply, which helps an agent route correctly.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context by clarifying it browses the raw catalog and has no keyword filter, which is useful beyond the annotations. It doesn't mention pagination or limits, but with zero parameters and a read-only operation, this is acceptable.

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, direct sentences. The core purpose is front-loaded, and the exclusions are stated clearly without any redundant words. 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 browse tool with no parameters, no output schema, and annotations already covering safety, the description is complete. It tells the agent exactly what it does and when to use a different tool, leaving no gaps 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?

The tool has zero parameters, so there is nothing to document. Per the rubric, 0 params earns a baseline of 4. The description does not need to add any parameter information since none exist.

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 (browse) on a specific resource (raw catalog of known product URLs), and clearly distinguishes it from the sibling split_search_products by noting it has NO keyword filter. This is a precise, unambiguous definition that leaves no doubt 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 tells the agent when NOT to use it ('for anything specific') and names the alternative (split_search_products). This gives clear routing guidance, making it easy for an agent to choose between the two 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 mark this as read-only, idempotent, and non-destructive. The description adds valuable context by explaining the 400 'already exists' error meaning and the behavioral difference between POST and GET variants, without contradicting 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, each carrying essential information: the core transformation, the required HTTP method and alternative behavior, and the error semantics. 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?

The description is complete enough for a simple one-parameter tool with read-only annotations. It covers the operation, method caveat, and error meaning. Not specifying the exact response structure is a minor gap since the output is implied by 'available slug.'

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 defines 'desired' as a string with no description. The description compensates by calling it a 'desired page handle' and explaining that it is transformed into an available slug, adding semantic meaning beyond the raw 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 states a clear action and resource: 'Turn a desired page handle into an available slug.' This is specific and understandable. It does not explicitly name sibling tools to differentiate from, but the purpose is distinct enough from the listed 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 says 'Must POST' and contrasts this with 'the GET variant of this endpoint ignores input entirely and derives a slug from the account name.' This gives the agent clear conditions for when to use this tool and what the alternative does.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds substantial behavioral detail beyond annotations: it lists the exact fields returned, explains null creator for private profiles, describes group_by behavior, and clarifies that filters only apply in link mode. This is rich, non-contradictory context that goes well 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?

The description is long but every sentence carries essential information. It is front-loaded with the core purpose and then details the output fields, usage, and filters. There is no fluff or repetition; each clause adds value. The structure is logical: purpose → fields → usage → grouping → filters.

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

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

For a read-only list tool with no output schema, the description is exceptionally complete. It covers the return fields, edge cases (private creators), grouping modes, filter constraints, and how to act on the results. An agent can correctly invoke the tool and interpret the output without additional information.

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

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

Schema coverage is 75% (3 of 4 params have descriptions). The description adds meaning beyond the schema: it explains the group_by enum values and that brand and creator_uuid filters are link-mode only, which is not in the schema. It also clarifies the default group_by behavior. The page parameter is not described in the schema, but the description doesn't add anything about it either, so there's a minor gap. Overall, the description compensates well for the schema's limitations.

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 click history for links the account has clicked as a shopper, newest first. It specifies the exact resource (click history) and the action (list). It distinguishes itself from siblings by explaining the purpose of finding previously seen items to buy and credit the creator, which is unique among the many split_* 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 provides strong usage context: it's for finding something seen earlier via a creator's link and buying it so the creator is credited. It explains how to use the output (open shop_it_url or pass to split_click_link). However, it does not explicitly name alternatives or state when not to use this tool, though the purpose is clear enough that an agent can infer typical use cases.

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

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

Annotations indicate readOnly=false and idempotent=false; the description confirms side effects ('Each call registers a click') and details attribution behavior, anonymous mode, and redirect handling. 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 long (~150 words) but dense, front-loading the purpose and covering usage, behavior, and parameters. Each sentence adds value without redundancy, though it could be slightly tightened.

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 lists key return fields (destination_domain, target_url, commission rate, own-link flag, disclosure flags) and explains tracked_url and requires_redirect. It also covers side effects and usage context, making it 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 coverage is 100%, so baseline is 3, but the description adds meaningful context: it explains the 'as' parameter's implications (anonymous: no buyer share, creator earns all) and mentions optional shopper id, going beyond the schema.

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

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

The description states a specific action: resolve a received SplitLink into its tracked destination and register a click. It clearly distinguishes from creating or monetizing links by saying 'Never re-monetize a received SplitLink's destination with your own link: resolve the link you were given.'

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 'Use this instead of navigating to the SplitLink' and 'call it per purchase intent, not per impression.' It also implies when not to use other tools by warning against re-monetizing the destination.

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

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

Annotations are all false and provide minimal safety context. The description adds a useful behavioral fact—the destination URL is preserved—and implies a mutating duplication operation, but it does not disclose whether a new UUID is generated, what other fields are copied, or the response shape.

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

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

The description is a single, front-loaded sentence with no filler. It states the operation and its key behavioral nuance in ten 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 one-parameter tool with no output schema, the description covers the core invocation and behavior. Still, it omits the return value—presumably the new cloned link and its UUID—and the full scope of what is duplicated, leaving a gap for agents that need to chain subsequent calls.

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

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

Schema coverage is 0%, so the description must compensate for the undocumented 'uuid' parameter. It implicitly frames the uuid as identifying 'an existing link' to duplicate, which is helpful, but it never explicitly maps the parameter to that role or explains where the uuid comes from.

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 'Duplicate' and the resource 'an existing link,' and adds the crucial outcome 'keeping its destination URL.' This distinguishes it from split_create_link and split_update_link without needing to inspect those 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 phrase 'existing link' provides clear context that this tool is for copying an already-created link, rather than creating a new one from scratch. However, it does not explicitly name alternatives or state when not 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?

The description reveals a non-obvious behavioral quirk: the response may have visible_on_splitpage=false, and the collection will not render until it is patched to true. It also explains how smart collections auto-include matching links. Since annotations only state readOnlyHint=false (no other detail), this description carries the full burden and excels.

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, front-loaded with the core purpose and required fields. It packs essential details (section-first requirement, smart vs. regular, visible_on_splitpage check) without redundancy. Some verbose phrasing could be tightened, but it's efficient for the information density.

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

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

Given the tool's complexity (8 parameters, two collection kinds, a hidden rendering pitfall), the description covers the most critical guidance: required fields, ordering, query semantics, link limitations, and the visible_on_splitpage caveat. It omits optional image_params and image_upload_id, but those have schema descriptions and are not essential 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?

While the schema already covers 75% of parameters with descriptions, the tool description adds semantic depth: it explains that `query` may be {} and gives useful keys (tags, q, domains, sort), and clarifies that `link_uuids` only works at creation. This compensates for the remaining 25% of undocumented parameters (e.g., image_params) without repeating schema content.

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 opening phrase 'Create a collection' is a specific verb+resource that clearly states the tool's purpose. It further distinguishes between smart and regular collections, and the requirement to create a section first sets it apart from sibling tools like split_create_section or split_update_collection.

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 prerequisites (create the section first) and clarifies when link_uuids can be used ('only works at creation time'), which implies that later modifications go through split_update_collection (also noted in the schema). It does not state 'use split_update_collection for edits' explicitly out loud, but the guidance 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 are all false (no read-only, idempotent, or destructive hints), so the description carries the full burden of behavioral disclosure. It does this well by detailing the async extraction: name may initially be the bare domain, image_url may be null, and meta_extraction_progress < 100. It also warns against PATCHing the name unless a custom title is wanted. This goes beyond the schema and annotations, though it does not mention any other side effects or response details.

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

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

The description is three sentences, front-loaded with the core purpose, and every sentence earns its place. It conveys the required field, the async extraction behavior, and a critical usage warning without any fluff or repetition. It is highly 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?

There is no output schema, so the description must compensate for explaining the response. It does so partially by mentioning the fields that may be incomplete (name, image_url) and the meta_extraction_progress indicator. For a creation tool, this gives enough context for an agent to know what to expect. It could be more explicit about the full response structure (e.g., link ID), but given the async behavior is the main nuance, it is 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?

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining that url is the only required field and that name and image are extracted automatically from the page. It also clarifies the meaning of the name parameter (custom title vs. auto-extracted) and the async behavior tied to name and image_url. This enriches the parameter semantics beyond the raw schema.

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

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

The description opens with a specific verb and resource: 'Turn a product or brand URL into a Split link.' This clearly distinguishes it from sibling tools like split_create_links_bulk (bulk creation) and split_update_link (updating). It also states the key requirement (url is required) and the automatic extraction behavior, 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 explains the creation context and the async extraction behavior, and it warns against PATCHing the name prematurely. However, it does not explicitly compare this tool to alternatives like split_create_links_bulk or split_update_link, nor does it state when to prefer one over the other. The guidance is implied rather than explicit, so it falls short of a 4.

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

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

The description adds a useful behavioral detail not otherwise evident: there is no /bulk/ endpoint, and the request is a bare JSON array sent to the normal create path. This is valuable beyond the annotations, which are all generic false flags. However, it does not disclose whether creation is atomic, what happens on partial failure, or any auth/rate-limit considerations, so the behavioral picture is incomplete.

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 primary purpose, followed by a concise and relevant implementation caveat. Every word earns its place and there is no filler or redundancy.

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

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

For a simple one-parameter bulk-create tool, the description plus schema is sufficient to attempt a call. But because there is no output schema and annotations are uninformative, the lack of any mention of response shape, partial success, or failure behavior is a noticeable gap. The "normal create path" hint partially compensates but does not fully answer what the agent should expect.

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 adds no parameter-level meaning beyond the name "links". The JSON schema itself is reasonably explicit, but the rubric requires the description to compensate when coverage is low. It does not explain item format, required fields beyond the schema, or relationship to the single create payload.

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

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

The description clearly states the tool's function: "Create several links in one call." It also adds an implementation detail, "Sends a bare JSON array to the normal create path," which helps distinguish this bulk variant from the single-link sibling split_create_link. However, it does not explicitly name or contrast the sibling, so it stops just short of full differentiation.

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

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

"Create several links in one call" gives clear contextual guidance: this tool is for bulk creation, not single creation. It does not explicitly say "use split_create_link for one link" or describe when not to use this tool, but the stated purpose implies the right usage condition. A short exclusion note would make it fully complete.

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 annotations, the description discloses that the page is published on creation, that a creator can only have one page, and that the page shows the creator's profile avatar. These are meaningful operational expectations not present in the schema or annotations.

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

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

Four dense sentences with no filler: purpose, constraint, parameter guidance, and follow-up workflow are each covered. Information is front-loaded and every sentence earns its place.

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

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

The description covers the one-page constraint, slug behavior, publication state, and subsequent tool usage. Since there is no output schema, a note about the return value would improve completeness, but this is a minor gap for a create tool whose parameters are fully documented.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds extra meaning by explaining that slug is unique and lowercased, that omitting it derives one from the name, and that preferred slugs can be pre-checked with split_check_slug.

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 the creator's SplitPage — their public page at split.co/splitpages/<slug>'. It also differentiates from siblings by noting the one-page constraint and pointing to split_update_page for existing pages.

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 gives when-to-use and alternatives: it 'refuses when one already exists (use split_update_page)', suggests checking a preferred slug with split_check_slug, and routes follow-up work to split_create_section and split_create_collection. 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?

The annotations only provide negative hints (not read-only, not idempotent, not destructive), so the description carries most of the burden. Beyond the word 'Create,' it does not disclose what happens after creation, whether changes are persisted immediately, what response to expect, or whether any side effects occur. It does not contradict the annotations, but it adds little 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?

The description is three short sentences with no filler. The primary action is front-loaded, followed directly by the most important constraints and the conditional rule. 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?

The main correctness trap—the conditional relationship between layout, as_collection, and collection_type—is fully explained, which is the most important part for invoking the tool correctly. However, with no output schema and weak annotations, the description omits what a successful call returns, whether default visibility applies, and any broader assumptions about the target section, making it adequate but not complete.

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

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

Schema coverage is only 40%, so the description must compensate, and it does well: it states title's max length and requiredness, makes the layout/as_collection/collection_type conditional explicit, and instructs the agent to omit layout when collection_type is sent. It still leaves is_visible and as_collection semantically lightweight, but the critical branching logic is much clearer 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 states a clear, specific action ('Create a section') with the exact resource, so an agent can tell this is a creation operation. It does not explicitly contrast with sibling tools like split_create_collection or split_transform_collection_to_section, but the resource noun and name are sufficient to avoid serious 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?

The description provides useful internal usage rules: title is always required, layout is required unless as_collection is true, and collection_type should be sent when as_collection is true. However, it gives no guidance on when to prefer split_create_section over its sibling tools or when not to use it, so alternatives are left to the agent to infer.

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

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

The annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds value by specifying the human-approval requirement before deletion. It does not describe permanence or cascading effects, but the confirmation context is a meaningful behavioral disclosure beyond the annotations.

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

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

The description is two short sentences with no filler. The core action is stated first, and the critical safety precondition follows immediately. 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?

The description, schema, and annotations together cover the destructive nature and the confirmation requirement, but the role of the uuid parameter is left entirely to inference. The description also does not indicate what happens after deletion, such as whether the deletion is permanent or affects linked content.

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 describes the 'confirmed' parameter, and the description's confirmation line mostly restates that. The 'uuid' parameter has no schema description, and the tool description never explains that uuid identifies the collection to delete. With 50% schema coverage, the description fails to compensate for the undocumented uuid parameter.

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

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

The description clearly states a specific verb ('Delete') and resource ('collection'), which directly distinguishes this tool from siblings like split_update_collection and split_delete_section. There is no ambiguity about what operation this tool performs.

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 instruction 'Confirm with the creator first' provides an explicit precondition for when this tool should be invoked, which is especially important for a destructive operation. It does not explicitly name alternatives or say when not to use it, but it gives clear contextual guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds critical behavioral nuance: collections moved to another section survive, while those still in the section are deleted. This goes beyond the annotation and provides functional transparency about the blast radius. The confirmation requirement also adds context about the intended workflow.

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 crisp sentences. The primary action leads, followed by the mandatory confirmation instruction, then the nuanced effect on collections. No filler or repetition. Perfectly front-loaded and efficient.

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

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

The description covers the essential behavioral outcomes (what survives, what is deleted) and the workflow requirement (confirmation). With no output schema, return format is not needed. It does not explicitly state what happens if `confirmed` is false, but that is implied by the schema parameter description. Given the simplicity of the operation, this is nearly complete; minor gap is the lack of explicit error/edge-case handling.

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

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

Schema coverage is 50%: the `confirmed` parameter has a description, but `uuid` does not. The description says 'Delete a section,' implying that `uuid` is the section's identifier, which provides some missing semantics. It also reinforces the `confirmed` flag by saying 'Confirm with the creator first,' but adds little beyond the schema description for that parameter. The description does not fully compensate for the missing `uuid` documentation, so middle score 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 a clear verb and resource: 'Delete a section.' It unambiguously identifies the operation and resource, and the additional detail about collections distinguishes it from delete_collection (which would delete collections). This is specific and non-tautological.

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 a clear prerequisite: 'Confirm with the creator first,' and explains the conditional effect on collections, which helps the agent decide when to call this tool. It does not explicitly name alternatives, but the resource specificity and the destructive nature make the usage context clear. A slight miss is not stating when NOT to use it (e.g., if the section still contains collections that should be preserved).

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

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

Goes well beyond the readOnly/idempotent/destructive annotations by explaining runtime behavior: fetches public links at load time, shows up to 50 items with images, preserves SplitLink attribution, and distinguishes the two layout modes' loading characteristics. Also specifies the exact return format ('fenced block, unchanged'), which is important for correct invocation.

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 moderately long but every sentence earns its place: purpose, layout semantics, runtime behavior, prerequisite, and return format. It is front-loaded with the most important information and contains no filler or repetition of schema fields.

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

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

For a two-parameter tool with no output schema, the description is complete: it explains the use case, layout options, behavioral constraints, dependency on a SplitPage, and the exact format in which the code should be returned. An agent has enough context to invoke the tool correctly and handle its output.

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

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

Schema coverage is 100%, so baseline is 3. The description adds useful parameter semantics by explaining what carousel and grid actually produce (horizontal slider with hosted script vs self-contained image grid) and clarifies that the collection is addressed by page slug, which supplements the uuid parameter's meaning without repeating schema text.

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

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

States a specific verb and resource ('get... embed code') and grounds it in a concrete artifact ('the same code the Split app's Embed Collection menu produces'), leaving no ambiguity about what is returned. The contrast with the output format and use case also makes it distinguishable from sibling get_* 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?

Gives clear intended contexts: pasting into a blog, newsletter template, or any HTML-accepting site. It also provides a prerequisite (requires a SplitPage, collection need not be visible) but does not explicitly name sibling alternatives or when not 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the behavioral nuance that the `count` field is more trustworthy than PATCH echoes, which is useful. It doesn't disclose any other behaviors like pagination or return format, but since annotations cover the main safety aspects, a 3 is appropriate.

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

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

The description is extremely concise—one sentence plus an imperative clause. It front-loads the key point ('authoritative contents') and immediately follows with the most important caveat. Every word earns its place, and there is 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 that the tool is a simple read operation with one parameter, and the annotations cover idempotency and read-only nature, the description is nearly complete. It adds the crucial caveat about PATCH responses, which is the only non-obvious context an agent needs. The only minor omission is that it doesn't explain what 'contents' means exactly (e.g., links, metadata), but the tool name and title suggest it.

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 there is only one required parameter, `uuid`. The description does not mention `uuid` at all, but with a single parameter named 'uuid' and no enums, the semantics are fairly self-explanatory from the schema. However, the description could have added context like 'the collection's uuid' or format expectations, so the baseline 3 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 clearly states the tool retrieves the authoritative contents of a collection, which is a specific resource and action. It distinguishes itself from siblings like split_list_collections and split_get_collection_embed by emphasizing 'authoritative contents' and the explicit caveat about PATCH responses, which subtly differentiates it. However, it doesn't explicitly name an alternative sibling that provides similar but different data, so it's not a 5.

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

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

The description advises using the `count` field to verify membership and warns against trusting PATCH-response link counts. This provides clear context on when to use this tool (for reliable membership checks) and implicitly when not to (when you have a PATCH response). It doesn't explicitly name alternative tools for getting collection info, but the guidance is actionable and context-rich.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering safety. The description adds the specific behavior of the 'items' flag (returning covered products instead of code detail), which is useful. However, no additional traits like pagination, error cases, or response structure are disclosed, and with annotations present the added value is moderate.

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 fronts the main purpose and the optional flag. There is no verbosity, and the extra phrase 'worth showing before the creator shares it' is brief and adds contextual intent without waste.

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

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

For a read-only tool with two parameters (one required), no output schema, and robust annotations, the description provides enough to call it correctly. It explains what it returns and the meaning of the optional flag. No critical gaps remain 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?

Schema coverage is 50% (only 'items' has a description). The description clarifies the semantics of 'items' (switching to product list), adding some value beyond the schema. It does not explain 'id' beyond its name, but its purpose is evident from the tool name. Given low coverage, the description partially compensates but not fully.

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 the specific resource (one discount code) and the two possible outputs (detail or covered products via the 'items' flag). It distinguishes from sibling tools like split_list_discount_codes by emphasizing singular access and explicitly mentioning the optional behavior.

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

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

The description implies use for retrieving a single code's detail or its product list, contrasted with listing tools. It offers a contextual hint ('worth showing before the creator shares it') but does not explicitly name alternatives or conditions for when not to use it. Lacks explicit routing, but the singular framing is sufficient for clarity.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, but the description adds valuable context beyond that: values are in cents, there is no cash-out API, and partial failures are reported inline instead of failing the whole call. This materially informs agent 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?

Three sentences, each with a distinct purpose: scope, unit conversion warning, and operational constraints. No filler or repetition; the most important scoping claim is front-loaded.

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

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

For a simple one-optional-parameter, read-only call with no output schema, the description covers the response categories, unit convention, failure behavior, and an important non-capability. An agent has enough to call it correctly and set user expectations.

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

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

Schema coverage is 100%, so the schema already documents redemption_status as a filter for cash-out history. The description mentions cash-out history and status-relevant sections but does not add new parameter-level meaning beyond what the schema provides. 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 states a specific verb and resource ('get earnings') and clearly enumerates what the call returns: current balance, pending/locked earnings, and cash-out history. This distinguishes it from money-adjacent siblings like get_referrals or list_invoices by claiming to be the single call for all money questions.

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 opening line 'One call for every money question' gives strong when-to-use guidance, and the explicit 'There is NO API to trigger a cash-out; that is app-only' prevents an agent from attempting an impossible operation. It does not explicitly name alternative tools, but the scope claim is sufficient given the sibling list.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds a valuable behavioral nuance: a 404 means the link is hidden, not that the uuid is invalid. This is exactly the kind of edge-case disclosure that helps an agent interpret 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 short sentences, zero fluff. The core action is front-loaded, and the second sentence earns its place by clarifying a potentially confusing error response.

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

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

For a single-parameter, read-only tool with strong annotations, the description is nearly complete. It covers the key behavioral edge case and gives the essential invocation condition. It does not describe the returned link structure, but 'Fetch one link' conveys the high-level outcome well enough.

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 the single 'uuid' parameter at 100% coverage, so the baseline is 3. The description adds meaning beyond the schema by explaining that a hidden link will still produce a 404 for a valid uuid, which is important for interpreting the parameter's correctness.

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

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

The description opens with a specific verb and resource: 'Fetch one link by uuid.' This clearly separates it from sibling list/search tools like split_get_collection_links and split_search_links, and the uuid-based lookup is 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?

The description implies the tool should be used when you already know a link's uuid, but it never names alternatives or states when not to use it. There is no mention of split_search_links or split_get_collection_links, so the routing guidance is left 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 mark this as read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds valuable behavioral detail beyond that: it enumerates what is included, explicitly states what is excluded (sections), and defines the null-result semantics. This is exactly the kind of non-obvious behavior 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?

Three compact sentences, each earning its place: the first states the resource and fields, the second clarifies a critical exclusion with an alternative, and the third explains null-result handling with a creation path. The essential caveat is front-loaded, and there is no filler.

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

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

For a zero-parameter, read-only metadata getter, the description is complete: it names the returned fields, warns about the sections omission, provides the alternative tool, and defines null results. Despite the lack of an output schema, an agent has enough information to call this tool correctly and handle both outcomes.

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 zero parameters, so the input schema fully defines invocation and the description carries no parameter-semantics burden. Per the baseline for zero-parameter tools, this scores 4; the description appropriately does not invent unneeded parameter details.

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

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

The description clearly identifies the resource (SplitPage) and specific metadata fields (name, description, slug, public_url), and explicitly contrasts itself with split_list_sections. An agent can immediately understand what this tool returns and how it differs from related tools.

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

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

The description gives explicit when-to-use guidance: it says the tool does NOT include sections, tells the agent to call split_list_sections for actual rendered content, and explains that a null result means a page must be created via split_create_page. This routes the agent to the correct alternatives without requiring inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds meaningful context by specifying that this is the public-facing view (what brands and shoppers see), which implies the returned data is the external representation, not private settings. This goes beyond the annotations and helps the agent understand what the response contains.

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 compact sentences with no filler. The core purpose is front-loaded in the first sentence, and the second adds a practical directive. Every word earns its place, making it easy to scan and understand.

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 comprehensive annotations, the description is largely complete. It identifies the resource returned and its practical use before updates. It could be more explicit that this returns the current creator's own public profile (versus fetching another creator's profile), but that is implied by the tool name and 'The creator's' phrasing.

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 zero parameters, so the input schema is trivially complete and no parameter details are needed. The description does not need to compensate for undocumented parameters. The baseline for a zero-parameter tool is 4, and nothing is missing.

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 identifies the tool as retrieving the creator's public profile, the view seen by brands and shoppers. This clearly names the resource and its audience, and the title reinforces the 'get' verb. However, it does not explicitly contrast with sibling getters like split_get_settings or split_whoami, so sibling differentiation is implied rather than stated.

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

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

The phrase 'Read this before updating anything' gives clear guidance on when to use this tool (before modifying the profile). It implies that this is the reference view for updates, but it does not explicitly say when not to use it or name alternative tools for other scenarios. The guidance is useful but lacks explicit exclusions or alternative 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds context about what the tool returns (referral link, bonus summary, referred users) but does not disclose details like whether the bonus is capped, how qualification works, or pagination. It doesn't contradict annotations, but it doesn't add much beyond the annotations.

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

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

The description is a single sentence that front-loads the core purpose ('Refer-a-friend status') and then elaborates with three specific components. It is concise and structured, though the parenthetical about capped cash bonus could be seen as slightly dense. 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 zero-parameter read-only tool with no output schema, the description covers the main return values (referral link, bonus summary, referred users). However, it doesn't explain the bonus qualification process or the cap details, which could be relevant for an agent deciding whether to call this tool. The annotations cover safety, so the description is adequate but not fully 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 tool has zero parameters, so the schema provides no parameter documentation. The description compensates by explaining what the tool returns, which is the relevant semantic content. With no parameters to document, a baseline of 4 is appropriate because the description clarifies the tool's scope and output.

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

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

The description clearly states the tool's purpose: retrieving refer-a-friend status, including the referral link, bonus summary, and referred users. It uses a specific verb ('get') and resource ('referrals'), and the title 'Referral status' reinforces this. It is distinguishable from siblings like split_get_earnings and split_list_campaign_bonuses, though it doesn't explicitly name them.

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

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

The description implies usage context (checking referral status) but does not explicitly state when to use this tool versus alternatives like split_get_earnings or split_list_campaign_bonuses. It provides no exclusions or conditions. The context is clear enough for an agent to infer, but it lacks explicit routing guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds only singular scope and no extra behavioral context such as error behavior, authentication needs, or response shape, but it does not contradict the annotations.

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

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

The entire description is one short sentence with no filler. It front-loads the resource type and singular scope, which is appropriately concise for such a simple read tool.

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 one required parameter and strong safety annotations, so the core invocation context is present. However, with no output schema, the description does not clarify what the returned 'detail' contains, and it does not distinguish this tool from the list-gift sibling.

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 a single bare `id` with 0% description coverage, so the description must compensate. It implies the id identifies a shopping-reimbursement gift, which is reasonable for a one-parameter tool, but it never explicitly states the id's meaning, format, or source.

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 resource ('shopping-reimbursement gift') and singular scope ('one'), making it clear this is a single-record detail lookup. It is reasonably distinguishable from siblings like split_list_gifts, though it does not explicitly contrast with them.

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

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

There is no guidance about when to use this tool versus split_list_gifts or other get_* siblings. The singular phrasing weakly implies a single-gift use case, but no when, when-not, or alternative is stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, establishing a safe read-only profile. The description adds no behavioral context beyond the annotations—it does not say what settings are returned, whether there are rate limits, or any access requirements. With annotations covering safety, the bar is lower, but the description still fails to add value by saying nothing beyond the resource 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 short, but brevity is not conciseness when it under-specifies. 'Account settings.' is a fragment lacking any sentence structure or front-loaded actionable information. It does not earn its place because it says almost nothing, similar to the 'Process' calibration example.

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

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

While the tool is simple (no parameters, no output schema) and annotations cover the safety profile, the description is incomplete because it does not clearly articulate the tool's function. An agent cannot confidently distinguish this from split_get_profile or split_whoami without additional inference. Given the simplicity, one would expect a minimal but explicit 'Retrieves the account settings'—this falls short.

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 zero parameters, so the description is not required to elaborate on parameter semantics. The schema is empty with 100% coverage, and any parameter-related context is unnecessary. The baseline of 4 for zero-parameter tools applies here.

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

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

The description 'Account settings.' is a noun phrase that restates the title 'Get settings' without adding an action verb. It does not distinguish this from sibling tools like split_update_settings or split_get_profile, leaving the agent to infer that it retrieves settings. This qualifies as a tautology, not a clear purpose statement.

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

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

No guidance is provided for when to use this tool instead of alternatives. The description does not mention split_update_settings, split_get_profile, or split_whoami, nor any conditions, prerequisites, or contrast with sibling tools. It is entirely absent of usage direction.

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

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

Annotations already declare the tool read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds a useful behavioral clue ('after creating a link') and explains the output's purpose, but it does not disclose edge cases, error behavior, or URL formatting. This is adequate but not rich.

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

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

The description is two short sentences with no filler. The main purpose is front-loaded, and the usage note is placed immediately after, making it easy to scan and act on.

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

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

For a simple one-parameter, read-only tool with strong annotations, the description is nearly complete: it states what is returned, its use case, and the required precondition. It does not explain return format details, but the return value ('shareable URL') is obvious from the stated purpose.

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 only parameter, uuid, has no schema description, and the description does not explicitly map it to the link identifier. However, phrases like 'for a link' and 'after creating a link' allow an agent to infer that uuid likely refers to the created link. This is helpful but not fully explicit, leaving some room for assumption.

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: 'Get the shareable “shop it” URL for a link.' It also clarifies the real-world meaning ('this is what the creator posts'), which differentiates it from other getters like split_get_link or split_get_discount_code. This is a clear, non-tautological statement of the tool's function.

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

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

The description gives explicit context for when to call the tool: 'Call it after creating a link.' This is a clear usage trigger. It does not name when not to use it or cite alternative tools, so it falls short of a full 5.

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

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

Annotations already mark destructiveHint=true and idempotentHint=true. The description adds essential non-obvious behavior: the action is permanent, the link 404s, never returns in search, cannot be un-hidden via API, and stats are preserved. This goes far beyond the annotations and clarifies exactly what the destructive action entails.

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

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

Four sentences, all high-signal, with the permanent/destructive warnings front-loaded after the one-line action. The opening phrase repeats the tool name somewhat, but the extra length is justified for a destructive, irreversible operation.

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 critical operational context for a destructive permanent operation: no undelete, 404 behavior, stats preservation, and the human confirmation step. No output schema exists, but return behavior is not necessary for invocation. Minor gap: no guidance on where uuid comes from, though it is a reasonably standard identifier.

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%: uuid has no schema description. The description reinforces the confirmed boolean workflow by instructing to confirm with the creator and show the title/short code, adding operational meaning beyond the schema. However, uuid semantics (how to identify the link) are not addressed at all, so the description does not fully compensate for the schema gap.

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

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

States a specific action ('Hide a link') and frames it as Split's removal mechanism, explicitly noting there is no DELETE for creator links. The title adds 'permanent'. This clearly distinguishes it from update_link (edit) and delete_collection/delete_section (different resources).

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

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

Explicitly labels it as the removal mechanism and warns there is no DELETE alternative, telling the agent this is the tool for removal. It also instructs confirming with the creator before calling. It does not name a non-destructive alternative like split_update_link for cases where the intent is editing rather than hiding, so not a full 5.

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

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

Annotations already declare this as read-only, idempotent, and non-destructive, so the description need not repeat that. It adds value by disclosing the output structure (top-line summary, daily histogram, paginated rows), the distinction between lifetime_* and filtered_* metrics, and the effect of include_comparison. It also warns about the date format (Elasticsearch date math), which is a behavioral detail not in the schema. This exceeds the 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?

Four sentences, all information-dense. The purpose is front-loaded, the output structure is summarized efficiently, the conditional comparison mode is explained with a usage hook, and the date format is noted in a single final sentence. No filler or redundancy.

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

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

For a tool with 9 parameters, no output schema, and no enums, the description covers the core behaviors (output shape, comparison flag, date format) but omits any description of the filtering parameters (tags, uuids, domains, q) and pagination mechanics. The read-only annotations reduce the need to discuss side effects, but the parameter semantics are incomplete, leaving agents to guess at how to use the filtering 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 description coverage is 44% (only sort, since, until, include_comparison have descriptions). The description partially compensates by explaining the date math for since/until and the effect of include_comparison, but it does not add anything for q, page, tags, uuids, or domains. The phrase 'paginated per-link rows' hints at page, but no concrete semantics are provided. Given the low coverage, the description does not do enough to fill the gaps.

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

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

The description opens with a clear purpose: 'Per-link performance: clicks, revenue, commissions, GMV, conversion rate.' It names the resource (per-link) and the specific metrics, distinguishing it from sibling tools like split_performance_by_brand or split_get_earnings. The verb 'returns' and the concrete output structure further solidify the purpose.

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

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

It explicitly instructs when to use include_comparison: 'use that for any "how does this compare" question.' This is direct usage guidance for a key flag. However, it does not name alternative tools or state when NOT to use this tool, relying on the tool name and purpose to differentiate it from siblings. The guidance is adequate but not exhaustive.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description's 'Read-only' merely repeats the annotation; the only added context is the enrollment scoping. It does not contradict annotations, but adds little beyond them.

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

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

The description is two short fragments and fully front-loaded. The trailing 'Read-only' duplicates annotation information and does not strictly earn its place, but the overall definition is appropriately minimal with no filler.

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

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

Adequate for a zero-parameter read-only tool whose safety profile is fully carried by annotations. However, with no output schema, the description does not clarify what fields or volume of campaign bonus data is returned, which is a modest gap for a list-style tool.

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

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

The tool has zero parameters, so the baseline is 4. Schema coverage is 100% for the empty schema, and there are no inputs whose meaning the description would need to clarify. The absence of parameter discussion 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 resource ('campaign bonuses') and scopes it with 'the creator is enrolled in,' which distinguishes it from sibling list_* tools by resource type. It lacks an explicit verb, but the title supplies 'List,' making the purpose clear. It is somewhat terse but not tautological.

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 resource naming implies when to use it (when campaign bonuses for the enrolled creator are needed). However, there is no explicit guidance about when to prefer this over closely related siblings like list_promotions or list_discount_codes, and no exclusions are stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds a useful behavioral gotcha beyond annotations: the embedded links preview is capped at 4 items, preventing a false assumption about collection size. This is meaningful extra context, though not exhaustive about pagination or ordering.

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 wasted words. The core purpose is stated first, and the important warning and alternative are packed into the second sentence. Every part 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?

Given the tool's low complexity, no parameters, and no output schema, the description is complete: it states what rows contain, warns about the preview cap, and points to the sibling tool for full contents. An agent has enough information to invoke it correctly and interpret its results.

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

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

The tool has zero parameters, so there are no parameter semantics to clarify. Per the baseline rule for 0-parameter tools, the description need not compensate for schema gaps; the 100% schema coverage and empty parameters make this dimension non-issue.

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 ('List') and resource ('collections'), and adds what each row contains (section_title, link_count). It also distinguishes itself from split_get_collection_links by explicitly pointing there for real link contents.

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 guidance: use this tool for the collection overview, and use split_get_collection_links when real link contents are needed. The warning about the 4-item preview cap also clarifies when this tool's output could be misleading.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description adds meaningful behavior beyond that: default returns up to 100 threads, ordering is most-recent-first, and the no-inbox case is not an error and is created on first inbound message. This is useful context the annotations 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?

Four sentences with the core purpose front-loaded, followed by return row fields and edge cases. Every sentence contributes real information; the only slight inefficiency is the final sentence about inbox creation, which is useful but could be seen as extra.

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 optional parameter and no output schema, the description covers the essential return fields, ordering, default scope, maximum threads, duplicate-brand threads, and the empty-inbox behavior. It doesn't explicitly explain the limit parameter's mechanics, but the tool is simple enough that this is not a major gap.

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

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

Schema description coverage is 0%, so the description must compensate for the lone optional limit parameter. It says 'whole inbox by default (up to 100 threads),' which hints at the maximum but never explicitly explains that limit controls the number of returned threads or how it interacts with the default. This is partial compensation 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 identifies the resource ('creator's brand chat inbox') and the action (list threads, most recent activity first). It does not explicitly name split_read_conversation as the alternative, but says each row contains channel_url 'for reading and replying,' which makes the list-vs-detail distinction clear enough for an agent.

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

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

The description provides clear context for when to call this tool: when you need the overall inbox with recent activity, default whole inbox, up to 100 threads. It doesn't explicitly state when not to use it or name alternatives, but the list/read distinction is implicitly conveyed and the default behavior is well specified.

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

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

Annotations already declare read-only, idempotent, non-destructive, and the description repeats read-only. It adds useful behavioral details: sorting expiring-first, purpose semantics, url format, and a commission-related suggestion, going 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?

The description is two sentences plus an action-oriented tip. It is front-loaded with the core purpose and keeps extra guidance brief. Slightly awkward grammar but 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 list tool with no output schema, it explains the return items (codes with urls), sorting, and the purpose field. It omits what happens with the 'status' parameter and any pagination, but these are minor for this simple list.

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 explains the 'purpose' parameter (share/gift) which the schema does not, but it leaves 'status' unexplained and only repeats that brand is a uuid. With schema coverage at 33%, it partially compensates but not fully.

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 Shopify discount codes for the current creator, sorted by expiry, and distinguishes it from singular alternatives like split_get_discount_code by emphasizing the plural scope and sorting.

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 context that it lists codes assigned to this creator, but it does not explicitly say when to use this tool versus alternatives like split_get_discount_code or other list tools. No exclusions or alternative names are mentioned.

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 read-only, idempotent, non-destructive behavior. The description adds valuable behavioral context: the response is heterogeneous and requires reading item_type for each item, reimbursement items carry specific temporal and monetary fields, and time_left should be surfaced prominently when expiring items are relevant. No contradiction with annotations exists.

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 structured: the first sentence identifies the feed, the second unpacks the mixed item types and field contract, and the third gives actionable display guidance. 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?

With no output schema, the description must convey the return contract, and it does so well for reimbursement items and acceptably for gift_code items. However, it omits behavior around pagination, ordering, default scope, and how brand_uuid affects results. These are meaningful gaps for a list tool, though the simple two-parameter shape and read-only annotations keep the tool callable.

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%, so the description bears responsibility for explaining inputs. It does not describe `scope` (active/upcoming/ended/all), `brand_uuid`, defaults, or how scope relates to starts_at/ends_at/time_left. The enum values and parameter names are somewhat self-explanatory, but the description never clarifies optionality or filtering behavior, so it fails to compensate for the missing schema documentation.

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 the resource ('The creator's gifts feed') and the operation (a MIXED list requiring item_type checks). The title 'List gifts' and tool name align, and the mention of reimbursement items and gift_code items distinguishes it from generic list tools. However, it does not explicitly name a sibling tool to differentiate from, so it stops just short of a 5.

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

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

The description provides context about what the feed contains but gives no explicit guidance on when to use this tool versus alternatives such as split_get_reimbursement, split_activate_reimbursement, or split_list_campaign_bonuses. There is no 'use when' or 'when not to use' statement, leaving the agent to infer selection criteria from the resource name alone.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds meaningful behavioral context beyond that: the tool has two modes (listing all invoices vs. retrieving commissions for a specific invoice based on invoice_id). This conditional behavior is not captured in annotations and is valuable for the agent.

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 the primary action front-loaded and the optional behavior introduced in the second sentence. There is no filler or redundancy. Every word contributes to understanding the tool's function and the parameter's role.

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

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

For a tool with one optional parameter, no output schema, and annotations covering safety, the description is largely complete. It states what the tool returns (list of invoices or commissions), and the 'creator's' clarifies scope. It doesn't describe the response format or pagination, but given the simplicity and lack of output schema, this is a minor gap. The agent can likely infer the list structure from the name and description.

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

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

Schema description coverage is 0%, so the description must compensate. The single parameter invoice_id is explained in the description: 'Pass an invoice_id to get the individual commissions that made it up.' This conveys the parameter's purpose and its effect on the output, which is sufficient for a string ID. It doesn't specify format or constraints, but for a simple ID that's acceptable. It fully covers the parameter's semantics beyond the bare 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 uses a specific verb and resource: 'List the creator's Stripe invoices.' It clearly states the primary action and resource, distinguishing it from sibling tools like split_get_earnings or split_list_discount_codes by focusing on Stripe invoices. The additional clause about invoice_id adds a secondary purpose without confusion.

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

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

The description provides clear context on when to use the tool: to list the creator's Stripe invoices, and optionally to drill into a specific invoice's commissions. It does not explicitly name alternatives or state when not to use it, but the context is sufficient given the uniqueness of the resource (Stripe invoices). No exclusions are mentioned, which fits the 4-level of 'clear context, no 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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered structurally. The description adds the scoping detail that the domains are those the creator has linked to, but does not disclose output ordering, duplicates, pagination, or format. This is consistent with annotations and minimally sufficient for a read-only list with no 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?

A single front-loaded sentence states the action and the resource with no filler. The phrase 'for filtering' earns its place by signaling the intended use case.

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 no parameters, rich safety annotations, and a straightforward output implied by 'List the domains,' nothing necessary for correct invocation is missing. The absence of an output schema is not a gap because the description names the returned entity type.

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

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

There are zero parameters, so schema description coverage is trivially 100% and the description carries no parameter-semantics burden. The baseline of 4 is appropriate because no additional parameter meaning is needed.

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 the specific verb 'List' and identifies a concrete resource: 'the domains the creator has linked to.' It also adds the purpose 'for filtering,' which differentiates it from sibling list tools such as list_link_tags and list_social_links.

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 offers only an implied usage signal: it says the list is 'for filtering,' so an agent can infer to use it when domain-level filtering is needed. It does not name alternative tools or state when not to use it, so explicit exclusion guidance is absent.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, so the description doesn't need to repeat those. It adds a small amount of behavioral context by explaining the returned tags are those 'the creator has used' for UI purposes, but it does not disclose details like uniqueness, ordering, or pagination. This is acceptable given the simple read-only nature.

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

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

A single concise sentence that states the action, object, and intended use. It is front-loaded and contains no filler or redundant wording.

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

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

For a zero-parameter read-only tool with no output schema, the description is sufficient: it says what is returned and why it would be used. It does not explain who 'the creator' refers to, but that is reasonably inferable from the tool's context.

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

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

The input schema has no parameters, so there is nothing to document. The description correctly focuses on what the tool returns rather than inventing parameter details.

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

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

The description uses a specific verb ('List') and resource ('tags the creator has used'), and clarifies the purpose (filtering/autocomplete). This clearly distinguishes it from sibling list_* tools like split_list_collections or split_list_social_links.

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 ('for filtering or autocomplete') and gives a clear intended use case. However, it does not explicitly mention when not to use it or name any alternative tools that might also return tags or related metadata.

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

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

Annotations already cover the safety profile with readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds only that the returned values are predefined/static types, but offers no further behavioral traits such as ordering or response shape.

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

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

One short sentence with no filler, and the key qualifier 'predefined' is front-loaded. It is appropriately concise for a no-parameter list tool, though it adds little beyond the title.

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

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

For a zero-parameter read-only tool, the description conveys what will be returned (predefined section types) and the annotations cover side-effect safety. Without an output schema, more detail about the shape of a 'section type' could help, but nothing critical is missing.

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

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

The tool takes zero parameters and schema coverage is 100%, so there are no parameter semantics for the description to add. The baseline for a 0-param tool applies.

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

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

The description uses a specific verb ('List') and resource ('predefined section types available'), making the tool's core function clear. It is distinguishable from split_list_sections by the word 'predefined', though it doesn't explicitly contrast with that sibling.

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

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

No guidance is given on when to use this tool versus alternatives like split_list_sections or how it relates to section creation/management tools. The context is only implied by 'predefined types available'; there are no exclusions or alternative 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?

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations: it confirms there is no accept or decline endpoint, notes these are active promotions, and gives intended UX direction. This helps the agent avoid offering impossible actions.

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

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

Three short sentences, each earning its place: the resource and scope, the behavioral limitation and user-facing framing, and the parameter usage. No fluff 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 simple read-only listing tool with two optional parameters and no output schema, the description is nearly complete. It conveys purpose, parameter behavior, and constraints. It stops short of describing the shape or fields of a promotion object, but that is a minor gap given the low complexity.

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

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

Schema description coverage is 100%, so the schema already documents uuid and organization. The description reinforces the uuid behavior ('Pass uuid for one promotion's detail') but adds little beyond the schema. It does not mention organization, but that is already covered in the schema.

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

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

The description clearly states the tool lists active brand promotions and can fetch a single promotion's detail via uuid. It distinguishes itself from generic sibling list tools by emphasizing the brand-promotion context and the read-only nature, though it does not explicitly name a sibling alternative.

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: read-only, no accept/decline endpoint, and how to present results. It tells the agent to treat promotions as opportunities and offer to create links, which is actionable guidance. It does not explicitly frame when-not-to-use or name alternatives, but the context is sufficient.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds value beyond those annotations by disclosing page ordering and emphasizing that the returned section uuids are the reference for later reordering; no contradiction is present.

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

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

Two short sentences, front-loaded with the primary purpose and followed immediately by the one critical usage caveat. There is no filler; every sentence carries operational 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 zero-parameter, annotation-covered read-only tool, this is nearly complete: it provides the output order, the reordering workflow, and references the uuid needed later. It does not spell out the return payload fields or explicitly distinguish from split_list_predefined_sections, but those are minor gaps that do not block 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?

The tool has zero parameters, so the schema covers 100% by construction. The description still adds useful context by implying that returned sections carry a uuid that reorder operations depend on, but there is no parameter to explain further.

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 the operation ('List sections') and a meaningful qualifier ('in page order'), so an agent understands what the tool returns and how it is ordered. It does not explicitly contrast itself with the sibling split_list_predefined_sections, so it stays just short of full sibling differentiation.

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

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

The second sentence gives an explicit, actionable when-to-use rule: 'Always call this before reordering' and explains why by tying reorder moves to another section's uuid. It does not mention alternatives or cases where it should not be used, but for a read-only listing tool that is a minor gap.

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

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

Annotations already declare the operation read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds useful context about the formats mode returning accepted URL formats per platform, but it does not describe the default response shape, ordering, or any other behavioral detail.

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

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

The description is very short and front-loads the core resource before the parameter instruction. Every word earns its place with no repetition 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 simple read-only tool with one optional boolean parameter, high schema coverage, and safety annotations, the description is largely sufficient. It could be slightly more explicit that the default call returns the list of social links, but the tool name, title, and description together make this inferable.

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 the 'formats' boolean. The description rephrases it as 'accepted URL format per platform', which adds slight clarity, but it does not provide meaning beyond what the schema's 'known platform URL prefixes instead' already conveys.

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

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

The description identifies the resource as 'the creator's social links' and mentions the format toggle, so an agent can infer this is a read/list operation. However, it lacks an explicit verb such as 'retrieves' or 'lists', and it does not explicitly distinguish this from the sibling add/remove social link tools.

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

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

The description gives no guidance on when to use this tool versus split_add_social_link or split_remove_social_link. The only usage instruction is 'Pass formats: true', which is parameter guidance rather than tool-selection guidance.

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

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

Annotations already indicate the tool is not read-only (creates clicks and possibly links), not idempotent (each call registers a click), and not destructive. The description adds crucial behavioral context: it registers a click on every call, with repeat calls within 24h counting as re-clicks, and explains the meaning of `requires_redirect` for following redirects and cookie handling. It does not disclose failure modes or rate limits, but given annotations cover safety, a 4 is warranted for the substantial added 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 long but information-dense, with the core purpose and output front-loaded in the first sentence. Every sentence adds critical operational detail (redirect behavior, click attribution, tag segmentation, exclusions for alternatives). It could be tightened but is well-organized, and the length is justified by the tool's complexity; the key action and output are immediately 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?

For an 8-parameter tool with no output schema and no required parameters, the description compensates well by explaining the return value ('tracked_url is the key output') and how to use it, as well as the requires_redirect flag. It covers mutual exclusions and varying use cases (creator, anonymous, shop_it_url) thoroughly. It lacks explicit examples or edge-case error handling, but given the output field is described, this is nearly 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?

The schema already has 100% coverage with detailed descriptions for each of the 8 parameters, including mutual exclusivity hints (e.g., 'Mutually exclusive with url/uuid/clicker' for shop_it_url). The description adds value by clarifying how tags affect link reuse, how anonymous_id's tail is stamped into the click id, and how target_url is used only for requires_redirect. While the schema covers each parameter, the description deepens understanding of their interplay, so a 4 is appropriate rather than a baseline 3.

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

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

The description opens with a specific verb ('Turn a product URL into a TRACKED destination URL') and clearly states the resource and the primary output ('tracked_url is the key output'). It frames the purpose as both a lookup-or-create action and a click registration, making the tool's job unmistakable. It also differentiates itself from siblings by explicitly naming split_click_link and split_get_share_url and stating when to use those instead.

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 conditions: use split_get_share_url when the creator is posting a link for people to click, prefer split_click_link for any SplitLink you RECEIVED, and call split_monetize_url per purchase intent rather than per impression. It also explains the 24-hour re-click behavior and the distinction between creator, anonymous, and shop_it_url flows, leaving no ambiguity about when to invoke 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 carry the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false); the description adds value beyond that by explaining what the tool produces (evidence, flags, next actions), its role as a first-call diagnostic, and the ordered journey it evaluates. 'It reads only' slightly restates the annotation but is harmless reinforcement. Without an output schema, the description does real work in setting 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?

Two sentences earn their place: the first packs the purpose, output contents, and the journey stages; the second delivers usage directives. The arrow-chain construction is ornate and slightly dense, but nothing is wasted and the core purpose is front-loaded before the usage guidance.

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

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

For a zero-parameter, read-only orchestrator with no output schema, the description covers the essentials: what it evaluates, what the output contains, and how to act on it. The return shape is described conceptually rather than precisely (no JSON structure), but 'next actions each named by the tool that does it' is enough for an agent to consume the result and route to siblings.

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 zero parameters and the schema is trivially complete at 100% coverage, so there is nothing the description must document. The baseline of 4 for zero-param tools applies; the description appropriately devotes no space to 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 states a specific verb+resource ('Read the creator's account and place it on the path...') with a concrete deliverable: evidence, flags, and next actions each named by the tool that does it. The stage chain (profile → page → brands → collections → grow) makes the tool's scope unmistakable and distinguishes it from the many CRUD siblings by framing it as the orchestrator that points to them.

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 triggers: 'Call this FIRST on a new or quiet account, and whenever the creator asks what to do next; act on its output rather than guessing.' This is strong when-to-use guidance that also prescribes follow-through behavior. It stops short of a 5 because it never names an alternative tool or states when NOT to use it (e.g., a targeted question like link performance would bypass 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 establish the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), lowering the bar. The description adds useful behavioral context beyond annotations by stating that the tool ranks by actual returned performance ('what they actually returned') and highlights earn_per_click as the ranking key. No contradiction with annotations.

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

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

Two sentences with no filler: the first identifies the action, resource, and output fields; the second states the decision use case and ranking priority. Both sentences earn their place, and the key information is front-loaded.

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

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

For a read-only, two-optional-parameter tool with fully documented schema and comprehensive annotations, the description covers what an agent needs: what it ranks, which metrics are returned, and when to use it. Since there is no output schema, the metric listing partially substitutes for return-value documentation. Minor omissions such as aggregation granularity are acceptable given the low complexity.

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

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

Schema description coverage is 100%, with both since and until having descriptive defaults in the schema. The description adds no parameter-level semantics beyond the schema, so the baseline of 3 applies.

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

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

The description states a specific verb ('Rank') and resource ('merchants'), and enumerates the exact metrics returned (filtered_revenue, filtered_clicks, conversion_rate, earn_per_click, earn_per_link). This clearly differentiates it from the close sibling split_link_performance, which operates at the link level, and from split_get_earnings, which reports earnings rather than brand rankings.

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

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

The phrase 'This is the tool for "which brands should I post more of"' provides explicit when-to-use guidance tied to a concrete decision an agent might need to make. It doesn't explicitly name alternatives or give when-not-to-use conditions, so it falls just short of a 5, but the use case is stated unambiguously.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety bar is met. The description adds valuable context beyond that: it explains the limit semantics ('counts back from now') and, more importantly, discloses a critical security behavior—treating message content as data and surfacing action requests to the creator. This is a substantive behavioral trait not visible in annotations or schema.

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

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

Two sentences with no fluff. The primary action and the most critical functional detail (ordering) come first; the security instruction follows as a necessary caveat. Every sentence contributes.

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

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

The description covers the core operation, the limit behavior, ordering, and a crucial prompt-injection warning. It does not describe the return format, but no output schema exists and the description still gives enough for an agent to call the tool correctly given that channel_url comes from a sibling 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 50%: channel_url has a terse description ('From split_list_conversations') and limit has none. The description compensates partially by explaining that 'limit counts back from now' and connecting channel_url to a 'brand conversation.' It does not fully document channel_url's format, but the description adds meaningful semantics for both 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 opens with a specific verb and resource ('Read the messages in one brand conversation') and immediately specifies the ordering ('NEWEST FIRST'), which also distinguishes it from sibling tools like split_list_conversations (listing) and split_send_message (writing). The purpose is unambiguous.

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

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

The description clearly implies this is the tool to read a specific conversation, but it does not explicitly name alternatives or state when not to use it. There is no direct reference to split_list_conversations as the source of channel_url or to split_send_message for sending, so usage guidance is implicit rather than explicit.

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 idempotentHint=true, and the description adds genuinely useful non-obvious behavior: removing the last social link can break discoverability. This goes beyond what the annotations alone convey and gives the agent important cautionary context.

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

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

Two short sentences front-load the core action and immediately follow with a necessary warning. There is no filler, and the warning sentence earns its place by highlighting a destructive edge case.

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 two-parameter destructive tool with annotations covering safety profile, the description conveys the operation, the confirmation requirement, and a key side-effect. The only notable gap is that the id parameter remains semantically unexplained, but this is minor for such a straightforward action.

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 'confirmed' well but leaves 'id' without any description, and schema coverage is only 50%. The description's 'Confirm first' reinforces the confirmed parameter's meaning, but it adds no clarity about what id refers to or how it should be obtained.

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, 'Remove a social link', which clearly distinguishes it from sibling add/list operations at a surface level. It does not explicitly name a sibling, so it stops just short of full differentiation.

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

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

The description implies the tool is for removing social links and gives a practical prerequisite ('Confirm first'). However, it does not explicitly state when not to use it or point to alternatives such as add_social_link or list_social_links, so the usage guidance remains implied rather than explicit.

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 meaningful behavioral detail beyond the generic false-valued annotations: the operation is asynchronous and returns a job reference rather than a direct file. It stops short of explaining job polling or completion semantics, but it does disclose the most surprising behavior.

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

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

Two brief sentences with no filler. The first states the action and scope; the second preempts the common expectation of a direct file download. The key constraint is front-loaded.

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

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

The description conveys the core invocation contract and the non-file return type, but with no output schema and sparse annotations it leaves an agent unsure how to use the job reference or track export completion. It is adequate for starting the operation but thin for the full workflow.

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 both optional parameters with defaults, and coverage is 100%, so the description does not need to restate them. The description also adds no extra context about since/until formatting or their effect on the export, so it sits at the schema-covered baseline.

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

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

The description clearly states the action ('kick off'), the resource ('async CSV export'), the data scope ('creator's performance data'), and a distinguishing return characteristic ('job reference, not the file'). This separates it from synchronous performance/viewing 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 async CSV purpose is understandable, but no alternatives are named and no explicit conditions or exclusions are given beyond 'not the file.' When to use it versus a synchronous analytics/report tool is implied rather than stated.

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

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

The annotations already mark the tool as read-only and idempotent, and the description adds essential behavioral detail: `search` is silently ignored and returns the entire unfiltered directory, and random *.myshopify.com domains indicate the query was not applied. This exposes a subtle failure mode the annotations cannot 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 the purpose and each subsequent sentence earns its place by revealing a silent-ignore trap, a troubleshooting signal, and the alternative id lookup mode. It is detailed without being bloated.

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

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

There is no output schema, so explaining return values is not required. The description covers the main failure mode, the filtering semantics, and the two invocation modes, making it sufficient for an agent to call the tool correctly despite the subtle `q` behavior.

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

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

The schema describes `q` and `id`, but the description enriches both: `q` has a critical silent-ignore edge case, and `id` provides detail including `can_request_gift`. The `type` param is not explained, but its enum values are self-explanatory and schema coverage is moderate at 67%.

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 action and resource: 'Look up brands and their commission rates.' It clearly identifies the tool's domain and differentiates it from sibling search tools like split_search_links and split_search_products by focusing on brand 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 guidance on using `q` for brand filtering and `id` for fetching one brand's detail, including what `id` returns. It does not explicitly state when to prefer this tool over sibling search tools, so it lacks full alternative routing, 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 readOnlyHint and idempotentHint, so the safety profile is covered. The description adds one useful behavioral note—hidden links never appear—but the reference to 'include_archived' is unsupported by the schema, which may confuse agents.

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 purpose, then a compact note about pagination/sort and hidden links. No filler; each sentence adds information.

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

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

The tool has 10 optional parameters and no output schema, so the description cannot fully cover all semantics. However, most remaining parameters have self-explanatory names, and the read-only annotations cover the safety profile. The main gap is the lack of any output/return information and the unresolved include_archived reference.

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 40%. The description adds helpful examples for `sort` and clarifies `page` is 0-based (though the schema already says that). It does not explain `size`, `tags`, `domains`, `is_favourite`, or `tags_to_exclude`, leaving part of the burden unaddressed.

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 opening phrase 'Search or list the creator's Split links' clearly identifies the action and resource. It doesn't explicitly name sibling tools for differentiation, but the scope ('creator's links') distinguishes it from collection-specific or single-link 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?

No when-to-use or when-not-to-use guidance is present. The description doesn't mention alternatives such as split_get_link or split_get_collection_links, nor any exclusions for when a different tool would be appropriate.

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 (readOnly, openWorld, idempotent, non-destructive), the description discloses the wrapped response shape {result: {results: [...]}} and instructs to unwrap both levels. It also warns about image_url quality and the resulting ugly link cards, and specifies a retry behavior for transient errors. These are substantive behavioral details that the annotations do 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 long but every sentence carries actionable information: the purpose, response unwrapping, image quality guidance, query construction tip, and error handling. It is structurally front-loaded with the core purpose before diving into nuances. A minor deduction for being somewhat dense and not splitting into clearly separated concerns, but it remains readable and efficient.

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

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

For a search tool with no output schema, the description is remarkably complete. It explains the response envelope, the meaning of commission_rate, the implications of image_url, how to craft queries for product pages, and a retry strategy for transient errors. The only untold details are the exact semantics of page and search_type, which are minor for a basic invocation and are partially inferable from the schema constraints. Overall, an agent can confidently call this tool correctly with the given description.

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

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

Schema coverage is only 50% (q and filter have descriptions; page and search_type do not). The description adds valuable guidance for q, such as embedding the merchant product-URL path to surface product pages, and indirectly explains the filter behavior through the commission_rate discussion. But it never explains the purpose of page (max 10, pagination) or search_type (web vs image), leaving those parameters underspecified for an agent. It adds some value but does not fully compensate for the coverage gap.

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

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

The description states a clear, specific purpose: a commission-aware web search for products worth linking to. It names the resource (products) and the distinguishing feature (commission_rate), and its phrasing implicitly separates it from search_links and search_brands. The verb 'search' is explicit, and it immediately tells the agent why this tool exists.

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 'Prefer this over a plain web search', which provides a when-to-use directive. It also gives a concrete tip for surfacing product pages (embedding the product-URL path in the query) and a retry instruction for transient errors. However, it does not mention sibling search tools like split_search_brands or split_search_links or state when NOT to use this tool, so it stops short of a full exclusion list.

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

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

The description adds meaningful behavioral context beyond the annotations: the action is irreversible, goes out under the creator's name, and must not be automated. This complements destructiveHint=true and gives the agent concrete consequences of calling the 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 tight sentences with no filler. The purpose is front-loaded, critical safety constraints follow immediately, and every sentence earns its place.

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

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

For a three-parameter, side-effectful tool, the description covers purpose, prerequisites, approval protocol, irreversibility, and cardinality. No output schema is present, but the description provides everything an agent needs to decide 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 67%, covering text and confirmed; the description reinforces and operationalizes those semantics by tying confirmed to explicit creator approval. It also adds a 'one channel per call' constraint that clarifies channel_url's intent, though it stops short of describing the expected URL format.

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 ('Send a reply to a brand') and the specific resource (brand message). It also adds scoping details like 'One channel per call' that distinguish this from broader or bulk messaging tools in the sibling list.

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 when-not-to-use guidance: never on your own initiative and never as an auto-reply. It also prescribes a precise workflow — draft, show verbatim to the creator, then call only with confirmed: true after approval — which fully directs an agent on when and how to invoke 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?

The annotations already flag destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the baseline safety profile is known. The description adds valuable context by emphasizing that the tool 'sends real email to real people', implying irreversibility and human impact, and by stating the confirmation precondition before setting confirmed: true. It does not add unnecessary detail beyond that.

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

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

Three short sentences carry all the essential guidance with zero filler. The most important warning ('real email to real people') is front-loaded, followed by the confirmation requirement and the address cap.

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 tool with two parameterscheschema and an output schema absent, the description covers the critical invocation conditions: the dangerous side effect, the needed confirmation, and the maximum list size. It only lightly addresses what happens when an address is invalid or whether calling with confirmed: false has any effect, but those gaps are not critical for correct 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 coverage is 50%, with the confirmed parameter already described in the schema. The tool description reinforces the meaning of confirmed ('get an explicit yes before calling with confirmed: true') and refers to emails as an 'address list', but it mostly restates what the schema's maxItems and confirmed parameter description already convey. It adds some clarity but does not substantially compensate for the undocumented emails array.

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 specific verb-resource pair 'Email referral invitations', which immediately identifies the tool's action and subject. It also makes the real-world, email-sending nature explicit, distinguishing it from nearby sibling tools like split_send_message by tying it specifically to referral invites.

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 an explicit workflow: show the creator the exact address list)Skip while you wait? I found in instructions:

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

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

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true). The description adds context about the privacy semantics and the default value, but does not disclose side effects or scope of effect (e.g., existing vs. future connections).

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

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

Two concise sentences: the first front-loads the purpose and valid values; the second adds a necessary caution. No filler.

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

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

For a simple one-parameter tool with no output schema and annotations covering safety, the description provides sufficient context: purpose, values, and a behavioral caution. It could mention effects on existing connections, but that is not essential 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 0%, so the description carries the burden. It explains the single parameter's meaning and defines all three enum values ('ask' default, 'accept' auto-allow, 'block'), effectively compensating for the missing schema descriptions.

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

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

The description states a specific verb ('Control') and resource ('whether brands may reveal the creator's identity when connecting'), and explains the three enum values. It is clear and not a tautology, but it does not explicitly distinguish from sibling tools, though none appear to overlap.

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 the tool (when controlling brand privacy) and adds a caution to explain the meaning before changing. However, it does not mention alternatives or exclusions, leaving usage guidance somewhat implicit.

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

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

The description adds substantial behavioral context beyond the annotations: it replaces the existing cover, performs upload and attach in one step, restricts formats to PNG/JPEG, and explains that omitting `crop` shows the whole image. The annotations only indicate non-read-only, non-idempotent behavior, so this is meaningful addition.

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 core action, then constraints, then the removal alternative. Every sentence earns its place; no filler or repetition of schema details.

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

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

The description is complete enough for correct invocation: purpose, parameter choices, format restrictions, crop semantics, and removal path are all covered. It does not describe the return value, and there is no output schema, but this is a minor gap for an action-oriented 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 100%, so the schema already documents all four parameters. The description adds value by reinforcing the either/or relationship between `source_url` and `image_base64` and by explaining the default behavior when `crop` is omitted, which is absent from the schema.

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

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

The description states a specific verb and resource: 'Replace a collection's cover image: uploads the image and attaches it in one step.' It makes the tool's scope unmistakable and, with the title and sibling names, the resource (collection vs. link vs. page image) is clearly distinguished.

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

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

The description gives clear usage conditions: supply either `source_url` or `image_base64`, PNG/JPEG only, and `crop` optional. It also provides an explicit when-not and alternative: 'To remove an image, call split_update_collection with image_upload_id: null.'

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 important behavioral traits beyond the annotations: the upload permanently overrides extracted metadata, the response's image_url is the new card image, and invalid formats are rejected before upload. This is especially valuable since annotations only indicate the tool is not read-only and not idempotent.

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, the either/or input choice, validation constraint, permanence and response field, then a guidance note on crop. The most important information is front-loaded, and the description is compact without being vague.

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 mutation tool with no output schema, the description explains the key behavioral outcomes, input constraints, and optionality of crop. An agent has enough information to decide whether to use this tool and how to populate its parameters 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?

With 100% schema coverage, the description benefits from a baseline of 3. It adds meaningful context for source_url (server fetches a merchant product photo), image_base64 (creator-supplied bytes), and crop (optional, rarely needed, omit to show the whole image). This is helpful but not radically more than the schema already conveys.

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

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

The description opens with a specific verb and resource: 'Replace the image on a link's card'. It goes beyond a generic label by framing the tool as the fix for wrong metadata-extracted images, which clearly distinguishes it from related link or page image tools. The purpose is unambiguous and actionable.

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

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

It gives a clear use-case signal: use this when metadata extraction grabbed a logo, favicon, or placeholder. It does not explicitly name alternative tools or state when not to use it, but the context is strong enough for an agent to route to 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 signal idempotentHint=false and destructiveHint=true, and the description adds the useful protocol detail 'PATCH with an empty body.' However, it does not disclose what destructive side effects occur, such as whether the original collection is removed or replaced, so the behavioral context beyond annotations is only modest.

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 contain only useful information: the operation and the required HTTP request shape. There is no filler, no repetition of the schema, and no 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?

For a one-parameter destructive mutation with no output schema, the description is minimally adequate: it identifies the operation and says the request body is empty. It is not complete because it does not state what the response will be or what happens to the original collection after promotion.

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

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

With schema description coverage at 0%, the description needed to compensate, but it does not explicitly explain that the required uuid identifies the collection being promoted. The uuid is left to inference from the tool name and first sentence rather than being clearly documented.

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 action—promoting a collection into its own section—which is far more informative than the tool name alone and distinct from siblings like split_create_section or split_update_collection. It stops short of a 5 because it does not explicitly contrast itself with those 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?

There is no guidance about when to use this tool versus split_create_section, split_update_section, or split_update_collection. The intended use is only implied by the phrase 'promote a collection,' with no prerequisites, exclusions, or alternative 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?

Annotations already establish that this is read-only, idempotent, and non-destructive. The description adds useful behavioral context beyond that: products are curated, commission percentages are creator-specific, and items require no further linking work.

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, both informative and non-redundant. The description front-loads the core purpose and immediately follows with the key creator-specific detail.

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

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

For a zero-parameter, read-only list operation with no output schema, the description is largely sufficient: it states the resource, personalization, and readiness to link. It could be slightly clearer that the result is a list and what 'trending' means, but these are minor 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?

The tool has zero parameters and the schema has 100% coverage, so there is no parameter semantics gap. The description helpfully indicates what the output contains, which is the relevant context for a parameterless call.

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 identifies the resource as curated trending products and adds important specifics: each has a creator-specific commission_percentage and is ready to link. It avoids simply repeating the title, though it lacks an explicit verb like 'return' or 'list'.

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

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

The intended use is implied: call this when you want curated trending products with precomputed commissions for this creator. However, it gives no explicit guidance about when to prefer this over similar siblings like browse_product_catalog or search_products.

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 important non-obvious behavior beyond the annotations: membership fields 'route to the regular-collection endpoint, which 404s for a smart collection', link_uuids is a 'full replace', and image_upload_id can be null to remove the cover. This goes well beyond the readOnly/destructive/idempotent hints, though it doesn't cover every edge case like invalid values or auth.

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 clause carries load-bearing detail: the full field list, the smart-collection exception, the null-to-remove behavior, and the verification step. There is no filler or repetition of schema fields, and the most important distinctions are front-loaded.

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

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

For a high-complexity tool with 11 parameters, no output schema, and no enum constraints, the description addresses the most error-prone behaviors and provides a follow-up verification step. It is incomplete only on a few less risky fields like layout and visible_on_splitpage, but the core collection-update semantics are sufficiently covered.

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

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

With only 55% schema coverage, the description compensates for the riskiest parameters: it clarifies image_upload_id null semantics, section patchability, and the meaning and constraints of links_to_add/links_to_remove/link_uuids. However, it does not add semantics for query, layout, visible_on_splitpage, or name, which remain underspecified by both schema and description.

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

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

The description states a precise, non-tautological purpose: it enumerates exactly what can be updated on a collection ('name, visibility, cover image, owning section, or membership'). It further distinguishes regular from smart collections, which anchors the tool's scope and separates it from sibling update/set tools.

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

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

The description gives clear conditional guidance: membership fields are for 'REGULAR collections only', smart collections can't use them because 'its membership is its query', and it tells the agent to 'verify with split_get_collection_links' after membership changes. It does not explicitly name alternatives like split_set_collection_image for cover images, but the regular-vs-smart distinction is strong enough for most 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?

The description goes well beyond annotations by disclosing that tags and regular_collection_names replace the existing set, that url is read-only, and that image_url updates are silently ignored unless handled through split_set_link_image. These are non-obvious behavioral details that materially affect correct invocation.

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 tool's purpose, the second provides critical replace-not-delta semantics, and the third routes image changes to the correct sibling. 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?

The description is thorough for a mutation tool with no output schema and strong annotations: it covers replace semantics, read-only fields, and the image alternative. The primary gap is the unmentioned `is_favourite` parameter, which an agent might not realize is updateable through this endpoint.

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

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

Schema description coverage is only 20%, so the description must compensate. It does for `name` (title), `tags` (replace semantics), and `regular_collection_names` (full desired list). It does not explain `is_favourite`, a non-obvious boolean parameter, and `uuid` is only implied as the link 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 clearly states the tool updates a link's title, tags, or collection membership with a specific verb and resource. It differentiates from split_set_link_image by noting image changes must go through that sibling. However, it omits the updateable `is_favourite` parameter, so the stated purpose is not fully complete.

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 alternative guidance for changing the card image: use split_set_link_image rather than PATCHing image_url, which is silently ignored. It does not discuss when to prefer this tool over other link-related operations, but the image-specific routing is clear and useful.

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 (idempotentHint=true, destructiveHint=false) already establish safety; the description digs deeper by clarifying that `public_url` and `image_url` are read-only in this tool and that `image_url` is the creator's profile avatar rather than a page image. This prevents an agent from attempting to mutate fields that appear mutable. No contradiction with annotations — description says 'Update' (write) and readOnlyHint=false, 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?

Three front-loaded sentences with no waste. The core intent leads, and each subsequent sentence defuses a distinct misconception (read-only URL, avatar caveat, missing theme field). Efficient and well-ordered.

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 4-param update tool with full schema coverage, idempotent/non-destructive annotations, and no output schema, the description covers what is updatable, what is explicitly off-limits, and where the exceptions live. The only mild gap is not naming the sibling tools by name, but nothing an agent needs to invoke 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 100% and the schema documents all four params (id, name, slug, description). The description adds value by clearing up domain confusion: it explains that `slug` is the public URL handle and warns that `public_url`/`image_url` from the broader API are read-only here, so they are not targetable via this tool. It goes beyond the schema to prevent misuse.

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

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

States a specific verb+resource+scope: 'Update page title, bio, or public URL handle.' This is unambiguous and matches the sibling family (split_update_link, split_update_profile, split_update_section). It doesn't explicitly name a sibling it is not, but the resource 'page' plus the field list makes the purpose clear.

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

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

Provides explicit when-not guidance: `image_url` is read-only here and image changes need an upload this tool does not do, and there is no theme/colour field since appearance is set per-section. This tells an agent when to look elsewhere, though the alternative tools (e.g., split_upload_page_image, split_update_section) are implied rather than explicitly named.

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

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

Beyond the annotations, the description discloses that the backend re-checks discoverability on every profile write while is_discoverable is on, exposes the exact rejection message, and clarifies that name changes are exempt. These are non-obvious behavioral traits that materially affect how an agent should handle failures.

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 core action and field list are front-loaded, followed by a dense but purposeful block explaining discoverability and error handling. The discoverability sentence is long, but every clause contributes critical usage information, so there is no wasted text.

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 covers what an agent needs to invoke the tool correctly and recover from failures. It omits the success response shape, but that is a minor gap for an update operation whose main complexity is already thoroughly explained.

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 covers 67% of parameters, and the description adds meaning for the less-documented ones: it explains is_discoverable's dependency on social links, the contact_email field, and that first_name is 'the name brands see'. However, some schema descriptions remain thin and the description doesn't fully compensate for all gaps.

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

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

The description states a specific verb and resource ('Update the public profile') and enumerates all updatable fields. It also distinguishes this tool from related siblings by exempting name changes (handled by a separate account endpoint) and pointing to split_add_social_link for social-link additions.

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