Yahad

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description usefully adds the returned information (signer count, open and close times), but says nothing about behavior for an invalid or expired invite, or about permissions.

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 outcome and then the input requirement. No filler, though the second sentence is somewhat redundant with the schema.

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

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

A single-parameter read tool with no output schema, and the description covers both what is returned and what is required to call it. Edge-case behavior for bad invites is the only notable omission.

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

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

Schema coverage is 100%, and the schema documents the invite parameter as a link or token. The description restates that it takes the participants' invite link, adding no format or validation detail beyond the schema, so the 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 and resource: shows collection progress for a card, with the concrete data points (signatures, opening and closing times). This is clearly a read operation distinct from the sibling write tool create_board, though it does not name those 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 conveys when this is useful (checking how a collection is going) and the required input, but offers no explicit when-not guidance or reference to alternatives such as list_occasions.

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, it discloses real side effects: management links are emailed to the organiser, a one-time 'take control' link is returned, and a participant-facing link is produced. It doesn't say that repeat calls create duplicate cards (relevant given idempotentHint=false), which is the main remaining 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?

Front-loaded with the action and outcome, then preconditions, then locale rules — every sentence carries information. The final locale sentence is slightly telegraphic ("names are Russian") but still 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 an 8-parameter, non-idempotent creation tool with no output schema, the description covers what it makes, what it returns, and the critical email dependency, while the schema carries the field-level detail. Only duplicate-creation behavior is left unstated.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds genuine value on top by flagging organizerEmail as the one value that must never be fabricated and by explaining the Russian/Hebrew naming convention that governs recipientName.

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 ("Creates a group greeting card") plus the defining mechanic (multiple signers, opens on a set date) and the return value (link to send to participants). This is unmistakably distinct from board_status, list_occasions and suggest_prompts.

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

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

Gives concrete preconditions and a hard rule: the organiser's email is required, "Ask the person for anything missing; never invent an email," plus locale conventions per brand domain. It stops short of naming sibling tools (list_occasions, suggest_prompts) as the place to source occasion/prompt values, leaving that routing to the schema.

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

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

Annotations already establish this as a safe, idempotent, non-destructive read. The description adds useful computation details: rounding down, organizer covering the remainder, currency, and mutual exclusivity of the two amount inputs.

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, presenting the main split behavior first and the alternative mode second. Every sentence carries useful information with no redundant restatement.

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

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

With no output schema, the description still explains what each mode returns: either the per-person contribution after rounding or the total budget. That is sufficient for a low-complexity calculation tool whose annotations cover safety.

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

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

Schema coverage is 100%, so the schema already documents the three parameters. The description adds the important exactly-one constraint between giftCost and perPerson and clarifies how payers affects the division, going beyond the schema text.

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

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

The description states the resource and both operations precisely: splitting a group gift per payer with rounding, or deriving total budget from a per-person amount. An agent can identify the calculation without inspecting the schema.

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

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

It clearly says to pass exactly one of giftCost or perPerson, which resolves the main invocation ambiguity. It does not name alternatives, but the sibling tools are unrelated, so there is no meaningful routing choice to explain.

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, non-destructive and closed-world, so safety behavior needs no restating. The description does add one piece of extra information the annotations cannot convey: the result is meant to feed create_board's argument. It says nothing about result ordering, caching, or whether the list is exhaustive beyond the single scoping phrase.

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 sentence with no filler. The resource is front-loaded and the consumer linkage to create_board follows immediately.

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, no-output-schema lookup, the description covers what the tool returns (occasion values) and why those values matter. It could be more complete by naming a result field or stating that the list is static, but the essentials an agent needs are present.

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

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

The tool takes no parameters, so schema coverage is a non-issue and the baseline 4 applies. The description does not need to explain any inputs and does not confuse the reader with any.

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 ("Lists the occasions this group-card service supports") and explicitly ties the output to create_board. An agent can distinguish it from board_status, create_board, and suggest_prompts without opening any schema.

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

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

The clause "with the value to pass to create_board" makes the intended usage clear: fetch this before calling create_board. It stops short of naming an explicit when-not or alternative path, but for a zero-parameter lookup the context is 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?

Annotations already declare this a safe, idempotent read, so the bar is lower; the description still adds genuinely new information — results are computed live from the calendar rule and never stale, two occurrences are returned, and fasts/memorial days carry a 'greetings not customary' note. It stops short of describing pagination or the exact response shape, but adds real behavioral context beyond the structured fields.

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

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

Two short sentences, no filler, with the primary behavior (next two dates, computed never stale) front-loaded and the fasts/memorial caveat placed last as a secondary note. Every clause carries information.

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

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

For a single-parameter read tool with no output schema, the description covers what is returned, how it is computed, and one important domain caveat. The only meaningful omission is how an agent should discover or validate occasion ids, which the sibling `list_occasions` presumably handles.

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 already documents the `occasion` parameter with example ids, so the baseline applies. The mention of Russian vs Hebrew services gives a useful hint about the two families of accepted ids, but no additional syntax or format detail is provided in the description.

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

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

The description names a specific resource (a professional day or Jewish holiday) and a specific output (the next date and the one after), plus the guarantee that it is computed from the calendar rule rather than stored. This implicitly separates it from a static list tool, but it never names or contrasts with `list_occasions`, so sibling differentiation is only inferred.

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 statement of when to call this versus `list_occasions` or `board_status`, and no guidance on where to obtain a valid `occasion` id — a real gap given the parameter accepts ids like 'avtomobilista'. Usage is only implied by the return-value description.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that the output is 'ready questions' that can be shown to participants and that recipientName fills the name into questions, but it does not describe things like quantity, source, or any limits. With annotations doing the heavy lifting, this is adequate but not rich.

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

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

The description is two short sentences with no wasted words, and the primary purpose is front-loaded. The optional personalization detail follows naturally.

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

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

For a simple, read-only, two-parameter tool with full schema coverage and rich annotations, the description is nearly complete. It states what is returned and how the optional parameter affects the output. A little more context on output shape or limits could still help, but no output schema exists and the core behavior is 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 100%, so both parameters are already documented in the schema. The description adds a small amount of context about recipientName filling the name in, but it largely restates what the schema already says. Baseline 3 is appropriate when the schema does the 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 a specific verb and resource: suggesting ready questions for an occasion, aimed at an organiser showing them to participants. It is clear what the tool does, though it does not explicitly distinguish itself from sibling tools such as list_occasions or create_board.

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

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

Usage is implied by 'the organiser can show participants' and 'for an occasion', but there is no explicit guidance on when to use this tool versus alternatives. It does not mention using list_occasions first to obtain a valid occasion value, even though the schema references that relationship.

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