Rolli MCP

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

With no annotations provided, the description carries the full behavioral burden. It does usefully disclose the post-condition ('Marks the run as failed'), but omits whether cancellation is immediate or cooperative, whether it is reversible or the run can be rerun, and what happens to partial output. Those gaps matter for a mutation tool with zero annotation coverage.

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 action and scope, then the side effect. Nothing is wasted and nothing needs reordering.

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 mutation tool with no annotations and no output schema, the definition covers the action, the eligible states, and the resulting status. It still leaves an agent guessing about irreversibility and about how to obtain a valid run id, which is the main remaining gap.

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

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

There is a single required parameter whose schema description ('Run UUID') and regex pattern already document it fully at 100% coverage. The description adds no format or sourcing guidance (e.g. obtainable from list_agent_runs), so it matches the 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?

States a specific verb and resource ('Cancel a ... Rolli Agent run') and scopes it to 'pending or running' runs, which separates it from delete_agent_run on state grounds. It does not name the sibling it differs from, so an agent must infer the distinction from sibling names alone.

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

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

The phrase 'pending or running' implies a state precondition, giving some implicit guidance on when the tool applies. However, it never says when to prefer this over delete_agent_run or update_agent_run, nor what to do for a completed run.

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 behavioral burden, and it discloses almost nothing beyond the surface purpose. For a mutation that creates an ongoing job with per-run credit consumption (available_credits), the description never says whether the schedule starts running immediately, what happens on duplicate names, whether notification failures block a run, or what the tool returns. Only the 'optional email and Slack notifications' clause adds real behavioral color.

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

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

A single front-loaded sentence with no filler; the cadence list and notification clause both earn their place. It could be marginally tighter, but nothing is redundant.

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

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

For a 20-parameter creation tool with six required fields, no annotations, and no output schema, the definition is minimum viable: it conveys what gets created and on what cadence but leaves the agent to infer startup behavior, return value, and the interaction between starts_at, ends_at, and the recurrence_* fields. The internal schema is well documented, which offsets part of the 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 every parameter including enums, defaults, and formats; the description adds no syntax or format detail beyond restating the cadence options. It does flag that notifications are optional, which helps an agent decide which of the three Slack/email parameters are safe to omit, but that is marginal against a 20-parameter 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 gives a specific verb+resource ('Create a recurring Rolli Agent report') and enumerates the supported cadences (daily, weekly, monthly, one-time) plus the notification channels, which maps directly onto recurrence_type's enum. The word 'Create' implicitly distinguishes it from the large family of update_/delete_/pause_/resume_/list_ schedule siblings, though it never names one explicitly.

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

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

Usage is only implied: 'recurring ... report' suggests this is the setup step rather than an execution step, which contrasts loosely with start_agent_run and the *_agent_schedule mutation siblings. There is no explicit guidance on when to choose a schedule versus a one-off run, nor any prerequisite note (e.g. that a schedule may need to be resumed/activated, or that credits are consumed per run).

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 and does well: it discloses that deletion is soft (record retained for audit, hidden from listings) and that the operation is gated on terminal run state. It stops short of stating permission/auth requirements, whether the deletion can be undone, or what a success response looks like — a meaningful but not fatal gap for a mutation 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?

Three short sentences with zero filler; the operation is front-loaded, followed by the persistence consequence, then the precondition. Every sentence contributes distinct information.

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

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

For a single-parameter mutation with no output schema, the description covers the essentials: effect on data, visibility consequence, and the state guard. Only permission requirements and the success/error surface are left unstated, which is minor at this complexity.

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

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

Schema coverage is 100% and the single 'id' parameter is already documented as 'Run UUID' with a strict UUID pattern, so the description adds no format or scope meaning beyond it. The baseline of 3 applies when the schema does the parameter work.

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

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

The description states a specific verb and resource ('Soft-delete a Rolli Agent run') and immediately qualifies it with the soft-delete semantics, so an agent knows exactly what operation is performed. Naming the running-state restriction also implicitly separates it from cancel_agent_run and update_agent_run.

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 preconditions: 'Only works on completed or failed runs' tells the agent when the call will fail, and 'cancel the run first if it is still running' names the alternative action for the excluded case. Both when-to-use and when-not-to-use are covered without 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 exist, so the description carries the full burden; it discloses the two most important traits — permanence ('Permanently', 'This is irreversible') and collateral destruction of execution history. It does not mention permission requirements or what happens when the id does not exist, keeping it short of a 5.

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

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

Three short sentences, front-loaded with the destructive nature and irreversible consequence, followed by the alternative. No filler, though the 'Rolli Agent' qualifier is slightly redundant for an agent already in this toolset.

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 destructive tool with no output schema, the description covers consequence, irreversibility, and the safe alternative. The only gap is behavior on an invalid or already-deleted id, which is a minor edge case given the simple 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?

