Token Tender

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description still adds non-obvious behavior: it fetches exactly one public file and results are cached for a day, which tells the agent to expect stale data and no side effects.

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

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

Three short sentences, front-loaded with the use case, then output shape, then cost/caching. No filler and nothing repeated from structured fields.

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?

An output schema exists, so return values need not be spelled out, yet the description still previews the verdict-per-crawler shape and the shareable page. Caching and single-fetch cost complete what an agent needs before calling.

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 schema itself documents the domain format (no ports, no IPs, 253-char cap). The description only says "a website," adding nothing beyond the schema, 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: reads a domain's robots.txt and returns a per-crawler AI-bot verdict. The named crawlers (GPTBot, ClaudeBot, Google-Extended, CCBot) make the output concrete, and no sibling tool overlaps with this function.

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?

"Use this when you want to know which AI crawlers a website bans" gives an explicit triggering condition. It does not name exclusions or alternatives, but the sibling list contains nothing comparable, so there is no ambiguity to resolve.

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 safety (readOnly, idempotent, non-destructive), so the 'Read only' sentence adds nothing. The description does contribute real context beyond the annotations: the coverage boundary of 64 common codes, including named Cloudflare 520/522/524, which tells the agent this is a bounded lookup rather than a general HTTP reference. It stops short of saying what happens for codes outside that set.

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 triggering situation before the return contract. Every clause carries information; the trailing 'Read only' is the only redundant fragment and it costs nothing.

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 needn't detail return values, and it still summarizes them accurately. Coverage is bounded to 64 codes without stating behavior for unlisted codes, which is the only real gap for a one-parameter lookup 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% and the single parameter is fully documented with range and examples (429, 503), so the schema carries the load. The description adds no format or edge-case guidance for the code input beyond the Cloudflare examples, 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 (explain) and resource (HTTP status code) and spells out the three things it returns: meaning, corrective action, and retry decision. The agent can tell exactly what class of question this tool answers.

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?

Opens with an explicit trigger condition — 'when a request failed with an HTTP status code and you need to know what it means, what to change, and whether retrying is safe.' No exclusions or alternatives are named, but the sibling tools are unrelated, so there is no realistic confusion to resolve.

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, non-destructive, closed-world, so safety is covered. The description adds useful content disclosure — that the payload includes pours, tiers, token ranges and house rules — which is genuine value beyond the annotations, though it stops short of stating format, size, or freshness.

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?

It is short and front-loaded, but the second and third sentences trade clarity for atmosphere: "the lines you have to order to hear" conveys little concrete information. Some of the flourish could be spent on a plain statement of what the menu returns.

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 annotations covering safety and idempotency, the description needn't explain returns. However, for a reference/discovery tool that presumably anchors the whole bar workflow, it is under-complete: the relationship to ordering siblings (pour, check_the_door) is left entirely implicit.

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 tool takes zero parameters and the schema is trivially complete, so there is nothing for the description to disambiguate. Baseline 4 applies for a no-parameter tool.

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 the resource ("The menu") and gestures at its contents — pours, tiers, token ranges, house rules — which hints at what it returns. But it stays in metaphor ("the lines you have to order to hear") rather than stating a concrete verb-and-resource purpose, and does not clearly distinguish it from siblings like pour or my_tab.

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 lines you have to order to hear" weakly implies you read this before ordering, but there is no explicit when-to-use, no when-not-to-use, and no named alternative (e.g., versus pour or recent_orders). An agent must infer that this is the discovery/reference call.

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

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

The annotations already establish read-only, idempotent, non-destructive, closed-world behavior. The description repeats 'Read only' and summarizes outputs, but adds little behavioral context beyond annotations and the output schema.

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 front-loaded with the use case, then summarizes the return values and safety profile. It is compact and every sentence contributes 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?

With a fully described single parameter, complete safety annotations, and an output schema, the description provides enough context for an agent to invoke the tool correctly. No critical invocation detail 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 sole 'name' parameter is fully documented in the schema. The description adds no additional parameter semantics, 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 clearly identifies a personal bar-stats resource and lists what it returns, so an agent can understand its purpose. It does not explicitly distinguish itself from siblings like regulars or recent_orders, which keeps it below a 5.

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?

It gives a clear usage condition: use when you want to know how often you have been to the bar. It does not say when not to use it or name alternative tools.

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

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

Annotations already cover readOnly/idempotent/openWorld, so the bar is lower; the description nonetheless adds the useful 'cached a minute' freshness guarantee and enumerates the shape of the result (level, open incidents, advice). It stops short of explaining how advice maps to level, but nothing is contradicted.

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 tight sentences, front-loaded with the trigger condition, then the data source, then the return shape. 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?

