founderssaid

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely non-obvious behavioral context beyond that: the tool surfaces 'evidence and overlap' and deliberately 'does not automatically declare a winner', telling the agent the result is neutral and requires its own synthesis.

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 core action and followed by the key behavioral caveat. No filler or repetition of schema content.

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 shapes needn't be described. But for a 5-parameter tool with three required fields and an undocumented nested filters object, the description leaves the agent without guidance on how the two perspectives and the limit parameter shape 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 0% and the description explains none of the five parameters. It doesn't clarify the distinction between topic, perspective_a and perspective_b, what the nested filters object accepts, or what limit_per_side controls – all of which an agent must infer from bare property names.

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 clear verb-plus-resource: 'Retrieve separate source groups for two competing views on one topic', which is distinct from a generic evidence search. It does not explicitly contrast with the sibling find_evidence or research, so the differentiation is implied 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 implied by 'two competing views on one topic' – an agent can infer this is the tool for balanced, side-by-side comparison. However, no sibling alternatives are named and no when-not-to-use conditions are given, leaving the agent to guess whether find_evidence or research would be a better fit.

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 read-only, idempotent, non-destructive behavior, so the bar is lower; the description nonetheless adds real context: hard caps on excerpt length (200 chars/40 words for articles, 300/60 for transcripts) with the rationale, plus an explicit 'no full transcript' limitation. It doesn't say how relevance/matching works or what happens when nothing matches.

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-loaded with the core action, then two short sentences of size limits and rationale — each earns its place. The 'up to five' framing versus the limit parameter's default of 3 introduces avoidable ambiguity in an otherwise tight description.

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 shape needn't be explained. Still, for a 3-parameter tool with 0% schema coverage, the description leaves video_id undefined and the limit ceiling-vs-default relationship unclear, which an agent needs in order 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 description coverage is 0% for all three parameters. The description only gestures at 'query' and implies a ceiling of five results via 'up to five', which actually conflicts with the schema's default of 3 and leaves the limit semantics ambiguous. video_id is never mentioned at all, so the most important required input is unexplained.

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 ('Find ... short transcript or article excerpts supporting a query') and implicitly distinguishes itself from full-text tools by saying full transcript access is unavailable. It never names a sibling such as read_summary or search_insights, so the agent must infer differentiation.

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

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

The phrase 'supporting a query' implies a verification/grounding use case, and 'full transcript access is intentionally unavailable' routes the agent away from a transcript-reading expectation. However, there's no explicit when-to-use vs. when-to-use-a-sibling guidance despite six siblings in the same domain.

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, openWorldHint=false, and destructiveHint=false, so the safety profile is fully covered. The description's value-add is scope: results come from the authenticated customer and cannot be targeted at another account. It does not, however, mention behavior when unauthenticated or whether calling it consumes quota (relevant given it reports rate limits).

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 sentence, front-loaded with the verb and the returned fields, with no filler. Every clause names a distinct piece of returned data, and nothing is repeated from the annotations.

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 the description does not need to explain return values, and with no parameters the schema is trivially complete. The remaining minor gap is error/auth-failure behavior, which is not addressed, but for a zero-argument read tool the description covers what an agent needs to select and 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?

There are zero parameters, so per the baseline the schema carries no semantics to compensate for. The description correctly implies the tool is argument-free and implicitly scoped to the caller's identity, which is the only parameter-like distinction that matters here.

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 ('Return') and enumerates the exact resources returned: plan, credits, rate limit, and usage totals. It is scoped to 'the authenticated customer,' which immediately tells an agent whose data this is. Sibling tools (research, get_video, search_insights) are unrelated, so no sibling differentiation is required, but the description also doesn't need to name an alternative.

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 tool for checking account status, credits, and limits, but there is no explicit when-to-use statement, no prerequisites, and no exclusions. Because the tool takes no parameters and is read-only, the ambiguity is small, but the description does not actively route the agent.

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 safety profile is covered. The description adds some value by qualifying the payload as 'public source metadata' (not transcript or analysis content) and noting the video must be 'indexed', but says nothing about failure behavior for unknown IDs.

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; the resource and scope arrive immediately.

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 return shape needn't be described, and annotations cover safety. However, for a lookup tool the description omits what happens when the ID is not indexed and where the ID should come from, leaving real gaps an agent would hit at call time.

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 the schema gives it zero description coverage (a bare string). The phrase 'one indexed video ID' adds the useful constraint that the ID must come from the index rather than being arbitrary, but the expected format or provenance of the ID is never stated.

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 with a clear scope: public source metadata for one indexed video ID. It is distinguishable from siblings like get_usage and read_summary, though it never explicitly contrasts itself with any of them.

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

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

