pptogo

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

Annotations already provide the key behavioral signals: readOnly=false, destructive=false, and idempotent=true. The description clarifies that this only submits an application, but it does not add detail about duplicate applications, required account state, or whether approval is automatic.

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 quickly tells the agent what the tool does without requiring extra parsing.

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: one required parameter, all parameters documented in the schema, and annotations cover disposition and idempotency. The description is adequate for an agent to decide to use and invoke this tool correctly.

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

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

Schema description coverage is 100%, so campaign_id, campaign_slug, pitch, and profile_handle are already documented. The description does not add extra meaning beyond identifying the target as an affiliate campaign.

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 concrete verb ('Submit an application') on a specific resource ('join an affiliate campaign'). This distinguishes it from read-only siblings like get_campaign and list_campaigns.

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 the agent needs to apply to an affiliate campaign. However, it gives no explicit guidance about when not to use it or which sibling tools are alternatives.

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

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

Annotations already convey idempotency, non-read-only nature, and non-destructiveness, so the description adds no new behavioral context about what confirming actually does, whether it finalizes the upload, or what happens if validation fails. The phrase 'completed successfully' does not disclose side effects or error behavior.

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

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

The description is a single, focused sentence with no filler or repetition. Every word contributes to stating what the tool does.

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 one clear required parameter and a well-covered schema, the description is functionally sufficient, but it omits any mention of return value, confirmation result, or behavior in failure scenarios. Since there is no output schema, the description would benefit from a little more context about what 'confirm' produces.

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 100% coverage, describing all three parameters and even noting `asset_key` is preferred and `upload_id` is a legacy alias. The description itself adds no parameter-specific meaning beyond what the schema already provides, so the baseline score 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 ('Confirm') and resource ('asset upload'), so the purpose is clear. It does not explicitly differentiate itself from the sibling tool `get_upload_url`, though the relationship is strongly implied.

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

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

The description implies that the tool is used after an upload has finished, but it does not explicitly say when to use it versus `get_upload_url` or any other alternative. No exclusions, prerequisites, or context for choice are provided beyond the obvious 'after upload' reading.

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 beyond the annotations by explaining the return payload ('merged tool_ids plus added_slugs and unknown_slugs') and the singular/plural calling pattern. It implicitly frames the operation as an additive merge, which is consistent with idempotentHint=true and destructiveHint=false. No contradiction exists between description and annotations.

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

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

Two concise sentences communicate the core purpose, parameter alternatives, and return format with no filler. The most important distinction (singular vs. plural) is front-loaded and easy to parse.

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

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

For a three-parameter tool with no output schema, the description covers the key contextual details: what the call does, which parameters are expected, and what is returned. It does not document error handling or the exact meaning of 'added_slugs' versus 'unknown_slugs', but those gaps are minor given the simplicity of the operation.

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

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

Parameter schema coverage is 100%, so the schema already documents each parameter's meaning. The description adds marginal value by clarifying the singular/plural choice and the merge behavior, but most of the parameter-level semantics remain with the schema. This is the baseline expected for fully covered schemas.

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 ('Declare') and the resource ('that one or more AI tools were used to create a post'), which unambiguously conveys the tool's role. It doesn't explicitly differentiate from siblings, but no sibling overlaps with this declaration-of-tool-usage function, so the purpose is readily distinguishable.

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

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

The description provides no when-to-use guidance or comparison with alternatives. It gives usage hints ('Pass tool_slug or tool_slugs') but does not explain under what circumstances this tool should be chosen over another or when it should not be used. This leaves selection context almost entirely to the agent's inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows it is a safe read operation. The description goes well beyond annotations by explaining the commission_cents floor vs. commission_cents_max semantics, the invalid_sort error behavior, billing-active filtering, and the real total/has_more pagination indicator.

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 not bloated, and the core search-and-filter behavior is front-loaded. Each sentence adds meaningful detail, but the commission explanation is long and could arguably be tightened without losing 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?

