Yappy

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds meaningful context beyond annotations: it returns the reasons and enforces the installer's actual compatibility rules, so the answer matches reality. This gives the agent useful behavioral expectations without contradicting any annotation.

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 concise sentences: the first states the purpose and required inputs, the second gives usage guidance and the benefit. Every sentence earns its place with no fluff or 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, well-schema-documented tool with four rich annotations, the description covers the task, inputs, output (reasons), and the reason this tool should be trusted. There is no output schema, but the description explicitly says the return will include reasons, giving enough context for an agent to invoke and interpret it.

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 the description repeats only that the tool uses 'macOS version and CPU architecture,' which maps directly to os_version and arch. It adds no new parameter meaning beyond the schema, 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.

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

States a specific verb ('Decide'), the exact resource (a specific Mac running Yappy), the inputs (macOS version and CPU architecture), and the output (reasons). This clearly differentiates it from the sibling get_system_requirements, which would provide general requirements rather than a compatibility verdict.

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 recommends using this tool instead of manually reasoning about requirements, and explains why: it encodes the same rules the installer uses. It does not name sibling alternatives or state when not to use it, but the guidance strongly narrows when the tool is appropriate.

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 readOnlyHint=false and destructiveHint=false, and the description adds meaningful behavior: the operation is asynchronous, returns a job id, must be polled until completed, and exposes result.url. It explicitly guarantees no user data is touched and nothing can be deleted. It could add failure or status details, but this is strong coverage beyond annotations.

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

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

Four sentences, all high-signal: purpose, workflow, when-to-use, and safety. Front-loaded with the core action, then proceeds to actionable details 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?

With no output schema, the description supplies the needed contract: returns a job id, poll until completed, read result.url. Together with full parameter schema and use-case guidance, an agent has enough to call and process the result 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 already has 100% description coverage, including enums for resource and format and a clear idempotency_key description. The tool description repeats those values but does not add meaningful new semantics beyond mapping the async workflow to the parameters. Baseline 3 applies.

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 starts with a specific verb-resource pair: 'Start an asynchronous export of a Yappy corpus', then enumerates the corpus types (documentation, FAQ, release history) and output formats (markdown, JSON). It also names the polling sibling get_export_job, which clearly distinguishes this job-creating tool from the read-oriented siblings.

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 an explicit use condition: 'Use it when you want the whole corpus rather than a page at a time', which implies not for single-page grabs. It also routes the agent to get_export_job for polling and clarifies the tool creates a job and nothing else, giving a clear boundary versus other data-access 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 mark the tool as read-only and idempotent. The description adds meaningful behavioral detail beyond that: the status progression (queued, running, completed), the result.url field on completion, and the retry_after rate-limiting hint. This is exactly the kind of context an agent needs to poll correctly.

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 with no filler: the opening identifies the operation, the second explains the lifecycle and output, and the third provides actionable polling guidance. Every sentence earns its place and the key 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 single-parameter polling tool with no output schema, the description covers the essential contract: how to identify the job, what states it goes through, what a successful result looks like, and how fast to poll. Nothing critical is missing for correct 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%, and the job_id parameter is already described as 'The id returned by create_export_job.' The description reinforces this by saying the job must come from create_export_job, but it doesn't add new parameter-level information beyond what the schema provides, so 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?

States a specific verb ('Check') and resource ('an export job started with create_export_job'), making the tool's role unambiguous. It also distinguishes itself from create_export_job by explicitly framing this as following up on a job created there.

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 clear context: the job must have been started with create_export_job, and polling should respect the retry_after hint. It doesn't explicitly list when-not-to-use or name alternatives, but the pairing with create_export_job and the polling guidance give sufficient direction.

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 safe read-only nature is known. The description adds that results are short Q&A pairs and authoritative, which gives a hint about response character, but discloses nothing about filtering behavior, pagination, or any other runtime trait beyond what is obvious.

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 zero extraneous content. The primary action and output format are front-loaded, followed by a compact list of covered topics and a single, useful use-case sentence.

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, read-only FAQ lookup with one optional parameter and no output schema, the description covers the output format, topical scope, and when to use it. The only minor gap is that the description does not explicitly mention the topic parameter's filtering capability, but the schema fully covers that, 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% and the single parameter has an enum with its own description ('Return only entries on this topic.'). The tool description mentions some topics (privacy, requirements, cost) but does not map them precisely to the enum values (privacy, requirements, pricing, comparison, developers), so it adds no meaningful semantics 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?

States a specific verb ('Get'), a concrete resource ('the Yappy FAQ'), and a clear output format ('question and answer pairs'). It also enumerates topical coverage (privacy, requirements, cost, permissions, offline use, comparison), making the tool's scope immediately understandable. The contrast with 'a documentation page' further sharpens the purpose.

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 a clear usage context: 'Useful when you want a short authoritative answer rather than a documentation page.' This tells an agent when the tool is appropriate relative to documentation retrieval, but it does not explicitly name sibling tools or state when not to use alternatives like get_pricing_plans or get_system_requirements.

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, destructiveHint=false, covering safety. The description adds meaningful behavioral context: it 'reads the same signed appcast the app updater reads, so the answer is never a stale hand-edited number,' which informs the agent about freshness and data source.

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, each earning its place: first defines the result, second explains the source/freshness, third gives the usage trigger. Front-loaded with the core purpose, 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?