Only one parameter and schema description coverage is 100%, so the schema already documents 'id' as a Schedule UUID. The description adds no format, source, or lookup guidance (e.g. where to obtain the schedule id) beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('Permanently delete a Rolli Agent schedule') plus the extended scope ('and its execution history'), which an agent cannot infer from the name alone. It is clearly distinguishable from sibling update_agent_schedule and pause_agent_schedule.

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 alternative (pause_agent_schedule) and the condition that selects it: temporarily stopping a schedule without losing history. This gives a direct when-to-use-this-vs-that routing rule.

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, and it does disclose real behavior: the call polls until completion, can return a results_pending status, and yields a specific result shape. It omits whether this persists a search record (siblings get_expert_search/list_expert_searches imply it does), timeout behavior, and whether repeated identical queries create duplicates.

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, then the return shape, then the edge-case routing, in three sentences with no filler. The field enumeration earns its space because no output schema exists.

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 must describe returns and it does so thoroughly, plus it covers the pending-status escape hatch. Minor gaps remain around empty-result behavior and how long polling may take before giving up.

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?

Only one parameter exists and schema coverage is 100% with a strong inline example, so the schema already does the work. The description adds only the framing that the query is natural-language, which is already implied by the parameter description.

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 — find experts matching a natural-language query — and names the engine behind it. It is clearly separable from get_expert_search (retrieves already-computed results) and list_expert_searches (enumerates past searches).

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

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

Gives a clear condition for the follow-up path: if status is results_pending, call get_expert_search instead of re-running. It does not explicitly say when to prefer this over lookalike siblings such as user_search or keyword_search, so the guidance stops short of full alternative routing.

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, and it discloses the key non-obvious trait: the response shape changes with run state, returning progress (percentage, phase, current tool) while running and a full report, signals, evidence links, and usage metrics when complete. It omits error behavior for invalid or deleted run IDs and any rate-limit or polling guidance.

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

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

Two short sentences, front-loaded with the core action and followed by the state-dependent return contract. Every clause carries information; nothing is repetitive filler.

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

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

With no output schema and no annotations, the description appropriately compensates by describing both possible return shapes and enumerating the completed-run payload. Minor gaps remain around failure modes and whether polling is expected, which matter for an agent driving a long-running job.

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

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

Schema coverage is 100% and the single parameter is documented as 'Run UUID' with format and pattern constraints, so the schema does the heavy lifting. The description's 'by ID' adds no syntax or format detail beyond that, matching the baseline for high-coverage schemas.

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

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

States a specific verb and resource ('Get a Rolli Agent run by ID'), which is unambiguous on its own. It does not reference siblings such as list_agent_runs or cancel_agent_run, so an agent must infer that this is the single-run retrieval counterpart to the list 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?

The two-state phrasing ('While running... Once complete...') implies the polling pattern for an in-flight run, which is useful implied guidance. There is no explicit statement of when to prefer this over list_agent_runs, nor any exclusion or precondition such as what to do if the ID is unknown.

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. It does disclose a real behavioral trait beyond the schema — the result is capped at the 10 most recent execution records — which tells an agent the payload is bounded and not a complete history. It says nothing about read-only safety, auth requirements, error behavior, or whether the 10-record cap is fixed.

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

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

One sentence with no wasted words, and the most decision-relevant information (what the response contains) is front-loaded rather than buried.

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

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

For a single-parameter read-only getter with no output schema, the description does the important remaining job by summarizing return contents, including the bounded recent-runs portion. The only real gaps are how the schedule id is discovered and any failure modes, which are minor for a tool this simple.

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?

There is a single required parameter whose schema coverage is 100% and which is explicitly described as the 'Schedule UUID' with a UUID format and pattern. The description adds no extra meaning about the identifier or its source, so the schema does all the work — the baseline 3 applies.

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

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

Names a specific verb and resource ('Get a Rolli Agent schedule') and, unusually, specifies the exact return payload: full configuration plus the 10 most recent execution records. That payload detail distinguishes it from list_agent_schedules and list_agent_schedule_runs, though it never names those siblings explicitly.

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

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

Usage is only implied: an agent can infer this is the detail-fetch for a single schedule whose UUID it already has, but the description never states when to prefer it over list_agent_schedule_runs or where to obtain the id. No exclusions or prerequisites are given.

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

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

With no annotations, the description carries the full burden and does substantial work: it discloses the two-phase return behavior (status first, experts plus AI match summaries once complete) and explains an ambiguous field, results_pending, with an explicit retry recommendation. It stops short of stating read-only semantics, error behavior for invalid IDs, or other status values.

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

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

Three short sentences with zero redundancy; the core action is front-loaded and the return shape and retry caveat follow in the order an agent needs them.

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 tool with no output schema and no annotations, the description covers what is returned and the tricky pending state well. It omits failure handling for a nonexistent search ID and the full set of possible status values, which keeps it just short of 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?

