Server Quality Checklist

Tool Scores

• portal_assignmentsC
  2.8/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 introduces unsupported views ('today', 'recent') and omits the valid enum value 'all', so actual behavior is less predictable. It also does not mention default behavior, return format, pagination, or permissions.

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

  Conciseness3/5

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

  The description is appropriately short and front-loaded with the verb and resource. However, the inaccurate parenthetical enumeration adds noise and undermines the clarity that conciseness is meant to provide.

  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?

  For a tool with no annotations and no output schema, the description should provide more behavioral context. The view options mismatch the enum, no default is clearly clarified, and return values/pagination are not mentioned, leaving an agent under-equipped to call it correctly.

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

  Parameters2/5

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

  Schema coverage is 100% and the single parameter is fully described by the enum, so the description does not need to repeat parameter information. Howver, the description's view list ('today', 'recent', 'archive') conflicts with the schema enum ('upcoming', 'archive', 'all'), potentially leading an agent to pass invalid values.

  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?

  Clearly states it retrieves homework assignments with a specific verb and resource, which distinguishes it from siblings like portal_exams and portal_evaluations. The parenthetical list of views is misleading because 'today' and 'recent' are not in the schema enum, but the core purpose remains unambiguous.

  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 appropriate usage by naming the resource, but it provides no explicit guidance on when to use this tool versus alternatives or which view to select. It mentions possible views, yet the view values contradict the schema, further weakening routing guidance.

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

• portal_materialsC
  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 indicates a read operation ('Get') but does not mention return format, pagination, whether omitting courseId returns all materials, or any access considerations. This is minimal but not misleading.

  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 short, direct, and front-loads the core purpose. Every sentence adds relevant information, though the overall terseness leaves some behavioral gaps.

  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?

  For a simple read tool with one optional parameter and full schema coverage, the description covers the basics. However, the lack of differentiation from sibling tools and the absence of any return-behavior details make it only minimally viable.

  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 optional courseId parameter, so the schema already documents it adequately. The description's phrase 'filter by course ID' adds little beyond what the schema states, hitting the baseline expectation.

  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 uses a specific verb ('Get') and a clear resource ('teaching/learning materials'), and identifies the optional courseId filter. It is clear about what the tool does, though it does not explicitly distinguish itself from sibling tools like portal_library or portal_lesson_plans.

  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 gives no guidance on when to choose this tool over portal_library, portal_lesson_plans, or other related siblings. It only states that courseId is optional, leaving the decision of when to use the tool entirely to the agent without context.

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

• portal_attendanceB
  3.2/5.0
  Behavior3/5

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

  With no annotations, the description carries the behavioral burden. It indicates a non-mutating read operation via 'Get' and adds rough temporal orientation for some views ('retroactive', 'forward by day/lesson'). However, it does not disclose what each view actually returns, any scoping, pagination, or output structure, so transparency is only partial.

  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 compact and front-loaded with the action and resource, and the view list is efficient and scannable. There is no filler or redundant schema repetition, though the terseness occasionally comes at the cost of clarity.

  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?

  For a one-parameter read tool, this is nearly adequate: all view options and the default are visible, and the general output category is stated. However, with no output schema and no usage guidance, an agent cannot reliably predict how the view outputs differ or when the sibling absence-submission tools should be used instead.

  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%: the single 'view' parameter is documented with enum values and a default, so the description does not need to restate it. The parentheticals add a little extra meaning beyond the schema, but they do not fully explain each enum value or its output, so baseline 3 is appropriate.

  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 states a clear verb and resource ('Get attendance records and statistics') and enumerates the six views, so an agent knows what domain and mode the tool operates in. It does not explicitly differentiate this read-only attendance tool from siblings like portal_excuse_absence or portal_report_absence, so the last bit of distinguishing context is missing.

  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 when-to-use, when-not-to-use, or alternative tool guidance is provided. The parenthetical labels hint at some semantic differences, but the description never tells an agent when to choose portal_attendance over the sibling absence tools or how to pick among 'report', 'report-lesson', 'stats', etc.

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

