Yank

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral context beyond annotations: it explains the bounded nature of NOT FOUND, that CLOSE MATCH lists differing tokens rather than a similarity number, that no model is consulted, and that audio requiring transcription returns CAN'T ESTABLISH with acquisition_required. This is rich, non-obvious behavior that an agent needs to interpret verdicts 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?

The description is dense and information-rich, front-loading the verdict taxonomy and then adding behavioral caveats. Every sentence earns its place, though the length is substantial. It is structured logically: verdicts first, then evidence details, then limitations and exclusions. Slightly long but justified by the complexity of the tool's output semantics.

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 2 parameters, no output schema, and complex verdict semantics, the description is remarkably complete. It covers all verdicts, the evidence returned, the scope of inspection, the handling of different source types, and the exclusion of audio requiring transcription. An agent has everything needed to call the tool correctly and interpret its results.

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 the schema already documents both parameters. The description adds meaning by explaining that 'statement' is 'one claim at a time, up to 600 characters' and that 'source' is 'the public http(s) link the statement is supposed to come from.' It also clarifies the relationship between the two parameters: the source is what the statement is checked against. This goes beyond the schema's field 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 states a specific verb ('check') and resource (a statement against a source), and enumerates the five verdicts with precise definitions. It distinguishes itself from sibling tools by describing the full verdict taxonomy and the bounded nature of NOT FOUND, which no sibling name suggests.

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 says when to use this tool: for checking a statement against a source, and when not: audio needing transcription should be yanked first, and sources Yank already holds check immediately. It also clarifies that no model is consulted and that verdicts are not truth judgments, which prevents misuse.

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 readOnly, idempotent, and non-destructive, and the description adds substantial behavior beyond them: equivalent URLs return the same answer (URL normalization/determinism), 'zero yanks is an answer, not an error' (empty-result semantics), 'for up to five yanks' (truncation cap), and 'never fetches the source' (side-effect guarantee). 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?

Four sentences, each earning its place and front-loaded in order: purpose, parameter semantics, return format/empty semantics, and safety guarantee. The parenthetical URL-form list is long, but it justifies its length by making the hard-to-guess normalization behavior concrete.

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 must carry the return contract, and it does: real counts (yanks, lines, verbatim lines) plus per-line details for up to five yanks. It also covers empty-result semantics, the truncation cap, and the no-fetch safety guarantee, leaving nothing missing for a single-parameter, read-only 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 is 100%, but the description converts the schema's generic 'in any of its forms' into actionable specifics: youtu.be timestamp short links, playlist watch URLs, tracking-parameter-laden articles, Apple Podcasts/Overcast episodes. It also attaches the normalization guarantee to the sole parameter, materially enriching the single url field.

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?

Opens with the directive 'Ask before you extract' and names the resource precisely: 'everything yank.info already holds from one source URL.' The breakdown of return values (counts, lines, verbatim flags, timestamps, moment links, card URLs) makes the scope concrete, and the strict one-URL focus differentiates it from the search/quote siblings without needing to 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?

'Ask before you extract' frames the tool as a pre-extraction lookup, giving clear workflow context for when it should be called first. However, no sibling tool is mentioned, so there is no explicit when-not-to-use routing; the boundary versus search_lines and get_yank must be inferred from the 'one source URL' vs. query/ID framing.

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 readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so safety is covered. The description adds valuable behavioral context beyond annotations by enumerating the response contents (verbatim flag, timestamp, moment link, surrounding context, permanent card URL, share image, and Markdown), which helps the agent anticipate the output structure. 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?

The description is a single, compact sentence that front-loads the action and then lists the included data fields. It is informative without being verbose, and every clause contributes to understanding the tool's function and output. The structure is clear and easy to scan.

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 single-parameter tool with annotations covering safety and no output schema, the description is fully adequate. It covers what a yank is, how to identify it, and what the response includes. There are no missing pieces that would prevent an agent from calling the tool correctly. Even without an output schema, the description preemptively details the return payload.

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 provides a single 'slug' parameter with an example, but the description adds semantic meaning by explaining the slug is 'the last path segment of a yank.info/y/<slug> URL'. This clarifies how to derive the value, going beyond the schema's example. With 100% schema coverage, the description adds supplementary context that improves 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?

The description clearly states the verb 'Fetch' and the resource 'a yank', and details exactly what is retrieved (five extracted lines, verbatim flag, timestamps, etc.). It defines the identifier (slug) as the last path segment of a yank.info/y/<slug> URL, making the tool's function unambiguous and distinct from sibling tools like search_lines or recent_yanks.

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 should be used when you have a specific slug and need comprehensive details of a single yank. However, it does not explicitly mention when not to use it or compare with sibling tools like check_quote or get_lines_for_url. There is no guidance on alternative selection, but the required parameter and identifier format make the usage 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 declare readOnlyHint, idempotentHint, and destructiveHint, so safety behavior is covered. The description adds useful output-format context (one card each with specific fields) and implies recency ordering, which goes beyond the structured data. It does not mention pagination or limit effects, but those are minor for a read-only listing.

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 sentence that front-loads the core purpose ('newest yanks') and packs the key output detail into a parenthetical. There is no redundant wording or 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 simple read-only listing tool with one parameter, the description plus annotations and schema provide enough to call it correctly. It specifies the output structure and the ordering, though it omits any usage boundary with sibling tools and does not clarify that limit controls how many cards are returned.

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 description never mentions the 'limit' parameter, and schema_description_coverage is 0%. Even though the schema fully constrains the parameter with default, minimum, and maximum, the description adds no semantic meaning or guidance about how the limit behaves in relation to the returned cards.

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 returns the newest yanks in the library and specifies the card structure with rank-1 line, author, source type, and URL. It does not explicitly contrast itself with sibling tools like get_yank or search_lines, so it stops short of full differentiation.

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 guidance is provided about when to use this tool versus alternatives such as get_yank, search_lines, or get_lines_for_url. There are no conditions, exclusions, or hints about when this tool is preferred, leaving the agent to infer from the name alone.

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, so safety is covered. The description goes beyond by detailing the exact return structure (verbatim flag semantics, source, timestamp, moment link, permanent URL) and query capabilities (quoted phrases, negation), giving the agent concrete expectations beyond the structured 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?

The description is dense but efficient: it front-loads the core function, then lists output fields, then query syntax. There is no fluff or redundancy; every sentence contributes essential information, making it highly scannable for an agent.

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 search tool with no output schema, the description covers scope, return fields, and query syntax sufficiently. It does not mention pagination or sorting, but the limit parameter is present and defaults are known. Minor gap: no explanation of what happens when no results are found, but this is acceptable for typical search 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 coverage is 50% (only query has a description). The description enriches query semantics by explaining quoted-phrase and minus-exclusion syntax, which is valuable. However, the limit parameter is undocumented in both schema and description, and the description does not address it, so compensation is incomplete.

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 performs full-text search across every line yank.info has ever extracted, and enumerates the returned fields (verbatim flag, speaker, source, timestamp, moment link, card URL). This unambiguously distinguishes it from siblings like get_lines_for_url or get_yank, which target specific URLs or yanks.

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 as a general search over the whole corpus but does not explicitly state when to use it vs. alternatives like check_quote or recent_yanks. It mentions query syntax (quoted phrases, minus) but offers no exclusions or comparison to sibling tools, leaving the choice to inference.

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