Chameleons

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

The readOnlyHint annotation already establishes this as a safe read operation, and the description adds a useful size cap ('<=1.5 KB') plus conditional content when a trader is supplied. It does not contradict annotations, but it leaves out other behavioral details such as failure modes or caching.

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?

The description is very short and front-loads the rating rule, but the semicolon-linked fragment ('with trader, that trader's check per level, radar and stars history') is cryptic and poorly structured. It avoids verbosity but sacrifices clarity through under-specification.

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 tool with three parameters, no output schema, and only readOnlyHint annotations, the description is too sparse. It names some returned content but does not explain the 'cat' parameter, how 'format' changes output, or enough about the response shape for an agent to call 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 only 33%, with 'trader' documented as 'as get_trader' but 'cat' and 'format' undocumented. The description clarifies that 'trader' adds trader-specific output but says nothing about what 'cat' means or how 'format' affects the response, so it does not compensate for the low 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?

The description identifies the resource as the 1-5★ rating rule and notes that adding a trader returns that trader's per-level check, radar, and stars history. It is understandable despite jargon like 'check per level' and does not explicitly differentiate from sibling tools, but the core purpose is clear.

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 only usage-like signal is the conditional phrase 'with trader', which describes an optional parameter effect rather than when to choose this tool over siblings like get_trader or find_traders. No when-to-use or when-not-to-use guidance is given.

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?

readOnlyHint=true already declares the safety profile, so the description's job is to add context, and it does disclose two non-obvious traits: header lines reporting applied filters/defaults, and a <=4 KB result cap with paging. However, the phrasing is so compressed ('the rows line pages on') that the actual pagination/truncation semantics remain ambiguous, and nothing is said about defaults beyond 'what the defaults hid'.

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 dense sentence-fragments, front-loaded with the purpose, so nothing is obviously wasted. But the telegraphic style ('head lines say what applied and what the defaults hid', 'the rows line pages on') crosses from concise into cryptic and costs comprehension.

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?

Insufficient evidence to score; the description has no bearing on this dimension.

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 95%, so the baseline is 3, but the description genuinely adds meaning for three key filters: copyable ('% of checked trades a follower could fill', n=checked), ret_lo ('profit per copy as % of stake, 80% low end', n=kept_n), and crowd ('% copied within 2 s, upper bound'). These definitions go beyond the terse schema strings, though most of the 20 parameters receive no extra explanation.

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 opening noun phrase 'Polymarket traders, filtered and sorted like the page' conveys a filtered trader listing but never states a verb (list/find/search) or scope explicitly. It does not name or differentiate from siblings such as get_trader (single trader) or list_categories, so an agent must infer the distinction. Purpose is recognizable but not sharp.

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 prerequisite or exclusion, and no named alternative among the siblings. 'like the page' and the paging sentence hint at behavior but give no conditions for choosing this tool over get_trader or the recipe/bot guides.

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?

readOnlyHint=true already tells the agent this is a safe read, so the description's main added value is that the payload is documentation rather than data, plus the 'Not advice' disclaimer. It doesn't say what form the content comes back in or whether it is static, which matters for an agent deciding whether to re-fetch.

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 short sentence plus a two-word disclaimer, front-loading the resource and its purpose with no filler. The brevity is close to being cryptic — 'Not advice' and '/bots.md' are terse to the point of needing interpretation.

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

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

With no parameters, no output schema and a read-only annotation, the description carries the remaining burden of telling the agent what it gets back. It signals a markdown guide but not its scope or shape, leaving a small but real gap for an agent deciding whether this document answers its question.

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 no parameters, so there is no parameter semantics to convey and the baseline applies. The description does not need to explain arguments for a zero-arg call.

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 identifies a specific artifact (the /bots.md guide on building a copy bot and steering it with find_traders' filters), which is clearly distinct from siblings like find_traders or get_trader. It never states the verb explicitly (retrieve/read a document), so the operation is inferred rather than declared.

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?

Referencing find_traders' filters implies this guide should be read in conjunction with find_traders, which is useful routing. However, it never says when to call this versus get_copy_recipe or get_trader, and no preconditions or exclusions are given.

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?

readOnlyHint already covers safety, and the description adds real value beyond it: the return is a markdown document at a known path, contains watch/rules/costs/YAML sections, is capped at <=5 KB, and carries a 'Not advice' disclaimer. It does not cover whether a missing trader or recipe errors.

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?

Highly compressed and front-loaded — resource, location, contents, caveat, size limit — with no filler. The fragment style borders on cryptic, but nothing 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 read-only two-param fetch with no output schema, the description adequately characterizes what comes back. It falls short on the undocumented `cat` parameter and on any failure behavior, which an agent needs before calling.

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 path hint implies `trader` is a slug, but the schema already says 'as get_trader'. The `cat` parameter is never mentioned in the description and its schema entry has no description, leaving one of two params (50% coverage) unexplained anywhere.

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 resource (a trader's copy recipe) and its form (markdown at /traders/<slug>/copy.md), which separates it from get_trader. The telegraphic 'watch, rules, costs, YAML' enumerates contents rather than clearly saying 'fetch'.

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 your own agent' implies the use case — building an agent that copies a trader — but there is no explicit when-to-use, and no mention of when to prefer get_trader or get_bot_guide instead.

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, so the safety profile is covered. The description adds a payload budget ("<=2 KB") and enumerates the returned sections, which is real behavioral context, but the section names are undefined and nothing is said about truncation when the cap is hit.

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 fragments with zero padding and the payload cap front-and-center, so it respects the size bar. But the telegraphic style trades clarity for brevity, and 'radar with n' does not earn its place without a definition.

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 three-parameter tool with only one documented parameter and no output schema, the description should pin down 'cat' and 'format' and clarify the section names. It does the section listing but leaves the calling contract underspecified.

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 33%: only 'trader' is documented in the schema. The description never mentions 'cat' or 'format', leaving two-thirds of the parameters unexplained in both places — exactly the case where the description should compensate.

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?

"One trader" plus a list of returned sections implies a single-trader detail/profile fetch, which distinguishes it loosely from the list-oriented find_traders sibling. But there is no verb and the section names ("rule check", "radar with n", "stars history") are opaque jargon an agent cannot map to a purpose.

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 statement of when to use this versus find_traders or explain_rating, and no prerequisites such as needing a resolved trader identity. The singular framing only weakly implies single-trader lookup.

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?

The readOnlyHint annotation already declares the safe read-only nature. The description adds only a size cap ("<=800 B") and vague output content, but does not disclose behavioral traits such as pagination, rate limits, or authentication needs.

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?

The description is extremely short, consisting of two cryptic sentence fragments. While brief, it is under-specified rather than efficiently front-loaded, and "<=800 B" is unexplained in context.

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 listing tool with one optional parameter and no output schema, the description should clarify what categories, stars levels, and chip counts mean and how the format parameter affects output. It leaves these essential details 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 single optional "format" parameter has an enum (tsv/json) in the schema but 0% schema description coverage. The description does not mention the parameter or explain when to choose tsv versus json, so it fails to compensate for the missing schema documentation.

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

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

The description implies the tool returns category-grouped rows with stars-level detail and chip counts, which is more than a tautology. However, it omits an explicit verb like "list" and uses unexplained jargon ("stars level," "chip counts"), leaving the core purpose vague.

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 guidance is given about when to use this tool versus the sibling tools or when not to use it. The description provides no context about appropriate scenarios or prerequisites.

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