API Tool Calls

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

With no annotations, the description carries the full behavioral burden. It does disclose useful traits: 'No live source lookup' (so results are static/cached guidance, not fresh data), a cap of three sources, and the shape of the returned plan — which substitutes for an output schema. It omits permissions, side effects, and rate/limit behavior, so it clears the minimum bar but not much beyond it.

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 compact sentences front-load the deliverable and its contents, then append the crucial 'No live source lookup' constraint and defaults. The list-heavy middle is dense but each item carries distinct information; nothing is 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?

Given 4 parameters, low schema coverage, no annotations, and no output schema, the description does substantial lifting by describing the plan's contents and parameter defaults. Remaining gaps are minor: no guidance on what a good use_case looks like (schema covers it) and no statement of constraints or determinism of the result.

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 low (25%, only use_case), so the description must compensate — and it largely does. 'cost at your monthly volume' ties the volume parameter to pricing, 'resale terms' explains the resell enum, and 'Defaults: volume 0, US, no resale' documents the defaults for three otherwise-undocumented parameters (volume, geo, resell). Only the semantics of geo beyond its default and volume units are left implicit.

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 deliverable (a free Data Finder plan for up to three sources) and enumerates its contents (fit, cost, resale terms, URL/read date, DIY guidance), so the agent knows exactly what comes back. It doesn't need to distinguish itself from siblings like get_transcript or make_qr, which are unrelated. Clarity is slightly undercut because the description sells the output more than stating the action, but the core purpose is unambiguous.

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?

Context is only implied: the tool produces a plan rather than a live search, and the 'No live source lookup' caveat tells the agent this is not a real-time data query. There is no explicit when-to-use/when-not statement against alternatives, though no sibling tool overlaps this space. Adequate but thin.

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?

No annotations are provided, so the description carries the full burden. It does add real value by disclosing the scope (captions only, no media) and the return shape (timestamped plain text), but it omits failure modes (no captions, private/unlisted videos), permission or rate-limit behavior, and whether the read has 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?

Two short sentences, zero filler, with the core capability front-loaded and the scope exclusion immediately after. Nothing could be cut without losing meaning.

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 two-parameter read tool with no output schema, the description covers what it does, what it does not do, and roughly what it returns. The remaining gap is failure behavior and read-only confirmation, which no annotations supply.

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%: the schema already documents the url format and the lang fallback chain (English, then any track). The description adds no parameter-level detail beyond that, 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 specific verb (Read) and resource (public YouTube captions) plus the output form (timestamped plain text), and adds a useful scope limiter ("no video or audio"). The siblings (find_data, make_qr, page_to_markdown, resume_gap) don't overlap with transcript retrieval, so no sibling differentiation is needed.

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 by the scope phrase "Captions only, no video or audio," which tells the agent this is purely a caption-fetch tool. However, there is no explicit when-to-use guidance, no mention of prerequisites (public/available captions) or what to do when no track exists, so it sits at the minimum-viable level.

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?

With no annotations, the description carries the full behavioral burden, and it largely restates the name. It discloses that output is SVG but says nothing about whether this is a pure/side-effect-free generation, size or content limits, error behavior for malformed input, or whether the result is returned inline or as a file.

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 tight sentence with the output artifact front-loaded, no filler or redundancy. It is appropriately short for a small utility tool, though it is too sparse to be maximally informative.

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, no-output-schema generator the description is minimally viable, and the nested wifi schema covers the structure. It omits the wifi-over-text precedence, the format enum, and any note on what the SVG return looks like, leaving those gaps to structured fields.

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 67% and the schema already documents text, wifi, and the wifi precedence rule. The description adds only a restatement of the accepted input categories and says nothing about the format parameter or the anyOf constraint beyond what the schema shows.

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 ('Make') and resource ('SVG QR code') and enumerates the three encodable payload types (text, URL, Wi-Fi), so an agent immediately knows what the tool produces. It does not name any sibling, but the sibling set (find_data, get_transcript, page_to_markdown, resume_gap) is so unrelated that differentiation is unnecessary.

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 when the tool is useful (when you have text, a URL, or Wi-Fi details to encode) but gives no explicit when-to-use guidance, no exclusions, and no alternatives. Nothing tells an agent whether this is the preferred path versus generating a QR some other way.

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?