There is a single parameter and schema coverage is 100%, with the schema itself documenting 'Expert search ID'. The description only restates 'by ID' and adds no format, origin, or sourcing guidance (e.g., where the ID comes from), 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 gives a specific verb and resource ('Get results for an expert search by ID') and the 'by ID' framing implicitly separates it from the sibling that initiates a search (expert_search) and the one that enumerates them (list_expert_searches). It does not name those siblings outright, so an agent must infer the pairing.

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

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

Usage is implied rather than stated: the polling/retry note ('results_pending: true means... retry in a few seconds') tells the agent how to call it repeatedly, but nothing says when to use this versus expert_search or list_expert_searches, nor what to do if the ID is unknown. Adequate but leaves the workflow 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?

With no annotations provided, the description carries the full burden. It indicates a read operation via 'get' but does not explicitly state read-only nature, auth requirements, or rate limits. The description is adequate but minimal.

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

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

The description is a single clear sentence with no wasted words, front-loading the action and result.

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 parameterless retrieval tool, the description covers the key information. However, the lack of output schema means the agent must infer the return format; mentioning the returned fields helps slightly.

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?

There are no parameters, so the description does not need to add parameter semantics. Baseline for zero parameters is 4.

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 tool gets current integration settings and specifies the two fields returned (webhook return URL and integration name), making the purpose specific and distinct from sibling tools like update_integration_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?

The description implies when to use (when current settings are needed) but provides no explicit guidance on when not to use or mention of alternatives like update_integration_setup.

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 does well: it discloses the return surface (status, analytics summary, posts), the truncation signal (truncated: true), and the asynchronous backend state (results_pending: true with a retry hint). It stops short of stating read-only semantics, error behavior, or any rate limits, which is the remaining 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?

Three dense sentences with zero filler, front-loaded with purpose before branching into the truncation workaround and the pending-state retry rule. Every clause carries operational information the agent needs.

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 tool with no output schema and no annotations, the description covers the return shape, the truncation edge case, and the async pending case, which is most of what an agent needs. Minor omissions (no mention of error/not-found behavior or what the analytics summary contains) keep it from a 5.

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?

There is a single parameter at 100% schema description coverage ('Keyword search ID'), so the schema already does the work. The description only says 'by ID' and adds no format or sourcing detail beyond the schema, making the baseline 3 correct.

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

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

States a specific verb+resource ('Get results for a keyword search by ID') and immediately distinguishes itself from the sibling that lists searches and from get_keyword_search_posts by describing what it returns (status, analytics summary, posts). An agent can pick it out of the crowded sibling list without opening the schema.

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

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

Explicitly routes the agent to get_keyword_search_posts (with offset, limit, fields=lean, one platform at a time) when the response is truncated, and explains that results_pending: true should be retried in a few seconds. No guidance on how to obtain the id or when to prefer list_keyword_searches first, so it falls short of full when/when-not coverage.

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 whole burden and does much of it well: it discloses the response envelope (a first line with count and next offset, plus total/returned/offset/platform_counts in JSON) and the truncation behavior when the size cap is exceeded. It does not cover ordering guarantees, auth requirements, or whether results are a cached snapshot, which keeps it short of a 5.

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

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

Four sentences, front-loaded with purpose then response shape then paging strategy, with essentially no filler. The middle sentence bundling total/returned/offset/platform_counts is dense but each item earns its place by telling the agent what fields to read.

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?

There is no output schema, and the description compensates by describing the return envelope and the truncation flag, which is exactly the missing structured information. For a 5-parameter read tool with full schema coverage, nothing an agent needs in order to page correctly is absent.

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, but the description adds real operational meaning: use the offset reported in the previous response's first line rather than computing it, filter per platform rather than fetching all, and note that lean roughly doubles posts per response because it omits media_url, profile_url and sentiment_reason.

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 and resource, 'Get raw posts from a keyword search', which pins down both the action and the scope. 'Raw posts' distinguishes it from the sibling get_keyword_search, which returns the search record itself, and from get_user_search_posts, so an agent can pick without opening a schema.

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

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

It explains how to consume a large result set: page with offset and limit, narrow to one platform at a time, and use fields=lean when text matters more than media and profile URLs. It never states explicit exclusions or names a sibling alternative, so it gives clear operating context rather than full when/when-not routing.

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 behavioral burden. It implies a read-only 'Get' operation, but does not disclose permissions, whether the tree is computed or cached, how deep the hierarchy goes, or how the platform filter affects the result—all important context for a tool with zero annotation coverage.

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 that are front-loaded with the core purpose and contain no filler. The second sentence adds a small but useful clarification of what the tree shows, though it could be slightly tighter.

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

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

With no output schema and no annotations, the description gives only a high-level sense of the return value (topics/subtopics distribution). It omits practical details an agent would want—such as return shape, tree depth, or how results relate to search_id—making it adequate but not fully complete for a tool of this nature.

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 search_id as the keyword search ID and platform as an enum filter. The description only loosely references the keyword search and says nothing about the platform parameter, so it adds no meaningful semantic detail beyond what the schema provides; a 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 pairs a specific verb ('Get') with a specific resource ('conversation topic tree for a keyword search') and explains what the tree represents (topics and subtopics distributed across results). This distinguishes it from siblings like get_keyword_search or get_keyword_search_posts, which retrieve raw search or posts, though it does not explicitly name those alternatives.

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

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

