tools

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

Annotations already declare `readOnlyHint: true`, `idempotentHint: true`, so the tool is safe and deterministic. The description adds value by explicitly stating 'deterministic calculation—no AI estimation,' which reinforces the behavior beyond annotations. No contradictions with annotations are present.

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 efficiently structured with two focused sentences plus a URL reference. It front-loads the core purpose and context. The URL to an interactive version may add slight bloat but is justified as an external reference. Every sentence contributes meaningful 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?

The tool has moderate complexity (4 parameters, 1 enum, output schema present). The description explains the core calculation purpose and deterministic nature well. With an output schema present, return value explanation is not needed. However, it lacks explicit explanation of how `samstag_frei` or `urlaubstage_budget` affect results, slightly reducing completeness.

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 4 parameters with descriptions. The description provides no additional information about parameters beyond what the schema includes. According to guidelines, since coverage is high (>80%), a baseline of 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 states a specific verb and resource (calculate the most efficient bridge days for a year) while distinguishing itself from siblings. It explicitly mentions the German federal state context (Bundesland) and the deterministic calculation based on public holidays, which differentiates it from tools like `compare_bridge_day_years` or `calculate_net_working_time`.

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 defines the context: calculate bridge days for years 2026-2030 and a German federal state. It implies when to use (for optimizing vacation days to maximize consecutive free blocks). However, it does not explicitly state when not to use this tool or provide direct alternatives among siblings, which would elevate the score to 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?

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds context about the regulatory basis and output breakdown, but does not disclose additional behavioral details such as error handling, authentication needs, or effects of extreme inputs. It does not contradict annotations.

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, information-dense sentence that packs the verb, input, legal reference, and output detail efficiently. It is front-loaded with the key action ('Berechnet den PeBeM-VZÄ-Höchstwert') and contains no superfluous words.

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 the five parameters are fully documented in the schema and an output schema exists (so return details are not needed), the description covers the calculation purpose, input, legal basis, and output structure well. It could mention prerequisite assumptions (e.g., that inputs represent current residents), but is largely 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 100% with each parameter described as 'Bewohner mit Pflegegrad X'. The description broadly confirms inputs are the resident structure but adds no new semantic detail beyond what the schema already provides, so 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 it calculates the PeBeM-VZÄ-Höchstwert from resident counts by Pflegegrad 1–5, referencing the legal mandate § 113c SGB XI. It distinguishes from siblings by naming a specific regulatory metric and output breakdown by qualification levels.

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 context (when you have resident counts and need the PeBeM staffing value), but does not explicitly state when to use or not use this tool versus siblings like calculate_shift_staffing or compare_bridge_day_years. No exclusions or alternatives are mentioned.

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 description discloses that the tool is a calculation (read operation) and can optionally compute a team sum, which adds context beyond the idempotentHint and readOnlyHint annotations. However, it does not explain what assumptions the calculation makes (e.g., base working days per year, treatment of weekends) or whether it handles regional variations. With annotations already signaling a safe, idempotent read, the description provides adequate but not rich behavioral detail.

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 long and front-loads the core purpose. The first sentence covers the function and outputs efficiently. The second sentence provides a reference URL, which is not strictly necessary but adds a helpful external resource. Almost no wasted words.

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?

The description covers inputs (deductions) and outputs (days, hours, ratio, team total). It does not explicitly state the assumed gross working days base (e.g., 260 days or 52 weeks), which could be important for understanding the calculation. However, the presence of an output schema likely documents return values, reducing the need for that detail. Overall, it is nearly complete for a straightforward calculation tool.

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 each parameter is already documented. The description adds value by explaining that the 'vollzeitkraefte' parameter enables an 'optional team total' output, which is not explicitly stated in the schema property description ('Anzahl Vollzeitkräfte im Team'). This gives the agent a clearer understanding of how parameters combine to produce output.

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 calculates net working time of a full-time employee per year, specifying the inputs (gross working days minus vacation, illness, training, holidays) and outputs (days, hours, ratio, optional team total). This distinguishes it from sibling tools like calculate_bridge_days or calculate_shift_staffing, which handle different staffing/time calculations.

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 no explicit guidance on when to use this tool versus alternatives. It does not mention prerequisites, conditions, or scenarios where another sibling tool would be more appropriate. The differentiation is only implicit through the tool's distinct 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?

