AIsa Prediction Markets

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

Adds substantial context beyond the readOnlyHint/openWorldHint/destructiveHint annotations: the call is free, it requires the Authorization header, and it discloses result semantics ('ok is true only when the balance was read; otherwise each entry of errors says what to do in next_step'). That tells an agent how to interpret partial failure, which annotations cannot convey.

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

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

Three sentences, front-loaded with what the agent gets, followed by cost/auth, then call triggers, then result interpretation. No sentence is redundant and none could be dropped 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 zero-parameter read tool with an output schema already present, the description covers the remaining gaps: cost, auth requirement, invocation triggers, and the ok/errors/next_step contract. Nothing an agent needs to call or interpret it correctly is missing.

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

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

The tool takes zero parameters, so the description has nothing parameter-level to compensate for, and the schema is fully covered. A 4 rather than 5 reflects that it adds no input-syntax detail, though none is possible here.

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

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

The description states a concrete resource set (identity/key, account balance, Go-to-Market wallet, usage over 1/7/30 days) rather than restating the name. It is clearly distinguishable from every sibling, which are all Reddit, batch, or search tools. An agent knows exactly what it will learn by calling it.

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 triggering conditions are given: 'Call it to verify a new connection or to explain a 402.' That is a strong when-to-use statement. It stops short of 5 because it names no alternative tool or a when-not condition, though the sibling list offers no obvious competing diagnostic.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description is not required to restate it. It adds genuine operational context: the batch_use prohibition, exact-name/prefix requirements, and session reuse semantics. It does not cover failure handling when names are invalid, keeping it below a 5.

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

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

Front-loaded with the core action and size limit, and every sentence carries workflow value. The session_id sentence duplicates the schema's own parameter description, which is minor redundancy rather than bloat.

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 batch retrieval tool with an output schema, the description supplies the orchestration context an agent needs (source of names, next steps, session handling) without needing to explain return values. Nothing essential to correct invocation is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds real meaning beyond the schema by constraining names to those returned by search and warning against a client prefix such as mcp__aisa__, which is not encoded in 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 ('Retrieve schemas for 1 to 20 exact tool names') and pins the source of those names to search. This clearly separates it from siblings like search (finds tools), batch_quote, and batch_use.

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

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

Explicitly sequences the workflow: build arguments from successful schemas, then call batch_quote, and 'Do not call batch_use yet.' This is an explicit when-to-use and when-not-to-use instruction naming the alternative siblings.

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?

Goes well past the readOnly/idempotent annotations by explaining that quotes are price observations rather than authorization grants, and precisely delimiting what auto_execute_eligible does and does not waive (user prohibition, narrower scope, tighter budget). It also guarantees no execution fallback, which is the key behavioral risk for this tool.

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?

Purpose is front-loaded and most sentences carry distinct rules (no fallback, eligibility limits, naming, session reuse). It is on the long side and the argument-shape constraint is stated twice in spirit, but little is truly wasted.

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

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

An output schema exists, so return-value documentation isn't required, yet the description still flags the two response fields that matter for a downstream decision. Combined with session and naming guidance, an agent has everything needed to call it correctly.

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

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

At 67% schema coverage the schema already documents each parameter, so the description earns credit only for added meaning: exact-name rules for 'tool', session_id reuse semantics, and the 1-to-20 argument-shape parallel with batch_use. It doesn't clarify search_id beyond what the schema states.

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 ('Obtain AIsaServices cost quotes for 1 to 20 published tools') plus the crucial scope qualifier 'without executing them.' It is immediately distinguishable from the sibling batch_use, which executes rather than quotes.

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

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

Explicitly names the parallel sibling ('Same input as batch_use') and draws the boundary ('Never falls back to execution'). It also gives operational conditions: use names exactly as search returns them, strip any mcp__aisa__ prefix, and reuse session_id from Search for the task.

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

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

Annotations already cover mutability, destructiveness, and open-world behavior. The description adds critical business logic: billable calls, quote dependency, the meaning of auto_execute_eligible (waives only cost confirmation, not user prohibitions), and no silent retry. It doesn't detail rate limits or return format, but with an output schema present, that's acceptable.

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 dense and front-loads the cost warning, but it packs many separate instructions into one block, making it less scannable. Some sentences like 'A missing or failed quote is not free' add value, but the overall flow could be better 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?

Given the destructive, open-world annotations and the presence of an output schema, the description covers the essential preconditions and behavioral constraints. It could mention error handling or partial failure behavior, but the core guidance is sufficient for correct invocation.

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 67%, and the description adds important semantics: tool names must be exact without client prefix, session_id reuse guidance, and 1-20 call limit. It doesn't explain search_id, but the schema description for search_id is already clear enough.

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 verb and resource: 'Execute 1 to 20 independent published-tool calls', and the title matches. It distinguishes itself from batch_quote by requiring a quote first, but doesn't explicitly contrast with the singular 'use' sibling, though that's implied by 'batch'.

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 when-to-use and when-not-to-use conditions: only after a successful batch_quote with auto_execute_eligible=true or explicit user authorization. It also states re-quote conditions and prohibits silent retries, leaving little ambiguity.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world behavior. The description adds nothing about pagination limits, result ordering, or rate/price behavior beyond a static price snippet – the one relevant line (per-request cost) is vague and unrelated to tool mechanics.

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?