Usage is only implied: an agent can infer this follows a keyword search, but the description never states when to choose this over get_keyword_search, get_keyword_search_posts, or other search-related tools, nor does it mention prerequisites such as needing an existing search_id.

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 behavioral burden and does meaningful work: it discloses the return contents and a non-obvious edge case, that credits_limit and period_reset_date are null for one-time credit grants. It does not cover permission requirements, response size, or whether per-user breakdowns are paginated, which keeps it from a 5.

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

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

Two sentences, front-loaded with the verb and resource, followed by the return inventory. The parenthetical listing credit field paths is dense but earns its place by conveying a null-semantics rule. Slightly over-packed, but there is no filler.

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

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

For a single optional-parameter, read-only reporting tool with no output schema, the description carries the necessary return-value explanation well, including the credit fields and their null behavior. The structure of per-user breakdowns and search counts is left unstated, a minor gap given there is no output schema to consult.

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

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

Schema description coverage is 100%, with the month parameter fully documented including the YYYY-MM pattern and the omit-for-12-months default. The description merely restates that filtering by month is optional and adds no format or default detail beyond the schema, so the baseline of 3 applies.

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

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

The description names a specific verb and resource ("Get API usage data") and then enumerates the payload: search counts, per-user breakdowns, and the IQ credit balance. That is enough for an agent to distinguish it from the surrounding search/agent-run siblings, none of which report usage or credits. It stops short of explicitly contrasting with a sibling, so it lands at 4 rather than 5.

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

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

Usage is only implied: an agent should call this when it needs usage or credit information. "Optionally filter by month" hints at the one scoping decision available, but there is no explicit when-to-use or when-not-to-use guidance and no mention of alternatives. For a read-only reporting tool with no competing sibling, this is adequate but thin.

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 does well: it discloses the return payload (profile info, metrics, content analysis), the truncation behavior with its 'truncated: true' marker, and the asynchronous 'results_pending: true' state with retry guidance. It omits any permission or rate-limit context, which keeps it from a 5.

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

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

Three tight sentences, front-loaded with purpose, followed by return contents and then the two edge-case behaviors (truncation, pending results). Every sentence carries operational information with no filler.

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

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

There is no output schema, so the description must explain return values and it does, including the sentinel fields an agent would otherwise misread. Retry and pagination escape hatches are both supplied, which is everything needed to call this correctly.

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

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

Schema description coverage is 100% and there is only one parameter (id), which the schema already documents as 'User search ID'. The description's offset/limit/fields mentions describe the sibling tool's parameters, not this tool's, so no extra meaning is added for this schema. 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 uses a specific verb and resource ('Get results for a user search by ID') and explicitly names the sibling get_user_search_posts as the route for the complete post list, so the agent can separate the two. It stops short of distinguishing this tool from user_search or list_user_searches, which sit in the same family.

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 concrete when-to-use guidance for the alternative path: if the response is truncated, page through posts with get_user_search_posts (offset, limit, fields=lean). It also tells the agent what to do on results_pending (retry in a few seconds). It does not cover when to call user_search versus this retrieval 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, the description carries the full disclosure burden and does well: it explains the response's first line, the JSON fields (total, returned, offset), the truncation flag for oversized responses, and the payload tradeoff of lean mode. It omits failure modes (invalid search_id, expired searches) and any permission or rate-limit context, which keeps it short of a 5.

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

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

Three tight sentences, front-loaded with the purpose before the response-shape and pagination details. Every sentence carries information, though the response-format sentence is dense and slightly awkward to parse on a first read.

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?

There is no output schema, so the description must explain return values, and it does: the first line's counts, the total/returned/offset fields, and the truncated marker. It never says where a valid search_id comes from (presumably user_search / get_user_search) or what happens on an invalid ID, leaving a small gap for a read tool with no annotations.

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 all four parameters are already documented, including the lean enum's omitted fields and the offset-as-next-page hint. The description mostly restates that contract plus a usage rationale for lean, adding modest meaning beyond the schema rather than new syntax or constraints.

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?

