Rotate Pilot — FAA exam prep

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds data sources (FAA Class Airspace, UAS Facility Map, USGS elevation) and the exclusion of TFRs/NOTAMs, which is beyond the annotations and useful for setting expectations. 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?

Two sentences, no filler. The core purpose and output list are front-loaded, and the exclusion statement is concise. Every clause earns its place.

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?

There is no output schema, so the description carries the burden of explaining return values. It lists the airspace class, controlled airspace, LAANC ceiling (conditional), and the verdict. It also clarifies data sources and scope. It could mention error behavior for invalid inputs, but for the tool's complexity this is nearly complete.

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 the parameters are already documented. The description only adds that zip uses the ZIP's center point, which is already in the schema. It does not add syntax, units, or interplay details beyond the schema, so a baseline 3 is appropriate.

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 states a specific verb ('checks') and resource (US location) and enumerates exactly what is returned (airspace class, controlled airspace, LAANC ceiling, verdict). It clearly distinguishes itself from aviation siblings like decode_metar/decode_taf by focusing on airspace at a point, not weather or TAFs.

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 states what the tool does NOT cover ('not TFRs, NOTAMs or special-use airspace') and limits scope to one point. It implies usage for point-specific airspace checks, but does not explicitly name alternatives or say 'use this when X'. Still, the scope statement gives strong 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: it returns correctness, the correct letter/text, explanation, and citations. It does not disclose any rate limits, auth requirements, or edge cases (e.g., behavior for invalid answer formats), but the annotations carry the main safety burden.

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?

Two sentences, front-loaded with the core action and return value, then a compact list of accepted answer formats. 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?

For a read-only, idempotent grading tool with 2 fully documented parameters, the description is nearly complete. It explains what the tool returns and what input formats are accepted. It doesn't specify error behavior for invalid question_id or answer, but that is a minor gap given the annotations and schema coverage.

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 the schema already documents both parameters. The description adds a small clarification that answer accepts a letter (A/B/C), a number 1-3, or the option text, which mirrors the schema but reinforces the accepted formats. This is baseline 3 territory since the schema does the heavy lifting.

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 grades one answer to a Rotate Pilot practice question identified by question_id, and lists the return contents (correctness, correct letter/text, explanation, citations). This distinguishes it from siblings like practice_questions (which presumably fetches questions) and score_diagnostic (which scores a broader diagnostic).

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 implies usage: call this when you have a question_id and an answer to check. It does not explicitly name alternatives or state when not to use it, but the context of grading a single answer is clear enough. Sibling names like practice_questions and score_diagnostic suggest broader flows, but no explicit exclusion is given.

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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it only lists verified competitor prices, includes the check date and free alternatives, and explicitly says the tool will say so instead of guessing for other exams. No contradiction with annotations was found.

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 compact and front-loaded: the main purpose ('Side-by-side prices and contents') appears first, followed by useful output details and a necessary caveat. Every clause earns its place without redundancy.

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 single-parameter read-only tool with rich annotations and no output schema, the description explains what the result includes (prices, contents, check date, free alternatives) and the verified-scope limitation. It is nearly complete, though it could explicitly tie the 'for other exams it says so' behavior to the exam enum values for extra clarity.

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 the single required 'exam' parameter is fully documented with its enum values. The tool description adds context about verified prices and common prep options but does not add new meaning to the exam parameter itself. With full schema coverage, a baseline of 3 is appropriate.

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 states a specific action and resource: 'Side-by-side prices and contents of common prep options for an FAA exam.' It clearly distinguishes this from siblings like cost_of_failing or practice_questions by focusing on comparing verified competitor prices and contents, and it adds the scope detail that only Part 107 data is currently verified.

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 implies usage: call this when you need side-by-side prices and contents of prep options. It also notes the limitation that only Part 107 competitor prices are verified, so it signals when expectations should be lowered, but it never names alternatives or explicitly says when not to use this tool versus siblings like study_plan or cost_of_failing.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false, and destructiveHint=false, fully covering the safety profile. The description adds the return-content context (fee, wait/endorsement, failure rate, expected cost) and a credibility signal ('with sources'), which is useful but not deep behavioral disclosure. No contradiction with annotations.

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

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