No explicit when-to-use or when-not-to-use guidance, and no alternative tool is named. The only implied usage is that the caller must already hold an indexed video ID, which the agent has to infer.

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, closed-world, non-destructive), so the description's added value is the negative disclosure that it never returns a transcript or filesystem path — a genuinely useful boundary that prevents misuse. It omits what happens when the ID has no validated summary, which would be the one remaining behavioral gap.

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 return-scope statement comes first and the negative boundary second. Nothing could be removed without losing 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?

An output schema exists, so return-value explanation is not required, and the description still adds a useful boundary note. For a one-parameter idempotent read, the missing piece is only failure behavior for an unknown or unsummarized ID.

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 0%, so the description carries the burden for video_id. It tells the agent the value is a "known source ID" and that exactly one is expected, but gives no format, no example, and no hint about where to obtain a valid ID.

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 (return) and a precisely scoped resource: the validated eight-section Korean summary for a single source ID. The contrast with transcripts implicitly separates it from get_video, though no sibling is named explicitly.

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?

"for one known source ID" implies the prerequisite that the caller must already have an ID (presumably obtained via get_video), but this is left to inference. No explicit statement of when to prefer this over get_video or search_insights, and no guidance on what to do if no summary exists.

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 description correctly focuses on output shape: recurring-principle candidates, tensions, counterpoints, actionable advice, follow-up questions, URLs, coverage and limitations. The 16-source cap is useful operational context. It doesn't explain pagination or how coverage/limitations are derived, keeping it short of a 5.

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-loaded with purpose in the first clause, then return contents and usage priority in a compact block. Slightly dense but every sentence carries information; no 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?

An output schema exists, so the description rightly does not need to define return values, and it still summarizes them helpfully. However, for a tool with a three-parameter signature whose only complex parameter has zero schema documentation, the description leaves the filter semantics entirely unexplained, which is a material gap.

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 0%, so the description must carry parameter meaning, and it largely does not. `filters` contains eight undocumented fields (people, channels, languages, business_axes, min_confidence, include_legacy, dates, published_to) with no explanation anywhere, and `limit`'s interaction with the 16-source cap is only obliquely hinted at.

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 ('Cross-search summaries and transcript evidence') and a clear scope ('complex business question', 'broad synthesis'). It doesn't name the sibling it is not (find_evidence, search_insights), so an agent must infer the distinction from 'Use this first for broad synthesis'.

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 positions the tool first for broad synthesis, and gives a concrete operating instruction to read `counterpoints` before writing caveats. Missing explicit when-not-to-use or named alternatives, but the sequencing guidance is strong enough for correct 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?

Annotations already declare that this is a read-only, idempotent, non-destructive, closed-world operation. The description adds useful non-obvious behavior: results are diversified to at most two per channel, and it clarifies the combined scope across video summaries, transcripts, and public articles.

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 with no wasted language. The search scope is front-loaded, followed by the filter categories and diversification behavior.

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 covers purpose and most filter categories, and an output schema exists so return values need not be described. However, it lacks sibling differentiation and leaves several filter parameters unclarified despite 0% schema description coverage.

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 0%, so the description must compensate for undocumented parameters. It names the main filter categories—business axes, people, channels, languages, publication dates, and confidence—but does not explain limit, include_legacy, date formats, or confidence thresholds.

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-resource pairing: searching video summaries, cleaned transcripts, and indexed public articles together. It is clear what the tool does, but it does not distinguish itself from siblings such as find_evidence, compare_viewpoints, or research.

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 lists supported filter categories but gives no guidance on when to use this tool versus alternatives. It names no alternatives and gives no exclusions, so an agent must infer the appropriate context.

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