"Get raw posts from a user search" gives a concrete verb (get), resource (posts), and scope (from a user search), which separates it from the metadata-oriented get_user_search and from get_keyword_search_posts. It never explicitly names those siblings, so the differentiation rests on the name and implication rather than on stated contrast.

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 says when to paginate a large search with offset and limit, and when to pick fields=lean ("when the text matters more than media and profile URLs"). It supplies a concrete next-page procedure (reuse the offset from the previous response's first line) but gives no guidance on when to call this versus get_user_search or get_keyword_search_posts.

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

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

With no annotations, the description carries the full burden and does well: it discloses blocking poll-until-complete behavior, truncation semantics (truncated: true, largest post arrays shortened), and the results_pending state meaning. It stops short of permissions/auth requirements, rate limits, or cost/latency expectations for a multi-platform poll, which keeps it from a 5.

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

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

Front-loaded with purpose, then truncation handling, then the status fallback — a sensible information order with no filler sentences. The parenthetical listing of eight platforms and mixed inline hints make the second half slightly dense, but every clause is actionable.

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 5-parameter search tool with no output schema and no annotations, the description covers the important unknowns: it is synchronous/polling, results may be truncated, and a pending status has a specific follow-up path. Missing only operational context such as expected latency for multi-platform polling and whether repeated identical queries are cached or duplicated.

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%, including a rich query-syntax description in the schema itself, so the baseline is 3. The tool description adds no parameter-level detail beyond naming the pagination parameters of the sibling tool, so it neither compensates for nor supplements 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?

Opens with a specific verb+resource ("Create a keyword/hashtag search") and enumerates the covered platforms. It explicitly distinguishes itself from the two sibling tools it interacts with, get_keyword_search_posts and get_keyword_search, so an agent can route 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?

Gives concrete conditional routing: when the response is truncated, read pages via get_keyword_search_posts with offset/limit/fields=lean and one platform at a time; when status is results_pending, fetch with get_keyword_search. The query parameter also advises running several focused boolean searches for broad topics rather than one wide query.

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 two useful behaviors: results are paginated and only a summary representation is returned, and discarded runs are filtered out. It says nothing about ordering, total-count metadata, permissions, or rate limits, which leaves meaningful gaps for an unannotated read tool, but the exclusion rule is genuine behavioral detail.

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

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

Three short sentences, front-loaded with the action and resource, then the return shape, then the exclusion rule. Nothing is redundant and nothing is buried.

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

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

For a four-parameter, all-optional listing tool with no output schema, the description is nearly sufficient: it establishes scope, return shape, and one filtering rule. The remaining gap is that it does not describe what fields the summary entries contain or whether pagination metadata is returned, which matters slightly more without an output 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%, including defaults, bounds, and an enum for status, so the schema already does the parameter work and baseline is 3. The description adds no filtering syntax or guidance beyond the note that discarded runs are excluded, which is tangentially relevant to the status filter but not explanatory.

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

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

States a specific verb and resource ("List Rolli Agent runs") and glosses what an agent run is ("AI-driven social intelligence investigations"), which is real disambiguation value. It also marks the result shape ("paginated summary list"). It stops short of naming the sibling it contrasts with, notably get_agent_run for a single run or list_agent_schedule_runs for the scheduled variant, so 4 rather than 5.

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

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

Usage is implied by the purpose and by the word "summary" (this is the browse/overview entry point, get_agent_run would be the detail path), but that inference is never made explicit. No when-not conditions or prerequisites are stated, and the sibling tools list includes several similarly named listing tools the agent must distinguish on its own.

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: "List" implies a non-mutating read, and "full execution history... preview of each linked agent run" usefully signals a truncated summary per run rather than full run payloads. It says nothing about result ordering, whether pagination is needed to obtain the "full" history, or rate/permission requirements.

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

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

A single front-loaded sentence with no filler; the resource comes first and the return-content note follows. Every clause 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 read-only list tool with three fully documented parameters and no output schema, the description is adequate but leaves ordering and the interaction between "full execution history" and the paginated limit/offset interface unexplained. It also does not clarify whether the embedded run previews require a separate get_agent_run call for detail.

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% (id, limit, offset all documented with defaults and bounds), so the schema already does the parameter work. The description adds no format, filtering, or sorting semantics beyond it. Baseline 3 applies.

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

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

States a specific verb ("List") and a specific resource ("execution history of a Rolli Agent schedule"), which cleanly separates it from list_agent_schedules/get_agent_schedule even though no sibling is named. It also notes the payload includes a preview of each linked agent run, so an agent knows what comes back. Sibling differentiation is implied by the resource scope rather than stated.

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

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

Usage is only implied: this is the tool to reach for when you need the run history of one schedule, and the required `id` parameter reinforces that. There is no explicit when-to-use/when-not guidance and no pointer to get_agent_run for full run details or to list_agent_schedules for the schedules themselves.

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 present, the description carries the full burden, but it does usefully disclose the cadence model (daily/weekly/monthly/once) and that each schedule execution spawns a new agent run. It omits behavior an agent would want: whether paused or deleted schedules are included, ordering, and whether the response is a bare array or wrapped.

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 action and resource, with the second sentence supplying genuinely useful domain context rather than filler. Nothing is redundant with the 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?

For a simple read-only listing with two optional pagination parameters and no output schema, the description covers purpose and domain semantics adequately. It falls short on what a returned schedule contains and whether filtering by status is possible, which an agent must discover empirically.

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

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

Schema description coverage is 100%, with limit and offset documented inline including defaults and maxima, so the description need not restate them. It adds no extra meaning about pagination strategy or how many schedules typically exist, which is the correct baseline for a fully documented two-parameter 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 gives a specific verb and resource ("List Rolli Agent scheduled reports") and clarifies what a schedule is (a recurring job producing agent runs). It does not distinguish this from siblings like get_agent_schedule or list_agent_schedule_runs, so the agent must infer the boundary from names alone.

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

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

There is no explicit when-to-use guidance, no mention of when not to use it, and no routing to alternatives such as get_agent_schedule (single schedule) or list_agent_schedule_runs (executions). The only cue is the word "List", which implies enumeration but leaves selection up 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 supplied, so the description carries the full behavioral burden, yet it only states that results are paginated and status-filterable - both of which the schema already declares. It says nothing about ordering, what fields an expert search carries, or whether results are scoped to the caller's account.

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 action, with no filler. The second sentence partially restates what the schema already conveys (pagination and status filtering), which is the only wasted effort.

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

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

For a simple two-optional-parameter read tool with no output schema, the description covers the essentials but leaves the concept of an "expert search" undefined and says nothing about result ordering or default behavior when no filter is given. It is adequate to call the tool, 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%: the schema documents the page parameter (100 results per page) and the show enum with a default of "all". The description adds no syntax or semantics beyond that, so the baseline of 3 applies.

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

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

"List all expert searches" names a specific verb and resource, and the second sentence clarifies the scope (paginated, status-filterable). It stops short of distinguishing this from the many sibling list tools (list_keyword_searches, list_user_searches, list_agent_runs), so an agent must infer the difference from the noun 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?

The description gives no when-to-use guidance, no exclusion of alternatives, and no prerequisites. With five sibling list/search tools present, it never says whether to call this versus get_expert_search for a single item or list_keyword_searches for a different resource type.

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. It does disclose two useful behavioral facts — results are paginated and can be filtered by status — but says nothing about permissions, result ordering, or what a page contains, which matters for a list tool with no output 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?

Two short sentences, zero filler, with the core purpose front-loaded before the return-behavior note. Nothing in it is wasted, even though the second sentence lightly overlaps the 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?

For a zero-required-parameter list tool with a fully documented schema, the description is minimally sufficient. However, with no output schema it does not describe what a result entry looks like, and it gives no way to distinguish this tool from the other list_* siblings.

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

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

Schema description coverage is 100%, including an enum for the status filter, so the baseline is 3. The description restates pagination and status filtering but adds no semantics beyond the schema (e.g. page-size implications or status lifecycle meaning).

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 ('List all keyword searches'), so an agent knows it enumerates keyword-search entities rather than executing one. It does not distinguish itself from the sibling list tools (list_expert_searches, list_user_searches), leaving the agent to infer the resource distinction from the name 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?

There is no explicit when-to-use guidance, no exclusions, and no reference to alternatives such as get_keyword_search or the sibling list tools. The agent must infer that this is the enumeration counterpart to keyword_search/get_keyword_search from naming conventions only.

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. It discloses only that results are paginated and filtered by status, which mostly restates the schema; it says nothing about permissions, default ordering, what fields each search record contains, or behavior when the status filter matches nothing.

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, front-loaded sentences with no filler. The second sentence adds pagination and filtering information, though it is somewhat redundant against the schema and could have spent that space on sibling differentiation instead.

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 zero-required-parameter list tool with no output schema, the description covers the basics of pagination and filtering. The notable gap is disambiguation from the four-plus sibling list/lookup tools in this namespace, which an agent needs in order to select correctly.

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

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

Schema description coverage is 100%, with both `page` (100 results per page) and `show` (status enum with default) fully documented in the schema. The description's phrase "filtered by status" merely echoes the `show` enum, so a 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 gives a clear verb+resource ("List all user searches"), so an agent immediately knows the operation and the entity. However, it never distinguishes this tool from sibling list tools such as list_expert_searches, list_keyword_searches, or get_user_search, so the agent must infer the difference from the name 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?

There is no when-to-use guidance, no stated prerequisites, and no mention of when to prefer a sibling such as get_user_search or list_keyword_searches. The only contextual cue is the implicit "list" semantics, which the agent could already derive from the tool name.

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 address the two facts that matter most for a pause mutation: the schedule and its history are preserved (no data loss) and the change is reversible via resume_agent_schedule. Gaps remain: it does not say whether an already-paused schedule errors or is a no-op, whether an in-progress run is affected, or what permissions are required.

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

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

Two short sentences with zero waste; the core action and effect are front-loaded, and the second sentence delivers the preservation/reversibility guarantee and the follow-up 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?

For a one-parameter mutation with no output schema and no annotations, the description covers purpose, the key side effect (preservation) and the reversal path, which is enough to invoke it correctly. It could be stronger by describing what is returned or the state transitions (paused vs. active), but nothing critical is missing 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?

There is a single required parameter whose schema description ('Schedule UUID') is fully covered at 100%, so the schema already does the documenting. The description adds no extra meaning about the id (e.g., where to obtain it via list_agent_schedules), so the baseline of 3 applies.

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

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

The description states a specific verb and resource ('Pause a Rolli Agent schedule') plus the immediate effect ('stops executing'), and it names the counterpart tool resume_agent_schedule, so the agent can distinguish it from resume/update/delete siblings without reading the schema.

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

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

Usage is clear from the stated effect: use this to stop a schedule from running while keeping it. The description also points to resume_agent_schedule as the way back, which is the main alternative an agent would weigh. It stops short of explicit exclusions (e.g., use delete_agent_schedule if the schedule should be removed permanently, or cancel_agent_run for an in-flight run).

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 does so well: it discloses the state mutation ('Resets the run to pending and re-enqueues it'), a destructive side effect ('Running runs are force-cancelled first'), a failure mode (422 on completed runs), and a cost precondition (at least 1 IQ credit, fails immediately if exhausted). These are exactly the behavioral facts an agent cannot infer from 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?

Four short sentences, each earning its place, with the core action and eligible states front-loaded before the side effects and error conditions. No filler or restatement of the 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 single-parameter mutation with no output schema, the description covers preconditions, destructive behavior, and failure codes thoroughly. The only gap is the success return value — it never says what a successful rerun yields (e.g., the updated run object), which matters since no output schema exists.

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?

There is a single parameter, 'id', and schema description coverage is 100% ('Run UUID'), so the schema already fully documents it. The description adds no format, sourcing, or constraint detail about the identifier, so the baseline 3 applies.

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

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

States a specific verb and resource ('Rerun a ... Rolli Agent run') and immediately qualifies the eligible states (failed, waiting, stuck). The verb 'Rerun' plus the state eligibility naturally separates it from start_agent_run, cancel_agent_run, and update_agent_run without opening any schema.

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

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

Gives clear when-to-use conditions (failed, waiting, or stuck runs) and an implicit when-not ('Returns 422 if the run is already completed'). It never names the sibling alternatives such as start_agent_run for a fresh run, so it falls short of fully explicit routing.

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 at all, the description carries the full behavioral burden, and it does deliver one genuinely useful disclosure: next_run_at is recalculated from the recurrence parameters rather than resumed at the old time. It omits permission requirements, idempotency, and the error behavior for a non-paused schedule, which matter for a state-mutating call.

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

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

Two short sentences with zero filler; the operation is front-loaded and the side-effect note follows immediately. Nothing could be removed without losing information.

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

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

For a single-parameter state toggle with no output schema, an agent still needs to know what the call returns and how it behaves when the schedule is not paused; neither is addressed. The description is adequate to attempt the call but incomplete for predicting its outcome.

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 `id` parameter is documented as "Schedule UUID" with a strict UUID pattern — so the schema already does the work. The description adds nothing about the identifier beyond what the schema states, which is acceptable at one parameter but earns no extra credit.

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 ("Resume") and a specific resource ("a paused Rolli Agent schedule"), which an agent can distinguish from pause_agent_schedule, delete_agent_schedule, or update_agent_schedule without opening the schema. It stops short of naming any sibling explicitly, so the differentiation is implicit rather than stated.

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 word "paused" implies the precondition for use, but the description never says what happens if the schedule is already active, nor does it point to pause_agent_schedule as the inverse operation or to update_agent_schedule when recurrence itself needs changing. Usage is inferable but not spelled out.

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 and does so well: it discloses the pre-flight failure mode (insufficient IQ credits aborts before starting), the inline polling window (up to 2 minutes), the expected total latency (3-5 minutes), and the two possible return shapes (full results vs. run ID plus a follow-up instruction). These are exactly the cost, timing, and failure facts an agent needs before committing to a long-running 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?

Four sentences, front-loaded with purpose, then the pipeline, then the failure/latency/return contract. Every sentence carries operational information an agent needs, and the parenthetical '(typical run takes 3-5 minutes)' pre-empts the obvious follow-up question about the 2-minute poll window.

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 an eight-parameter, long-running async tool with no annotations and no output schema, the description covers what matters: what it does, what it costs, how long it takes, how it can fail, and what comes back in each outcome. Return-value explanation is present precisely because no output schema exists to supply it.

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 eight parameters are already documented in structured data, which sets the baseline at 3. The description only reinforces the 'question' parameter as plain English; it adds nothing about mode selection, platform defaults, time_window syntax, or the fact that the field named available_credits actually controls reasoning effort rather than a credit balance.

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 ('Start a Rolli Agent investigation') and then spells out the full pipeline: plan search strategy, query Rolli IQ across platforms, analyze posts, produce a markdown report with signals, evidence links, and confidence rating. An agent can distinguish this from siblings like get_agent_run, rerun_agent_run, or expert_search without opening any schema.

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

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

Gives clear conditions for calling it (submit a plain-English question) and explicitly routes to get_agent_run when the inline poll window expires. It also flags the credit-balance precondition. It stops short of stating when NOT to use it versus rerun_agent_run, cancel_agent_run, or the expert_search/keyword_search alternatives, so it is strong but not exhaustive.

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

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

No annotations are supplied, so the description must carry the behavioral burden. It does add one genuinely useful constraint the schema does not encode (no anyOf/oneOf enforcing at least one of pinned/label), but it omits permission requirements, whether label overwrites or clears, and whether the update is idempotent.

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, with the resource and the allowed operations front-loaded ahead of the precondition. Every clause 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 three-parameter mutation tool with no annotations and no output schema, the definition is minimally viable. The schema covers the parameters well, but the description leaves the agent guessing about side effects, permissions, and what a successful update returns.

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 id, label, and pinned. The description adds only the cross-parameter requirement that at least one of pinned or label be present, which is real value but limited; nothing is said about label length, empty-string semantics, or pinning behavior.

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

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

States a specific verb and resource ("Update a Rolli Agent run's metadata") and narrows the scope with "(rename or pin)", which lets an agent separate it from get_agent_run, delete_agent_run, and cancel_agent_run. It stops short of naming a sibling or stating what the tool does NOT do.

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

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

The only conditional guidance is a precondition ("At least one of pinned or label is required"), not a when-to-use rule. There is no indication of when to choose this over adjacent tools such as update_agent_schedule or rerun_agent_run, and no 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 full behavioral burden. It usefully discloses that unspecified fields are left unchanged and that next_run_at is recalculated when recurrence parameters change, but it omits permissions, validation behavior, error handling, and whether updates affect currently running schedules.

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 three short sentences, front-loaded with the core action and partial-update semantics. Every sentence adds relevant information about behavior without unnecessary wording.

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 an 18-parameter mutation tool with no annotations and no output schema, the description covers the most important update semantics: partial updates and next_run_at recalculation. However, it leaves out prerequisite state, permission requirements, and side effects that would help an agent invoke it confidently.

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

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

Schema description coverage is 100%, so the schema already documents all 18 parameters in detail, including enum values and ranges. The description adds useful context about recurrence parameters triggering next_run_at recalculation, but otherwise does not add meaning 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: 'Partially update a Rolli Agent schedule.' The word 'Partially' distinguishes it from a full replacement update, and the resource is unambiguous, though it does not explicitly name sibling tools like pause_agent_schedule or create_agent_schedule.

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 does not say when to use this tool versus alternatives such as pause_agent_schedule, resume_agent_schedule, or create_agent_schedule. Usage is only implied by the 'partially update' wording, with no explicit context or 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, the description carries the full burden of behavioral disclosure for a mutation tool. It never says whether the URL replaces an existing one, whether other integration settings are preserved, whether authentication or an existing integration is required, or what the call returns on success.

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

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

Two short sentences with the verb and the target field front-loaded; nothing is padded. The second sentence largely duplicates the schema's parameter description, which is the only minor 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?

For a one-parameter, fully documented schema this is close to sufficient — an agent knows what to send. But with no annotations and no output schema, the description should have covered the write's effect (overwrite semantics, required pre-existing integration), which is the remaining gap.

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

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

There is a single parameter and schema coverage is 100%; the schema already documents return_url as the webhook notification URL with URI format and a max length. The description's second sentence merely restates that schema text, adding no new constraint or format detail, so the baseline of 3 applies.

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

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

States a specific verb and resource ("Update integration configuration") and names the single configurable field, the webhook/return URL. It does not mention the sibling get_integration_setup, so the read-vs-write distinction is left to inference, but the operation itself is unambiguous.

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 only implies when to use it ("Set the webhook URL that receives notifications when a search completes"). It gives no prerequisites, no note that get_integration_setup can be used to read the current value first, and no guidance on what happens if an integration is not yet configured.

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 does well: it discloses that the call polls until completion (latency/blocking behavior), that responses may be truncated with a 'truncated: true' marker, and that 'results_pending' is a success state rather than a failure. It omits permission/auth requirements and whether the created search persists or is billed, which keeps 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?

Four sentences, front-loaded with the core action, then the polling/truncation/pending behaviors in priority order. Dense and mostly waste-free, though the truncation and pending sentences could be tightened into one.

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?

No output schema exists, so the description must explain returns; it covers the truncated flag, the results_pending status, and the pagination path, which is what an agent needs to act on results. It stops short of describing the post object shape or the full result payload, a minor gap for a 4-parameter search tool.

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

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

Schema description coverage is 100%, so the schema already documents query, platform, and the date bounds; the description adds no extra meaning about start_date/end_date semantics or platform-specific behavior. Baseline 3 applies, with the only added hint (fields=lean) referring to a sibling tool rather than this tool's parameters.

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

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

States a specific verb and resource ('Create a user profile search on a social media platform') and implicitly scopes it against sibling search tools (keyword_search, expert_search) by naming the user-search follow-up tools. An agent can identify this as the user-scoped search entry point without opening the schema.

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

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

Gives concrete conditional routing: paginate with get_user_search_posts when truncated, and fetch with get_user_search when status is results_pending. It does not explicitly say when to choose this over keyword_search or expert_search, so the sibling-selection guidance is incomplete.

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