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

With no annotations, the description carries the full burden of behavioral disclosure. It does mention a notable side effect — writing findings to Notion via the Notion MCP server — and the iterative ratchet behavior. However, it ambiguously attributes that write to 'the AI agent' rather than to the tool call itself, leaving uncertainty about what actually happens when this tool is invoked. It also omits prerequisites or potential non-deterministic 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?

The description is short, front-loaded with the primary purpose, and avoids redundant phrasing. The middle sentence is somewhat convoluted and could be split or clarified, but overall the length is appropriate for the tool's complexity.

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 no output schema and no annotations, the description gives useful workflow context: it generates a prompt, involves an AI agent, writes findings to Notion, and supports iterative refinement. However, it leaves ambiguity about the tool's return value, whether the write happens immediately as a side effect, and what the generated prompt should contain. These gaps make the definition minimally viable but not 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%, so the schema already explains both market_id and iteration. The description adds little beyond restating the iteration ratchet concept already present in the schema's iteration description. It does not clarify formats, defaults, or how iteration affects output, so it provides no significant additional semantic value.

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 sentence names a clear verb and resource: it generates a structured research prompt for a Polymarket market. However, the following sentence blurs the tool's actual behavior by stating 'the AI agent should analyze the prompt, form a thesis, then write findings to Notion' — it is unclear whether the tool merely produces a prompt or also performs the research/write. It also does not distinguish itself from siblings like research_with_ollama or batch_research.

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

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

The description gives a clear usage hint for the iteration parameter: 're-run with higher iteration to refine.' It does not explain when to choose this tool over sibling research tools, nor does it mention exclusions or prerequisites such as requiring the Notion MCP server to be configured. The usage context is implied rather than explicit.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It does disclose the main side effect—writing reports to Notion—and indicates an agent-driven multi-step flow. It does not mention potential long-running behavior, external service dependencies, or what happens if a market fails, leaving moderate transparency gaps.

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 a single sentence with no filler and front-loads the primary purpose. The second clause adds needed behavioral context about processing and Notion output, though the run-on structure slightly reduces crispness.

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

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

The description covers the main action, batch scope, and Notion side effect, but omits return behavior, execution expectations, and any explicit differentiation from sibling tools. Given the absence of annotations and an output schema, it is adequate but not comprehensive for a multi-step orchestration 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 coverage is 100%, so the baseline is 3. The description adds no parameter-specific meaning beyond the schema, but the parameters themselves are well documented in the schema with defaults and bounds.

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 clearly states a batch operation over multiple trending markets and names the downstream effect of writing reports to Notion, distinguishing it from singular research tools like auto_research_market. The phrase 'Generate research prompts' is slightly ambiguous about whether the tool itself performs research or merely produces prompts, but the overall intent is discernible.

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 context is implied: use when multiple trending markets need research and Notion reporting. However, there is no explicit guidance about when not to use this tool or which sibling to prefer for single-market research, direct analysis, or formatting-only tasks.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It implies a pure computation via the verb 'Calculate' and the phrase 'before logging a trade' hints that it does not itself log, but it never explicitly states read-only behavior, whether it makes network calls (e.g., fetching prices), requires special permissions, or has any side effects. For a tool in a trading context, where an agent might confuse calculation with execution or recording, this ambiguity is a real gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no fluff: the first front-loads the tool's outputs, the second gives timing. Every word earns its place. It loses a point only because the brevity also skims past behavioral information that, with no annotations on the tool, an agent would benefit from.

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 neither annotations nor an output schema, the description itself must communicate what the agent gets back; the four named outputs partially cover this. However, it does not clarify whether the computation requires prior price fetch for market_id, how fair_value affects the results, or whether the tool is safe to call at any point. For a six-parameter calculation helper this is adequate but incomplete — an agent could call it correctly yet be surprised by missing prerequisites or ambiguous return shape.

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 every parameter already has meaning in the input schema, meriting the baseline 3. The description names output metrics (risk/reward ratio, max gain/loss) but does not explain how they relate to inputs like fair_value, stop_loss, or size_usd; the optional fair_value parameter's role in the calculation is left untouched. No value beyond the schema is added, but none needed for a 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?