• portal_excuse_absenceB
  3.2/5.0
  Behavior2/5

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

  No annotations are provided, so the description bears full responsibility for behavioral disclosure. It states the action ('submit') and retroactive nature, but not what happens as a result, whether changes can be reversed, what permissions are needed, or what response/confirmation the agent should expect.

  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?

  One concise sentence that states the core purpose front-loaded, with no filler or redundancy. Every word contributes meaning, making it easy for an agent to consume quickly.

  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?

  For a mutation tool with no annotations and no output schema, the description is minimal. It lacks guidance on expected outcomes, side effects, or how it relates to portal_report_absence/portal_attendance, leaving an agent to infer important operational context.

  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%, so the structured schema already fully documents both parameters and their date format. The description adds only minor context ('specific dates') and does not substantially enhance parameter semantics beyond what the schema provides.

  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 uses a specific verb ('Submit') and a specific resource ('retroactive excuse for absences on specific dates'), clearly articulating the tool's core function. The term 'retroactive' also helps distinguish it from sibling portal_report_absence, even though the sibling is not named explicitly.

  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 implies the tool is for retroactive excuses but provides no explicit guidance on when to use it versus alternatives like portal_report_absence or portal_attendance. It does not state exclusions or conditions that would help an agent pick between sibling tools.

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

• portal_libraryB
  3.2/5.0
  Behavior2/5

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

  No annotations are provided, so the description carries full responsibility. 'Get' implies a read-only operation, but the description does not disclose behavior such as whether the response includes a single combined list, separate lists, or additional metadata. No pagination, sorting, or access considerations are mentioned.

  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, concise sentence that immediately states the action and resource. Every word contributes to understanding, with no filler or repetition.

  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 that the tool has no parameters and no output schema, the description is somewhat complete, but it leaves ambiguity about whether 'borrowed and available' are two separate result sets or a single combined listing. An agent could call the tool correctly, but it would not know what response shape to expect.

  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 no parameters, so the baseline is 4. The description adds meaningful domain context by specifying that both borrowed and available books are involved, which is useful even though there is nothing to parameterize.

  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 uses a specific verb ('Get') and a clear resource ('library books'), and it indicates the two relevant categories (borrowed and available). It distinguishes itself from sibling portal_* tools by naming a distinct resource, though it does not explicitly contrast with any sibling.

  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?

  There is no guidance about when to use this tool versus alternatives, and no exclusions or prerequisites are mentioned. The intended use is only implied by the tool name and description, which is not enough to help an agent decide between this and other portal tools.

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

• portal_report_absenceB
  3.2/5.0
  Behavior2/5

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

  No annotations are provided, so the description carries the full burden. It mentions the operation is for 'future (upcoming)' absences, which is a temporal constraint, but does not disclose side effects, whether it creates a record, whether it can be modified/deleted later, or any permission/approval process. For a tool that reports an absence (likely a write action), important behavioral details are missing.

  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 a single concise sentence with no wasted words. It front-loads the action and resource, and includes the key distinction of day vs lesson. It could be slightly more structured by mentioning the date range aspect, but it is efficient and clear.

  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?

  The tool has 4 parameters (3 required) with 100% schema coverage, but no output schema and no annotations. The description provides the core purpose but does not explain return values, validation rules, or the relationship to sibling portal_excuse_absence. Given the moderate complexity (date range, mode, reason) and lack of annotations, the description is adequate but leaves gaps in behavioral and alternative guidance.

  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%, so the schema already documents all four parameters. The description adds little beyond the schema: 'by day or by lesson' maps to the mode enum, which the schema already lists. Since coverage is high, baseline 3 is appropriate. It does not add details like date format or optionality that are not in the schema.

  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 ('Report') and the resource ('a future (upcoming) absence') with a scope qualifier ('by day or by lesson'). It distinguishes itself from sibling portal_excuse_absence by focusing on future absences, but does not explicitly name that sibling. The verb and resource are specific enough for an agent to understand the core purpose.

  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 usage context: it is for future absences, which hints at when to use it versus alternatives. However, it does not explicitly state when not to use it or mention the sibling portal_excuse_absence, which appears related. Since the description provides a clear context (future absences) but no explicit exclusions or alternatives, it earns a 3.

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

