Shelem Scorekeeping MCP Server

Overview Schema Source Related Servers Discussions Admin

Calculate Shelem score

calculate_shelem_score

Read-onlyIdempotent

Score a completed Shelem hand from the bid and captured points, applying contract and threshold rules to return both teams' updated totals.

Instructions

Score one completed Shelem hand and return both teams' new totals.

Pass the cumulative scores from before the hand, the declaring team, the bid, and how many points were captured (defending_points, declarer_points, or outcome "mak"/"sweep"). The engine applies the doubled sweep award, failed and heavily failed bids, Shelem/sar-shelem (+330/-330/-660), the 1000-point rule for a defending team, and the 1165 winning threshold. All arithmetic is integer and deterministic.

Invalid or contradictory input returns an error and no score.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "team1_score": "<team1_score>",
      "team2_score": "<team2_score>",
      "bid": "<bid>"
    },
    "name": "calculate_shelem_score"
  }
}

Input Schema

Name	Required	Description
`bid`	Yes	The winning bid: 100, 105, ..., 165. Expand spoken abbreviations first ("20" is 120).
`outcome`	No	"mak": the declarer captured exactly the bid. "sweep": the defenders captured nothing. Use instead of, or consistently with, the point fields.
`contract`	No	Omit below 165. Required when bid is 165: "shelem", "sare-shelem" or "normal" (scored differently on failure).
`hakem_team`	No	Team of the Hakem (the declarer): 1 or 2.
`team1_score`	Yes	Team 1 cumulative score before this hand. May be negative.
`team2_score`	Yes	Team 2 cumulative score before this hand. May be negative.
`bidding_team`	No	Team that won the bidding: 1 or 2. Must equal hakem_team when both are given. At least one of the two is required.
`bid_successful`	No	Optional cross-check. The captured points decide success; if this flag disagrees the hand is rejected. Mak is successful.
`declarer_points`	No	Points captured by the declaring team: 0-165, multiple of 5. Must sum to 165 with defending_points when both are given.
`defending_points`	No	Points captured by the defending team: 0-165, multiple of 5.

Output Schema

Name	Required	Description
`hand`	Yes
`winner`	Yes	1 or 2 when the game is finished, otherwise null.
`explanation`	Yes	Plain-English account of how the hand was scored.
`game_finished`	Yes	True when exactly one team reached 1165 or more.
`score_changes`	Yes
`updated_team1_score`	Yes	Team 1 total after the hand.
`updated_team2_score`	Yes	Team 2 total after the hand.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Nov 6, 2026

TDQS

A4.3/5.0

Behavior4/5

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

Annotations already declare that this is a read-only, idempotent, closed-world, non-destructive operation, so the description need not restate safety. It adds genuinely useful behavior beyond annotations: integer deterministic arithmetic, the specific scoring rules applied, and that invalid or contradictory input yields an error with no score.

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

Conciseness5/5

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

The description is short, front-loaded, and every sentence carries useful information: purpose, required inputs, scoring rules, determinism, and error behavior. There is no redundant restatement of the name or schema.

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

Completeness5/5

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

For a 10-parameter domain-specific scoring calculator, the description covers the essential purpose, input categories, rule set, determinism, and error handling. With a full input schema, rich annotations, and an output schema, no critical agent-facing information appears to be missing.

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

Parameters3/5

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

Schema description coverage is 100%, and the schema already documents bid ranges, outcome values, contract requirements at 165, team identity constraints, point ranges, and summation rules. The description groups the important inputs and mentions captured points/outcome, but it does not add much parameter-level meaning beyond the schema, so the baseline 3 is appropriate.

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

Purpose5/5

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: "Score one completed Shelem hand and return both teams' new totals." That is precise enough for an agent to know exactly what the tool computes, and there are no sibling tools to distinguish it from.

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

Usage Guidelines4/5

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

It clearly establishes the input context: cumulative scores from before the hand, the declaring team, the bid, and captured points or outcome. It also states that invalid or contradictory input returns an error, but it does not discuss when-not-to-use cases or alternatives, which is less important here because no siblings exist.

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

Deploy Server

Other Tools

calculate_shelem_scoreA