Only Fake Facts

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

Annotations already cover read-only, idempotent, closed-world behavior, so the description only needs to add context. It does, by disclosing the fallback trait that near matches are suggested when no exact fact exists — an error/empty-result behavior the annotations do not reveal. It omits what happens if both id and no are supplied.

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

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

Two short sentences, front-loaded with the lookup keys, with the example inline and the fallback behavior last. No filler 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, single-record lookup with full schema coverage and safety annotations, the description covers the essentials plus the near-match fallback. Only the combined id/no case and result shape (no output schema) remain unaddressed, which are minor.

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 id, no, and lang including the language default. The description adds one useful detail beyond the schema — a concrete id format example ('flamingos-embarrassed') — but nothing about precedence when id and no are both passed, so baseline 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 and resource ('Get one fake fact') and names both lookup keys (id or catalogue number), which distinguishes it from random_fact and search_facts implicitly. It stops short of explicitly contrasting with those siblings, so it is clear but not fully differentiated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied: call this when you already hold an id or catalogue number rather than a query string. No explicit when-to-use/when-not statement or pointer to search_facts for partial-text lookups is given.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety and determinism profile is covered. The description adds that each entry carries a fact count, which is genuine behavioral context, but says nothing about category stability, ordering, or whether empty categories appear.

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 front-loaded sentence with no filler; every clause (categories, plus fact counts) contributes information an agent would otherwise have to discover by calling.

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 listing tool with a fully documented schema and no output schema, the description covers purpose and the essential return content. It falls short only on ordering/empty-category behavior and on routing guidance relative to search_facts.

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

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

There is only one parameter and its schema description is fully documented (100% coverage), including the Accept-Language default and the note that labels are machine-translated. The description adds no meaning about `lang`, so the baseline of 3 for high schema coverage 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 ("List the fact categories") and adds a concrete payload detail — fact counts per category — that makes the result shape predictable. It doesn't explicitly name a sibling, but the siblings (get_fact, random_fact, search_facts) are so distinct that mis-selection is unlikely.

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 when-to-use or when-not-to-use statement, and no mention of the natural workflow (browse categories, then use search_facts or get_fact). Usage is only implied by the verb "list" and the domain vocabulary, leaving the agent to infer that this is a discovery/overview step.

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 (readOnlyHint, idempotentHint, openWorldHint=false), so the bar is lower, yet the description adds genuine context: every fact is fabricated, and the agent should relay the `quote` field including its "Fake fact (not true):" prefix so the falsehood stays labelled. That is a real disclosure about output semantics that no structured field carries; it only lacks any note on rate limits or variation across calls.

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

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

Two short sentences with no waste; the core purpose is front-loaded and the critical output instruction follows immediately. Every clause earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description usefully identifies the return field (`quote`) and its mandatory prefix, which is the main thing an agent needs. It does not mention the optional lang/category behaviour or hint at fact variety, but the schema covers those adequately.

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

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

Schema description coverage is 100%, with `lang` fully enumerated and defaulted and `category` documented as coming from list_categories, so the schema already does the work. The description adds nothing about either parameter, which is acceptable at this coverage level but earns only the baseline.

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

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

The description uses a specific verb and resource ("Get one random fake fact") and the qualifier "fake" implicitly separates it from get_fact and search_facts. It stops short of naming those siblings explicitly, so the differentiation must be inferred rather than stated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: an agent can infer this is the novelty/false-fact generator rather than the real-fact lookup, but there is no explicit "use this instead of get_fact when..." guidance and no exclusions. The bulk of the text is about output handling, not tool selection.

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 cover safety (readOnlyHint, idempotentHint) and openWorldHint=false, so the bar is lower. The description still adds real behavior beyond them: matching is stemming/prefix-based ("plurals and word starts match"), which tells the agent it can search loosely and need not pass exact tokens. It omits result ordering, relevance ranking, and what an empty match looks like.

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

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

Two short sentences with zero filler. The core purpose comes first and the input-syntax hint follows, with a parenthetical example that earns its space by showing both accepted query styles.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-required-parameter, read-only search tool with no output schema, the definition covers purpose and query semantics adequately, and the schema carries the lang default and limit bounds. The main gap is category – its valid values and its relationship to query are left entirely implicit, which matters because list_categories exists as a sibling.

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 only 25%: lang is documented in the schema, but query, limit, and category are bare. The description compensates well for query (free text, sentence or keyword, plural/prefix matching) but says nothing about limit or about what category accepts or how it interacts with query. With low coverage, that leaves roughly half the parameters unexplained in either place.

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 clear verb and resource: "Find fake facts by topic." That is enough for an agent to separate it from get_fact, random_fact, and list_categories without opening a schema. It stops short of naming those siblings or explicitly contrasting the lookup modes, so it lands at 4 rather than 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?

The description gives useful input guidance ("Plain words or a sentence both work", with examples like "owls" and "anything about cheese?"), so the agent knows how to phrase a query. It never says when to pick this tool over get_fact or random_fact, nor when a category filter should be used instead of a query. Usage is implied by the name and the 'by topic' phrasing rather than stated.

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