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

Discloses read-only nature and performance caveat ('may be slower than score-only tools'). No annotations provided, so description carries full burden; it covers behavioral traits adequately.

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

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

Front-loaded with purpose, then usage, then parameter details, then notes. Each sentence serves a purpose; no fluff or redundancy. Efficient communication.

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

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

Describes outputs (section clock usage, thirds, tags, time sinks, fast guesses) but lacks explicit return structure or error conditions. However, for selection purposes, it provides sufficient context.

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

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

Schema covers all 3 parameters; description adds context: explains limit range, minN filters tag rankings, forceRefresh refreshes mock list. Adds value beyond schema, but schema already provides baseline descriptions.

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

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

The description clearly states the tool analyzes per-question timing with specific metrics (section clock usage, thirds, tags, time sinks, fast guesses). It distinguishes from sibling tools like analyze_score_trends by focusing on pacing analysis.

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

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

Explicitly states when to use ('when the user asks about pacing, running out of time, or rushing') and what it is not a substitute for ('score trends or topic accuracy rankings'). No ambiguity.

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

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

No annotations provided, so the description carries full burden. It discloses read-only behavior, explains that cognitive total excludes SJ, and mentions cache metadata in returns. This is thorough, though it could mention potential rate limiting or caching effects.

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

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

The description is three sentences, front-loaded with purpose, then usage guidance, then parameter explanations. Every sentence is essential and no fluff.

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

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

Given the tool's simplicity (2 params, no output schema), the description covers inputs, behavior, and return content (analysis plus cache metadata). However, it is slightly vague on the exact output format (e.g., chart vs text), which could be clarified.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining that 'kind' filters mock types (full/mini/all) and 'forceRefresh' reloads from Medify, providing context beyond the schema.

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

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

The description clearly states the tool analyzes personal Medify UCAT mock score trends over time, including cognitive totals, per-section averages, best/worst sits, and comparisons. It also explicitly distinguishes from sibling tools, making its purpose unique.

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

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

The description explicitly tells when to use this tool (for score trends, improvement, or history chart) and when not to use it (for subtype drills or timing analysis), naming specific alternative tools.

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

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

No annotations are provided, so the description carries full burden. It declares 'Read-only', explains caching behavior via forceRefresh, and describes return value structure ('ranked sections with averages and relative standing; SJ is summarised separately').

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

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

Three sentences: purpose and scope, usage with alternative, and parameter/behavior details. Front-loaded with most important info, no wasted words.

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

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

Given no output schema, the description fully explains return values. It covers read-only, caching, mock filtering, and the distinction between cognitive sections and SJ. All relevant context is present.

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

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

Schema coverage is 100% and already describes kind and forceRefresh. The description adds value by stating default values ('default all') and behavioral effects ('bypasses cache'), which goes beyond the schema.

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

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

The description clearly states 'Rank VR, DM, and QR strengths and weaknesses from completed Medify UCAT mocks' and specifies both the verb (rank) and the resource (sections from completed mocks). It distinguishes from analyze_topic_performance by noting it does not break down question subtypes.

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

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

Explicitly says 'Use to answer “which section is weakest?” before recommending drills.' and provides a clear alternative: 'use analyze_topic_performance for that' when question subtype breakdown is needed.

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

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

No annotations provided, so description carries full burden. Clearly states 'Read-only' and 'Fetches live topic-performances from Medify (includes practice history aggregated by Medify, not only mocks).' Discloses behavior beyond defaults, with 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.

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

Description is concise with 6 sentences, front-loaded with purpose and usage. Every sentence adds value: purpose, usage guidance, parameter details, data source. No redundant information.

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

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

Given schema coverage 100% and no output schema, description covers parameters, read-only nature, data source, and sibling context. Lacks output format details (e.g., ranking presentation) but sufficient for selection and invocation.

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

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

Schema coverage is 100% with descriptions for both parameters, so baseline is 3. Description adds value by stating defaults (includeSj false, minN 10) and explaining their effect ('omit Situational Judgement', 'drops sparse subtypes'), which aids agent understanding.

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

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

Description clearly states tool ranks UCAT question subtypes by personal accuracy vs population averages, with specific verb 'rank' and resource 'question subtypes'. Distinguishes from siblings by specifying it complements analyze_section_performance and analyze_question_timing.

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

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

Explicitly says 'Best tool for what should I drill? at the question-type level.' Provides guidance on parameters (includeSj defaults false, minN defaults 10) and mentions complementary tools, giving clear when-to-use and when-not context.

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

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

Discloses that it is read-only (does not modify cache), requires network access, and succeeds from persisted session even without env credentials. No annotations provided, so description fully covers behavioral traits.

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

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

Informative but slightly verbose; could be tightened. However, front-loads purpose and uses clear structure.

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

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

Returns explained (flags, env config, message). Covers prerequisites, limitations, and behavior. No output schema, so description adequately documents return values and context.

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

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

No parameters, so schema coverage is 100%. Baseline for 0 params is 4; description adds no param info but doesn't need to.

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

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