The description uses a specific verb and resource ('Calculate trade parameters') and enumerates concrete outputs (position sizing, risk/reward ratio, max gain, max loss), so an agent knows roughly what this tool produces. It does not explicitly differentiate itself from siblings like generate_execution_plan or compare_markets, but the 'calculate' framing and output list make the purpose clear enough.

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?

'Use before logging a trade' gives clear temporal context and tells the agent where this tool fits in the trading workflow. It does not, however, name alternatives or exclusions — e.g., there is no guidance on when to prefer generate_execution_plan or when this tool is unnecessary — so it stops 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?

With no annotations supplied, the description carries the full burden of behavioral disclosure. It discloses the main behavior—fetching prices and computing P&L—but leaves ambiguity about whether the tool directly writes to Notion or only prepares data for a downstream write. This is a notable gap, though the core operation is understandable.

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 concise, front-loaded sentences. The primary action is stated first, followed by the workflow context. No filler or redundant restatement of the tool name or 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?

The tool is simple with a single well-documented parameter, and the description explains the operation and its workflow purpose. However, there is no output schema and the description does not indicate the return structure or whether it writes to Notion directly, leaving a small 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%, so the schema already documents all parameter meanings. The description adds only the relationship between entry prices and P&L calculation, which is marginal value 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?

The description states a specific verb and resource: 'Fetch current prices for a list of market IDs and calculate P&L against entry prices.' This clearly distinguishes it from price-only siblings like get_prices by adding the P&L calculation and the Notion Trade Journal workflow context.

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 explicitly says 'Use this to update the Notion Trade Journal,' giving clear context for when to call it. It does not name alternatives or state when not to use it, but the purpose is specific enough that the intended workflow is understood.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It conveys a presentation style ('side by side') and the use case, but is silent on output format, odds freshness/aggregation, error behavior for invalid market IDs, and any authentication or rate-limit expectations. For a tool with zero annotation coverage, this is a meaningful transparency gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, each earning its place: the first states the operation, the second the decision-relevant use case. The action verb is front-loaded and there is zero filler or restatement 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?

For a one-parameter read-only comparison tool, the definition is mostly adequate: the schema fully documents the input, and the description communicates the core operation and use case. However, with no annotations and no output schema, the agent is left guessing about return format and about when to prefer this over the sibling tools. Adequate but with clear gaps.

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

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

Schema description coverage is 100%: the sole required parameter market_ids is documented as 'Market IDs to compare' with minItems (2) and maxItems (10) constraints. The description's mention of 'odds across multiple markets' reinforces the parameter's meaning but adds nothing beyond what the schema already provides. 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?

The description states a specific verb and resource — 'Compare odds across multiple markets side by side' — and adds a concrete use case. The action reads distinct from siblings like get_market (single market) and search_markets (discovery), though it never explicitly names or contrasts itself with any sibling. Clear purpose, but sibling differentiation is only implicit, so 4.

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?

'Useful for finding relative value or arbitrage opportunities' implies when the agent should reach for this tool, but there is no when-not-to-use guidance and no named alternatives. The sibling list is noisy and repetitive (get_market, scan_trending_markets, search_markets, get_events), so an agent gets little help choosing among overlapping market-centric tools. Usage context is implied, not explicit.

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

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

With no annotations, the description carries the burden and does disclose that output is heuristic-based ('simple heuristics') and intentionally shallow ('quick filter'). It stops short of describing return shape, pagination, or potential side effects, though 'scan/flag' implies a read-only screening operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no wasted words. The first sentence states the action and outcome; the second adds workflow context. The content is front-loaded and all earns its place.

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 screening tool, the description gives purpose and usage context. It does not explicitly describe the return format, and there is no output schema to compensate, but 'flag those where...' sufficiently implies a list of candidate markets.

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 parameter 'limit' is already fully described in the schema as 'Markets to scan', so schema coverage is 100%. The tool description adds no additional meaning about limit behavior, keeping this at baseline.

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

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

