mcp-server-il-benefits

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

With no annotations, the description carries the full burden and does well: it discloses that it makes a single live request to connected benefit sources, that results are ranked with the user's own providers first, and that it is read-only in effect ('Never buys anything'). It omits auth/permission requirements and any freshness or rate-limit caveats, keeping it out of 5 territory.

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

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

Three sentences, each earning its place: trigger first, then behavior/return shape, then the agent-facing obligations (show links, attribute sources, tell the user to confirm at checkout). Front-loaded and free of 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?

There is no output schema, so the description must describe returns — and it does: ranked options, how to use each, and a link, plus attribution expectations. Missing only edge-case handling (unknown store, no matching offers) and the effect of the optional amount/channel/country parameters.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds only one genuine semantic beyond the schema — that the store name may be supplied in Hebrew or English — which is helpful but marginal against four well-documented 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?

States a precise verb+resource: it returns ranked payment options (card, club, cashback portal, discounted gift card) for a given store. The subject matter is clearly distinct from the wallet and source-listing siblings, and an agent can tell what a call produces before opening 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?

Gives an explicit trigger condition — the user is in or heading to a store and asks which payment method to use. It also implies a boundary with 'Never buys anything'. However, it never names an alternative (e.g. wallet_get) or states when NOT to call it, so the routing guidance 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?

With no annotations, the description carries the full behavioral burden. It discloses the shape of the result (databases, terms page, coverage), which is useful since there is no output schema, but says nothing about permissions, read-only nature, or rate limits. Adequate but incomplete for an annotation-free 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, with the content description front-loaded and the usage cue second. 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, annotation-free read tool with no output schema, the description covers both what is returned and when to reach for it. Only minor gaps remain, e.g. freshness or any auth requirement for reading source metadata.

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

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

The tool takes zero parameters, so the schema imposes nothing to explain. Baseline of 4 applies; the description adds no parameter detail because none 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?

States a specific verb ("Show") and resource (the benefit databases this server queries), plus what each entry contains (terms page, coverage). It is clearly distinct from the wallet/best_way_to_pay siblings, though it never explicitly contrasts itself with them.

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

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

Gives an explicit trigger: "Use to explain where an answer came from or why a store has no result." That is a concrete when-to-use condition. It does not name when-not to use it or point to an alternative tool, 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?

With no annotations, the description carries the full burden and does disclose meaningful behavior: the wallet is a local file that 'never leaves the machine,' which tells the agent this is a private, non-network read. It stops short of stating read-only guarantees, pagination, or error behavior, but the privacy disclosure is substantive.

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 what the tool returns and followed by a useful privacy note. Every sentence earns its place with no 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 read tool with no output schema and no annotations, the definition identifies content (portals, clubs, sellers) and privacy posture, which is enough to call it correctly. It could add a hint about the return shape (e.g., list of names) but is otherwise 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?

The tool takes zero parameters, so there is nothing to disambiguate; baseline for a no-parameter tool is 4. The description correctly implies no input is required.

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 clear verb (Show/get) and resource (the saved wallet), and goes further by enumerating what it contains: cashback portals, clubs, and sellers. This distinguishes it from wallet_set and from list_sources, though it never explicitly names those siblings as alternatives.

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 only implied by 'the user said they use' — the description suggests this reads saved preferences but gives no explicit when-to-use or when-not guidance relative to list_sources or best_way_to_pay. An agent can infer the context but gets no routing rules.

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 burden and does disclose important traits: this is a full replacement of the saved wallet (implicitly destructive), only names should be stored, and card numbers/balances/personal details must never be asked for or stored. It omits auth requirements, error behavior, and what an empty array does, which keeps it below 5.

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

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

Three tight sentences with no filler, front-loaded with the replace action and immediately followed by the purpose and the safety boundary. Every sentence earns its place.

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

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

For a single-parameter setter with no output schema and no annotations, the description covers what is stored, the replacement semantics, and the privacy constraints. The remaining gap is return/confirmation behavior and the empty-array edge case, which are minor.

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. It clarifies that the array elements are provider names in the exact form shown in results and gives examples (cashback portal, gift card seller), which is meaningful. However it does not mention the 100-item cap, 80-char limit, or whether an empty array clears the wallet.

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 (replace) and resource (the saved wallet) plus exactly what is stored: provider names as they appear in results, with concrete examples. The 'replace' framing distinguishes it from the read-only wallet_get sibling without needing to open either 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?

'Used to rank the user's own providers first' gives clear context for why and when the tool is invoked, which is more than a bare 'set'. It stops short of naming alternatives or stating exclusions (e.g., use wallet_get to read, or what happens on an empty list).

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