• portal_evaluationsB
  3.3/5.0
  Behavior2/5

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

  No annotations are present, so the description carries the full burden. It conveys a read-only intent and grouping behavior, but it does not disclose what the by-date or trends views return, how results are structured, or any limitations or prerequisites. The 'grouped by subject' phrasing also creates mild ambiguity against the by-date and trends view options.

  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 sentence that front-loads the verb and target with zero filler. Every word contributes to the meaning, and it is easy to parse quickly.

  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?

  For a tool with only one optional enum parameter, the description is nearly sufficient, but with no annotations or output schema it would benefit from clarifying what 'evaluations' includes and how the by-date and trends views behave. The current text leaves some behavioral gaps for the agent to discover.

  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%: the single view parameter has an enum and a description ('Which evaluation view to fetch'). The tool description adds no additional meaning beyond that, so the baseline of 3 is appropriate.

  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 uses a specific verb ('Get') and resource ('grades and evaluations') and adds a clear grouping criterion ('by subject'). This helps distinguish it from siblings like portal_assignments, though the boundary with portal_exams is not explicitly drawn.

  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 establishes an obvious use case—retrieving grades/evaluations—but gives no guidance about when not to use it or when a sibling like portal_exams or portal_search would be preferable. An agent must infer the appropriate selection from the tool name and one-line description.

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

• portal_inboxB
  3.3/5.0
  Behavior3/5

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

  No annotations are present, so the description must carry behavioral disclosure. 'List' clearly signals a read-only action and 'optionally filter by type' describes the primary behavior. However, it does not disclose output shape, ordering, pagination, or whether listing affects read/unread state.

  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?

  A single, front-loaded sentence communicates the operation and resource, with the optional-filter behavior appended. There is no filler, making it easy for an agent to parse quickly.

  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?

  For a one-parameter list tool, the description covers the main call purpose and filter behavior. Yet with no output schema or annotations, it omits details about the returned item structure and any default sorting or limit, which an agent might need to interpret the response.

  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%, so the schema already documents the filter parameter and its default. The description adds little semantic value beyond restating that filtering is optional; its mention of 'assignments' as an inbox item type could even be confusing because the filter enum does not include assignments.

  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 states a specific operation (list) and resource (inbox items), and enumerates example item types (messages, events, assignments) that make the aggregation scope clear. It does not explicitly contrast with portal_messages or portal_assignments, but the 'inbox' framing separates it from those siblings.

  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?

  There is no guidance on when to use this tool instead of a sibling like portal_messages or portal_assignments. The intended use is implied by 'List inbox items', but no exclusions or alternatives are provided, so an agent must infer the boundary.

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

• portal_lesson_plansB
  3.3/5.0
  Behavior3/5

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

  There are no annotations, so the description must carry the behavioral burden. 'Get' signals a read-only operation, and 'for the student' scopes the data, but the description does not explain what happens by default, how the week parameter affects output, or what response format to expect. This is adequate but not rich.

  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, direct sentence that conveys the core purpose without redundancy. Every word earns its place, and no filler or repetition exists.

  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?

  For a simple one-optional-parameter lookup tool, the description covers the basic purpose and the schema covers the parameter. However, without usage guidance or clarification of how this differs from related portal tools, the definition is only minimally complete for reliable selection and invocation.

  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 fully describes the single optional 'week' parameter with 100% coverage, so the description needs to add little. The description does not misinterpret or conflict with the schema, but it also does not enrich the parameter semantics beyond what is already present.

  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 uses a specific verb ('Get') and a clear resource ('lesson plans / curriculum content'), making the tool's purpose immediately understandable. It does not explicitly distinguish itself from sibling tools like portal_materials or portal_courses, but 'lesson plans' is specific enough to be reasonably differentiated.

  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 guidance is provided about when to use this tool versus alternatives such as portal_materials or portal_courses. The description only states what the tool does, leaving an agent to infer when it is the right choice.

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