The description uses a specific verb ('Scan') and identifies the resource ('trending markets') plus the purpose ('flag those where simple heuristics suggest potential mispricing'). It is clear but does not explicitly contrast with the similarly named sibling 'scantrending_markets'.

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?

'A quick filter before deep research' gives clear placement in the workflow, implying it should be called before deeper market analysis. However, it does not name alternatives or explicitly state when not to use this tool.

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

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

With no annotations provided, the description carries the full transparency burden. It clearly discloses that this tool returns Notion API block content and does not create the page itself, as indicated by the workflow step 'First create a page... Then call this tool to get the formatted blocks.' It could further specify the types of blocks generated, but the core behavior is transparent and not misleading.

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 concise and well-structured with a front-loaded purpose and a numbered workflow that is easy to follow. The adjectives 'beautiful,' 'rich,' and 'stunning' add little functional value, but the overall description remains focused and efficient.

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 the tool's complexity (9 parameters, no output schema, no annotations), the description explains the essential external integration context: how to wire this tool with page creation and block patching. It does not enumerate output block types, but the statement that it returns an exact Notion API block structure is sufficient for a caller to understand the return value and pass it downstream.

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 input schema covers 100% of parameters with descriptions, so the baseline is 3 even though the tool description adds no per-parameter information. The workflow implicitly ties parameters to producing a research report, but no additional meaning is provided 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?

The description starts with a specific verb ('Generate') and resource ('Notion page content blocks for a market research report'), and clarifies the exact output type ('the exact Notion API block structure'). It clearly distinguishes itself from sibling formatting tools like format_watchlist_entry by focusing on research report pages rather than watchlist entries.

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 provides a clear three-step workflow involving API-post-page and API-patch-block-children, showing exactly where this tool fits in the broader process. It doesn't explicitly contrast this with alternatives like format_watchlist_entry or mention when NOT to use it, but the research-report focus and integration steps give strong contextual 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?

With no annotations, the description carries the behavioral burden. It is transparent that the tool only generates and returns a structure rather than performing side effects, and it explicitly states that the result is meant for another tool to consume. It does not detail edge cases, but the non-mutating formatting behavior is sufficiently clear.

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 two sentences with no filler. The first sentence states the core purpose, and the second adds the crucial integration context about how the result should be used. Every sentence earns its place.

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 formatter with complete input schema coverage, the description explains both what it returns and how the return value should be used. There is no output schema, but the description clarifies that the output is the exact Notion API properties structure, which is sufficient given the tool's narrow scope.

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 all four parameters with descriptions and constraints. The tool description adds no additional parameter-level meaning, so the baseline score of 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?

The description states a specific verb ('Generate'), a precise resource (the properties object for adding a market to the Notion Watchlist database), and the exact deliverable (Notion API properties structure). It clearly differentiates the tool from siblings like watch, which likely performs the actual write, and format_research_for_notion, which targets a different format.

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 clear usage context: use this tool to produce a properties object that is then passed to the Notion MCP's API-post-page tool. It does not explicitly name alternatives or exclusion conditions, but the downstream instruction leaves little ambiguity about when this tool is needed.

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

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