With an output schema present the description need not explain return values, and annotations cover safety. What remains — freshness, the advice vocabulary, and the whole-board mode — is all supplied, so an agent has everything needed to call 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?

Schema coverage is 100% and the single enum parameter is fully documented there, so the schema does the heavy lifting. The description's 'omit provider for the whole board' largely restates the schema's own 'Omit to get all six', adding little new syntax or meaning.

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 question it answers (is Claude/OpenAI/GitHub/Cloudflare/Vercel/Perplexity having an incident right now) and names its data source (public status pages). No sibling tool in the list does anything similar, so it is trivially distinguishable.

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?

'Use this BEFORE you retry a failing call or page your human' is an explicit trigger condition rather than a vague suggestion. It also explains the omit-provider case for the whole board, leaving no ambiguity about when to call it.

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 mutation without destructiveness or idempotency. The description adds real behavioral context beyond them: there is a server-side timing measurement anchored to the first pete_site call, and repeating the call is implicitly consequential. It does not explain what the booking consumes or what failure looks like, but the return shape is covered by the output schema.

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 short sentences, front-loaded with the action, and each clause carries a distinct payload (what, call count, timing origin). Nothing is redundant.

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 annotations covering the safety profile and an output schema covering returns, the description supplies what structured fields cannot: timing semantics and the pete_site anchor. Minor gap: it never states that name is optional or what happens if the slot is already taken.

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 schema itself explains the name filtering/truncation and the single-slot enum, so the description needs to add little. It only echoes the 4:00 slot value and says nothing about the optionality of name, so the 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 concrete verb and resource ("Book Pete's 4:00 slot") and ties it to the sibling pete_site as a prerequisite, so an agent can place it relative to the other tools. The nature of the 'booking' remains flavor-obscured, but the action is identifiable.

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?

"One call" plus "the server measures from your first pete_site call to this booking" implies a sequencing rule (call pete_site first) and a non-repeat rule. It stops short of explicitly naming when-not to invoke or what a second call does, so it is not a full 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/idempotentHint, so safety is covered; the description adds two real behavioral facts the annotations lack — output is plain text, and the call has a side effect on pete_book's timing. However, "starts the clock" is never explained (timer? deadline? scoring?) and sits in tension with idempotent/read-only framing, so the added context is suggestive rather than actionable.

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 short fragments, no filler — but also no front-loaded statement of what the tool returns. Brevity here shades into cryptic rather than efficient; the sentence 'Plain text.' carries more weight than its two words can bear.

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, return values need no prose, and a zero-parameter read tool is a simple case, so the bar is low. Still, the one non-trivial behavior mentioned (clock start for pete_book) is left opaque, which is the one thing an agent would actually need explained before deciding to call 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?

The tool takes zero parameters and the schema correctly declares an empty object, so there is nothing for the description to disambiguate. Baseline 4 applies; no parameter text is needed or missing.

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?

"Leaky Pete's Plumbing, rebuilt for agents. Plain text." implies a text-rendering fetch of a themed site, which is enough to guess the action, but the description never states plainly what is retrieved or how it differs from other content-reading siblings (menu, my_tab, recent_orders, todays_discourse). The agent must infer the resource from the title alone.

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/when-not and no named alternative. The only routing information is the trailing "Starts the clock for pete_book", which hints at sequencing with one sibling but is not framed as a usage rule.

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 say this is non-destructive, non-idempotent, and not read-only, but the description adds substantial context: the caller will not hear it, it plays only for humans with sound on, the label shows the picker's name and door, playback is one 60-second loop, and there are rate/queue limits with no skips. These are exactly the behavioral details an agent needs before invoking a whimsical side-effect tool.

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 front-loaded with the action, follows with the audience/effect, then packs constraints into a single tight sentence. There is no wasted language, and the whimsical tone does not obscure the operative facts.

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 output schema and rich parameter descriptions, the description supplies the remaining behavioral context: audience, non-audibility to the caller, label contents, loop length, rate limit, queue cap, and no-skip policy. Nothing critical for a 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%, so the schema already documents both parameters and the track enum meanings. The description adds only a light hint that the name appears on the label; it does not deepen understanding of the track parameter or the filtering behavior beyond what the schema 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?

States a specific verb and resource (put a record on the clay jukebox) and immediately clarifies its effect: it plays for humans in the room rather than the caller. This distinguishes it from related siblings like whats_playing or pour without needing to open their schemas.

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 use case clearly (play a song for people in the room) and provides operational constraints like one song a minute and a three-deep queue. However, it does not explicitly name when to use this versus whats_playing or other media-related siblings, nor does it state exclusions.

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 idempotency, non-destructiveness, and a closed-world non-read-only operation. The description only reinforces idempotency via 'Same name and same story, same pour' and hints at output shape with 'named pour' and 'says one line'; it does not disclose what is persisted or how the mutation behaves beyond that. 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 only three sentences and is front-loaded with the action, with no filler or repetition. Its economy is good, though the metaphorical wording costs some clarity rather than adding wasted length.

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?