Clearly states it verifies authentication and endpoint reachability. Distinguishes from sibling tools which deal with mocks and analysis, not connection checking.

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

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

Explicitly tells when to call: after setup fails, after changing credentials, or before trusting other tools. Also states what it does not do (list mocks, modify cache).

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

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

The description declares the tool is read-only, explains behavior when mocks are not found ('Returns found=false with missing ids'), and describes forceRefresh effect. Without annotations, this is strong transparency, though slight ambiguity in 'refresh the list'.

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

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

The description is two sentences, front-loaded with main purpose, no redundant words. Every sentence adds value, including usage guidance and return behavior.

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

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

Despite no output schema, the description covers return states (found=false, structured diff). For a 3-parameter tool with no nested objects, this is complete enough, though slightly more detail on the diff structure would push to 5.

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

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

Schema coverage is 100% but description adds value by clarifying idA/idB accept 'mock id, compositeId, or exact title' and explaining forceRefresh refreshes cache. This goes beyond the schema's basic descriptions.

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

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

The description explicitly states the tool compares two completed Medify UCAT mocks section-by-section and by cognitive total. It uses a specific verb ('compare') and resource ('mocks') and distinguishes from siblings by referencing analyze_score_trends and get_mock_details.

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

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

The description clearly says 'Use when the user names two sits (ids or titles)' and provides explicit alternatives: 'For overall history use analyze_score_trends; for one mock use get_mock_details.' It also explains input acceptance (ids, compositeId, titles).

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

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

Despite no annotations, the description covers read-only nature, error handling ('Missing id throws; unknown id returns not-found style'), and caching behavior (forceRefresh).

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

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

The description is concise with no redundant words, front-loaded with purpose, and efficiently structured in a few sentences.

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

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

Given no output schema and no annotations, the description covers return fields, error behavior, cache refresh, and parameter variations, providing a complete picture for the agent.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by clarifying that id can be id, compositeId, or exact title, which is beyond schema descriptions.

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

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

The description specifies the verb 'get' and resource 'detailed scores for one completed Medify UCAT mock', and distinguishes from siblings like list_completed_mocks and compare_mocks.

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

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

Explicitly states to use after list_completed_mocks when needing a single sit, and suggests compare_mocks for diffs, providing clear when-to and when-not-to guidance.

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

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

No annotations, so description carries full burden. Discloses read-only nature, caching behavior (forceRefresh bypasses), and empty list implying auth failure. 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.

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

Every sentence adds value. Front-loaded with purpose, efficient with no fluff. Uses bullet-like formatting for readability.

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

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

No output schema, but description explains return values (section scores, cognitive totals, metadata). Handling of empty list and auth failure completes the picture for this list tool.

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

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

Schema coverage 100%; description adds context beyond schema: kind filters, forceRefresh purpose, includeRaw for debugging. Significantly aids parameter understanding.

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

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

Explicitly states 'list completed Medify UCAT mocks with section scores and cognitive totals'. Distinguishes from analyze_* tools by noting they provide ranked insights. Clear verb and resource.

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

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

Provides explicit use case: 'inventory before trends/comparisons'. Warns to prefer analyze_* for ranked insights. Explains empty list meaning and fallback action.

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

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

No annotations provided, but description fully discloses behavior: 'Read-only', 'Returns ordered recommendations with reasons/suggestions plus a short summary', and 'Does not create Medify practice sets'.

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

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

Three focused sentences, front-loaded with purpose, no redundant words. Every sentence adds value.

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

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

Given 4 optional params and no output schema, description covers what is returned and what is not done. Sufficient for an agent to correctly invoke.

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

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

Schema coverage is 100%, but description adds meaning for kind ('filters mocks'), includeSj ('defaults true for SJ advice'), and targetTotal ('adds a gap recommendation'). forceRefresh not elaborated, but overall useful.

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

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

Description states 'Recommend prioritised UCAT practice focus areas from mock history' – a specific verb+resource. It distinguishes from sibling tools like analyze_topic_performance and analyze_question_timing.

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

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

Explicitly says 'Use for a practice plan' and suggests calling analyze_topic_performance and/or analyze_question_timing for evidence. Also clarifies kind filtering, includeSj default, and targetTotal usage.

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

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

With no annotations provided, the description fully covers behavior: requires valid Medify auth, overwrites cache only, does not change Medify account data, and returns fetch metadata. 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.

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

Four sentences concisely convey purpose, usage, limitations, and return value. No wasted words; essential information is front-loaded.

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

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

For a refresh/cache tool with no input or output schema, the description is fully complete. It covers triggers, effects, requirements, and limitations.

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

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

Tool has zero parameters, so parameter semantics are not applicable. The description effectively explains the tool's behavior without needing parameter details.

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

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

The description clearly states the tool's specific action: force re-fetch completed mock scores from Medify and update local cache. It distinguishes from sibling tools like analyze_score_trends by noting it does not analyze scores.

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

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

Explicitly states when to use (after finishing a mock with stale data or cache TTL not expired) and what not to use it for (does not analyze scores). Recommends pairing with analyze_score_trends or list_completed_mocks for further analysis.

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