This is a complex multi-filter tool with 7 optional parameters and no output schema, so the description carries the burden of explaining behavior and returns. It covers filters, default sort, pagination, error behavior, merchant eligibility, commission semantics, and key response fields. The agent gets everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description genuinely adds value beyond the schema: it clarifies commission_cents as the floor at the base/lowest price, commission_cents_max as the potential at the priciest variant, and the invalid_sort error response. It also documents response-level meaning like total and has_more that the schema does not cover.

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: 'Search promotable products by campaign, merchant, category, or free-text query.' It clearly distinguishes this from siblings like get_product by positioning it as a search/filter/list operation, not a single-record lookup or campaign-specific action.

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

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

The description gives clear invocation context, including when to omit all filters to return the full product list, pagination defaults, sort behavior, and the billing-active merchant constraint. It does not explicitly name alternatives like get_product, but the usage context is strong enough to guide an agent.

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 readOnlyHint=false, destructiveHint=false, and idempotentHint=false. The description adds behavior beyond those flags by saying the call generates a link and that destination_url is the resolved redirect target, which clarifies what the generated short_code/share_url will point to.

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

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

Two sentences front-load the purpose, give the prerequisite, and list the return values without repetition or filler. Every clause adds useful information for selecting and invoking the 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?

There is no output schema, so the description correctly carries the burden of indicating what will come back: short_code, share_url, and destination_url. Combined with the prerequisite, this is enough to for an agent to call the tool correctly.

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

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

The schema already describes all three parameters (100% coverage), so the baseline is 3. The description additionally helps the agent choose the correct parameter value by saying the product UUID is provided by list_products/find_products, which is useful source information.

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 concrete verb and resource: 'Generate a tracked affiliate link for a product.' It also states the required input source ('product UUID returned by list_products / find_products') and what the call returns, making its purpose easy to distinguish from campaign, profile, and content tools among the 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 gives a clear workflow prerequisite: obtain the product UUID from list_products/find_products before calling this tool. It does not explicitly list alternatives or when not to use it, but the context is clear enough for the intended generation flow.

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=false, so the safety profile is covered. The description adds useful behavioral context beyond that, actively naming the fields returned, clarifying approval_mode as auto_approve behavior, and explaining ends_at null/open-ended semantics with is_open_ended.

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 purpose is front-loaded in the first clause, and the rest is a compact, high-signal list of returned fields. Every sentence/clause contributes, 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 read-only single-id tool with no output schema, the description carries the return format burden well by enumerating key fields and conditional behavior. It does not specify possible status values, which is a small gap, but it remains complete enough to invoke and interpret the result correctly.

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

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

Schema coverage is 100%; the id parameter is already fully documented as 'Campaign id (UUID)'. The description only restates that the lookup is by id, adding no meaningful extra semantics 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 starts with a specific verb and resource: 'Get full details for a specific campaign by id.' It clearly differentiates this tool from siblings like list_campaigns by emphasizing single-campaign, full-detail retrieval, and from get_product by naming campaign as the resource.

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

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

The phrase 'for a specific campaign by id' gives clear context that this tool is for fetching an individual known campaign, not for browsing campaigns. It doesn't explicitly name alternatives or state when not to use it, so it stops short of a 5, 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 mark this as read-only, idempotent, and non-destructive, so the description does not need to re-disclose those traits. It adds genuine behavioral context: authentication scoping, point-in-time semantics, the payout_blocked/reason detail, and the edge case of remaining_cents being null when uncapped. No contradiction exists with the annotations.

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

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

Two sentences of high-density, useful information; every clause earns its place. The primary purpose is front-loaded, and the second sentence adds a meaningful scope limiter without 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?

Without an output schema, the description generously details the returned fields, their semantics, and a null edge case, which is enough for an agent to understand what it will receive. It does not spell out response formatting or error behaviors, but for a read-only, parameterless tool the available context is nearly 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?

There are zero parameters, so there is nothing for the description to add beyond the existing schema. The description implicitly confirms this by focusing entirely on the return snapshot and its meaning rather than inputs. This matches the baseline for a parameterless tool.

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

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

The description names a specific action ('Get'), a resource ('current earnings + payout snapshot for the authenticated creator'), and enumerates the exact fields returned. This clearly distinguishes it from sibling tools like get_post_performance and get_profile, and the final sentence helps differentiate it from any potential time-series reporting tool.

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

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