With no annotations, the description carries the full burden of disclosing behavior. It reveals that the tool consumes human-approved markets and produces a plan involving Kelly sizing, risk limits, and correlation checks. However, it does not disclose whether the plan is purely returned, persisted somewhere, or triggers any trades, nor whether it actively reads from Notion itself.

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 carry the full message with no filler: the first states the core function and method, the second gives the workflow context. The essential information is front-loaded and every sentence earns its place.

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 only three parameters, a complete schema, and moderate complexity, the description covers the important prerequisites, inputs, and processing approach (Kelly sizing, risk limits, correlation checks). The main gap is the absence of an output schema or explicit description of the returned plan format, but this is a minor omission given how clearly the tool's role is stated.

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 approved_markets, total_bankroll, and max_portfolio_risk with descriptions and defaults. The tool description adds useful high-level framing ('human-approved', 'fair values', 'risk limits') but does not significantly elaborate on individual parameter semantics beyond what the schema provides.

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 action ('generate a portfolio execution plan') on a specific resource ('human-approved markets with fair values'), and includes distinctive details such as Kelly criterion position sizing, risk limits, and correlation checks. This clearly differentiates it from siblings like calculate_trade, which likely targets individual trades rather than a portfolio plan.

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 explicit contextual guidance: 'Use after reading human approvals from Notion,' establishing the prerequisite workflow and when this tool is appropriate. It does not explicitly name alternatives or exclusions, but the temporal cue is strong enough for an agent to decide when to invoke 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?

No annotations are provided, so the description carries the full burden. 'Get' implies a read-only operation and the scope is stated, but the description does not disclose limitations, required permissions, response shape, or what 'full details' actually includes. It adds some behavioral context but remains thin.

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 wasted words. It immediately communicates the action, resource, and scope.

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

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

For a one-parameter read with no output schema, the description is minimally adequate: the agent knows what to pass and that all markets are included. However, without annotations or an output schema, response details and constraints remain underspecified, so the agent still has to make inferences.

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 only parameter, event_id, is already described in the schema as 'Polymarket event ID' with 100% coverage. The description reinforces event-level semantics but adds no new parameter-level guidance, so the baseline of 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?

The description uses a clear verb ('Get'), names a specific resource ('a Polymarket event'), and adds the distinctive scope 'and all its markets.' This makes it easy to tell apart from market-level siblings like get_market and list-level tools like get_events.

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 'event and all its markets' gives clear context for when to choose this tool over a single-market tool. However, it does not explicitly name alternatives or say when not to use it, leaving some routing 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?

No annotations are present, so the description carries the full burdon. It fails to define what 'top' means, how results are sorted, whether full event details or summaries are returned, or any pagination/behavioral notes. The agent is left guessing about the actual response characteristics.

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 primary action and a use case hint are front-loaded. Every word serves a purpose.

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 no output schema and no annotations, the description should compensate by describing return values or behavior. It doesn't specify what an event contains, how top is determined, or the response shape. For a simple tool this is still a notable gap that leaves an agent uncertain about 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?

Schema coverage is 100%, so the schema already documents the limit paramater with default, min, max, and description. The description adds no extra paramater semantics beyond loosely suggesting 'top' but doesn't link it to the limit value or ordering.

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

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

The description uses a specific verb ('Fetch') and resource ('top Polymarket events') and even defines what an event is. It implicitly differentiates from get_market and get_event by focusing on a group of related markets, but it does not explicitly name the singular alternative or contrast 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?

It says 'Great for finding multi-market opportunities,' which gives a use case. However, it does not provide when-to-use vs alternatives, exclusions, or conditions that would route an agent to get_event or search_markets 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?

No annotations are provided, so the description carries the disclosure burden. The verb 'Get' and the listed return fields make clear this is a read-only fetch returning a market snapshot, which is useful. However, it does not disclose response structure details, potential error behavior, or how condition_id versus slug resolution behaves.

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, front-loaded sentence with no filler. Every element earns its place: the verb, resource, and return fields.

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 fetch with no output schema, the description is mostly complete: it states the resource and the main payload categories. It stops short of fully specifying the shapes of outcomes, prices, volume, and liquidity, but that level of detail is not necessary for selecting and invoking the 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 coverage is 100%, with market_id described as 'Polymarket market ID (condition_id or slug)'. The tool description adds no parameter-specific meaning, but with complete schema coverage the baseline of 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?