Annotations already indicate readOnlyHint=true and idempotentHint=true, so the description adds moderate value by stating 'reine Arithmetik nach offengelegter Formel,' confirming deterministic behavior. However, it does not disclose return format, error handling, or any additional behavioral traits beyond what annotations cover.

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 at two sentences, front-loading the core purpose. The link to an interactive version is extraneous for an AI agent but does not detract. No wasted words, though the structure could be slightly improved by separating the arithmetic note from the link.

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 the tool's complexity (10 parameters, output schema exists), the description covers the high-level purpose: calculating FTE from shift occupancy and downtimes with a buffer. It mentions the output concept (VZÄ) and the arithmetic nature. The output schema handles return values, so the description is sufficiently complete for a simple calculation tool.

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 summarizes inputs as 'Schichtbesetzung pro Tag und Ausfallzeiten' but does not add semantic detail beyond the schema's parameter descriptions. No new meaning is provided for parameters like 'puffer_prozent' or 'betriebstage_pro_woche'.

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 calculates personnel requirement (FTE) for shift operations using shift occupancy and downtime inputs. It specifies the verb 'Berechnet' and the resource 'Personalbedarf eines Schichtbetriebs', which is distinct from sibling tools like 'calculate_care_staffing_pebem' that focus on care staffing with a different method, though it does not explicitly differentiate.

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 no guidance on when to use this tool versus alternatives like 'calculate_care_staffing_pebem' or other sibling tools. It mentions 'reine Arithmetik' and a link to an interactive version, but does not specify context, prerequisites, or exclusions for 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?

Annotations already declare readOnlyHint=true and idempotentHint=true, indicating safe, non-mutating behavior. The description adds transparency by stating the formula is 'disclosed' and 'purely rule-based', which builds trust. It does not contradict annotations. Slight deduction because it doesn't detail what 'disclosed' means or mention any side effects, but annotations cover the core safety profile.

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 efficiently communicates the core purpose, scope, and nature (disclosed formula, rule-based). Every phrase serves a purpose; no redundancy or unnecessary detail. The description is front-loaded with the action and resource.

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 an output schema exists (covering return values), the description covers all essentials: what it does, the year range, the metric (score), and the methodology (disclosed rule-based formula). For a comparative analysis tool, this is complete – no missing context that would hinder correct invocation.

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 clear descriptions for both parameters: 'bundesland' has an enum of state codes, 'samstag_frei' has a default and meaning. The description adds value by specifying the year range (2026–2030) which is not in the schema, providing essential context beyond the parameters themselves.

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 compares years 2026–2030 for a federal state to identify the best year for bridge days, using a disclosed rule-based formula. It specifies the action ('compare') and the resource ('Bundesland'), and while it doesn't explicitly contrast with siblings like 'calculate_bridge_days', the unique scope (multi-year comparison) is evident.

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 explains the tool's purpose (comparing years for bridge days) but provides no guidance on when to use it versus the sibling 'calculate_bridge_days' or other tools. It implicitly suggests use for multi-year comparisons, but lacks explicit context or alternatives, leaving the agent to infer usage boundaries.

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=true, idempotentHint=true, and openWorldHint=false. The description adds context beyond these: it reveals the tool returns a product profile, links, and a pointer to the full MCP. No behavioral contradictions. The description enriches understanding of what the read-only operation yields.

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 in German, front-loaded with the purpose ('Kurzprofil von vigotime') and immediately followed by product context and what the tool provides. Every sentence is meaningful with zero redundancy. Very 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?

Given zero parameters and an existing output schema (from context signals), the description fully covers what the agent needs: it explains the tool's purpose, the content of the profile, and the path to the full MCP. No gaps remain for a read-only informational tool.

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 no parameters, so baseline is 4. The description does not need to add parameter details. It correctly focuses on the output and usage context.

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 provides a 'Kurzprofil' (short profile) of the vigotime product, including product overview, key links, and the path to the full product MCP. This is a specific verb-resource combination that distinguishes it from sibling tools, which are all calculation-oriented (e.g., calculate_bridge_days). No tautology or 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 description explains what the tool delivers but does not explicitly state when to use it versus alternatives. While sibling tool names (all 'calculate_*') strongly imply they are for calculations and this tool for product info, the description lacks explicit guidance like 'Use this for product overview; use sibling tools for shift calculations.' No exclusions or when-not logic is provided.

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