Server Quality Checklist

Tool Scores

• get_curriculum_progressA
  4.1/5.0
  Behavior5/5

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

  The description adds substantial behavioral context beyond annotations: it explains the derivation logic (passing quiz scores >=70), grouping by topic/module, and guarantees it always returns all 9 topics even if unstarted. This complements the readOnlyHint and idempotentHint annotations without contradiction.

  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: it opens with a clear purpose, then explains derivation, parameters, return schema, and error handling. Every sentence adds value, and the length is appropriate for the tool's complexity.

  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?

  Despite having no output schema, the description provides a complete return schema and explains guaranteed behavior (all topics returned). With good annotations and a simple parameter, the description fully enables correct agent invocation without gaps.

  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 single parameter `student_id` is well-documented in the schema (100% coverage) with a detailed description of its format (Firebase Auth UID / Supabase user_id). The description's Args section merely repeats this, adding no new meaning, so a baseline score of 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 clearly states the tool retrieves completion status across specific financial literacy topics, using a specific verb ('Retrieve') and resource ('student's completion status'). It implicitly distinguishes from siblings like `get_assessment_results` and `get_student_progress` by focusing on topic-level completion derived from quiz attempts.

  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?

  No explicit guidance on when to use this tool versus alternatives like `get_student_progress` or `get_assessment_results`. The description does not provide when-to-use or when-not-to-use context, leaving the agent to infer usage from purpose alone.

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

• get_student_progressA
  4.2/5.0
  Behavior4/5

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

  Annotations already indicate read-only, idempotent, non-destructive. The description adds valuable behavioral context: reads from Firestore, lists exact fields returned, specifies error handling ('Student not found'). This supplements the annotations well.

  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 efficiently structured with sections for Args, Returns, and Error Handling. It front-loads the main purpose. Slightly verbose with the full return schema, but overall concise.

  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?

  Despite no output schema, the description provides a complete return type spec. It includes error handling and data source. Input schema is fully described. The tool is simple (1 param), and the description covers all necessary information.

  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%, providing a detailed description of student_id. The description's Args section repeats a truncated version of the schema description, adding no new meaning. Baseline score of 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 states a specific verb and resource: 'Retrieve a student's current XP, level, streak, and points balance.' It explicitly distinguishes from a sibling tool: 'Does NOT include quiz-level detail — use get_assessment_results for that.'

  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 provides clear context: it reads from Firestore and is for gamification/progress data. It explicitly directs to an alternative for quiz detail. However, no explicit when-not-to-use beyond quiz-level.

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

• get_student_profileA
  4.3/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint and idempotentHint; the description adds context about excluding sensitive fields and error handling ('Student not found'), enhancing transparency without contradiction.

  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?

  Description is concise, front-loaded with purpose, followed by exclusions, param/returns/errors in a clear structure with no wasted words.

  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 retrieval tool with no output schema, the description provides a complete return schema, error handling, and clear boundaries, making it adequately complete.

  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 coverage is 100% with a detailed schema description for student_id. The description adds minimal extra ('student's unique identifier'), meeting baseline for high coverage.

  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 states 'Retrieve a student's basic identity and enrollment information' with a specific verb and resource, clearly distinguishing from siblings like get_assessment_results by specifying what it returns and what it excludes.

  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 says what the tool does NOT return (parent contact, raw assessment data) and implies usage for personalizing coach tone, but does not name alternative tools for other purposes.

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

• get_learning_signalsA
  4.4/5.0
  Behavior5/5

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

  Annotations already indicate readOnlyHint=true and idempotentHint=true, but the description adds detail: it never returns raw internal fields, explains data sources (Supabase and Firestore), and documents error handling for inactive students (sentinel values). No contradictions with annotations.

  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?

  Well-structured with paragraphs and bullet points for Args, Returns, Examples, and Error Handling. The first sentence clearly states purpose. Slightly verbose (Args redundant with schema), but overall efficient for the level of detail.

  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?

  Despite no output schema, the description provides a detailed output schema with types, examples, and error handling. Covers all scenarios (inactive student, sentinel values). Fully complete for a single-parameter 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?

  Schema description coverage is 100% for the single parameter student_id, with a clear explanation of its meaning. The tool description's Args section merely repeats the schema, adding no additional meaning, so 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 clearly states it retrieves behavioral signals for Coach to decide what to show a student next. It specifies the verb 'retrieve' and resource 'learning signals', and distinguishes from sibling tools by focusing on behavioral signals for next action, not assessments or progress.

  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?

  Provides explicit examples of when to use this tool (e.g., 'What should Coach show this student right now?' and deciding on re-engagement copy). It also notes what it never returns (raw dormancy-decay scores), giving clear context. However, it does not explicitly name alternative tools for when not to use it.

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

• get_coach_contextA
  4.5/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds behavioral context beyond annotations: it composes data from two databases, defaults to safe empty states for new students, and specifies error handling ('Student not found'). No contradictions.

  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 well-structured and concise: it starts with a clear summary, then sections for motivation, args, returns, examples, and error handling. Every sentence adds value with no redundancy.

  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 simple input schema (1 param), rich annotations, and detailed return schema documentation in the description, the tool definition is fully complete. Sibling tools are referenced, and context signals confirm high coverage.

  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 coverage is 100%, and the description restates the parameter in the Args section without adding new meaning beyond the schema's description. Baseline score 3 is appropriate as the schema does 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: 'Retrieve everything Coach needs to open a session with a student, in one call.' It specifies the verb, resource, and distinguishes itself from siblings by labeling it as the primary entry point and listing alternative tools for individual data.

  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 provides usage guidance: 'Use when: Start a Coach session for this student' and 'Don't use when: you only need one field.' It names sibling tools as alternatives and gives examples, making it easy for the agent to decide.

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

• get_assessment_resultsA
  4.7/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds that it reads from Firestore, is paginated, and always check has_more. It also discloses error handling (empty array for no attempts). This significantly enriches the behavioral understanding beyond annotations.

  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 well-structured with clear sections: main action, data source, pagination notes, args, returns, examples, and error handling. No fluff, every sentence adds value. Front-loaded with the core purpose.

  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 tool with 3 parameters (1 required) and no output schema, the description provides a complete picture: data source, pagination mechanism, return schema, examples, and error handling. It covers all necessary context for an agent to use it correctly.

  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 is 3. The description's Args section repeats parameters but adds useful context: default for limit, optional cursor, and why cursor is used (pagination). It also includes a full return schema, which is not in the structured schema. This adds value beyond the schema.

  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 it retrieves a student's recent quiz/assessment attempts, sorted most recent first. The verb 'Retrieve' and resource 'quiz/assessment attempts' are specific, and it's distinct from sibling tools like get_student_progress or get_coach_context.

  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?

  Provides concrete examples of when to use ('How did this student do on their last few quizzes?') and how to paginate for full history. Does not explicitly mention when not to use, but the context is clear enough for an agent to decide.

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