• portal_portfoliosB
  3.3/5.0
  Behavior2/5

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

  No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Get' implies a read-only operation, but the description does not clarify default behavior when studentId is omitted, whether multiple portfolios can be returned, response shape, ordering, or pagination. It discloses the operation type but nothing else about runtime behavior.

  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?

  One clean, front-loaded sentence with zero filler words. Every word earns its place, and the verb-resource structure is immediately parseable by an agent.

  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?

  The tool is simple (one optional parameter, no output schema, no annotations), so a one-line description is nearly adequate. However, an agent cannot tell from the description what happens when studentId is omitted or how 'portfolio work items' differs from portal_assignments in practice. Minimal viable, but with clear 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?

  Schema description coverage is 100%, so the parameter 'studentId' is already documented in the schema ('Student ID (optional)'). The description adds no semantic detail beyond naming the resource being queried. Baseline 3 is appropriate when the schema handles parameter documentation.

  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 uses a specific verb ('Get') and a specific resource ('student portfolio work items'), naming exactly what the tool returns. This clearly distinguishes it from sibling tools like portal_assignments, portal_materials, or portal_evaluations, which target different resource types. The intent is unambiguous.

  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 gives no guidance on when to use this tool versus alternatives such as portal_assignments, portal_evaluations, or portal_lesson_plans. There is no mention of exclusions, prerequisites, or the optional studentId parameter's intended use-case context.

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

• portal_searchB
  3.3/5.0
  Behavior3/5

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

  With no annotations, the description carries the full burden. 'Search' strongly implies a non-mutating read operation, so the safety profile is reasonably clear. However, it does not disclose result format, pagination, authentication needs, or exactly which content areas are included by 'any content'.

  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, efficient sentence with no filler. The core action and target are front-loaded, and every word earns its place.

  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?

  For a simple one-parameter tool, the description is minimally adequate: an agent knows to provide a keyword. But without an output schema or annotation guidance, it leaves gaps about the return structure and the exact scope of the search, so it is not fully 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?

  The input schema provides 100% description coverage for the single parameter, so the schema already documents 'query' adequately. The description adds nothing beyond the schema, making the baseline 3 appropriate.

  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 states a clear verb ('Search'), resource ('the portal'), and scope ('any content by keyword'). It implies a broad cross-module search, which distinguishes it from the specific sibling tools like portal_inbox or portal_materials, though it does not name a specific alternative.

  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 guidance is provided on when to use this generic search versus the more specific portal_* tools. The description doesn't mention whether users should first try a specific module or when the generic search is appropriate, leaving the agent to infer usage from the tool name alone.

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

• portal_send_messageB
  3.3/5.0
  Behavior2/5

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

  No annotations are provided, so the description carries the full burden. It discloses that the tool sends a message but does not mention side effects, delivery behavior, permission requirements, or whether the action is reversible. For a mutation tool, this is a meaningful transparency gap.

  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 no filler. It front-loads the core action and avoids unnecessary detail.

  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?

  For a simple three-parameter tool the description is minimally adequate, but with no annotations and no output schema it leaves the agent without information about expected outcomes, delivery confirmation, or constraints. The lack of guidance versus sibling tools further limits completeness.

  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%, so the schema already documents all three parameters clearly. The description adds no parameter-level meaning beyond stating the general action, which meets the baseline but does not exceed it.

  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 ('send'), the resource ('message'), and the action ('compose and send a new message to a recipient'), making it easy to distinguish from read-only sibling tools like portal_inbox or portal_get_message.

  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 implies use when the agent needs to send a message, but it provides no explicit guidance on when to choose this tool over siblings such as portal_messages or portal_get_message, and gives no exclusions or preconditions.

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