A single sentence that front-loads the core concept ('The concrete cost of failing an FAA knowledge test') before enumerating the delivered data points. Every clause carries information — fee, retest requirement, failure rate, expected cost — with zero filler.

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 single-parameter tool with no output schema, the description compensates by enumerating the return fields (fee per attempt, wait/endorsement, failure rate, expected cost), effectively standing in for an output schema. Given the simple input and full annotation coverage of the safety profile, nothing critical is missing for a correct call.

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% — the exam parameter is fully documented with all five enum values and their expansions (part107, ppl, ifr, cpl, atp). The description adds no parameter-specific detail beyond what the schema already provides, so the baseline of 3 for full schema coverage is appropriate.

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 states a specific resource ('concrete cost of failing an FAA knowledge test') and enumerates the exact content delivered: fee per attempt, mandatory wait/endorsement, 2025 national failure rate, and expected failure cost. This precision distinguishes it from siblings like exam_facts (general facts) and compare_prep_options (prep product comparison), which cover different aspects of FAA tests.

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?

Usage is implied by content — the agent would call this when a user asks about the cost of failing an FAA test. However, the description never names a sibling or states when NOT to use it, nor does it route the agent away from exam_facts, which could plausibly cover similar ground. No explicit exclusions or alternates are given.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds meaningful behavioral context: fetching the latest report from NOAA's Aviation Weather Center and the disclaimer that it is training-only, not for flight planning. There is no contradiction with annotations.

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

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

Two sentences, no filler, with the core purpose and output fields front-loaded. The invocation guidance and safety caveat follow naturally. Every sentence earns its place.

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 simple decode tool with no required parameters, no output schema, and strong read-only/idempotent annotations, the description is complete. It specifies inputs, behavior, output contents, and the training-only constraint. Nothing necessary for correct invocation is missing.

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%, with both 'icao' and 'metar' already documented including an example. The description adds the either/or relationship and explains that an ICAO code fetches the latest report, but it largely reinforces what the schema already provides.

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 opens with a specific verb and resource: 'Decodes a METAR aviation weather report into plain English'. It enumerates the decoded fields (wind, visibility, weather, clouds, ceiling, temperature/dew point, altimeter, flight category), which clearly distinguishes it from siblings like decode_taf.

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 states how to invoke the tool ('Pass either the raw METAR text or a 4-letter ICAO airport code') and provides an important operational caveat ('For training, not for flight planning'). It does not explicitly mention alternatives or when not to use it, but the context is clear enough for an agent to proceed.

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?

Annotations already indicate read-only, idempotent, and non-destructive behavior, which the description aligns with. The description adds behavioral context by explaining it fetches data from NOAA when given an ICAO code, and that it's for training only. It does not contradict annotations. The safety-relevant training limitation is a valuable addition beyond the annotations.

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: three sentences, each packed with information. It front-loads the core function, then explains inputs and the output format, and ends with the critical safety disclaimer. 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?

For a simple tool with two optional parameters and no output schema, the description is complete. It explains what the tool does, how to invoke it, what to expect, and adds the training-only safety caveat. Nothing appears missing for an agent to use it correctly.

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

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

The schema has 100% coverage, with clear descriptions for both parameters: 'taf' expects raw TAF text, 'icao' expects an ICAO code and is used when taf is not given. The description reinforces this by stating 'Pass the raw TAF text or a 4-letter ICAO code...' and adds the constraint that either can be used. The description adds the context that these are alternative inputs, which is slightly beyond the schema, but the schema is already quite good.

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 a specific action (decode) on a specific resource (TAF) and describes the output (plain-English periods with flight categories). It distinguishes itself from the sibling decode_metar by focusing on TAF rather than METAR, and from other tools that don't decode weather data.

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 states when to use it: to decode a TAF into plain English. It also provides two usage modes: pass raw TAF text or use an ICAO code to fetch from NOAA. It explicitly states it's for training, not flight planning, which is a crucial usage boundary. However, it doesn't explicitly mention when not to use it (e.g., for METAR), but the sibling decode_metar makes that implicit.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false, lowering the burden. The description adds meaningful behavioral detail: questions span exam areas, answers are hidden, each question has a question_id, and scoring produces per-area results, pass-mark comparison, and a next step. Minor gaps remain around randomness or exact weighting for non-Part 107 exams.

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 compact and front-loaded, starting with 'Starts a free readiness diagnostic' and then providing output and scoring details. It is a single long sentence with no filler, though a slight structural break could improve 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?

