Desearch

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered upstream. The description adds nothing behavioral beyond that — no mention of source coverage, latency, billing, or how results differ between models/sources. It essentially restates the annotation's open-world nature without new information.

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 zero padding or repetition — structurally clean. It avoids wasting tokens, though its brevity borders on under-specification rather than true conciseness.

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 9-parameter, open-world search tool with no output schema, the description should at minimum hint at what comes back and how source/model selection shapes results. It supplies none of that, leaving the agent reliant entirely on the schema to understand a fairly complex 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 description coverage is 100%, so all nine parameters (model, tools, date filters, result_type, domain filters) are already documented in the schema with defaults, enums, and examples. The description adds no parameter meaning whatsoever, 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?

"AI search and analysis on web using Desearch AI" gives a verb (search/analyze) and a resource (web), so the general purpose is inferable. But against siblings like web-search, x-search, and extract, it offers no distinguishing scope — it does not say what makes this an "AI" search versus the plain web-search tool. The purpose is vague enough that an agent couldn't confidently route between 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?

There is no when-to-use guidance, no when-not-to-use, and no named alternative. With 14 siblings including web-search and x-search, an agent has no signal for choosing this tool over them. The description is purely a label, not usage instruction.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered structurally. The description adds one genuinely useful constraint beyond that — the URL must be public — plus the JS-rendering capability, but says nothing about rate limits, timeouts, content-size truncation, or failure 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?

Two short sentences, front-loaded with the core action and back-loaded with the sibling routing hint. 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?