• portal_discussionsA
  3.5/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 the burden of disclosure. The verb 'Get' reasonably implies a read-only operation, and 'upcoming or archived' defines the two modes. However, it does not mention permissions, pagination, return shape, or any side-effect-free guarantee beyond the verb itself. It is not misleading but leaves behavioral details undisclosed.

  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?

  A single, front-loaded sentence with no filler. Every word contributes meaning, and the clarifying parenthetical is efficient. It is appropriately minimal for a one-param read tool without being under-specified to the point of uselessness.

  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?

  For a simple one-param retrieval, the description plus schema is almost sufficient: the agent knows what it returns and how to filter via the view enum. However, with no annotations and no output schema, the description does not disclose what the returned discussion objects look like, whether archived items are sorted, or any access constraints. It is adequate but leaves standard retrieval details unaddressed.

  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 0% and the schema only provides the enum ['upcoming','archive'] with no per-property description. The description reinforces these values by naming 'upcoming' and 'archived', and clarifies that these are discussion types, but it does not explicitly say that the 'view' parameter selects between them. For a single-param tool this is passable but not fully compensated.

  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 ('Get'), the resource ('discussions'), and the two relevant scopes ('upcoming or archived'), with a parenthetical clarifying that discussions are parent-teacher talks. This uniquely identifies it from the other portal_* siblings, none of which cover discussions.

  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 gives a clear context—when you need upcoming or archived parent-teacher discussions—but it never says when this tool should not be used or names alternatives. With many sibling tools like portal_messages or portal_inbox, some explicit routing would help. No exclusions or alternative guidance is provided.

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

• portal_examsA
  3.5/5.0
  Behavior3/5

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

  With no annotations, the description carries the behavioral burden. The verb 'Get' implies a read-only operation, and 'upcoming or past' discloses temporal scoping, but the description does not mention defaults, response shape, pagination, or portal-specific access considerations.

  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 front-loaded sentence with no filler. Every word contributes to identifying the resource and the available temporal modes.

  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 — one optional enum parameter, no nested objects, no output schema, and no annotations — the description is minimally viable. Still, it leaves the default view behavior implicit and does not clarify how it relates to similar portal tools, so it is complete enough to invoke but not fully self-sufficient.

  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 one enum parameter with no description coverage, so the description's 'upcoming or past' effectively adds a gloss for 'upcoming' and 'archive.' However, it does not explicitly tie the wording to the view parameter or state what happens when view is omitted, leaving the enum to do most of the semantic work.

  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 states the verb 'Get' and the resource 'exams and written tests,' making the tool's purpose clear. It does not explicitly contrast with sibling tools such as portal_evaluations, so there is some ambiguity about boundary between exams and evaluations.

  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 phrase 'upcoming or past' implies when the tool is appropriate and maps naturally to the view parameter. However, it never says when to prefer this tool over sibling tools like portal_evaluations or portal_assignments, nor does it give exclusions.

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

• portal_paymentsA
  3.5/5.0
  Behavior2/5

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

  With no annotations, the description must carry the full burden of behavioral disclosure. It only states 'Get', implying a read operation, but doesn't disclose auth requirements, data scope when personId is omitted, response format, or whether balances are real-time.

  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?

  Single sentence, front-loaded, and every word earns its place. It conveys the operation and resource without filler.

  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?

  For a simple one-optional-parameter read tool, the description plus schema is minimally usable. However, no output schema exists and the description doesn't state the behavior when personId is omitted or required access scopes, leaving some context 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?

  Schema description coverage is 100% and describes personId as an optional filter. The tool description adds no parameter semantics, but the schema already covers it, so baseline 3 applies.

  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 uses a specific verb ('Get') and resource ('payment history and outstanding balances'). It clearly separates portal_payments from sibling portal tools like portal_assignments or portal_timetable by naming the domain.

  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 intended use is implied when a user needs payment history or balances, but no explicit when-to-use or when-not-to-use guidance is given. There are no sibling payment tools, so alternatives aren't named.

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