It is short, but it is also front-loaded with irrelevant pricing markup rather than purpose. Conciseness without substance is under-specification, not quality.

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 15-parameter read tool with siblings like get_polymarket_markets, an output schema present, and rich filtering semantics, the description supplies zero functional context. An agent has nothing to decide selection or interpretation beyond the schema.

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 each parameter (limit, cursor, status, tickers, timestamps) is well-documented in the schema. The description adds no parameter meaning, 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 contains only pricing boilerplate ('默认价格配置' / published reference price) and says nothing about what the tool does. An agent cannot tell from this text that it retrieves Kalshi markets or how it differs from get_polymarket_markets or get_kalshi_trades.

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, no exclusions, and no reference to sibling tools. The pricing note provides no invocation guidance whatsoever.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description's only real behavioral content is a per-request price ($0.02 USD), which is marginally useful cost information, but it says nothing about pagination limits, result ordering, or data freshness beyond what the schema states.

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?

It is short, but every sentence is injected boilerplate rather than tool documentation, and it is front-loaded with an unrelated '默认价格配置' heading. Nothing in the text earns its place for the purpose of invoking this 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?

The tool has an output schema and full annotations, which lightens the burden, but the description still omits the bare essentials: that it retrieves trade history, what a trade record contains, and how filters combine. For a six-parameter market-data query, this is completely 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%, so all six parameters (limit, cursor, max_ts, min_ts, ticker, is_block_trade) are already documented with defaults and constraints. The description adds no parameter meaning whatsoever; per the rubric, full schema coverage establishes a baseline of 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 never states what the tool does. It consists of the phrase '默认价格配置' (default price configuration) and a pricing boilerplate block, with no verb, no resource, and no mention of Kalshi trades or markets. The only hint of purpose comes from the tool name itself, which the description does not reinforce.

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 exclusions, and no reference to any alternative such as get_kalshi_markets or get_polymarket_activity. The text provides zero context for selecting this tool over its ten siblings.

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

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

Annotations already declare readOnly/idempotent/openWorld/non-destructive, so the safety profile is covered. The description adds only pagination/filtering presence and a pricing note — no behavior like default time windows, offset caps, or stable ordering, all of which matter for an activity query and are pushed entirely into the schema.

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

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

Only one substantive sentence, with the rest being an HTML-comment pricing banner that is irrelevant to invocation. It is short but under-specified rather than concise, and the pricing block bloats the payload.

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 12-parameter tool with tricky defaults (default ~3-year window, offset 5000 cap, excludeDepositsWithdrawals overriding type), the description is far too thin. An output schema exists, so return values need not be explained, but operational pitfalls are unaddressed in prose.

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 83%, so the schema documents nearly all parameters richly (windows, caps, mutual exclusions, default quirks). The description adds no parameter guidance beyond generic 'pagination and filtering', 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 says it 'returns user activity' with 'pagination and filtering' — an accurate but generic purpose statement. It doesn't name the platform (Polymarket, inferable from the tool name) or distinguish it from sibling tools like get_kalshi_trades, though those target different venues.

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

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

No explicit when-to-use or when-not-to-use guidance. The description only states pagination/filtering exist; the schema carries all nuance (e.g., excludeDepositsWithdrawals caveat, ASC/start interaction). No alternatives named.

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

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), so the bar is lower. The description does add one behavioral fact beyond the annotations, that pagination is offset-based, which matters for how the agent pages through results, but it says nothing about result volume, defaults, or how the many filters combine.

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 one functional sentence is front-loaded and waste-free, but it is drastically under-sized for a 26-parameter listing tool, so brevity here is under-specification rather than conciseness. The injected pricing block is boilerplate that contributes nothing to tool selection or invocation.

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 presence of an output schema means return values need not be described, which removes one expected burden. Even so, a 26-parameter, zero-required filtering tool with no sibling differentiation and no parameter or pagination-detail guidance is not complete enough for confident selection and invocation.

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 26 parameters with only 4% description coverage, so the description carries nearly the full burden of explaining them. Instead it offers only the generic phrase 'filter parameters' and names none of them; the agent gets no meaning for id, slug, cyom, recurrence, related_tags, the volume/liquidity/date bounds, or the closed:'any' union type.

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 ('List events') and adds the pagination style ('offset based') and that filters exist. However, it does nothing to separate this tool from the sibling get_polymarket_markets or get_polymarket_activity, so an agent must guess whether 'events' vs 'markets' is the right resource.

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 statement of prerequisites, and no naming of alternatives among the eleven siblings. The mention of 'filter parameters' implies the tool supports narrowing, but nothing tells the agent when this tool is preferred over get_polymarket_markets.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds that pagination is offset-based, which is mildly useful, but says nothing about rate limits, default/max page size, or the fact that results reach live external data. The injected pricing block is commerce boilerplate, not behavioral disclosure.

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

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

