Server Quality Checklist

Tool Scores

• timecard_get_summaryC
  2.9/5.0
  Behavior2/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 states this is a 'Get' operation, implying read-only access, but doesn't clarify if it requires authentication, has rate limits, returns aggregated data, or what 'summary statistics' entails (e.g., totals, averages). This leaves significant gaps for a tool that likely interacts with sensitive timecard data.

  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 a single, clear sentence with zero wasted words. It front-loads the key action and resource, making it easy to parse quickly. Every part of the sentence earns its place by conveying essential information without redundancy.

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

  Completeness2/5

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

  Given the lack of annotations and output schema, the description is incomplete. It doesn't explain what 'summary statistics' includes (e.g., numeric totals, breakdowns), how the 'current timesheet week' is defined relative to the date parameter, or behavioral aspects like error handling. For a tool with one parameter but potentially complex output, this leaves too much unspecified.

  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 description coverage is 100%, with the 'date' parameter fully documented in the schema as a required string in YYYY-MM-DD format. The description adds no additional meaning beyond implying the date determines the 'current timesheet week', which is minimal value. This meets the baseline for high schema coverage.

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

  Purpose4/5

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

  The description clearly states the action ('Get summary statistics') and the resource ('for the current timesheet week'), making the purpose immediately understandable. However, it doesn't explicitly differentiate this tool from its siblings like 'timecard_get_timesheet' or 'timecard_get_activities', which might also retrieve timecard-related data but with different scopes or formats.

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

  Usage Guidelines2/5

  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. It doesn't mention prerequisites, context for 'current timesheet week', or compare it to sibling tools like 'timecard_get_timesheet' for detailed data or 'timecard_save' for updates, leaving the agent to infer usage scenarios.

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

• timecard_get_activitiesB
  3.2/5.0
  Behavior3/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 states the tool returns a list with specific fields (id, name, value) and explains the 'value' field format, which adds useful context beyond a basic read operation. However, it doesn't cover other behavioral aspects like error handling, authentication needs, rate limits, or whether it's read-only (implied by 'Get' but not explicit). The value format detail is helpful but incomplete for full transparency.

  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 appropriately sized and front-loaded: the first sentence states the core purpose, and the second adds crucial context about the 'value' field. Both sentences earn their place by providing essential information without redundancy. However, it could be slightly more structured (e.g., bullet points for returns) and misses a brief usage hint, keeping it from a perfect score.

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

  Completeness3/5

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

  Given the tool's low complexity (1 parameter, no output schema, no annotations), the description is somewhat complete but has gaps. It explains the return fields and value format, which is helpful, but lacks output structure details (e.g., list format, pagination) and behavioral context. Without annotations or output schema, the description should do more to compensate, but it provides a minimal viable explanation, making it adequate but not thorough.

  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 has 100% description coverage, with 'project_id' clearly documented. The description adds no additional parameter semantics beyond what the schema provides—it doesn't explain what a 'project_id' is, how to obtain it, or any constraints. Since the schema does the heavy lifting, the baseline score of 3 is appropriate, as the description doesn't compensate but also doesn't detract.

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

  Purpose4/5

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

  The description clearly states the tool's purpose: 'Get list of activities for a specific project.' It specifies the verb ('Get'), resource ('activities'), and scope ('for a specific project'), making the intent unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'timecard_get_projects' or 'timecard_get_timesheet', which likely retrieve different data types, so it misses the highest mark.

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

  Usage Guidelines2/5

  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. It mentions that the 'value' field is needed by 'timecard_save', which hints at a dependency but doesn't clarify when to choose this over other get tools (e.g., 'timecard_get_projects' for projects vs. activities). There's no explicit when/when-not or alternative usage context, leaving the agent to infer based on tool names alone.

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

• timecard_get_projectsA
  4.1/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries full burden. It discloses the return format (project id and name) and hints at a read-only operation ('Get list'), but lacks details on behavioral traits like pagination, error conditions, authentication needs, or rate limits. For a read tool with zero annotation coverage, this is minimally adequate but leaves gaps.

  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 highly concise and well-structured: two sentences that front-load the core purpose and follow with specific usage guidance. Every sentence earns its place by providing essential information without redundancy or fluff.

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

  Completeness4/5

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

  Given the tool's simplicity (0 parameters, no output schema, no annotations), the description is reasonably complete. It explains what the tool does, what it returns, and how to use the output with siblings. However, it lacks details on output structure (e.g., list format) and behavioral aspects, which could be improved for full completeness.

  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 input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately adds no parameter details, focusing instead on usage context. This meets the baseline for tools with no parameters, as it doesn't need to compensate for schema gaps.

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

  Purpose4/5

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

  The description clearly states the tool's purpose: 'Get list of available projects' with specific outputs (project id and name). It distinguishes itself from siblings by focusing on project retrieval rather than activities, summaries, timesheets, or saving. However, it doesn't explicitly contrast with timecard_get_activities which also retrieves data, though for different resources.

  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 provides explicit guidance on when to use this tool: 'Use the project id with timecard_get_activities to get activity options, and with timecard_save to set entries.' It names specific sibling tools (timecard_get_activities and timecard_save) as alternatives for downstream actions, clearly establishing this as a prerequisite step in a workflow.

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