• portal_messagesA
  3.8/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 the full burden. 'List' clearly signals a read-only, non-destructive operation, which is useful. However, it does not disclose potential behavioral details such as pagination behavior, ordering, or whether the default view is inbox when the view parameter is omitted, beyond what the schema already states.

  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 front-loaded sentence with no wasted words. It states the operation ('List') and the resource scope immediately. Every word earns its place.

  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 simple two-parameter list tool with no annotations and no output schema, the description plus schema is largely sufficient to invoke the tool correctly. The main gap is the absence of any description of the return shape or pagination behavior, but the core semantics are clear.

  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%, so the schema already documents both page and view. The description adds no deeper parameter semantics beyond tying the view values to inbox, sent, and archive, which the enum already conveys. The baseline 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 uses a specific verb ('List') with a clear resource ('messages') and explicitly names the three scopes: inbox, sent, or archived. This differentiates it from sibling tools like portal_send_message and portal_get_message, and clarifies it is a list operation rather than a single-message or send operation.

  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 the tool is used to list messages in inbox, sent, or archive views, but it does not explicitly state when to use this tool instead of alternatives such as portal_inbox or portal_get_message. No when-not-to-use or alternative routing is provided.

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

• portal_timetableA
  3.8/5.0
  Behavior3/5

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

  There are no annotations, so the description carries the burden of explaining behavior. It does add view semantics like 'static (permanent)' and 'upcoming events,' which goes beyond the raw enum names. However, it does not disclose return format, pagination, authentication, or error behavior, so transparency is only partial.

  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 sentence that immediately states the action and then lists the key view distinctions. There is no filler or redundant restatement of the tool name. Every phrase earns its place.

  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?

  For a simple read tool with two optional parameters, the description is adequate but minimal. The views are listed and the schema fully covers the parameters, but return value structure, empty results, and any access prerequisites are not mentioned. Given the lack of annotations and output schema, a bit more context would improve 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?

  Schema description coverage is 100%, so the baseline is 3. The description adds meaning to the 'view' parameter by expanding enum names into understandable concepts ('current week,' 'static (permanent),' 'upcoming events,' 'archive'). The 'offset' parameter is not described in prose, but the schema already fully documents it, including its restriction to the 'current' view.

  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 verb and resource: 'Get the student timetable.' It also enumerates the available views, making the tool's scope concrete. It does not explicitly differentiate from sibling tools, but the resource and views are specific enough that an agent can understand what this tool does.

  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 gives clear context about when this tool is relevant — whenever a student timetable is needed — and lists the view options. There are no explicit exclusions or alternative tool recommendations, but since this is a single focused getter with optional parameters, the usage context is sufficiently clear.

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

• portal_consentsA
  4/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 the behavioral transparency burden. The verb 'Get' clearly implies a read-only operation, and mentioning that it returns status adds some behavioral context. Still, it does not disclose potential caveats such as scoping to the current user, available status values, or whether the response lists historical consents.

  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 short sentence that front-loads the verb and resource, then adds the relevant qualifier about status. Every word earns its place with no fluff or repetition.

  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 zero-parameter read-only portal tool with no output schema, the description gives the essential information: what is fetched and that status is included. It could be more detailed about return shape or status values, but the low complexity makes the one-liner reasonably complete.

  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 zero parameters and 100% schema description coverage, so the baseline for a no-parameter tool is 4. The description correctly introduces no parameter information because there are no parameters to document.

  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 uses a specific verb ('Get') and identifies a clear resource ('consent forms (agreements)') plus the key attribute ('their status'). It is distinct from sibling tools like portal_inbox and portal_assignments, which cover different portal domains, so an agent can easily tell when this tool is relevant.

  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?

  Usage context is implied: use this tool when consent forms and their status are needed. However, the description provides no explicit guidance on when not to use it, no mention of alternatives, and no special conditions, so the guidance is only implicit.

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