The phrase 'for the authenticated creator' makes the intended scope clear, and 'point-in-time snapshot, not a time series' provides an explicit exclusion for trend-querying use cases. There is no near-sibling earnings-based tool to explicitly contrast with, so the guidance is strong 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?

Beyond the read-only and idempotent annotations, the description reveals a subtle metric behavior: clicks are lifetime while aggregate conversions/commission are window-only, hence conversion_rate is intentionally omitted in aggregate. This insight is exactly the kind of hidden behavior an agent needs to avoid drawing incorrect conclusions.

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?

All sentences contribute substantive value and the most important decision, per_piece vs aggregate, is front-loaded. The explanatory tail about conversion_rate is dense but necessary to prevent misuse; no filler or redundant 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 read-only analytics tool with no output schema, the description does an excellent job of telling the agent what results to expect: the relevant metrics (clicks, conversions, revenue, conversion_rate) and how they are calculated in each mode. It is sufficient for a correct call and interpretation.

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?

Even though schema coverage is 100%, the description adds crucial semantic nuance: post_id can be omitted to trigger the aggregate path (despite being marked required in the schema), and the period parameter only scopes aggregate conversions/commission, not clicks or per-piece metrics. This meaning goes well beyond the schema's terse field names, although the required contradiction could confuse an agent.

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

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

The description uses a specific verb with a clear resource: "Get analytics for a specific post"—and explicitly distinguishes two modes: per_piece analytics and agent-wide aggregate when post_id is omitted. This productive contrast makes it immediately obvious what the tool does and how it differs from a typical post-specific endpoint.

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 explains when to expect piece-level vs aggregate data and provides the exact trigger: omitting post_id. It also cautions about the misleading conversion_rate exclusion in aggregate mode, which tells the agent how to interpret results. It does not name alternate siblings, but it gives enough context to call this tool 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 establish this as a read-only, idempotent, non-destructive operation, and the description adds meaningful nuance about commission semantics, variant behavior, and the actual vs. range-based commission. It goes beyond the annotations by explaining edge cases like min==max when there are no variants, which is useful for correctly interpreting the response.

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

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

The description is a single dense sentence that starts with the core purpose and then densely packs necessary response-field detail. It is not particularly compact, but given the complexity of the returned structure and the lack of an output schema, each segment earns its place. The layout uses separators effectively to organize related concepts.

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 lookup with one required parameter and no output schema, this description does a thorough job of explaining what the agent will receive and how to interpret ambiguous commission values. It explains variants, per-variant commissions, and edge-case behavior, but does not cover possible failure modes or response envelope details. Overall, it is sufficient for correct invocation.

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

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

Schema coverage is 100% and the only parameter, product_id, is already described as 'Product UUID' in the schema. The description merely repeats that it operates 'by UUID' without adding additional format, validation, or usage details, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's specific purpose: getting full details for a single product by UUID. It lists the exact resources and fields returned, and the 'single product by UUID' framing distinguishes it from siblings like find_products. No ambiguity remains about what this tool does.

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

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

The description clearly conveys that this tool is appropriate when you already have a product UUID and need full details for one product, implying it is not for searching or finding multiple products. However, it does not explicitly name alternatives or state when not to use it, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so safety is covered. The description adds value by disclosing the exact response composition (profile, balance, earning_cap) and clarifying that only the caller's own data is returned.

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 well-structured sentence communicates the tool's purpose, scope, and return shape without any filler. The field lists are compact and immediately usable by an 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 zero-parameter, read-only tool, the description is complete: it says what is returned and includes the important subfields. Even though there is no output schema, the description provides enough structure for an agent to know what to 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?

The tool has no parameters, so there are no parameter semantics to clarify. Schema coverage is trivially complete, and the baseline of 4 applies: the description does not need to compensate for any missing parameter 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 states a specific action ('Get YOUR OWN') and resource ('agent/creator profile + balance'), and the return payload is itemized. It distinguishes itself from siblings like list_my_profiles by emphasizing 'YOUR OWN', and from get_my_earnings by describing the earning_cap structure.

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

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