With no annotations, the description carries the full burden and does disclose real behavioral limits: no auth, no paywall bypass, no JS execution, and a 2 MB HTML ceiling. It stops short of describing failure/error behavior for blocked or oversized pages, but the operational envelope is clearly communicated.

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, zero filler: the first states the transformation and output shape, the second front-loads the constraints that determine whether the call will succeed. Nothing 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?

For a single-parameter, no-output-schema utility tool, this is complete: the description substitutes for a return-value spec by enumerating the Markdown elements produced (title, headings, lists, tables, absolute links) and covers the operational limits that could cause a failed call.

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?

Only one parameter exists and schema description coverage is 100%, so the schema already documents 'url' as a public http/https URL. The description reinforces the 'public' constraint but adds no syntax or format detail beyond the schema, matching the baseline of 3.

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 ('Read one public HTML page as clean Markdown') and enumerates the converted structure (title, headings, lists, tables, absolute links). The sibling tools (find_data, get_transcript, make_qr, resume_gap) are unrelated, so no further differentiation is required for an agent to select this tool.

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 scope constraints ('public', 'No logins, paywalls or JavaScript rendering') effectively define when the tool will and won't work, which is strong implicit usage guidance. However, it names no alternative tool for dynamic/authenticated pages, so the routing half of the guidance is absent.

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?

With no annotations, the description carries the full burden and does disclose real behavioral traits: a hard cap of 10 results, coverage blind spots (not every batch or country), and an explicit no-endorsement disclaimer. It does not clarify read-only status, latency, or result shape, but the coverage caveats are the valuable part.

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 core action. Slightly redundant with 'check the notice' and 'read the notice' saying nearly the same thing, which costs a little tightness.

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 search tool with no output schema, the description covers the essentials: what it searches, the result ceiling, and the reliability caveat. Only minor gaps remain, such as return fields or whether results are ranked.

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?

Only one parameter with 100% schema description coverage, so the schema already explains that query accepts product name, brand, model number or UPC. The description adds no additional syntax or matching-behavior detail, which matches the baseline-3 case.

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 (Search) and resource (local U.S. CPSC recall data), plus a scope limit (up to 10 notices). No sibling overlap exists among find_data/page_to_markdown/etc., so explicit differentiation isn't needed, but it doesn't hurt to omit it.

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?

Implies usage indirectly via 'may match' and the repeated instruction to verify against the full notice, but never states when to use this versus alternatives or what a valid query context looks like.

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?

With no annotations, the description carries the full disclosure burden. It adds one useful behavioral trait: the résumé is not stored. It also points to an external service for a full check and rewrite, implying this tool is a limited comparison. However, it does not describe return format, rate limits, authentication, or what happens to the submitted résumé during processing.

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 the core comparison stated first and the non-storage note second. There is no filler, though the external URL is slightly promotional. Overall the text is appropriately sized and 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?

No output schema exists, so the description should clarify what a comparison returns, but it does not. The family parameter is unexplained, and there is no indication of response format, limits, or how results should be interpreted. For a two-parameter tool with no annotations, this leaves important gaps.

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 50%: resume_text is documented in the schema, while the family enum has no description. The description says the résumé is not stored, which adds privacy meaning for resume_text, but it never mentions the family parameter or its allowed values. It therefore does not compensate for the missing parameter documentation.

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 and resource: compare résumé skills with Columbus, Ohio job postings. It is clearly distinct from the sibling tools, which handle data lookup, transcripts, QR codes, and page conversion. It does not explicitly frame the result as a gap analysis, but the core purpose is unambiguous.

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 explains what the tool does but gives no guidance on when to use it versus alternatives or prerequisites. There is no mention of when not to use it, what input is required, or what the tool is not suitable for. The external link suggests a fuller service exists, but does not help an agent choose this tool over anything else.

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