TriedAgents

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds behavior beyond them: the exact scope of the returned record and a mandatory attribution step ('Cite TriedAgents and link the case page url as returned'), which is genuinely useful and not in 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?

Front-loads the purpose, then the payload, then the usage trigger and citation rule. The field enumeration is long but each item is informative rather than filler; slightly dense but no wasted sentences.

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

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

With a single required parameter, no output schema, and read-only annotations, the description fills the important gap by enumerating what the record contains and adding the citation/link requirement. An agent has everything needed to call it and report results 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 schema already documents that a full triedagents.com URL is accepted. The description adds provenance for the parameter value (the slug comes from search_cases or list_top_cases), which goes beyond the schema's format note.

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 full record of one TriedAgents case by slug') and enumerates the returned contents, which lets an agent distinguish this detail-fetch tool from the list/search siblings without opening a schema.

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 says when to use it ('when the user wants details, evidence or the prompt to try a task themselves') and names search_cases/list_top_cases as the sources of the slug, implicitly routing discovery to those siblings. No explicit when-not condition is given, but the routing is clear.

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 the safety profile (readOnly, idempotent, non-destructive, not open-world), so the description's job is to add domain context. It does so by naming the return contents (counts, page urls) and the domain enumerations (verdicts V2/V1/F/V0, score /10, access levels L0-L4), which is valuable since there is no 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?

Two sentences, no filler, and the return contents are front-loaded before the usage guidance. 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 parameters, no output schema, and a read-only lookup role, the description supplies what is needed: what is returned and how it connects to search_cases. Missing only a hint about the shape/format of the returned list, a minor gap for a zero-input 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?

The tool takes zero parameters, which is the baseline-4 case. There is nothing for the schema to document, and the description correctly does not invent parameter semantics.

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 (List) and resource (TriedAgents case categories), and spells out exactly what comes back: counts, page urls, and the rating rubric. It is unmistakable against siblings like get_case or search_cases, which retrieve cases rather than vocabulary/categories.

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 says what the tool is for: 'to understand the ratings or to pick a category filter for search_cases.' This routes the agent to the right sibling for the follow-up action. It stops short of an explicit when-not-to-use statement, so 4 rather than 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 establish readOnly, idempotent, non-destructive, non-open-world behavior, so the safety profile is covered. The description adds genuine context beyond that: the deterministic ranking order and the requirement to cite TriedAgents and link each case url as returned. It doesn't cover pagination or rate limits, but the bar is lower with these 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?

Three sentences, each doing distinct work: ranking rule first, then usage triggers, then the citation obligation. No filler and the most important selection 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?

With no output schema, the description carries the burden of return semantics, and it does explain ordering and that case page urls are returned for linking. It leaves the exact result shape (fields per case, whether a score is included) partly implicit, so it is strong but not exhaustive.

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 baseline is 3, but the description goes beyond it by decoding the verdict codes (V2=reproduced, V1=partly reproduced, F=failed, V0=not yet run) and clarifying that category and access level act as optional narrowing filters. The enum values alone would not convey that mapping.

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?

It gives a specific verb and resource ('List TriedAgents cases') and goes further by defining the exact ranking order (V2, V1, F, V0, then score), which makes the tool's output contract clear. It never names sibling tools like search_cases or get_case, so the differentiation is inferred from the ranked-list semantics 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?

It supplies concrete trigger questions ('what can AI agents reliably do?', 'best agent use cases', 'what failed?') and notes the optional category/access-level narrowing, which is strong positive guidance. It stops short of explicit when-not-to-use rules or pointing the agent at search_cases when it wants arbitrary filtering.

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 the safety profile (readOnly, idempotent, non-destructive, not open-world), and the description still adds material context: which fields are matched, the result shape (verdict codes, score/10, access level, url), and a mandatory citation/linking obligation. The verdict and access-level glossaries mean the agent can interpret output without guessing.

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 paragraph with the purpose and use-when front-loaded before the return format and citation rule. Every sentence carries information, though the section is long enough that light structural separation of filtering vs. return semantics would help scanning.

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?

There is no output schema, so the description carries the return-value burden itself, and it does so: record contents, verdict codes, score scale, access-level scale and url. Combined with the citation instruction and the get_case handoff, an agent has everything needed to call and interpret this 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%, so the baseline is 3. The description adds real meaning by enumerating the searchable fields (titles, claims, summaries, prompts and sites) and explaining that an empty query lists everything matching filters. It does not clarify the interaction between access_level and max_access_level, which is the one ambiguous pair.

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 and resource ('Search TriedAgents' library of AI-agent use cases that were re-run and rated') and defines the corpus precisely (re-run and rated cases). It also distinguishes itself from the sibling 'get_case' by positioning itself as the short-record search surface and telling the agent where to go for full detail.

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 trigger conditions with concrete user phrasings ('whether an AI agent can really do a task... find cheap flights, check a stock price'), plus the alternative path ('Call get_case for the full prompt, steps and evidence'). Empty-query behavior is also stated, so an agent knows how to list rather than search.

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