TrendsAGI

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

Annotations already cover readOnlyHint, idempotentHint, destructiveHint and openWorldHint, so the safety profile is handled. The description adds genuinely new behavioral context: single SELECT only, returns columns and rows, and results are truncated at max_rows — a non-obvious silent-cap behavior an agent must plan around.

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, front-loaded with the operation and scope, then usage guidance, then return/limit behavior. The table list is dense but earns its place by telling the agent what it can query without a discovery call.

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 still describes the return shape (columns and rows) and the truncation limit, and it names the queryable tables plus the schema-discovery sibling. Nothing essential for 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 both parameters are already documented in the schema, including an example SELECT and the 1-200 range. The description only echoes the max_rows truncation, so 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?

States a specific verb and resource ('Run one read-only PostgreSQL SELECT over the account's TrendsAGI data') and enumerates the exact tables covered, which clearly separates it from the narrow siblings like get_trend, list_trends and search_trend_insights.

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?

Gives an explicit selection condition — 'Use for questions that need filtering, joins or aggregation' — which implicitly routes simple single-entity lookups to the get_*/list_* siblings, and points at read_data_schema for discovery. It stops short of naming the alternatives or stating exclusions, so it is clear but not exhaustive.

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, closed-world), so the bar is lower. The description adds real behavioral context beyond them: the return can be either a tool list or a UI page, and it imposes a privacy constraint ('do not include personal details'). It does not say what happens when no capability matches, which keeps it from 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?

Three short sentences, each earning its place: purpose/return, when-to-use with examples, and input constraint. The fallback condition is front-loaded where an agent will see it.

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, read-only lookup with no output schema, the description supplies everything needed: the routing condition, the two shapes of the response, and the input phrasing rules. Nothing an agent needs to call it correctly 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 coverage is 100% and the schema already supplies examples for 'goal', so the baseline is 3. The description adds genuine guidance not in the schema: keep the task to a few words and omit personal details, which shapes how the single parameter should be written.

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 ('Check whether TrendsAGI can do a task') and states the two possible outcomes: a set of tools or the app page where the user does it. It is clearly distinguishable from the sibling tools, which are all concrete data-retrieval calls rather than a capability lookup.

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 an explicit routing rule — 'Use when no other tool fits the user's request' — and concrete examples (setting up an alert, exporting data, connecting an ad account). It also instructs how to phrase the input ('a few words'), so both when-to-use and how-to-call are covered.

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, and closed-world, so the safety profile is fully covered externally. The description adds the meaningful detail that usage is measured against a daily limit, but says nothing about the shape of the returned data or whether failures (e.g. auth errors) are surfaced. Useful context, not rich disclosure.

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, no filler. The purpose is stated first and the trigger condition follows, so an agent can act on the first clause alone.

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-parameter read-only tool with no output schema, the description covers purpose and trigger adequately. The only omission is what the response actually contains (counts, percentages, reset time), which would help an agent interpret results.

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 the baseline is 4; there is nothing for the description to compensate for and it introduces no conflicting parameter expectations.

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 account's API usage against its daily limit'), including the scope of measurement. This is unambiguously distinct from every sibling tool, all of which concern trends, recommendations, or watchlists.

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?

Gives an explicit situational trigger: 'Use when a tool reports a rate or daily limit.' That tells the agent exactly when to reach for it. It stops short of naming alternatives or exclusions, but no sibling overlaps this function, so the gap 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 readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds the return-field list, which is genuinely useful with no output schema, but says nothing about auth needs, rate limits, or behavior for missing 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?

One compact sentence with the resource and returned fields front-loaded and zero filler. 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?

For a simple single-entity read with complete annotations and a fully documented one-parameter schema, the definition covers what the tool returns and how it is addressed. Only the absence of any sibling routing keeps it from being fully complete.

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 there is a single parameter, so the schema fully documents both the type and the source of trend_id. The description's 'by id' adds no syntax or meaning beyond what the schema already states — baseline 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 (get) and resource (a single trend), and enumerates the returned fields (volume, velocity, growth, category). The phrase 'one trend by id' distinguishes it from list_trends, though it never explicitly names or contrasts with the sibling 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?

Usage is only implied: the tool takes an id, and the schema notes the id comes from list_trends or search_trend_insights. There is no explicit guidance on when to choose this over get_trend_analytics or get_trend_ai_insights, so the agent must infer the distinction.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context on top: the insight is pre-generated ('stored') and the tool returns not_found when none exists yet — a real failure mode not visible in annotations or 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, zero filler: capability first, routing second, failure behavior last. Nothing is repeated from the title or schema and every sentence carries distinct 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 no output schema, the description carries the return-value burden and does so by naming the insight components. Combined with the not_found note and annotations covering safety, an agent has everything needed to decide and invoke 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 100% and the single parameter already documents its origin ('Numeric trend id from list_trends or search_trend_insights'), including a minimum of 1. The description adds no further syntax or provenance detail, 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 ('get') and a precisely scoped resource ('the stored AI insight for one trend'), then enumerates the payload (summary, key themes, sentiment, audience, marketing angles). That enumeration distinguishes it from siblings like get_trend_analytics and search_trend_insights without needing either schema opened.

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?