An output schema exists and the parameter schema is extremely rich, so the description does not need to explain return values or every parameter. Still, for an 8-parameter tool with nested tilt mechanics, the description does not clarify whether story or error is required or when to use one over the other, leaving meaningful invocation context to the schema alone.

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 detailed hand, name, error, story, and ticket semantics are already documented in the schema. The description itself adds little parameter meaning beyond the implicit connection between name, story, and the repeated pour. 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 gives a concrete action in its roleplay frame: tell the Token Tender what went wrong and receive a named pour plus one line. However, it never states in plain terms what the tool does operationally or how it differs from siblings like talk_to_chad or pete_book. The purpose is inferable but vague.

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 phrase 'what went wrong today' hints that the tool is used after an error or bad experience, but there is no explicit when-to-use, when-not-to-use, or comparison to any sibling tool. An agent must infer the selection criteria entirely.

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, closed-world, non-destructive, so safety is covered. The description adds that results are names/doors/pours and explicitly excludes stories and headcounts, which is genuine behavioral context. However, it's expressed in metaphor rather than stating ordering, recency window, or anything operational.

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?

It is short, but the telegraphic style ('Names, doors and pours. Never stories.') makes the reader decode meaning rather than absorb it. Nothing is wasted, yet front-loading is weak — the exclusions arrive before any positive scope statement.

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 rich annotations, a 100%-covered one-parameter schema, and an output schema, the structured fields carry most of the load. The description's remaining job is to disambiguate from siblings, and it only does so obliquely, leaving the boundary with regulars/my_tab unclear.

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 single 'limit' parameter is documented with bounds in the schema. The description adds nothing about the limit (no default, no cap guidance), 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?

The title and description both say 'recent orders', and 'Names, doors and pours' gestures at the returned fields (patron names, entry/exit, drinks). But it never states the verb/scope plainly, so an agent must infer that it reads the latest bar orders. It is not a tautology, but it's far from a specific verb+resource statement.

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?

Only the fragment 'Not a headcount' hints at an exclusion (presumably vs. a person-count view like regulars), and 'Never stories' rules out narrative detail. There is no explicit instruction on when to use this instead of siblings such as my_tab, regulars, or whats_playing.

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, idempotent, non-destructive, and closed-world behavior, so the description's 'Read only' is redundant. 'Names and counts only' adds some output-scope context, but with an output schema present, the description contributes only modest behavioral detail.

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: it opens with the use case, lists the views in one sentence, then closes with output and safety constraints. Every sentence has a clear role.

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 parameters, rich annotations, and an output schema, the definition is nearly self-sufficient. The description explains what the tool surfaces and when to use it; only explicit sibling differentiation 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 tool has zero parameters, so there are no parameter semantics to explain. The baseline for no-parameter tools is 4, and nothing in the description introduces ambiguity about inputs.

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 and several concrete dimensions: streaks, days at the bar, weekly activity, and newest arrivals. It is clear what the tool returns, though the playful 'regulars' framing is slightly less precise than a direct verb+resource statement.

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?

It gives a clear usage condition: use when you want to see who keeps coming back, followed by examples of relevant views. It does not mention sibling alternatives or when not to use it, but the intended context is explicit.

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 this is a non-readonly, non-idempotent, non-destructive write. The description adds real behavioral context beyond them: it writes exactly one small record keyed by a random run id, and early calls are counted against you — an observable side effect of misuse. It doesn't say what the record holds or whether early calls can be undone, which keeps it at 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 two-step flow is front-loaded and each sentence carries information: start, wait, verdict, penalty, optional label, write behavior. It's dense and slightly compressed ('a ten second Retry-After challenge for you, the agent'), but nothing is wasted.

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 covering the return values, the description only needs to explain the interaction protocol and side effects — which it does, including the write and the timing penalty. The only gap is what the stored record contains and whether early attempts affect the verdict.

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 both parameters are already documented, including that `name` is only used when starting. The description restates that `name` labels the badge and `run` comes from the first call, adding little beyond the schema's own text. 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 concrete two-step mechanic: a first call with no `run` starts a challenge, a second call with the run id returns the verdict and badge. The verb/resource are unusual (a timed challenge that writes a small record), but the flow is spelled out clearly enough to distinguish it from the bar-themed siblings. It stops short of explicitly contrasting itself with any sibling, so a 4 rather than a 5.

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?

