Drivings

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds that it does not create an account, learner session, purchase, or message, and notes determinism and boundedness—extra behavioral context beyond annotations. No contradiction.

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 short sentences: the first states the core action, the second states side-effect guarantees. Both sentences are purposeful and free of 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?

With an output schema present and parameter enums, the description covers the key side-effect guarantees and determinism. It doesn't explicitly state usage context versus alternatives, but the schema and sibling names provide enough for an agent to invoke it correctly. Slightly incomplete on when to use, so not a 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 description coverage is 0%, and the description provides no parameter-specific detail. While property names like weeks and daysPerWeek are self-explanatory, the description doesn't compensate for the lack of schema descriptions—it doesn't explain how region or course affect the schedule or what 'bounded' means for the numeric fields.

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 'Compute a deterministic, bounded study schedule' with a specific verb and resource, and the title clarifies it's a preview. This distinguishes it from siblings like list_study_options and get_driving_guide, which list or retrieve rather than compute.

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 alternative tools are mentioned. The note that the preview is not saved implies use for trial calculations, but this is indirect. The agent is left to infer usage context from the sibling names.

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 read-only and non-destructive behavior. The description adds valuable context about results ('Returns evidence') and the unusual 'optional confirmation-required official browser handoffs', which goes beyond the annotations and clarifies the tool's side-effect-free nature.

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: the first front-loads the primary action and scope, the second adds a key boundary. There is no redundancy or filler, making it highly efficient.

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 structured output schema and annotations, the description adequately covers behavioral scope (search, evidence, optional handoffs, no booking) and search criteria. It omits details like pagination or limit behavior, but these are largely inferable from the schema, making it complete enough for agent selection.

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 0%, so the description must compensate. It explains what the query parameter can match (name, locality, address, etc.) and 'UK or US' maps to region. However, the 'service' and 'limit' parameters are not addressed, though their schema enums and defaults make them fairly self-explanatory.

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 ('Search') and a clear resource ('source-backed UK or US test-centre directory'), while enumerating searchable fields (name, locality, address, postcode/ZIP, alias, identifier). It distinguishes itself from siblings by focusing solely on test-centre lookup and explicitly notes it never books or changes a test.

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: searching for test centres in the UK or US. It also states a clear exclusion ('Never books or changes a test') but does not explicitly name alternatives or elaborate on when not to use it relative to sibling 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?

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds value by disclosing what content is included ('bounded Markdown content, update metadata, primary-source review details') and explicitly excluding access to private learner data, which goes beyond the structured annotation fields.

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 no filler. Every sentence contributes meaningful detail (content scope, privacy boundary).

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?

With an output schema present, the return value is already covered. The description provides enough about data scope and privacy for a simple retrieval tool, but the missing region semantics and lack of guidance toward search_driving_guides make it slightly incomplete.

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 0%, so the description must compensate. It mentions 'by slug' but does not explain the 'region' parameter at all, nor does it clarify how region interacts with slug selection. The agent gets little semantic guidance beyond the schema's enum and pattern constraints.

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 ('Retrieve') and resource ('one published Drivings guide by slug'), clearly distinguishing it from sibling tools like search_driving_guides. It also names content categories ('bounded Markdown content, update metadata and primary-source review details'), sharpening the 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 context is clear: this tool is for retrieving a single known guide by slug, and the note 'It does not access private learner data' sets expectations. However, it does not explicitly mention alternatives like search_driving_guides for finding slugs, so it falls short of a 5.

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 and destructiveHint, but the description adds the explicit requirement of Drivings sign-in and OAuth consent, which is beyond what annotations provide. It also reinforces non-mutating behavior, though that partly duplicates 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 two sentences, front-loaded with the main action ('Read...'), and every sentence adds value: purpose, auth requirement, and safety guarantee. 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?

For a zero-parameter read tool with an output schema, the description fully covers purpose, authentication, and safety. It does not need to explain return values because an output schema exists. The context is complete for an agent to select and invoke 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 input schema has zero parameters, so the baseline is 4. The description correctly does not attempt to document parameters that do not exist, and it clarifies the data scope (profile, target, activity) instead.

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 reads the connected learner's Drivings profile, study target, and recent learning activity. This specific verb+resource combination distinguishes it from siblings like get_driving_guide or find_test_centres.

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 that this tool is for reading a connected learner's overview and adds an authentication prerequisite (sign-in and OAuth consent). It does not explicitly discuss when not to use it or name alternatives, but the context is sufficient.

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 and idempotentHint, so the read-only nature is covered. The description adds critical context: it triggers a confirmation-required browser handoff and does not start or save onboarding, which is unexpected for a list operation. This goes beyond the annotations and reveals a side effect, earning a 4.

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 the core action, and contains no unnecessary words. The first sentence states the purpose, and the second adds important behavioral nuance, making it highly efficient.

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?

With a single parameter, an output schema, and robust annotations, the description sufficiently covers the tool's behavior, including the unusual handoff detail. It is complete enough for an agent to select and invoke the tool correctly, and the output schema handles return value documentation.

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 0%, but the description explicitly mentions 'for the UK or US,' which directly aligns with the region parameter's enum values. This compensates for the lack of schema descriptions and makes the parameter's purpose clear, though it does not explicitly name the parameter.

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 lists study courses for the UK or US, using a specific verb 'list' and a resource ('study courses'). It distinguishes itself from sibling tools like search_driving_guides and get_driving_guide, which serve different purposes.

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 context that this tool lists courses and returns a browser handoff, but it does not explicitly state when to use it over alternatives or exclude sibling tools. The scope (UK/US) is clear, but without direct alternative guidance, usage is implied rather than explicitly directed.

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 the operation as read-only, idempotent, and non-destructive. The description adds valuable behavioral context by stating the return content (metadata, update dates, canonical URLs) and explicitly ruling out private learner data access. This goes beyond the annotation hints and gives the agent clear expectations about side effects and data boundaries.

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, well-structured sentence that front-loads the core purpose, then efficiently adds return-type and privacy information. There is no redundant or filler content, and the extra detail is directly relevant to an agent's decision-making. The minor typo 'Drivings' does not detract from clarity.

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?

With an output schema present, the description does not need to detail return structure, but it still provides a summary of returned fields (metadata, update dates, URLs) and the non-access to private data. It also covers the main user intent (search by topic/question) and is sufficient given the tool's low complexity. Lacks mention of pagination or sorting, but these are not necessary for basic usage.

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 0%, so the description was expected to compensate. It explains that the query parameter can be a topic or question, which adds some semantic meaning, but it does not mention the required 'region' parameter or the optional 'limit' parameter. The schema's enum values (uk/us) and limits are self-explanatory, yet the description still leaves the purpose of region and the tuning behavior of limit to inference.

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 purpose with a specific verb ('Search'), a defined resource ('published driving guides'), and the search mechanism ('by topic or question'). It also distinguishes itself from sibling tools by specifying that it returns concise metadata rather than full guide content, and explicitly notes it does not access private learner 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 implies use when the agent needs to find guides by topic or question, and the boundary 'does not access private learner data' provides a clear exclusion. It does not explicitly name sibling tools or state 'use this instead of X', but the context of sibling tools (e.g., 'get_driving_guide') strongly implies the search-for-listing versus retrieve-specific-guide distinction.

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