makeup.land

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

With no annotations, the description carries the full burden. It specifies auth requirements, selection behavior (most-recently-updated), and return contents (reward projection). However, it does not explicitly state read-only behavior or how missing carts are handled, leaving some ambiguity.

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 that front-load the primary function, then add auth and return details. There is no unnecessary content, making it appropriately concise for a simple 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?

For a simple one-parameter tool with no output schema, the description adequately covers the return value and auth requirement. It could mention empty-cart behavior or error cases, but the core functionality is clearly specified.

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

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

Schema coverage is 100% with the phone parameter fully described, so the description adds minimal extra meaning beyond mentioning 'Bearer + phone required'. This aligns with the baseline of 3 when the schema handles 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 states it returns the customer's most-recently-updated cart with per-line and total reward projection, using a specific verb and resource. This clearly distinguishes it from sibling tools like get_customer and list_orders.

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 on when to use this tool versus alternatives. The mention of 'Bearer + phone required' is a prerequisite rather than usage context. The description does not reference any sibling tools or 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?

No annotations are provided, so the description carries the full burden. It discloses the auth requirement ('Bearer required') and the return fields, but doesn't explicitly state read-only behavior, error handling, or other side effects. This is partially transparent but leaves some ambiguity.

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

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

Two concise sentences, front-loaded with the main action and returning the specific data fields. Every word adds value, and the structure is immediately scannable.

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

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

For a simple single-parameter lookup with no output schema, the description adequately covers what the tool returns and the auth requirement. It doesn't describe response format or errors, but the tool's complexity is low, making this 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 100%, so the baseline is 3. The description repeats the E.164 requirement but adds no new information about the phone parameter 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?

Description explicitly states it returns specific customer attributes (tags, ℳ-credit balance, M Club tier) for a customer identified by phone. This clearly distinguishes it from sibling tools like get_customer_best_deals and list_orders.

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

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

The description provides clear context for when to use the tool: when you need customer profile details by phone number. It implies the use case without explicitly listing alternatives or exclusions, making it a clear but not fully explicit guideline.

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 no annotations, the description carries the full burden and does add the auth requirement (bearer token plus phone), which is genuinely useful. But it discloses nothing about how deals are ranked, whether results are cached/stale, rate limits, or what a 'projection' means operationally.

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, no filler, and the substantive claim about what drives the results is front-loaded ahead of the auth note. Very efficient, if slightly clipped.

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 small read tool with no output schema and no annotations, the description covers the input requirement and the personalisation basis, which is adequate. It stops short of describing the returned deal shape or the possibility of an empty/failed lookup, which would help an agent interpret 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?

Schema description coverage is 100%, so the schema already documents both phone (E.164) and the ignored limit. The description adds the framing that personalisation is driven by tags and M Club tier, but no additional parameter-level semantics. Baseline 3 applies.

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

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

The description states a specific resource and scope: top deal projections personalised by the customer's tags and M Club tier. That is enough to distinguish it from siblings like get_customer or get_cart, though the verb is implicit (a restatement of 'get' rather than an action 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?

It gives a prerequisite ('Bearer + phone required') but no guidance on when to choose this tool versus alternatives such as get_customer or get_cart, and no exclusions or failure conditions. Prerequisites are not usage 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?

With no annotations, the description carries the full burden of disclosure. It adds value by stating the required Bearer authentication and the specific output fields (product counts and slugs). However, it does not mention potential pitfalls like pagination, rate limits, or exact response structure, which would be useful for a production consumer.

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 stating exactly what the tool does, followed by a crucial authentication requirement. There is no wasted verbiage; every word earns its place.

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

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

For a simple list tool with no parameters, the description is complete: it states the resource, the included fields, and the auth requirement. Although there is no output schema, the description's mention of 'product counts and slugs' sufficiently conveys the expected return structure.

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. The description adds no parameter-level information, but none is needed since the input schema is empty. The schema coverage is effectively 100%, and the description is not expected to elaborate on nonexistent parameters.

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

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

The description uses the specific verb 'Return' with the resource 'brands' and specifies the output includes 'product counts and slugs.' This clearly distinguishes it from sibling tools like list_products or list_orders, which operate on different entities.

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

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

The description clearly indicates this tool is for retrieving all brands, and the context of 'every brand' implies use when a complete list is needed. While it doesn't explicitly exclude alternatives, the sibling tools are all for different resources, making the usage context 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?

With no annotations, the description carries the full disclosure burden. It usefully reveals the auth requirement (Bearer token plus phone) and the recency scoping, and 'list' implies a read-only operation, but it says nothing about rate limits, error behavior, or the paging quirk that the schema flags. Partial coverage for a no-annotation 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?

Two tight sentences/fragments with the resource and status axes front-loaded and no filler. Nothing is wasted, though the telegraphic style leaves behavioral gaps the length budget could have covered.

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

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