The description names the exact operation ('Get full details') and target resource ('a Polymarket market'), then enumerates the returned fields: description, outcomes, prices, volume, liquidity. This clearly distinguishes get_market from price-only or search-oriented siblings like get_prices and search_markets.

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 use when a caller needs the full detail set for a single market, but it does not explicitly state when to prefer this over siblings such as get_prices, get_event, or search_markets. There are no exclusions or alternative routing cues; the selection must be inferred from the word 'full'.

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

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

With no annotations provided, the description must carry the behavioral disclosure burden. It implies a safe read-only operation ('get current prices') but doesn't mention how errors are handled, whether the data is live vs. cached, or what constitutes a 'current price.' This is adequate for a simple price fetch but not deeply transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no wasted words. The purpose is front-loaded and the usage guidance is immediately actionable. It earns its place.

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 one well-documented parameter and no output schema, the description is sufficient to call it correctly. It doesn't describe the response shape or error behavior, but those are not critical for a straightforward price query given the low complexity. Minor gaps remain, but overall completeness is strong.

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 schema has 100% coverage for the single parameter 'market_ids,' including a clear description. The description adds no extra parameter meaning beyond echoing 'by ID' and 'markets.' Baseline 3 is appropriate when the schema already documents the parameter well.

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 and resource: 'Get current prices for one or more markets by ID.' This is specific and actionable. It doesn't explicitly distinguish from siblings like get_market or search_markets, but the purpose is unambiguous on its own.

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 provides clear context for when to use the tool: 'Use this to refresh watchlist or check positions.' It gives practical scenarios but does not explicitly mention alternatives or exclusion cases, so it falls short of the highest bar.

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

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

With no annotations, the description carries the burden and discloses key behaviors: it fetches external market data, depends on a local Ollama service, returns three artifacts, and does not itself write to Notion ('ready to write'). It could also mention failure behavior when Ollama is unavailable, but the main behavioral traits are covered.

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 front-loaded with purpose, then gives a numbered return breakdown and a clear prerequisite. It is slightly redundant ('research' repeated and the Research Button phrase), but each section earns its place for a multi-artifact tool.

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?

Because there is no output schema, the description compensates by enumerating the three return components and telling the agent where to pass each one ('pass to API-patch-block-children', 'pass to API-post-page or API-patch-page'). It would be more complete with an explicit mention of what happens if Ollama is not reachable, but the actionable downstream flow is present.

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%, with both `market_id` and `iteration` described in the schema. The description adds no additional parameter detail beyond the schema, so the high-coverage 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?

The description states a specific action: 'One-click AI research: fetches market data, calls local Ollama LLM for analysis, and returns both the research results AND formatted Notion blocks ready to write.' It clearly marks the tool as the 'Research Button' and lists distinct outputs, but it does not explicitly contrast with sibling research tools like auto_research_market or batch_research.

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

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

It provides direct usage context: 'call it, then write the output to Notion,' and specifies a prerequisite: 'Requires Ollama running locally (default: http://localhost:11434).' However, it does not explain when to choose this over sibling automation/formatting tools, so it stops short of explicit exclusions.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It does disclose the key filtering and ordering behavior ('active' and 'ranked by volume'), but it does not elaborate on output structure, potential latencies, or any live-data caveats. The basic read-only nature is implied by 'Fetch' but not expanded.

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, direct sentences with no filler. The first sentence states the core action and output; the second gives the intended use case. Every word earns its place and the key 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 tool with one optional, fully-documented parameter, no required inputs, and no output schema, the description is reasonably complete. It tells the agent what the tool returns, how it ranks results, and when to use it. It could add return-format specifics, but the low complexity makes the absence non-critical.

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

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

Schema description coverage is 100%: the single 'limit' parameter already has a default, min, max, and description. The tool description adds no additional parameter meaning, so the baseline score 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?