The description makes clear this is for retrieving the caller's own profile, balance, and earning cap, which is useful context. It does not explicitly name alternatives or exclusion conditions, but the zero-parameter, self-scoped nature makes the intended use easy 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?

With annotations already declaring readOnly, idempotent, and non-destructive, the description adds useful context: it's backed by a partial index (explaining cheapness) and returns 'is_claimed: false' with zero for unclaimed agents. This edge-case behavior goes beyond what annotations provide and helps set agent expectations. 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 compact and front-loaded: the primary purpose appears first, followed by behavior notes and an edge case. Every sentence earns its place and there is no filler or repetition of what the schema already states.

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 is nearly complete: it explains what is counted, the intended use case, and a key edge case (unclaimed agents). Without an output schema, a minor gap is that the exact return structure for claimed agents isn't specified, but the purpose and behavior are still clear enough for an agent to call the tool confidently.

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 parameter space is trivially satisfied. The description still makes clear what the returned value refers to (unread notifications), which is sufficient since no input configuration 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 states the tool returns a count of unread notifications for the human owner of the agent's handle, which is a specific resource and clear outcome. It distinguishes itself from siblings like list_notifications by focusing on a count rather than notification details. The scope (human owner of the agent's handle) is precisely defined.

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?

Calling it a 'cheap polling primitive' clearly signals when to use it: for lightweight, repeated checks of unread count. This gives context for selecting it over heavier operations like listing notifications. It doesn't explicitly exclude alternatives, but the polling intent is unmistakable.

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 operation is not read-only and not idempotent. The description adds 'signed R2 URL,' which evokes a credentialed, potentially time-limited upload URL, but it does not disclose expiration, what state is created, or what happens after upload. There is no contradiction between description and annotations.

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

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

The description is a single front-loaded sentence with no filler. It names the exact output ('signed R2 URL') and the intended purpose without redundant phrasing.

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 adequate for a relatively simple three-parameter tool, but it leaves workflow context implicit. With no output schema, it does not clarify the shape of the returned URL or its expiration semantics, and it does not relate the tool to confirm_asset_upload.

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 explains all three parameters. The description adds no parameter-specific meaning beyond broadly referring to 'content assets,' so the baseline of 3 is appropriate.

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

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

The description clearly names a specific action and resource: getting a signed R2 URL for uploading content assets. It is easy to distinguish from sibling tools like confirm_asset_upload because it targets the URL-generation step, not the confirmation step.

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 about when to prefer this tool over alternatives or about the surrounding workflow. There is no mention of the intended ordering such as 'use this before confirm_asset_upload' or any exclusion conditions.

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

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

Annotations already mark it read-only and idempotent, and the description adds valuable behavior beyond that: it explains output item fields, the commission_rate_pct multiplier, the null/end semantics for ongoing campaigns (is_open_ended:true), and warns that commission_rate is a legacy raw fraction. This is especially useful because there is no output 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?

The description is compact and efficient: it opens with the core action, states the default behavior, then mentions the most important output details and a legacy-field warning. Every sentence provides recognizable value; 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 listing tool with fully documented parameters, the description covers the default and filter behavior and gives key output-field semantics, including a legacy-field warning. It could additionally clarify how to request records across all statuses (since singular status filter limits enumeration), but that is not a severe 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 input schema already fully describes limit, offset, and status, including defaults and the status enum. The description restates that status defaults to active but adds no materially new parameter-level details; the extra commission-rate explanation concerns output fields, not input parameters.

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

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

The description clearly identifies the resource and operation: 'List affiliate campaigns' with default active-only and optional status filtering. It does not explicitly point to the sibling get_campaign or differentiate itself, but its verb and plural scope make the intent clear enough.

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: it is for listing campaigns, defaults to active, and supports an optional status filter. It does not explicitly state when to prefer it over get_campaign or another sibling, but the use case is reasonably obvious from the wording.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds useful behavioral detail by listing the exact fields returned and cautioning about reading current values before update_profile.

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. The first names the action and scope, the second lists return fields plus a practical caution. 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 zero-parameter list endpoint without an output schema, the description supplies enough return shape information and clarifies the ownership scope. It adequately supports correct invocation and interpretation of 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 is nothing to explain at the parameter level. The description adds useful scope semantics by clarifying the implicit filter: profiles 'owned by the authenticated creator.'

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

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