For a four-parameter read tool with full schema coverage and annotations, the description covers purpose, output format, and alternative-tool routing. No output schema exists, but the return shape (text or HTML) is stated; only edge-case behavior like truncation or error handling is unaddressed.

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 schema already documents url, js, wait, and format. The description only echoes the format options ('plain text or HTML') and adds no syntax, defaults, or interaction details (e.g., that 'wait' only applies when 'js' is true) beyond the schema.

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 (extract) and resource (a public URL's content), and names the return formats (plain text or HTML). It also explicitly distinguishes itself from the sibling web-crawl, so an agent can choose between them 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?

The sentence 'Preferred over web-crawl for new integrations' names the alternative and the condition that selects this tool, which is exactly the kind of routing guidance an agent needs. It stops short of stating when NOT to use it (e.g., for non-public or authenticated pages beyond the implicit 'public URL' constraint).

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful lifecycle context the annotations don't carry: deprecation status and legacy-route parity. It says nothing about auth needs, rate limits, or size/page limits, so with annotations carrying safety it lands at a solid 3.

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 and output. The 'legacy' concept is stated twice ('legacy Desearch /web/crawl route' and 'stays for parity with that route'), a minor redundancy that keeps it just short of a 5.

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 does cover the return shape (plain text or HTML) and the deprecation/alternative story, which is what an agent needs to choose and call it. Missing only operational details like payload size limits or JS-rendering caveats for a read-only, open-world crawl 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 description coverage is 100% (js, url, wait, format are all documented in-schema with an enum for format). The description's mention of 'plain text or HTML' only echoes the format enum values, adding no syntax or behavioral detail beyond the schema. Baseline 3 applies when the schema does all the parameter work.

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+resource (crawl a public URL) and the exact output shapes (plain text or HTML), plus the underlying route (/web/crawl). It also distinguishes itself from the sibling 'extract' by naming it, so an agent can route without opening either 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?

Names the alternative tool explicitly ('Prefer extract for new integrations') and gives the condition that selects it (new vs. legacy integrations), plus the reason this tool still exists (parity with the legacy route). Nothing about when to pick this versus extract is left to inference.

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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the non-obvious behavioral fact that non-'web' source ids are rejected, but says nothing about result format, pagination, or latency/rate 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?

Two short sentences with the tool's action front-loaded and the source restriction immediately following. No filler beyond the minor branding mention of 'Desearch'.

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 read-only search tool with rich annotations and a fully documented schema, this is adequate but thin. With no output schema, the description could have sketched what a result looks like, and it offers no context on how it differs from the many sibling search tools.

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

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

Schema description coverage is 100%, with the schema documenting count bounds, the tools enum/default, and a prompt example, so the baseline is 3. The description adds nothing beyond the schema for parameters.

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 ('search the web for links') plus the backend (Desearch), which is enough to identify it as a general web link search. It does not explicitly name the sibling it contrasts with (e.g. x-links-search or web-search), so an agent must infer differentiation from the namespace.

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 constraint 'Only the web source is accepted' implicitly tells the agent not to use this for X/Twitter link search, which is useful negative guidance. However, it never states when to prefer this over siblings like web-search, ai-search, or web-crawl, so selection 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=true, openWorldHint=true, and destructiveHint=false, so the safety and open-world profile is covered structurally. The description adds useful return-shape context ('ranked titles, links, and snippets') that annotations do not convey, but says nothing about rate limits, result caps, or pagination behavior beyond what the schema hints.

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, zero filler, with the core purpose front-loaded before the return-format detail. Nothing is padded or 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 two-parameter, annotated, read-only search tool the description covers what it does and what it returns; the absence of an output schema makes the return-shape sentence valuable. It stops short of routing guidance relative to the many search siblings, which is the one real completeness 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% and both parameters are documented there, including the pagination semantics of 'start', so the description adds no parameter-level meaning. Baseline 3 is appropriate when the schema carries the full burden.

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 ('SERP-style web search') plus the backend ('Desearch') and the returned artifact (ranked titles, links, snippets). However it never distinguishes itself from siblings like ai-search, web-links-search, or extract, so an agent cannot tell which search entry point to choose without inferring.

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 when-to-use guidance at all. With three closely related siblings (ai-search, web-links-search, x-search) the description gives no condition or exclusion that would route an agent to this tool over an alternative; the only hint is the implicit 'general web query' framing of 'SERP-style'.

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, openWorldHint, and destructiveHint=false, so safety is covered. The description adds that results come from an AI/Desearch pipeline and are links only, which is useful context, but says nothing about rate limits, result freshness, or what happens when no matches are found.

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, purpose front-loaded, with no filler. The second sentence is mildly redundant with the first ('search for post links' vs 'returns links from posts') but does clarify the return shape, which matters because there is no output schema.

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 states that links are returned, and annotations carry the safety profile. However, for a tool sitting among five-plus overlapping search siblings, it lacks the differentiating detail an agent needs to route to it confidently.

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

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

Schema description coverage is 100% with only two parameters, and the schema already documents prompt and count (including min/max bounds). The description adds no syntax, format, or prompt-engineering guidance beyond what the schema provides, 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?

Specific verb (search) plus resource (X/Twitter post links) and the backing engine (Desearch), so an agent knows this returns links rather than posts. It implicitly separates itself from web-links-search by scoping to X, but never names or contrasts the many sibling search 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?

The description gives no when-to-use guidance and no alternatives. Siblings like x-search, ai-search, and web-links-search overlap heavily, and nothing here explains which one an agent should pick for link discovery versus post retrieval.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond that: no auth requirements, no rate-limit note, no behavior for missing/invalid IDs or protected posts.

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 front-loaded sentence with zero filler; the resource and lookup key come first. Nothing is wasted and nothing is buried.

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 tool with no output schema and full annotation coverage, the definition is essentially sufficient to invoke correctly. It could go further on error/missing-post behavior, but nothing essential 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% and the single 'id' parameter is documented with an example in the schema itself. The description adds no format or constraint detail beyond what the schema already provides, 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 ('Fetch a single X post') plus the lookup key ('by its ID'), which implicitly separates it from x-posts-by-urls and x-posts-by-user. It never names a sibling or explicit boundary, so it falls short of the 5 tier.

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 when-to-use guidance at all. With a crowded sibling set (x-posts-by-urls, x-posts-by-user, x-search, x-post-replies), the description should say when ID lookup is preferable, but it leaves the agent to infer everything.

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, destructiveHint=false, and openWorldHint=true, so the safety and reach profile is covered. The description adds essentially nothing beyond that: no pagination behavior, no ordering, no rate-limit or result-cap context, and no note that count caps at 100.

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 zero filler. The core action leads and the optional modifier trails it. Nothing can be trimmed 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 read tool with no output schema and full schema coverage, the description is barely sufficient. It leaves open the practical questions an agent faces: how many replies come back by default, whether results are paginated or ordered, and how the keyword query interacts with the fetched set.

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 schema already documents post_id, count (1-100), and the advanced query string. The description only restates the query parameter and adds no format, syntax, or default value 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?

The description states a specific verb and resource: 'Fetch replies to an X (Twitter) post.' That is unambiguous on its own. However, it does not distinguish this tool from close siblings such as x-user-replies (replies authored by a user) or x-search, so an agent must infer the boundary.

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 when-to-use guidance, no prerequisites, and no mention of alternatives. The phrase 'with an optional keyword query' hints at filtering but never says when keyword filtering is preferable to a plain fetch or to using x-search for reply discovery.

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 and destructiveHint=false, so the safety profile is covered. The description adds the pagination/cursor behavior, but says nothing about auth requirements, rate limits, or result completeness for a public X endpoint.

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, and the core action is front-loaded ahead of the paging hint.

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?

A simple two-parameter read tool; annotations carry the safety profile and the schema documents both params. There is no output schema, so the return shape is not explained, but nothing essential for a correct call 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% and both parameters are fully documented in the schema, so the baseline is 3. The description restates cursor's purpose (paging) without adding syntax or format detail beyond the schema.

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

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

States a specific verb and resource: 'List users who retweeted an X (Twitter) post.' The resource is precise enough to separate it from siblings like x-post-replies or x-posts-by-user, 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?

'Pass cursor to page through more users' gives operational guidance for the pagination parameter, but there is no statement of when to use this tool versus the other X-post tools (e.g., replies, by-id). Usage is implied by the resource name rather than stated.

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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds essentially nothing beyond that — no batch size limits, rate-limit notes, behavior on invalid or deleted URLs, or partial-failure handling, which matter for a batch fetch against an open-world source.

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 verb and resource come first. Nothing in the sentence is 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 simple one-parameter read tool with full schema coverage and safety annotations, the description is minimally sufficient. It is missing the operational context that would make a batch external fetch fully usable, such as batch limits or per-URL failure behavior.

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 only one parameter, so the schema carries the semantics (array of URL strings, minItems 1, with an example). The description only restates 'a list of post URLs' without adding format constraints or limits, so 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?

The description states a clear verb ('Fetch') and resource ('full X (Twitter) posts') scoped to a list of post URLs, which is specific enough to understand the operation. However, it does not distinguish itself from the closely related sibling x-post-by-id, which an agent might reasonably choose for the same intent.

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 guidance on when to use this bulk-by-URL tool versus x-post-by-id, x-user-posts, or x-search. The description also omits any prerequisites or conditions such as URL validity requirements or what happens with mixed/broken URLs.

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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds nothing behavioral beyond that — no mention of rate limits, pagination, result ordering, or what an empty result means — making it essentially redundant with 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?

A single tight sentence with no filler, and the core action is front-loaded. It is arguably too terse for a tool with a confusable sibling, but there is no wasted language.

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 3-parameter read tool with full schema coverage and annotations, the description is minimally sufficient to call the tool correctly. It falls short on sibling disambiguation (x-user-posts) and any behavioral context about result volume or ordering.

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 all three parameters (user, count, query) are documented in the schema itself. The description restates the optional keyword query but adds no syntax, format, or default details beyond the schema, 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+resource (search X posts) scoped to a user, plus an optional keyword filter. It is clear what the tool does, but it offers no differentiation from the very similar sibling x-user-posts, which an agent could easily confuse it with.

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 'with an optional keyword query' implies one usage pattern (keyword-filtered user timelines), but there is no explicit when-to-use guidance, no prerequisites, and no naming of alternatives such as x-search or x-user-posts.

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, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral fact beyond the schema — 'Sort stays Top' — meaning ordering cannot be changed, but it says nothing about result volume, rate limits, or the cost of the AI-backed search.

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 qualifier about optional filters. There is minimal waste, though the 'using Desearch AI' branding adds little operational value.

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 14 parameters and no output schema, the description is thin: it does not describe the return shape (posts? fields?), pagination, or the cost/latency of an AI-backed search. The 100%-covered schema compensates for parameter documentation, making this merely adequate rather than inadequate.

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%, including the format example for 'query' and the min_* engagement filters, so the schema does the heavy lifting. The description only recaps filter categories (user, date, language, verification, media, engagement), adding no syntax or constraint detail beyond what parameters already document.

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 ('Search X (Twitter)') and names the underlying engine (Desearch AI), so the agent knows this is a general keyword/query search. It does not, however, explicitly distinguish itself from close siblings like x-links-search, x-posts-by-user, or web-search.

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 usage by noting that filters are optional and narrow results, but it never states when to pick this tool over siblings such as x-user-posts or x-links-search, nor any prerequisites or exclusions. Guidance is inferred rather than stated.

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, destructiveHint=false, and openWorldHint=true, so the safety and scope profile is covered. The description adds only that results come from Desearch, and says nothing about rate limits, freshness of trends, or failure modes.

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 with zero filler, front-loading the action and resource before the input mechanism. Nothing is redundant or padded.

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 read-only two-parameter tool with no output schema and full schema coverage, the description is nearly complete. It could note what a trend entry looks like or whether count defaults, but nothing critical 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 description coverage is 100%: both woeid and count are documented in the schema with ranges and an example. The description adds no syntax or format detail beyond repeating the WOEID requirement, 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 (retrieve) and resource (trending topics on X/Twitter), plus the scoping mechanism (location via WOEID). It does not explicitly name a sibling, but no sibling covers trends, so it is implicitly distinct.

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 tool versus alternatives, no prerequisites, and no exclusions; the only added detail is the data source (Desearch). An agent must infer usage entirely from the name and the WOEID requirement.

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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered without the description. The description adds nothing beyond that — no notes on rate limits, auth requirements, result ordering, or timeline scope (e.g., replies/retweets included) — so its behavioral contribution is minimal.

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 free of filler. The second sentence is somewhat redundant with the schema's cursor description, so it doesn't fully earn its place, but overall sizing is appropriate.

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 full schema coverage and a complete read-only annotation set, the description is adequate. It omits what the returned post objects contain (no output schema exists) and, more importantly, how this differs from the sibling x-posts-by-user.

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 (username, cursor) are already documented in the schema, giving a baseline of 3. The description's cursor note restates pagination behavior rather than adding format or semantics beyond the schema.

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+resource ('Retrieve a user's X (Twitter) timeline posts by username'), which is clearer than a bare name restatement. However, it offers no differentiation from the near-identical sibling x-posts-by-user (or x-search/x-user-replies), leaving the agent unable to tell which to pick without opening schemas.

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 when-to-use or when-not-to-use guidance and no named alternative. The only operational note, 'Pass cursor to page through more posts,' is parameter mechanics rather than selection guidance, so the agent gets no help choosing between this and x-posts-by-user.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the useful behavioral detail that both posts and replies are returned, but says nothing about pagination, rate limits, or result 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 front-loaded sentence with no filler; the primary action and the optional qualifier are both stated 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?

For a simple read-only, 3-parameter tool with no output schema this is minimally adequate, but it leaves the overlap with x-user-posts and x-post-replies unresolved and gives no hint about result volume or pagination behavior.

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 all three parameters are already documented. The description only restates the optional keyword query, adding no format, syntax, or default semantics beyond the schema, so the baseline of 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 (Fetch) and resource (posts and replies by an X user), so the agent knows the operation. However, it does not differentiate itself from close siblings like x-user-posts, x-post-replies, or x-search, and the phrase 'posts and replies' blurs the boundary with x-user-posts.

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 when-to-use guidance is given. The mention of an 'optional keyword query' implies a filtered-search use case, but the description never says when to prefer this tool over x-user-posts, x-post-replies, or x-search.

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