The description states a specific verb ('Fetch') and a specific resource ('hottest active Polymarket markets ranked by volume'), which clearly distinguishes it from siblings like search_markets or get_market. It conveys exactly what the tool returns and by what criterion (volume ranking).

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 'Use this to discover trading opportunities' provides clear contextual guidance on when to select this tool. It does not explicitly name alternatives or exclusions, but the discovery-oriented framing is enough to steer an agent toward this tool for top-market exploration.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only restates the search function and gives examples; it does not mention result ordering, live vs cached data, rate limits, pagination behavior, or what the returned market objects look like.

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 a single sentence that front-loads the action and resource, then provides helpful examples in parentheses. There is no filler or redundant 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-only search with fully documented parameters, the description and schema are minimally viable. However, the lack of annotations and output schema leaves the agent without guidance on return value shape, ordering, or behavior relative to sibling searching 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%, so the schema already documents both parameters adequately. The description adds example keyword values but does not provide additional semantics beyond what the schema states for query or limit.

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 action (search), a resource (Polymarket markets), and the matching criterion (keyword), with concrete examples. This clearly distinguishes it from siblings like get_market (fetch by ID) and scan_trending_markets (trending, not keyword-based).

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

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

The description implies when to use the tool: when you need markets matching a keyword. However, it does not explicitly state when to prefer this tool over scan_trending_markets or get_market, nor does it mention any exclusions or fallback conditions.

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

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

With no annotations, the description carries the full burden, and it does disclose the main side effects: creating databases, populating data, and auto-watching. However, it does not mention whether rerunning setup is safe, whether it overwrites existing databases, whether it requires authentication, or what 'auto-watching' implies operationally.

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, each earning its place: the first states the purpose, the second lists the concrete actions, and the third gives trigger phrases and reassures the agent that no further steps are required. There is no filler or redundancy.

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

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

The description covers purpose, effects, and triggers, which is solid for a setup tool with one optional parameter. However, it lacks important operational context: no mention of possible side effects on existing Notion content, no output/return behavior, and no indication of whether setup is async or long-running. The absence of annotations and output schema makes these gaps more noticeable.

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 schema has 100% coverage for the single optional parameter 'market_count', including its default, range, and description. The tool description adds no extra detail about this parameter, but since the schema already documents it well, the baseline of 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?

The description clearly states the action ('Set up'), the target ('PolyDesk trading desk in Notion'), and the concrete outcomes: creates databases, populates with live Polymarket data, and starts auto-watching. This makes it distinct from the sibling tools, which perform individual operations rather than full setup.

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?

Explicit trigger phrases are provided ('setup', 'set up', 'create trading desk', 'start'), and the description says no extra steps are needed. It does not list alternative tools or explicitly say when not to use it, but for an all-in-one setup command the trigger conditions are clear enough.

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

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

With no annotations, the description carries the transparency burden. It lists concrete side effects: running research, writing reports, unchecking the research checkbox, searching Polymarket, populating data, generating execution plans, and refreshing prices. It does not discuss failure modes, authorization, or idempotency, but it is fairly transparent about the tool's mutating 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?

The description is front-loaded with purpose and trigger, then uses a numbered list to organize five behaviors. It is somewhat long, but the extra detail is substantive for a multi-step sync tool and the example reinforces usage.

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 complex tool with no annotations and no output schema, the description covers the main operations, trigger, and a realistic example. It does not describe the return value or what the user sees after sync completes, but an agent has enough information to decide when to call it and what it will do.

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 and the schema already documents each parameter. The description adds workflow context, especially around the research step, but does not clarify the relationship between the run_research parameter and the Notion research checkbox described in the first workflow item.

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: 'Bidirectional sync between Notion Watchlist and Polymarket/Ollama' with a clear trigger ('Call this when user says sync'). It describes several concrete behaviors, but does not explicitly differentiate itself from sibling tools like research_with_ollama or generate_execution_plan, which it orchestrates.

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 explicit when-to-use guidance: 'Call this when user says "sync"' plus a concrete example. It does not mention when not to use it or when a sibling tool would be more appropriate, but the trigger and high-level workflow are clear enough.

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

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