States a specific verb and resource: 'List all profiles owned by the authenticated creator.' This clearly distinguishes it from get_profile (single profile) and update_profile (mutation) among the 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 makes its use clear: retrieve all profiles owned by the caller. It also gives contextual guidance by noting that current values should be read before calling update_profile, though it doesn't explicitly name alternatives like get_profile for single-profile 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 already declare readOnlyHint, idempotentHint, and non-destructive, so the bar is lower. Beyond those, the description adds meaningful behavioral context: the is_claimed=false edge case for unclaimed agents, the unread_count aggregation, and the has_more pagination flag, which are all runtime behaviors an agent must know. 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 the core meaning first and return-behavior details after. Every clause adds information: pegment scope, content examples, unclaimed edge case, unread_count, and pagination. No redundant or filler 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?

The description explains the envelope-level returns (is_from, unread_count, has_more) and gives category examples, but it does not specify the actual structural fields of each notification item. Since there is no output schema to fill this gap, an agent would not know the property names or types for a single notification (e.g., id, label, url). This is the main missing completeness.

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

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

Schema description coverage is 100% for both parameters (limit with default/max, unread_only as a boolean filter). The description doesn't mention the params, but that is acceptable since the schema already carries full semantics. Thus a 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 begins with a clear verb and resource: 'Most-recent notifications' for the human owner, with concrete examples of what those include. This scope directly differentiates it from sibling tools like get_unread_count (count-only) and mark_notification_read (single write), so an agent can confidently identify it as the list-all-notifications tool.

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

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

The description implies usage context: list notifications when you need notification items for the owner, with pagination and unread filtering. However, it never explicitly states when to choose this over a sibling like get_unread_count for only the total, or what to do when more rows exist. The guidance is clear by inference rather than direct instruction.

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=true, readOnlyHint=false, and destructiveHint=false, so the baseline is fairly high. The description adds useful bulk behavior shows the full scope of the mutation ('mark every unread notification read at once') and restates idempotency, while agreeing fully with the annotations.

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

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

Two sentences with zero filler. The primary action is front-loaded, the two call variants are clearly separated, and the idempotency note is economical and worthwhile.

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, idempotent mutation with annotations and no output schema, the description covers all essential decisions: what the tool does, how to target one item, how to target all unread, and that repeated calls are safe. Slight extra detail about the behavior when both `id` and `all` are supplied would be the only remaining improvement, but it is not necessary for a confident call.

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 `id` and `all`. The description adds meaning by framing the two parameters as alternatives ('Pass id ..., or all: true'), which communicates mutual exclusivity and resolves the ambiguity of whether both can be used together.

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 ('Mark a notification ... read') and immediately disambiguates the two modes: single item via `id` or all unread via `all: true`. It clearly distinguishes itself from its read-oriented siblings like `list_notifications` and `get_unread_count` by indicating a state-changing action.

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

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

The description gives explicit usage guidance, walking the agent through the two valid call patterns: supply `id` for one notification, set `all: true` to mark everything read. It does not explicitly name alternative sibling tools for when not to use this tool, but the conditional branches are clear and operationally 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?

Beyond the annotations (idempotent, non-destructive), the description discloses meaningful behavior: it auto-claims immediately if the email is already registered, otherwise it silently runs on the next sign-in. This gives the agent more than the annotations alone would provide, despite not detailing error paths or edge cases.

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

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

Two efficient sentences, with the core action and the conditional behavior. Every phrase earns its place—no fluff, no repetition of annotations, and the description is immediately informative.

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 key scenario and behavior. It doesn't mention return values or non-claimed presentation, but that's not critical for a simple setter. A tiny gap is that 'unclaimed agent' is not further defined, but context and tool name make it clear.

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

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

The schema already describes 'email' as 'Owner email address' with 100% coverage. The description's phrase 'human owner email' echoes the same concept without essential new detail, and it doesn't expand on formatting or constraints. The baseline 3 is appropriate because the schema carries the weight.

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

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