• timecard_get_timesheetA
  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 full burden and does so well by disclosing key behavioral traits: it's read-only with no side effects, retrieves saved data from the server, and describes the return structure including status values. It doesn't mention rate limits or auth needs, but covers essential operational context.

  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 appropriately sized and front-loaded, starting with the core purpose and key behavioral notes. Each sentence adds value, such as explaining return values and statuses, and it avoids redundancy. The structure is logical and efficient.

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

  Completeness4/5

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

  Given the tool's moderate complexity (1 parameter, no output schema, no annotations), the description is largely complete: it explains the purpose, usage, behavior, and return structure. However, it lacks details on error handling or edge cases, which could be useful for an agent. With no output schema, the description compensates well by detailing return values.

  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 description coverage is 100%, so the schema already documents the single parameter 'date' with its format. The description does not add any parameter-specific details beyond what the schema provides, such as clarifying the date's role in determining the week. Baseline 3 is appropriate as the schema handles the heavy lifting.

  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 tool's purpose with a specific verb ('Get') and resource ('timesheet data for a specific week'), and it distinguishes from sibling tools by explicitly mentioning 'timecard_save' for making changes. It avoids tautology by not just restating the name.

  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?

  It provides explicit guidance on when to use this tool (to retrieve saved data) and when not to use it (for making changes, directing to 'timecard_save' instead). This clearly differentiates it from alternatives like 'timecard_save' and other siblings.

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

• timecard_saveA
  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 full burden and does well by disclosing key behavioral traits: it's a write operation ('apply', 'POSTs'), requires authentication (though 'handled automatically'), has atomic/transactional nature ('in one operation'), fetches and reconstructs state automatically, and includes important warnings about prohibited actions and note character restrictions. It doesn't mention rate limits or error handling, but covers most critical aspects.

  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 appropriately sized and well-structured with clear sections: purpose statement, parameter explanations, workflow example, and warnings. While somewhat lengthy, every section earns its place by providing essential information. The front-loaded purpose statement is clear, and the workflow example is valuable but could be more concise.

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

  Completeness4/5

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

  For a mutation tool with no annotations and no output schema, the description does an excellent job providing context. It covers the tool's purpose, usage workflow, parameter relationships, behavioral constraints, and warnings. The main gap is lack of information about return values or error responses, but given the comprehensive parameter coverage and workflow guidance, it's mostly complete for practical use.

  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 description coverage is 100%, so baseline would be 3. However, the description adds significant value beyond the schema: it explains the relationship between parameters ('All dates in hours/notes must fall within the same week as the top-level date'), provides source guidance for activity_value ('Get activity_value from timecard_get_activities'), clarifies date format expectations, and includes a comprehensive example showing how all parameters work together. This elevates the score above baseline.

  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 tool's purpose with specific verbs ('apply entries, hours, and notes', 'fetches', 'reconstructs', 'POSTs') and resources ('specific week', 'target week's page', 'full form state'). It distinguishes from siblings by emphasizing atomic save in one operation versus get/read tools like timecard_get_timesheet.

  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 provides explicit workflow guidance with numbered steps (1-3), names specific sibling tools to use first (timecard_get_timesheet, timecard_get_activities), and includes clear exclusions ('Only save (draft) is supported', 'submit (for approval) is strictly prohibited'). It tells when to use this tool versus alternatives in the workflow context.

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

• timecard_versionA
  4.6/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 effectively describes the tool as a read-only operation that returns version metadata (commit, branch, buildDate), which is appropriate for a version-checking tool. However, it doesn't mention potential errors, rate limits, or authentication needs, leaving some behavioral aspects unspecified.

  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 front-loaded with the core purpose, followed by a clear breakdown of return values and a specific usage guideline. Every sentence adds value without redundancy, making it efficiently structured and easy to parse.

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

  Completeness4/5

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

  Given the tool's simplicity (0 parameters, no annotations, no output schema), the description is nearly complete. It explains what the tool does, when to use it, and what it returns. However, without an output schema, it could benefit from more detail on error handling or response format nuances, but this is minor for a version-check tool.

  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 tool has 0 parameters, and schema description coverage is 100%, so the schema fully documents the lack of inputs. The description appropriately doesn't add parameter details, focusing instead on the output semantics, which is sufficient given the context.

  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 tool's purpose with a specific verb ('Get') and resource ('TimeCard MCP version information'), distinguishing it from sibling tools that handle activities, projects, summaries, timesheets, and saves. It precisely defines what information is retrieved.

  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 states when to use this tool: 'Use this to verify which version of TimeCard MCP is running.' This provides clear context and distinguishes it from sibling tools that serve different purposes, such as retrieving data or saving records.

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