For a simple three-parameter listing tool with a fully-described schema and no output schema, the description covers purpose, return shape (status axes), and auth prerequisites. The main omission is any note on return volume or the ignored page parameter, but the schema already documents the latter.

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 restates that phone is required (already in the schema's required list) and adds no syntax or format detail for phone, page, or limit, so it does not exceed 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?

States a specific verb+resource ('orders' for a customer) and enriches it with the 6-axis status breakdown, so an agent knows exactly what data shape comes back. It does not explicitly contrast with siblings, though the sibling set (get_cart, list_products, list_brands, etc.) targets different resources, which limits 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 word 'Recent' implies the tool is scoped to the most recent orders and 'Bearer + phone required' signals the auth/customer prerequisite. However, there is no explicit when-to-use guidance, no exclusions, and no pointer to alternatives such as get_cart or get_customer for related lookups.

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 no annotations, the description carries the full burden. It discloses the scope (unpaid orders) and authentication requirement (Bearer + phone), which is useful. However, it doesn't explicitly state that this is a read-only operation or describe any side effects, rate limits, or error conditions. The title 'List' implies read-only, but the description doesn't add much beyond that and the scope.

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

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

The description is two concise sentences that immediately state the core function and requirements. No filler or redundancy. It is front-loaded and every word contributes value.

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

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

For a simple tool with one parameter and no output schema, the description adequately explains what it returns (pending payment_requests) and the required context (unpaid orders, auth). It falls slightly short of a 5 because it doesn't provide any hint about the response structure or optional parameters, but overall it is sufficient for an agent to select and invoke 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 input schema covers the lone parameter 'phone' with a clear description and pattern. The tool description repeats that phone is required but adds no new semantic information beyond the schema. Since schema coverage is 100%, 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 clearly states the tool lists pending payment requests associated with the customer's unpaid orders. It uses a specific verb ('list') and resource ('pending payment links'), and distinguishes itself from sibling tools like list_orders or get_cart which serve different purposes.

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: this is for pending payment_requests on the customer's unpaid orders, and it explicitly requires Bearer + phone. While it doesn't name alternative tools or exclusion scenarios, the context is specific enough for an agent to know when to invoke this tool over siblings.

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

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

With no annotations, the description carries the full behavioral burden, and it does disclose one non-obvious trait: bearer auth kicks in only when `phone` is supplied. Beyond that it says nothing about read-only nature, pagination, page-size caps, or result shape; and the auth note largely restates what the `phone` schema description already says.

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

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

Two tight, front-loaded sentences with no padding. Minor inefficiency: it enumerates five of nine parameters while omitting the primary search parameter `q`, so the list is both redundant with the schema and incomplete.

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 nine-parameter tool with no output schema and no annotations, the description covers auth and filter surface but omits pagination behavior, honor of limit/page caps, and any sense of the returned product shape (only the near_hex schema description hints at a shade_match field). Adequate but with clear gaps given the tool's complexity.

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

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

Schema description coverage is 100%, so the schema already documents all nine parameters including enums, defaults, patterns, and the q-vs-tag distinction. The description re-lists a subset of filter names (glossing near_hex as 'color-distance shade match') without adding syntax or format meaning, so baseline 3 applies.

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

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

States a specific verb ('browse') and resource ('the catalog') and enumerates the filter dimensions, so an agent can distinguish it from siblings like list_brands or get_customer_best_deals. It is clear but never explicitly frames itself as product search/retrieval, relying on the tool name and siblings to disambiguate.

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 when-to-use or when-not-to-use guidance: nothing says to prefer this over list_brands, nor how q vs tag should drive selection (that guidance lives entirely in the schema). The filter enumeration hints at capability but not at selection between this tool and 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?

With no annotations, the description carries the burden of behavioral disclosure. It reveals that the endpoint is public and gated on code knowledge, which is a useful auth-related trait. It does not mention error cases or rate limits, but for a simple balance check, the key behavioral trait (no bearer required) is disclosed.

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

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

Two concise sentences front-load the primary purpose and then provide key auth context. Every word earns its place, and there is no fluff or redundancy.

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

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

For a simple one-parameter tool with no output schema, the description is complete. It explains what it does, the auth requirement, and implies the return value (remaining balance). The absence of an output schema is mitigated by the explicit statement of what is checked.

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

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

The input schema already provides a 100% coverage description for the 'code' parameter ('Gift card code (full string as printed on the card).'). The tool description adds marginal value by mentioning 'using its code,' but this largely restates the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's function: 'Check a gift card's remaining balance using its code.' It uses a specific verb+resource (check balance, gift card, code) and distinguishes itself from sibling tools like get_cart or list_products, none of which deal with gift cards.

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 a public endpoint and no bearer token is required, gated on knowledge of the code. It does not explicitly mention alternatives or when-not to use it, but given the absence of related sibling tools, this is a minor gap and context is sufficient for an agent to select it appropriately.

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