• portal_coursesA
  4/5.0
  Behavior3/5

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

  With no annotations, the description carries the burden of disclosing behavior. It indicates a read-only action via 'Get' and clarifies that 'enroll' means viewing available enrolments rather than performing an enrollment action. However, it does not disclose response format, pagination, or any other behavioral details.

  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 concise sentence that front-loads the action and resource. Every part of the sentence earns its place by mapping to the three view modes, with no redundant filler.

  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 single-param read-only tool with no output schema, the description gives enough context to identify the correct view values and expected results. Minor gaps remain: it does not explain the exact structure of returned class groups or what fields an enrolled-course list contains, but these are not critical for basic invocation.

  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?

  Though the schema covers the view parameter with 100% coverage, the schema only documents the default value. The description adds semantic meaning by mapping each enum value to its output: list → enrolled courses, groups → class groups, enroll → available course enrolments. This goes beyond the structured 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 uses a specific verb ('Get') with a clear resource (courses) and enumerates the three distinct outputs: enrolled courses, class groups, and available course enrolments. This clearly scopes the tool and distinguishes it from sibling portals like assignments or exams.

  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?

  Usage context is implied by the description: use it when you need course-related data. However, it does not explicitly state when to choose this tool over alternatives, nor does it provide any exclusions or alternative tool references.

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

• portal_dashboardA
  4/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 the disclosure burden. 'Get' clearly implies a read operation and the content list describes the return payload, but it does not mention authentication expectations, data freshness, or any error/empty-state behavior.

  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?

  A single, direct sentence that leads with the verb and resource, then lists the dashboard contents. Every clause adds useful information and there is no filler.

  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 zero-parameter read tool, the description is nearly complete: it names the resource and all main content categories. It could go slightly further by explicitly contrasting with the more detailed sibling tools, but 'main dashboard' and 'highlights' convey enough for correct invocation.

  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 is empty and the description makes no parameter claims, so there is no parameter ambiguity to resolve. Baseline 4 applies for zero-parameter tools.

  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?

  Description uses specific 'Get' plus a clearly named resource, 'main dashboard,' and enumerates the concrete contents returned (student name, pinned items, weekly attendance, timetable highlights). The 'main' qualifier helps distinguish it from focused sibling tools such as portal_attendance and portal_timetable.

  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 phrase 'main dashboard' implies this is the high-level overview, while sibling tools cover specific areas, but it does not explicitly state when to prefer this over portal_attendance, portal_timetable, or portal_inbox. Usage context is only implied, not directly stated.

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

• portal_get_messageA
  4/5.0
  Behavior3/5

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

  No annotations are present, so the description carries the burden. 'Get' implies a read-only operation and 'full content' indicates what is returned, but the description does not disclose response format, error behavior, permissions, or whether related data such as attachments or thread context is included.

  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?

  A single, front-loaded sentence with no filler. Every word contributes to understanding the tool's purpose and invocation.

  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 simple one-parameter read tool, the description plus the fully documented schema are nearly sufficient. The only real gap is lack of details about the return payload, but for a simple getter this is a minor omission rather than a blocking gap.

  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 only parameter, id, already has a meaningful description ('Message ID (numeric, from portal_messages)'). The tool description adds no new parameter semantics beyond what the schema provides, so the baseline of 3 applies.

  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?

  States a specific verb ('Get'), a specific resource ('full content of a single message'), and the key identifier ('by its ID'). This clearly distinguishes it from sibling tools like portal_messages or portal_send_message.

  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 makes clear this is for retrieving the full content of one message when an ID is available. It does not explicitly state when not to use it or name alternatives, but the context is unambiguous and the ID reference implies a prior listing step such as portal_messages.

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