For a one-optional-parameter read-only tool with no output schema, the description is complete: it lists return fields, data source, freshness guarantee, and when to use it. Nothing an agent needs to call it correctly 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 coverage is 100% for the single optional include_notes parameter, with its own clear description and default. The tool description does not need to add parameter details; the schema carries the burden, so baseline 3 applies.

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?

States a specific verb and resource ('Get the current Yappy release of the Yappy macOS app') and enumerates the returned fields (version number, publication date, release notes, download URL). The singular 'current' distinguishes it from sibling list_releases, so an agent can tell them apart.

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: 'whenever a user asks what the newest version is or where to download Yappy.' It doesn't explicitly say when not to use or name alternatives, but the trigger context is clear and sufficient for this simple read 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 establish read-only, idempotent, non-destructive behavior; the description builds on this by warning that many costs may be zero, preventing incorrect assumptions about paid plans. It does not describe return structure, but that is acceptable given the simple retrieval nature and strong 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?

Two sentences with no wasted words. The first sentence lists exactly what the tool returns, and the second gives actionable usage guidance. Everything included 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 one-parameter, read-only pricing lookup with rich annotations, the description fully enables an agent to decide when to call it and what it will contain. The lack of an output schema is not a gap since the returned pricing info is naturally described by the tool's purpose.

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 only parameter, include_backends, is already fully documented in the schema with a default and a clear explanation. The tool description mentions per-backend costs but adds no semantic detail beyond what the schema provides; the schema carries the load here.

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?

States the exact resource being retrieved: the Yappy app's free Mac app, per-backend language-model costs, and public API terms. This clearly distinguishes it from siblings like get_frequently_asked, list_product_features, and get_system_requirements, which address different information needs.

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 an explicit trigger: 'Call this before telling a user about price.' It also adds important context that most of the product is free and some backend options cost nothing, so the agent should not assume paid pricing. Though it doesn't name alternatives, the sibling set makes the pricing tool's unique role obvious.

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 useful content-level context, especially that permission consequences are included ('what breaks if it is denied'), but it does not discuss caching, freshness, or error behavior. 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?

One dense, well-structured sentence front-loads the core purpose and then lists exactly what categories of information the response will contain. Every part of the description earns its place, with no filler or repetition.

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 read-only tool with one optional, fully documented parameter and no output schema, the description gives enough detail for an agent to call it correctly. It names all the major content areas, and the optional parameter behavior is fully covered by the input schema.

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 the permissions_only parameter already has a clear schema description. The tool description does not add parameter-level meaning beyond the schema, 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.

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

The description names a specific verb ('Get'), a clear resource (Yappy system requirements), and a precise scope: what a Mac needs before Yappy runs. It enumerates the exact contents — macOS version, CPU architecture, install size, and permission details — so an agent can easily distinguish it from siblings like get_pricing_plans or create_export_job.

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 guidance about when to use this tool versus alternatives such as check_mac_compatibility, and no exclusions are stated. The phrase 'before Yappy will run on it' implies a requirements-checking use case, but the tool does not communicate when not to use it or what makes it the preferred choice.

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, openWorldHint, idempotentHint, and destructiveHint false. The description adds useful behavioral context beyond that by specifying that results are structured objects rather than marketing bullets and by enumerating the meaningful feature attributes returned.

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 needed information with no filler. The verb and resource are front-loaded, the output shape is enumerated compactly, and the stated use case justifies the tool's existence.

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?

Even though there is no output schema, the description fully enumerates the returned fields, which compensates for the missing schema. The optional filter is fully documented in the input schema, and the annotations cover safety and idempotency, so nothing essential 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?

The schema covers the single optional on_device_only parameter with a complete description at 100% coverage, so the description does not need to add parameter explanation. The description adds no parameter-level meaning, but none is necessary here.

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 action (list), the resource (Yappy features), and the exact shape of the returned objects: id, name, description, on-device status, network requirement, and macOS permission. This distinguishes the tool from siblings like get_system_requirements or get_pricing_plans.

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 a concrete use case: building an accurate comparison against another dictation tool. It does not name explicit alternatives or exclusions, but the sibling set makes the intended context clear enough.

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 cover read-only, open-world, idempotent, and non-destructive behavior. The description adds that results are newest first and include specific fields, providing helpful expectations for the response. This goes beyond annotations without contradicting them.

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 fluff. The first sentence front-loads the core purpose and scope, the second gives usage guidance. Every word 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 read-only list tool with one optional parameter, the description covers purpose, scope, ordering, and returned fields. The only minor gap is no mention of pagination beyond the limit, but the schema's default and max cover that. Complete enough for an agent to call 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 fully documents the limit parameter with type, default, min, max, and description (100% coverage). The description does not add extra meaning to the parameter, but that is not necessary given the schema's completeness. 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 (List), a resource (Yappy release history for macOS), and the content returned (version, publication date, and changes). It clearly distinguishes from the sibling get_latest_release by covering history rather than just the latest release.

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 explicit usage guidance: 'Use this to answer questions about what shipped recently or when a particular fix landed.' It does not explicitly name the alternative get_latest_release, but the usage context implies when this tool is appropriate, so the guidance is clear but lacks explicit exclusions.

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