dearhuman

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

No annotations are provided, so the description carries the full burden. The verb 'List' makes the read-only, non-destructive behavior clear, and all allowed filter values are disclosed. However, it does not describe the return format or any pagination behavior, which would further enhance transparency.

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

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

The description is a single, front-loaded sentence with no wasted words. Every element adds value: the action, the resource, and the explicit filter values.

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 one optional parameter and no output schema, the description adequately conveys the action and filter values. It could further specify the default behavior when no occasion is provided (implied but not stated) or whether the result is sorted, but these are minor gaps for this simplicity level.

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 parameter 'occasion'. It fully compensates by enumerating all acceptable values in parentheses, providing meaning that the bare string schema (with default '') lacks. This is a strong addition.

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' with the clear resource 'card templates' and an optional filter by occasion. It distinguishes itself from sibling tools like get_offers and get_phrases, and the parenthetical list of occasions adds specificity.

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

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

The description clearly indicates when to use the tool (to list templates) and provides the valid occasion filter values, which gives practical usage context. It does not explicitly mention alternatives or exclusion cases, but sibling tools are clearly different in 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?

With no annotations, the description carries the full burden. It discloses a meaningful privacy behavior ('their data never leaves you') and implies a read-only list operation, but it does not mention other aspects like authentication, rate limits, or side effects. For a simple list tool, this is adequate but not exhaustive; the description adds some context beyond the obvious.

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: the first states the action, the second provides actionable guidance and a privacy note. Every part earns its place with 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 parameterless tool with no output schema, the description adequately explains what the tool does and how to apply the results. It could explicitly mention that it returns a list of offers, but that is implied by 'List the gift-offer shelf.' The guidance on selection and privacy adds useful 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?

There are zero parameters, so the description cannot add parameter semantics. The baseline of 4 is appropriate because the schema already covers everything (trivially, since there are no inputs), and the description need not explain anything about inputs.

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 'the gift-offer shelf', using a specific verb (list) and resource (gift offers), which distinguishes it from sibling tools like card templates or phrases. The additional instruction about selecting an offer reinforces its role in the gift-giving workflow, making the purpose unmistakable.

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

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

It provides clear guidance on how to use the output (e.g., 'Pick the one offer... match on what you already know about them'), which tells the agent what to do with the results. It doesn't explicitly state when to use this tool versus alternatives, but the distinct resource type (offers) implicitly differentiates it from siblings. The privacy note also adds context on how to approach selection.

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

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

With no annotations provided, the description carries the full transparency burden. It discloses that this is a list operation, explains the three register modes including the self_only ownership caveat, and clarifies the selection-based composition model. It does not detail return shape or pagination, but for a simple list tool this is a minor gap.

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

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

The description is concise and well-structured: three short sentences cover purpose, parameter semantics, and usage rule. It is front-loaded with the primary action and contains 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 read-only list tool with two optional parameters and no output schema, the description covers all essential aspects: what is listed, filters, register meanings, and how results are consumed. It could be more explicit about the returned fields, but the comment about picking phrase IDs makes the output shape sufficiently 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?

Schema description coverage is 0%, so the description is the only source of parameter meaning. It fully defines 'register' with its default and all values ('plain', 'lore', 'all'), explains 'occasion' as an optional filter, and ties the output to phrase IDs for card composition. This completely compensates for 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 opens with a specific verb+resource: 'List the selectable phrase library (and sign-offs)', and mentions optional occasion filtering. This clearly distinguishes it from sibling tools like get_card_templates, get_offers, and get_todays_holidays by naming the phrase library as its unique 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 description provides practical usage context: the register explanation recommends 'plain' for most recipients, and the final sentence clarifies that cards are composed by selecting phrase IDs rather than writing text. This signals when to use the tool in the workflow, though it does not explicitly name alternatives 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?

