Server Quality Checklist

Tool Scores

• get_rosters_preloadA
  4/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden and provides substantial behavioral context: it states that the API call is single-call covering multiple areas, returns 'raw API data', and explicitly notes that the days list is 'not sparse' (all days included). It also details the structure of each response section. However, it does not mention permissions, error handling, or side effects, which would have made it more complete.

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

  Conciseness4/5

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

  The description is long but exceptionally structured: the first sentence states purpose, and the rest is a well-organized code block with comments explaining each top-level key and nested fields. Every section earns its place given the absence of an output schema. It could be slightly trimmed, but the density of useful information justifies the length.

  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?

  Given the lack of an output schema, the description thoroughly documents the return value with nested structures, making the tool's behavior fully understandable. It covers all major response areas (calendar, swap offers, vacant duties, absences). Error handling and pagination are not discussed, but for a single-call preload with a clearly defined output, the description is sufficiently complete for an agent to select and invoke the tool.

  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?

  The input schema already provides descriptions for both parameters (year and month) with 100% coverage. The description adds no additional meaning beyond confirming the tool targets 'one month', which aligns with year/month but does not enrich the parameter semantics. Baseline 3 applies because schema coverage is high.

  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 clearly states what the tool does: 'Returns the personal roster preload for one month' and lists the specific areas it covers (Einsatzwünsche, Vakante Dienste, Diensttausch). This is a specific verb+resource+scope that distinguishes it from siblings like get_planungsgruppen or get_vakante_duty_details, which are narrower in focus.

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

  Usage Guidelines3/5

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

  The description implies it is a single combined call for a month's personal roster, but does not explicitly state when to prefer it over alternatives or when not to use it. Sibling names suggest other tools for specific details, but no direct guidance is given. Usage context is implied rather than explicitly stated.

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

• get_abteilungsdienstplanA
  4.4/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the burden and does well by stating 'Returns raw API data' and showing the complete response structure, including the sparse nature of assigned days. It adds meaningful behavioral context, though it does not mention auth requirements or rate limits.

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

  Conciseness4/5

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

  The description is front-loaded with the purpose, followed by a detailed JSON example that illustrates the return format. While the JSON block is long, it is directly useful given no output schema, and the structure is clean with each sentence earning its place.

  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?

  Since there is no output schema, the description compensates by providing a complete JSON response layout and explaining the data's granularity. It also covers the prerequisite planningGroupId lookup and the temporal scope. This is sufficient for an agent to invoke the tool correctly, despite not covering error scenarios.

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

  Parameters4/5

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

  Schema coverage is 100%, so all parameters already have descriptions. The description adds value beyond the schema by giving a concrete example for planningGroupId ('e.g. 948 for RW 44 Haßloch') and instructing to use get_planungsgruppen to find it, which enriches the schema's bare definition.

  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 clearly states the verb 'Returns' and the specific resource 'full team duty roster' scoped to one planning group and month. It also differentiates from siblings by noting it contains every employee's duty codes per day and references get_planungsgruppen for finding the planningGroupId.

  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?

  The description explicitly instructs 'Use get_planungsgruppen first to find the planningGroupId', providing a clear prerequisite and naming an alternative tool. However, it does not explicitly contrast with other sibling tools like get_vakante_duty_details or get_rosters_preload, so it lacks a full when-not explanation.

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

• get_planungsgruppenA
  4.5/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses that results are scoped to the logged-in employee, provides the return structure (Array of { name, id }), and warns that example IDs may vary per installation. These are useful behavioral details beyond a generic 'get' operation, though it does not mention edge cases like empty results or errors.

  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 concise and well-structured: a single-purpose statement, a return type line, and a helpful example section. Every sentence contributes value, and the formatting makes it easy to scan. There is no unnecessary filler or repetition.

  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 simple list-returning tool with two well-documented parameters, the description includes all essential elements: purpose, usage context, return format, and example IDs. It also benefits from sibling tool context, making it sufficiently complete for an agent to select and invoke correctly.

  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?

  The schema already provides complete descriptions for both parameters (year and month) with ranges and examples, achieving 100% coverage. The description's phrase 'given month' only lightly echoes the schema without adding new semantic meaning. The baseline of 3 is appropriate because no additional parameter context is needed.

  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 clearly states the verb ('Returns'), the resource ('all planning groups'), and the scope ('visible to the logged-in employee for the given month'). It also distinguishes itself from siblings by explicitly stating it should be used before get_abteilungsdienstplan, making its purpose unmistakable.

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

  Usage Guidelines5/5

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

  The description explicitly says 'Use this to discover available group IDs before calling get_abteilungsdienstplan,' providing direct guidance on when to use the tool and its relationship to a sibling. This is a clear, actionable usage instruction that goes beyond merely describing the tool.

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

• get_vakante_duty_detailsA
  4.5/5.0
  Behavior4/5

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

  With no annotations, the description must carry the behavioral transparency burden. It clearly indicates this is a read operation ('Returns'), documents the return shape, and adds context like UTC times and duration format. It does not mention failure modes or side effects, but for a simple read with a well-defined output, this is strong.

  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 efficiently structured: a one-sentence purpose, a concise usage pointer, and a compact return schema with inline comments. No filler or redundancy; every line contributes to understanding the tool.

  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 simple one-parameter read tool with no output schema, the description is complete: it states what it does, where to get the parameter, and precisely what the response contains. It provides enough detail for an agent to select and invoke the tool successfully, and even to interpret the response fields.

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

  Parameters4/5

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

  The schema already covers the parameter with a description (100% coverage). The tool description adds significant value by pinpointing the exact source (get_rosters_preload → vacantDutiesOccupied.data.duties[].idVacantDuty), which is more actionable than the schema's generic mention of 'vacantDutiesOccupied or vacantDutiesAssumed'.

  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+resource: 'Returns full shift details for a single vacant duty entry.' This clearly distinguishes it from siblings like get_rosters_preload (which preloads a list) and get_abteilungsdienstplan (a department plan). The scope ('single vacant duty') is explicit.

  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?

  The description explicitly instructs the agent to obtain idVacantDuty from get_rosters_preload and provides the exact response path. This gives a clear 'when to use' (after preloading). However, it does not explicitly mention when not to use or name alternative tools for different scenarios, so it falls 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.