With no annotations provided, the description carries the behavioral burden. It honestly discloses that the tool mutates state by stopping the polling loop. It does not mention idempotency or error behavior when no loop is running, but the core side effect is clearly named.

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 primary action, and zero filler. Every word contributes to understanding what the tool does and how it relates to 'watch'.

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 no-argument control command with no output schema, the description is complete. It explains the action, the target resource, and the relationship to the starting command. Nothing essential is missing for an agent to invoke it correctly.

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

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

The tool has zero parameters, so there is no parameter semantic burden on the description. The schema already fully covers the empty parameter set, and the description adds no unnecessary parameter detail. Baseline 4 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?

The description states a specific verb ('Stop'), the resource ('auto-watching the Notion Watchlist'), and the mechanism ('Stops the polling loop started by watch'). It clearly distinguishes itself from its sibling tools, especially the paired 'watch' 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?

It explicitly ties usage to stopping the loop started by 'watch', making the intended call context clear. It does not enumerate alternatives or edge cases like calling when no watch is active, but for a simple stop command this is sufficient 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?

There are no annotations, so the description carries the behavioral burden. It clearly implies a read-only validation action ('Check', 'flagging') rather than a mutation, but it does not state whether the tool modifies state, requires special permissions, or how it handles invalid input. The return format of the flagged errors is also unspecified.

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 consists of two short sentences with no filler. The main purpose is front-loaded, followed by a clear usage directive, making it easy for an agent to parse quickly.

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

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

The description gives enough context to understand why and when to call the tool, and the schema defines the input. However, with no output schema and no explanation of the return value, an agent cannot anticipate whether the tool returns a pass/fail boolean, a list of flagged errors, or some other structure. The lack of side-effect and output details leaves a notable 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?

The tool description adds the conceptual context of 'human fair value overrides' and 'market data', but the input schema already documents the array structure, required fields, bounds, and individual property meanings. The description does not significantly compensate for the top-level parameter's lack of description beyond what the schema already provides.

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

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

The description uses a specific verb ('Check') and names the exact resource ('human fair value overrides') while stating the mechanism ('comparing against market data') and expected outcome ('flagging potential errors'). It clearly distinguishes itself from sibling tools like calculate_trade or auto_research_market by framing itself as a pre-trade validation step.

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 'Use before executing approved trades' provides explicit timing and context for when to invoke the tool. However, it does not mention when not to use it or identify alternative tools for different scenarios.

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

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

With no annotations, the description carries the full burden of disclosing behavior. It discloses the polling mechanism, the automatic research trigger, the NOTION_TOKEN requirement, and the stopping mechanism. However, it does not state whether the tool returns immediately, blocks, or creates side effects beyond triggering AI research, which is a meaningful gap for agent invocation.

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 compact and front-loaded: it states the core purpose first, then prerequisites and stop behavior. Each sentence adds information, and the 'no need to say sync' note earns its place by preventing a misuse. Minor redundancy exists between 'polls every N seconds' and 'auto-watching', but overall it is well-structured.

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

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

The description covers the key operational context: what is watched, what triggers research, the required environment variable, and how to stop the process. It does not describe the return value or explicitly connect research_database_id to the research trigger, but the schema covers the parameter meaning and the tool is conceptually simple enough that this is an acceptable minor 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 schema already documents all three parameters. The description adds only a loose connection ('every N seconds' to interval_seconds) and does not clarify the role of research_database_id beyond what the schema already states. 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?

The description uses a specific verb ('Start auto-watching') and identifies the exact resource ('Notion Watchlist'), with concrete behavior: polling for checkbox changes and keyword entries. It also distinguishes itself from siblings by noting that 'sync' is unnecessary and that 'unwatch' stops the watcher.

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 clearly states when to invoke the tool (to begin continuous watching) and tells the agent to call 'unwatch' to stop. It also implies an alternative ('no need to say sync') that differentiates it from sync_notion_watchlist, though it doesn't explicitly enumerate when not to use it.

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