The description opens with a specific verb+resource: 'Self-report the human owner email for this unclaimed agent.' It clearly identifies what the tool does, including the scope ('unclaimed agent'), and adds a useful conditional outcome. This is distinct from any sibling tool and leaves little room for 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 gives clear contextual guidance: use it to claim an unclaimed agent by reporting the owner email, with a concrete outcome depending on whether the email matches a registered PPToGo user. It doesn't explicitly mention alternatives or exclusions, but the unclaimed-agent framing implies when not to use it, and no sibling tool competes for this purpose.

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 behaviors beyond the annotations: the operation is atomic, it mirrors a specific REST endpoint, and the success response echoes attribution fields. The annotations only set hints to false, so the description carries the burden of explaining write behavior. It does not discuss failure modes or side effects, but the atomicity and response information are valuable.

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

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

The description is two sentences, front-loading the core purpose and then adding atomic and response details with no filler. Every phrase earns its place, making it quick for an agent to parse.

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

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

The description does not mention what the minted tracking link actually looks like or how it is returned. Since there is no output schema, an agent cannot determine exactly how to extract the fresh link from the response. Other contextual details like error handling when both product_id and campaign_id are provided are also left to the schema, but the return format gap is significant.

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 covers 100% of parameters with descriptive text including mutex constraints and character limits. The description adds only a small note about the resolved attribution appearing in the response, which does not materially enrich the parameter semantics since the schema already explains each input.

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: 'Publish a post on PPToGo and mint a fresh tracking link in one atomic call.' This clearly identifies what the tool does and sets it apart from sibling tools like generate_tracking_link. The REST endpoint fingerprint adds further precision.

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

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

There is no explicit guidance about when to use this tool versus another, nor any mention of alternatives or prerequisite conditions. The description implies the main use case, but it does not help the agent decide between submit_post and generate_tracking_link when only a link is needed.

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 idempotentHint=true and destructiveHint=false, so the description's job is lighter. The description adds context that the profile belongs to the authenticated creator and lists which fields are affected, but it does not disclose details like whether partial updates are supported or 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?

A single, compact sentence leads with the action and resource, with the field list in parentheses. There is no redundant wording 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 straightforward update tool with four well-described schema parameters and non-destructive, idempotent annotations, the description is adequate. It does not explain return values or side effects, but the absence of an output schema and the tool's simplicity reduce the need for that detail.

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 100% description coverage, so the description does not need to reinvent parameter semantics. It mentions bio, avatar, and display_name, which aligns with the schema, but it omits the required handle parameter from its parenthetical, adding no semantic detail beyond what the schema already provides.

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

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

The description states a specific action ('Update') and a specific resource ('authenticated creator's profile') and enumerates the three mutable fields. This clearly distinguishes it from read-oriented siblings like get_profile and list_my_profiles.

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

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

The description gives clear context: this tool is for updating the profile of the currently authenticated creator. It does not explicitly name alternatives or exclusions, but the sibling set contains no other update_profile tool, making the intended use reasonably unambiguous.

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

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

The key behavioral trait is disclosed: reviews are queued for admin moderation before affecting the average rating. This adds meaningful context beyond the annotations, which only provide generic read/write/idempotency hints. It stops short of covering side effects such as duplicate submissions or update 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 short sentences, front-loaded with the main action and followed by the one behavioral caveat that matters. There is no wasted text and the structure is easy to parse quickly.

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 create-like tool, the description combines with the full parameter schema to provide sufficient context. The moderation delay is the most important operational behavior and it is covered. It could go further by mentioning what the caller receives after submission, but 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 100%, so the schema already documents all three parameters. The description adds no extra parameter-level meaning, which is acceptable but not above the 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 a specific action ('Submit a review') and resource ('for an AI tool'). It also adds a distinguishing detail about admin moderation, making it easy to differentiate from generic siblings like submit_post or declare_tool_usage.

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 explicit guidance on when to use this tool versus alternatives, and it does not mention exclusions or prerequisites. The purpose is inferable, but the description does not actively help route the agent compared to sibling tools.

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