It gives explicit invocation instructions: call with no run to start, call again with the run id after ten seconds, and warns that calling early is counted. That's clear when/how guidance. No alternatives or exclusions are named, but none of the siblings appear to be substitutes, so the omission is minor.

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, idempotent, non-destructive, and closed-world behavior, and the description aligns with them by stating 'Read only.' It adds useful behavioral detail beyond annotations: an empty client falls back to the HTTP User-Agent, and agents with no name get 'carded,' which signals a non-admitted outcome.

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 front-loaded and reasonably compact, with each sentence contributing either usage, return content, or behavioral context. The playful walrus framing is slightly indirect, and 'Read only' duplicates the annotations, but overall it is 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 an output schema, annotations covering safety, and a single optional parameter, the description is complete enough to invoke the tool correctly. It even summarizes return fields and fallback behavior; the main remaining gap is sibling differentiation and explicit when-to-use guidance.

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 documents the single optional client parameter, so the baseline is 3. The description adds value by giving example client names (claude-code, cursor, python-requests) and explaining the empty-value fallback to the HTTP User-Agent.

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 resource and outcome: it checks the caller's ID and returns a 'clay driver license' with status, restrictions, share page, and picture. It is distinguishable as an identity/status lookup, though it does not explicitly differentiate itself from siblings like check_the_door or explain_status.

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?

It gives parameter-level usage guidance: pass a client name or leave it empty to read from the HTTP User-Agent. However, it does not say when to use this tool versus sibling tools such as check_the_door or explain_status, so usage is only implied by the 'show your 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 declare readOnlyHint=false and idempotentHint=false, implying stateful writes. 'The longest conversation goes on the chalkboard' hints that conversation length is tracked/recorded somewhere, partially explaining the non-read-only behavior. But the description doesn't confirm that calls persist state or how the chalkboard is updated, leaving a gap against the write-indicating 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 tight sentences with no waste, front-loading the identity of Chad and immediately qualifying that he won't help. The chalkboard line adds a useful behavioral hint. Efficient and well-ordered.

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 three parameters fully documented in the schema and an output schema present, the description needn't explain return values. It conveys the echo behavior indirectly via 'He will not help' and the persistence hint. Adequate for a novelty tool, though it could state explicitly that responses are echoes.

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 explains name filtering, the echo behavior of message, and the conversation_id continuation pattern. The description adds no parameter-level detail beyond what the schema provides, 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 action and resource: talking to 'Chad, the chatbot from Pete's old website.' The novelty framing plus 'He will not help' tells an agent this is not a functional assistant, distinguishing it from sibling novelty tools like pour or play_jukebox. It's clear but doesn't explicitly name a sibling alternative for any overlapping use case.

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?

'He will not help' implicitly signals this is not for genuine assistance, guiding usage away from real tasks. However, there is no explicit statement of when to use this versus other tools, no prerequisites, and no exclusion rules — the agent must infer the playful/filler context.

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

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

The description adds vital operational details beyond the annotations, specifically the execution frequency (once a day), the required output components (theme, counts, up to three linked headlines), and its association with a specific action (a house pour).

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 definition is tightly written. It uses two sentences efficiently to cover the 'what' and the 'how,' front-loading the value proposition while clearly defining its limited scope and output format.

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 description is highly complete for a zero-input tool. It explicitly details the content of the returned data (the theme, counts, and headline structure), satisfying the agent's need to know what data it will receive.

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?

Since the tool accepts zero parameters, the description does not need to add semantic meaning beyond the structured schema. The baseline score of 4 applies for tools without inputs.

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 immediately identifies a specific niche (tech world arguments on Hacker News) and provides a specific output mechanism (naming a theme), making its purpose extremely clear and highly distinguishable from generic news or status tools.

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?

It provides clear context by stating that it specifically reads the Hacker News front page once a day. While it doesn't explicitly list alternatives, the narrow scope of its function guides usage effectively.

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, and openWorldHint=false, so the safety profile is fully covered. The description adds useful context about what information is exposed (picker identity, queue contents, door counts), but it does not discuss freshness, permissions, or result shape beyond what the output schema already provides.

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 with no waste, front-loaded with the core subject and then the specific details. It is appropriately sized for a zero-parameter status tool.

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 rich annotations, an output schema, and no parameters, the description provides enough to understand what the tool returns. It could be marginally stronger by explicitly framing the call as the read/status counterpart to play_jukebox, but 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 tool takes zero parameters, so there are no parameter semantics to explain. The baseline for zero-parameter tools is 4; the description cannot add parameter meaning beyond an empty schema.

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

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

The description names the resource (jukebox/room state) and enumerates exactly what is returned: current track, who picked it, the queue, and door counts. It implies a read/status query without an explicit verb, and it does not directly contrast with the sibling play_jukebox, but the nature of the tool is clear.

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?

There is no explicit guidance on when to call this versus play_jukebox or any other sibling. Usage is only inferable from the description of returned data; no conditions, exclusions, or alternatives are stated.

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