The substantive sentence is short and front-loaded with the verb and resource. The trailing pricing block is injected boilerplate rather than author text, so it is noise in the payload but not a structure failure of the description itself.

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

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

An output schema exists, so return values need not be explained. However, for a tool with 26 optional parameters and almost no schema documentation, the description is far too thin: no filter semantics, no pagination defaults, no guidance on combining filters, and no routing to sibling market/event 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?

With 26 parameters at 4% schema coverage, the schema is nearly silent (only 'order' is documented), so the description must carry the burden and does not. It generically says 'filters' without naming or explaining any of the filters (closed, tag_id, volume_num_min, uma_resolution_status, etc.), leaving most parameters semantically opaque.

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

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

States a specific verb (List) and resource (markets) with the platform implied by the tool name, and mentions pagination plus filters. It is clear on its own, but it never distinguishes itself from the sibling get_kalshi_markets or clarifies what a 'market' is versus an 'event' from get_polymarket_events, 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 explicit when-to-use guidance, no prerequisites, and no mention of alternatives such as get_kalshi_markets or get_polymarket_events. The only usage hint is 'offset based pagination and filters', which describes capability rather than context for selecting 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?

Annotations already establish that this is a safe, read-only, closed-world operation. The description adds useful context beyond annotations by saying it returns categories, servers, tool counts, and the dedicated endpoint, and that it is free. It omits auth/rate-limit details, but those are less critical given the read-only annotations.

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

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

The description is front-loaded with what the tool returns and is generally efficient. The parenthetical about tool-router and the endpoint URL add some density, but each part contributes usage or content 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?

With zero parameters, read-only annotations, and an output schema available, the description supplies enough context for correct invocation. It explains the catalogue contents and gives the category-specific endpoint alternative, leaving no critical gap for an agent.

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 parameter semantics are not a meaningful differentiator. The schema has no properties to explain, and the description does not need to document any inputs.

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

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

The description clearly states that this tool gives a catalogue overview: categories, servers per category, tool counts, and a dedicated endpoint. The resource is specific and recognizable, though sibling differentiation is only partial because it references 'tool-router' rather than the listed siblings like search/use.

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

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

It gives a clear alternative: use the category-specific endpoint if you only need one category, rather than going via search. It also notes the tool is free and AIsa-only, but it does not explicitly state when to call list_categories instead of search or use.

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 workflow behavior the annotations cannot: the has_full_schema flag gates a required batch_get_schema call, and the next step after search is batch_quote, not batch_use. It stops short of disclosing retrieval limits or catalog breadth that would push it to a 5.

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

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

It is a dense run of imperatives rather than flowing prose, but each sentence carries a distinct rule (scope, language, workflow branch, negative cases, result interpretation) and the most important scoping guidance is front-loaded. Slightly more compression would help.

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

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

With an output schema present, the description need not explain return values, and it correctly avoids doing so while still referencing the output fields that drive the workflow (has_full_schema, next_steps_guidance). A mutation-free, well-annotated search tool is adequately covered, though catalog scope ('AIsa-only', no external providers) could be stated more explicitly.

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 structured baseline is 3. The description adds genuine meaning beyond the schema by telling the agent to write the query in English and to place tickers, URLs, providers, or identifiers in known_fields, which is non-obvious routing guidance for a nested free-form object.

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 opens with a specific verb+resource: 'Discover AIsa tools and Plans for external data or actions.' It also separates this discovery step from the sibling execution tools by naming batch_get_schema, batch_quote, and batch_use and stating when each follows, so an agent can place it in the workflow 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?

It gives explicit when-to-use ('tasks needing external data or actions'), when-not ('tasks that only need supplied content or general knowledge'; no standalone rewriting, translation, summarization, formatting, or calculations), and named alternatives (batch_get_schema when has_full_schema=false, batch_quote rather than batch_use). It also specifies query language and atomic-query style, leaving little 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=false, destructiveHint=true, and openWorldHint=true, so the agent knows this is a state-changing, open-world operation. The description adds only the deprecation status and says nothing about what gets mutated, spend behavior (despite a max_price_usd param), or authorization 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?

A single clause with zero waste; the deprecation notice and the replacement are front-loaded. It is terse by design for a deprecated endpoint, though it is under-specified rather than optimally 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?

Has an output schema and annotations, which reduces the burden, but a 4-parameter operation tool with a deprecation notice gives no information about what it executes or whether it remains functional. For an agent deciding between this and batch_use, the description is thin.

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 four parameters (operation_id, arguments, search_id, max_price_usd) are already documented in the schema. The description adds no parameter meaning on top, 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 never states what the tool does — no verb or resource. It only labels the tool as deprecated and points to a replacement, leaving the actual capability ('Run an AIsa operation' from the title) unexplained. An agent must infer the purpose from the title and schema alone.

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

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

It explicitly routes the agent to the alternative ('use batch_use instead'), which is exactly the guidance needed for a deprecated tool. It doesn't explain when, if ever, this tool should still be called (e.g., during a migration window), 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.