Gives a clear when-to-use signal: 'Use for audience, messaging or creative questions about a specific trend.' It does not, however, name an alternative or state exclusions (e.g. when to prefer search_trend_insights or get_trend instead), so it stops short of full routing guidance.

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, non-destructive, closed-world, so the safety profile needs no restating. The description usefully discloses the shape of the result (a volume time series, not a summary), but says nothing about data freshness, resolution, or truncation for long windows. Adequate but thin beyond the 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 sentences, zero filler. The capability statement comes first and the decision-support guidance second, so the agent gets the 'what' before the 'why'.

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 two-parameter read tool with no output schema, the description covers the resource, the windows, and the intended interpretation of the returned series. It omits any note on result granularity or window limits, which is the only remaining 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 description coverage is 100%: both period (with enum and default) and trend_id (with provenance from list_trends/search_trend_insights) are already documented. The description restates the three period values but adds no semantics the schema lacks, 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 and resource: 'Get one trend's volume time series', plus the exact lookback windows supported. It is clear what is returned, but it never names or contrasts the sibling tools it could be confused with (get_trend, get_trend_ai_insights), so an agent must infer the boundary from the names 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?

Explicitly frames the decision the tool supports ('tell whether a trend is still rising, flat or fading') and gives a concrete downstream use ('before deciding on campaign timing or budget'). There is no when-not-to-use or named alternative, which keeps it short of a 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, destructiveHint=false and openWorldHint=false, so safety behavior is covered. The description adds one genuinely useful behavioral fact — the plan entitlement requirement — but omits the default scoping behavior (only active events in the last 24h unless overridden), which materially affects what a caller receives.

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, each earning its place: purpose, usage trigger, prerequisite. The capability statement is front-loaded and there is 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?

For a zero-required-parameter, read-only list tool with an output-free contract this is close to adequate, but with no output schema and two undocumented enum parameters the description should have flagged the default active/24h narrowing. The entitlement note is good but leaves the default-result behavior unexplained.

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 only 33%: limit is documented in the schema, while status and time_range have no descriptions at all in either place. The description adds nothing about parameters, so the agent must infer that the default status=active and time_range=24h silently narrow results.

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 with scope: listing reputation or crisis events detected for the account's monitored topics. No sibling tool covers crisis/brand-risk detection (siblings are trend, watchlist, and capability tools), so the agent can route here without opening the 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?

It gives an explicit use trigger ("Use when the user asks about risks around a brand or topic") plus a prerequisite ("Requires a plan with crisis monitoring"). It does not name alternatives or when-not-to-use conditions, but none of the sibling tools overlap with this capability.

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 non-destructive behavior, so safety is covered. The description adds genuinely non-obvious context: that each item carries a decision brief plus evidence, and the important caveat that the confidence score measures evidence completeness rather than probability of success. It still omits ordering and pagination behavior.

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, each load-bearing: scope, return-content semantics, and a precondition. The caveat about the confidence score is front-loaded where an agent will read it before interpreting results.

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 characterizes what comes back (recommendations with decision briefs, evidence, and a confidence score) and the precondition for calling. Minor gaps remain around default status filtering and result ordering, but nothing essential to 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 coverage is only 40%: limit and match_user_interests carry descriptions, while status and priority have none. The description partially compensates by enumerating recommendation categories that map to the recommendation_type enum, but it says nothing about status, priority, or default filtering behavior.

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 a specific resource ("recommendations TrendsAGI generated for this account") and enumerates the concrete types returned (marketing angles, content ideas, SEO actions, PR responses). This cleanly distinguishes it from siblings like list_trends, list_crisis_events, and search_trend_insights.

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?

Provides one real gating condition — "Requires a plan with recommendations" — which tells the agent when the call is even valid. However, it never states when to prefer this over adjacent tools such as search_trend_insights or get_trend_ai_insights, so the routing guidance is only implied.

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, destructiveHint=false and closed-world, so the safety profile is fully covered. The description adds the dependency relationship to list_trends, which is useful, but says nothing about the shape, size, or stability of the returned category set. With annotations carrying the behavioral burden, a 3 is appropriate.

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 key relationship (whose categories these are) appears immediately and 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?

For a zero-parameter lookup with full annotations and no output schema, this covers the essentials: what is returned and who consumes it. It could go slightly further by noting that the returned names are meant to be passed back as a category argument, but the reference to list_trends largely conveys that.

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 per the rubric the baseline is 4. The description correctly signals a no-input enumeration call and adds no misleading parameter implications.

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 (List) and resource (trend category names) and explicitly ties the result to a sibling tool, 'list_trends accepts'. An agent can immediately tell this is an enumeration helper for a sibling's valid inputs rather than a data-fetching 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?