For a read-only tool with two parameters and no output schema, the description covers the essential call contract: what is returned, that answers are hidden, that question IDs enable scoring, and what the scored result contains. It omits a precise output shape, but the information needed to invoke the tool successfully 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 50%: exam is well documented, but count only has min/default/max. The description partially compensates by mentioning 10-20 questions and Part 107 weights, but it does not explicitly map count to the number of questions returned or elaborate on behavior for each exam enum value.

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 uses a specific verb ('Starts') and resource ('readiness diagnostic for an FAA knowledge test'), and clearly states the output (10-20 quiz questions with hidden answers). It is distinguishable from siblings like practice_questions and score_diagnostic, though it does not explicitly name or contrast them.

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 implies the usage context: start a free diagnostic, get questions, then score them to see results. However, it does not explicitly state when to use this tool versus practice_questions or score_diagnostic, nor does it offer exclusions or alternatives.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the core behavioral safety profile is carried by metadata. The description adds a conditional disclosure ('test fee when the FAA states it') and says facts come with sources, but does not describe error behavior or what happens when a fact is unavailable. This is adequate given the annotation coverage.

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 a single run-on enumeration but each clause contributes a distinct fact category, so nothing is filler. It could be restructured with semicolons for readability, but it remains scannable and front-loaded with 'Official facts about an FAA knowledge test'.

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 one-parameter read-only lookup with 100% schema coverage and no output schema, the description provides a detailed list of returned fact categories, which is enough for correct selection. It does not specify units or formatting, but that is unlikely to block correct invocation of a facts-retrieval 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?

The schema covers 100% of the parameter: 'exam' has a full description and enum values with exam-specific codes. The description mentions Part 107 but adds no syntax or parameter-level meaning beyond the schema. Baseline 3 is appropriate.

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 identifies the resource (FAA knowledge test facts) and enumerates the exact fact categories returned, making its purpose concrete. It does not explicitly contrast with siblings like practice_questions or cost_of_failing, but the content list clearly marks it as a factual reference tool.

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?

No explicit when-to-use or when-not-to-use guidance is given, and no alternative tools are named. However, the description implies it is for retrieving official test facts for one of the FAA exams, which is enough for a simple one-parameter lookup.

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 readOnlyHint=true and idempotentHint=true, the safety profile is already disclosed. The description adds meaningful behavioral context by enumerating the returned content: price, inclusions, guarantee/refund terms and links, free practice options, and purchase links. It does not contradict the annotations.

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 a single, dense sentence that front-loads the core purpose and then lists the returned offer aspects without wasted words. Every phrase adds useful 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?

The tool has one well-documented parameter and no output schema, so the description's list of returned content largely suffices. It is complete enough to invoke correctly, though it could strengthen guidance on when to use it instead of compare_prep_options.

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?

There is only one parameter and the schema already covers it thoroughly with an enum and per-value exam descriptions. The description adds little semantic detail beyond 'for an FAA exam,' so the schema carries the burden. A baseline 3 is appropriate.

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 states a specific action and resource: retrieving Rotate Pilot's current paid prep package for an FAA exam, including price, inclusions, guarantee/refund terms, free practice, and purchase links. It is clear but does not explicitly name or contrast a sibling like compare_prep_options, so differentiation is left to inference.

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 implies the tool is for getting a single exam's current offer details rather than comparing multiple options. It provides useful context for when to call it, though it does not explicitly state exclusions or point to an alternative tool.

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?

Annotations already mark the tool as read-only and non-destructive, and the description adds meaningful behavioral context: quiz mode withholds answers, study mode adds explanations and regulatory citations, and questions come from Rotate Pilot's reviewed bank in an FAA-like format. No contradiction with annotations exists, and the description goes beyond what the annotations alone provide.

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?

Two sentences carry all the essential information: the first front-loads the main behavior and constraints, and the second compactly defines both modes. There is no filler, repetition, or unnecessary restatement of schema enums.

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 four parameters, the description is largely complete: it covers purpose, exam scope, optional area filtering, count limits, and mode-specific return contents. It does not specify the exact JSON response shape or any randomness/ordering behavior, leaving a small amount of inference 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 description coverage is only 50%, because mode and count lack descriptions. The description compensates by explaining mode=quiz versus mode=study, noting the count range of 1-10, and clarifying the optional area/topic filter. This adds practical meaning to the under-documented parameters.

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 opens with a specific verb and resource: 'Returns 1-10 multiple-choice practice questions' and adds concrete details like 3 options, the reviewed question bank, and the eligible exams (Part 107, PPL, IFR, CPL, ATP). This clearly distinguishes it from siblings like check_answer, exam_facts, or study_plan even without opening the schema.

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 gives clear mode-level guidance: mode=quiz returns questions without answers, while mode=study includes answers, explanations, and citations. However, it does not explicitly explain when to choose this tool over sibling tools such as check_answer, exam_facts, or study_plan, nor does it state any exclusions or prerequisites.

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?