Since no annotations are provided, the description carries the transparency burden. It communicates a lighthearted read-only lookup and a selection rule, but it does not say whether the result is one holiday or many, what format the result takes, or how 'today' is resolved.

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, each earning its place: the first states the resource, the second gives the selection behavior. It is concise, front-loaded, and free of repetitive 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?

Given that the tool has zero parameters and trivial input complexity, the description is almost complete for selection and invocation. It would be more complete if it explicitly stated the output shape or that it can return multiple holidays, but the light context still gives enough for a simple lookup.

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 is empty, so there are no parameters for the description to clarify. This is the zero-parameter baseline case; the description does not need to add parameter-level detail.

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 ('today's micro-holiday') and makes the purpose understandable, especially combined with the tool name. It is clearly distinct from sibling tools like get_card_templates, preview_card, and send_card, though it does not use an explicit verb like 'retrieve'.

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 an implied use case: finding a whimsical holiday the human would enjoy, and the second sentence gives a clear 'choose one' instruction. However, it does not explicitly explain when to prefer this over the other sibling tools or when not to use it.

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

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

With no annotations, the description carries the burden. It clearly discloses that this is non-destructive ('without creating anything') and echoes text back, which is important behavioral context. However, it doesn't specify error behavior or output structure, which would be more thorough.

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

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

Two sentences, no fluff, directly states purpose and behavior. Highly concise.

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 basic purpose and non-destructive nature, but lacks details on output format, error handling, and parameter specifics. Given 6 parameters and no output schema, it could be more complete.

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

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

Schema description coverage is 0%, and the description doesn't explain any parameters beyond 'every ID'. It doesn't add meaning to template_id, phrase_ids, offer_id, holiday_id, or occasion. The description must compensate for the lack of schema annotations but does not.

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

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

The description clearly states the tool's purpose: it performs a dry-run of a card composition, validates IDs, and echoes back assembled text. The verb 'validates' and resource 'card composition' distinguish it from send_card, which likely creates/sends.

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 (before sending, to validate IDs) but doesn't explicitly state when to use this versus alternatives like send_card or get_card_templates. It gives context but no exclusions or explicit when-not-to-use.

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

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

No annotations exist, so the description carries full burden. It discloses: free tier with hard cap, v0 returns a URL for delivery, relationship semantics with rejection of self_only phrases, and a critical behavioral rule for fact_confirmed (never confirm unverified facts). This goes beyond a simple action and provides essential behavioral context for safe/effective use.

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 main action is in the first sentence, then critical constraints and special cases are presented. Every sentence adds value: free tier, output format, relationship mode, fact_confirmed rule. No fluff, just essential operational knowledge.

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 complex tool with 10 parameters and no output schema or annotations, the description covers the most critical aspects: tool source, pricing, output, and special behavioral flags. It does not explain all parameters in depth, but it explicitly points to the catalog tools, which is logical. The missing piece is any detail on output besides 'returns a card URL', but that is sufficient for usage. The description is quite complete given the 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?

Schema coverage is 0%, so description must compensate. It explains that all IDs come from catalog tools (implying they are IDs from get_templates/get_offers et al.) and clarifies semantics for relationship and fact_confirmed. However, it does not detail every parameter (e.g., holiday_id, occasion, signoff_id) – it relies on the schema for that. Given low coverage, it provides meaningful additions but not exhaustive explanation, which is acceptable given the 'catalog' mention.

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

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

Description clearly states 'Send a Dear Human card' with specific verb and resource. It distinguishes from siblings by noting 'All IDs must come from the catalog tools' and explicitly mentions relationship modes and fact_confirmed semantics, which are unique to this tool. 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?

Provides explicit when-to-use guidance: 'All IDs must come from the catalog tools' tells the agent to use sibling tools first. It also specifies constraints ('First 5 cards per sender are free (tier 0, hard cap)') and conditional usage ('relationship... on-behalf... self_only phrases are rejected; use the plain register'). This is strong contextual guidance for tool selection.

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