By saying the categories are the ones 'list_trends accepts', it clearly implies the call-this-before-list_trends workflow. It does not, however, state explicit exclusions or name alternative discovery routes among the other siblings (list_trends, get_trend_analytics).

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 and closed-world, so the safety profile is covered. The description adds genuinely useful operating context beyond that: the 24-hour default window and a hard cap of at most 25 returned trends, which an agent needs to avoid misjudging result completeness.

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, all front-loaded: purpose and metrics first, then routing/filtering guidance, then scope limits. No filler and no repetition of the tool name.

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 describing returns; it states the metrics available (volume, velocity, growth) and the 25-item cap, which is nearly sufficient. It does not describe the shape of a single trend entry, leaving a small gap for an agent relying on the response.

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 already explains limit ranges, period values, sort_by semantics and category lookup. The description largely restates these ('sort_by=velocity returns the fastest-accelerating topics first', the 24h default) rather than adding new semantics, 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?

Names a specific verb and resource — trending topics on social platforms — and immediately qualifies the output with 'measured volume, velocity and growth', which distinguishes it from sibling readers like get_trend (single trend) and search_trend_insights. An agent can tell what it returns without opening the 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?

Gives clear positive context ('use to find what is rising in a category or around a brand, product or competitor') and routes to list_trend_categories for valid category names. It stops short of saying when NOT to use it versus get_trend or search_trend_insights, so the disambiguation is only partial.

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, destructiveHint=false and a closed world, so the safety profile is fully covered without the description. The description adds one genuinely useful behavioral fact beyond the structures: the response includes each topic's alert conditions. It stops there, saying nothing about scoping to the authenticated account beyond 'this account' or about ordering.

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 that front-loads the resource and then the returned fields. Every clause earns its place and there is 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?

With no input parameters and no output schema, this is a simple read tool and the description covers what it returns (watched topics plus their alert conditions). The remaining gap is minor: it does not say whether the list is scoped or ordered, or how an agent should behave if the watchlist is empty.

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 empty, so there is no parameter semantics for the description to explain. Per the baseline for zero-param tools, a 4 is appropriate; nothing is missing 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 names a specific verb and resource ('List the topics this account watches') and adds the payload detail that alert conditions are included. It is clear on its own, but it does nothing to distinguish itself from or relate to any sibling tool, which is the only thing keeping it from 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?

There is no statement of when to use this versus alternatives, no prerequisites, and no exclusions. The usage is only inferable from the tool name itself; the description adds no routing guidance at all.

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, openWorldHint=false and destructiveHint=false, so safety is covered. With no output schema, the description usefully discloses what the call returns (tables, column types/meanings, query rules, example queries), which the agent would otherwise have to guess.

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 resource and followed by the contents and the call condition. No filler or redundant restatement of the title.

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 a zero-parameter read tool with no output schema, the description covers both what is returned and the one operational rule (invoke once before writing SQL). Nothing an agent needs to call it correctly 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 is no argument semantics to explain and the baseline is 4. The description correctly spends no words on nonexistent 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?

States a specific verb ('List') and a precisely scoped resource ('the tables execute_sql can query') plus the payload contents (column types and meanings, query rules, examples). It names the sibling it feeds into, so an agent can distinguish it from execute_sql and the list_* siblings at a glance.

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?

'Call once before writing SQL' gives an explicit trigger and ties the tool to the execute_sql workflow, which is real routing value. It stops short of stating a when-not condition (e.g., not needed again within a session) but the 'once' phrasing implies 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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds a genuinely new behavioral fact not present in structured data: the entitlement requirement ('Requires a plan with insight search'). It does not describe result shape or paging, 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?

Three tight sentences with no filler: purpose and examples first, then the usage trigger, then the prerequisite. Every sentence earns its place and the most decision-relevant 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?

For a two-parameter, read-only search tool with a required query and a defaulted limit, this covers purpose, trigger and prerequisite. Since no output schema exists, the terse 'return the matching trends' leaves the response shape somewhat unspecified, which is the only real 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 description coverage is 100%, so the baseline is 3; the example queries ('AI chips', 'sustainable packaging') add real meaning by showing that 'query' takes topical phrases rather than exact trend names. The limit parameter is left entirely to the schema, which is acceptable given full coverage.

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 (AI-generated trend insights), with concrete example queries that make the target content unambiguous. The clause 'rather than naming a trend' implicitly separates it from the get_trend/get_trend_ai_insights siblings, so an agent can route correctly 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?

Gives an explicit trigger condition ('when the user describes a topic or product rather than naming a trend') plus a hard prerequisite ('Requires a plan with insight search'). It stops short of naming the alternative tool (e.g. get_trend) for the naming-a-trend case, so the when-not path is implied rather than stated.

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