Annotations already communicate read-only, idempotent, and non-destructive behavior, so the description does not need to restate those. It adds genuinely useful behavioral context: per-area results, FAA-weighted scoring for Part 107, pass-mark comparison, correct answers with explanations, and a suggested next step. There is no contradiction with the annotations.

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 a single, front-loaded sentence that begins with the core action and then packs the return-value details into a clear list. Every clause carries meaningful information and there is no filler.

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?

There is no output schema, so the description reasonably enumerates what the tool returns: overall and per-area scores, weighted Part 107 scores, areas below pass mark, explanations, and a next step. It omits error-case behavior and answer-format details, but for a read-only scoring tool with annotations already covering safety, the context is largely complete.

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?

The schema documents the exam enum values well, but the answers parameter is only described as an array in the schema, and the description adds little beyond 'a set of answers' and 'each question.' With only 50% schema coverage, the description should compensate for the missing answers semantics, but it does not explain how answer values map to question_id or what constitutes a valid answer.

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 states a specific action and resource ('Scores a set of answers to a Rotate Pilot readiness diagnostic') and enumerates the outputs in detail, including the Part 107 weighting nuance. It is clearly distinguishable from siblings like check_answer and practice_questions, though it does not explicitly name them.

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 implies the tool is for scoring a full answer set from a readiness diagnostic, and the required exam and answers parameters reinforce that context. However, it does not explicitly say when to use this tool over alternatives such as check_answer or diagnose, nor does it state any exclusion criteria.

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?

Annotations already convey readOnlyHint, idempotentHint, and non-destructive behavior, so the bar is for added context. The description adds valuable behavioral detail: it does not charge anything and hands payment to the user's browser, plus it may return the plans page instead of a checkout link. This meaningfully clarifies side effects beyond the annotations.

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?

Two sentences with no filler, front-loading the core return value and immediately clarifying the no-charge behavior. Every clause earns its place, and the fallback behavior is included without redundancy.

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 simple two-parameter tool with full schema coverage and strong annotations, the description is nearly complete: it covers the return type, the no-charge side effect, and the fallback path. It could explicitly state the return shape (a URL string) or mention the tier default, but the schema already documents the tier, so nothing critical is missing.

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 the baseline is 3: the enum parameter descriptions already explain exam codes and the tier limitation to Part 107. The description itself adds no parameter-level detail beyond 'an exam', but because the schema is fully self-documenting, it does not 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?

Description states a specific verb ('Returns') and resource (direct purchase link / Stripe Checkout for a named exam), and clearly distinguishes this from broader sibling tools by spelling out the exact deliverable. The fallback to the plans page adds precision about scope.

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 implies when to use the tool: whenever a purchase link for a Rotate Pilot prep is needed, with a conditional fallback for exams without one-click checkout. However, it does not explicitly compare against sibling tools such as get_offer, so an agent must infer the boundary between them.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral detail beyond annotations: it notes that lessons are included 'where available' (i.e., some areas may lack coverage), that the plan personalizes via 'weak areas', and that free FAA references are appended. This gives an agent a better sense of what the tool will and won't produce.

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 a single dense sentence that front-loads the core purpose ('Builds a dated study plan from today to the exam date') and then lists the plan components. It is efficient, but the parenthetical about Part 107 makes the sentence slightly convoluted and could be clearer with better structuring.

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 tool with 3 parameters and no output schema, the description covers the plan's structure well but leaves gaps: it does not mention the hours_per_day parameter or its effect, does not clarify what 'weak areas' means or whether a prior diagnostic is required, and does not describe the return format. Annotations cover safety but not these operational details.

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 67% (exam and exam_date are described; hours_per_day is not). The description adds some context around exam_date ('from today to the exam date') and mentions 'Part 107' which partially aligns with the exam enum, but it does not explain hours_per_day or how it affects the plan. Since the schema already documents most parameters, the description provides only marginal additional parameter semantics.

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 a specific verb ('Builds') and resource ('dated study plan'), with a detailed breakdown of what the plan includes. However, the parenthetical '(Part 107 in proportion to the official FAA weights)' is confusing because the tool accepts multiple exam types (ppl, ifr, cpl, atp) and the description does not clarify whether this applies only to part107 or to all exams.

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 provides clear context for when to use the tool: when a user needs a day-by-day study plan leading up to an FAA exam date. It does not explicitly mention alternatives or exclusions, but none of the sibling tools (e.g., exam_facts, compare_prep_options) appear to offer the same functionality, so 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.