Crawdar Business Research

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety bar is low. The description adds real behavioral context beyond them: results are owner self-reports, not verified budget, and there is no authorization to contact owners outside the application flow — a genuine constraint on downstream agent behavior.

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

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

Two short sentences, front-loaded with the core purpose, no filler. The second sentence is a disclaimer rather than operational detail, but it earns its place by preventing misuse of the results.

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

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

An output schema and rich annotations carry the return-shape and safety burden, so the description needn't explain them. However, for a five-parameter filtered/paginated browse tool with zero schema documentation, leaving every parameter unexplained and providing no sibling routing leaves meaningful gaps.

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

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

Schema description coverage is 0% for all five parameters (limit, query, cursor, industry, geography), and the description never mentions any of them, so an agent gets no meaning for pagination semantics, query matching behavior, or how industry/geography values are formatted. It does not compensate at all for the total schema documentation gap.

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: browsing public business (owner) requests, with the qualifier that they carry current website-control proof. That distinguishes it from the provider-browsing sibling, though it never names browse_service_providers or any other alternative 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?

The second sentence sets expectations about what a request IS (owner-reported need, not a funded contract or permission to contact), which is useful framing, but it gives no when-to-use routing against the 19 siblings (e.g. browse_service_providers, match_demand_providers, search_businesses) and no prerequisites for filtering.

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

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

Annotations already cover read-only, idempotent, non-destructive and closed-world behavior, so the bar is lower, yet the description adds genuinely non-structured context: the data is provider-declared and should not be read as a skill or performance endorsement. It omits pagination behavior even though a cursor parameter exists.

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 substantive content front-loaded and the trust caveat immediately following. Nothing needs trimming.

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

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

An output schema exists so return values need not be described, and the data-provenance caveat is a real addition. But for a five-parameter browse tool with zero schema coverage, the missing filter and pagination guidance leaves the definition under-specified for correct invocation.

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

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

Schema description coverage is 0% across five parameters, so the description carries the full burden and largely fails: limit, query, cursor, industry and geography are never mentioned or explained. The listed concepts (markets, capabilities) describe return content rather than parameter meaning, giving at best an indirect hint.

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 concrete verb ('Read') and enumerates the resource content (capabilities, portfolio URLs, markets, capacity), which matches the title's 'published provider profiles'. It does not, however, differentiate itself from siblings such as browse_owner_demands or search_businesses.

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

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

There is no statement of when to choose this tool over alternatives like search_businesses or match_demand_providers, nor any prerequisite or exclusion. The browsing intent is only implied by the name and the word 'Read'.

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

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

Annotations already flag destructiveHint and idempotentHint. The description adds useful behavioral context: only queued or running jobs are affected, and completed/failed jobs are immutable, which clarifies why the operation is idempotent for terminal states.

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

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

Two sentences deliver the action, the resource scope, and an important caveat without any filler. The main verb and target are front-loaded, making the purpose immediately clear.

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

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

With an output schema present, both required parameters fully documented, and annotations covering safety profile, the description provides everything an agent needs to invoke cancellation appropriately. The immutability caveat covers edge cases of completed/failed jobs.

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

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

The input schema provides full descriptions for both required parameters (id and jobToken) with 100% coverage. The description adds no additional parameter-specific meaning, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb ('Cancel') and resource ('search job'), and further narrows scope to 'queued or running' jobs. This clearly distinguishes it from sibling tools like start_lead_search or get_lead_search.

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

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

The description implies when cancellation is valid by noting 'Completed and failed jobs remain immutable', which serves as a when-not. However, it does not explicitly name alternatives or direct the agent to a different tool for other job states.

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

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

Annotations already declare readOnly=false, destructive=false and openWorld=false; the description adds the meaningful behavioral boundary that creation is inert (no research executed, no demand established) and that idempotencyKey makes retries safe, which resolves the apparent tension with idempotentHint=false. It omits visibility ('private' appears only in the title) and failure/side-effect details, but adds real value beyond the structured fields.

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

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

Three short sentences, front-loaded with the action and then the two highest-value clarifications. No filler or restatement of the title.

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

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

The output schema means return values needn't be described, and mutation safety is covered by annotations. But for a create tool with a nested, entirely undocumented profile object and 0% schema coverage, the description leaves the agent without enough information to populate the payload 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 0%, so the description carries the full burden, yet it only explains idempotencyKey and gestures vaguely at 'declared capabilities' for the nested profile object. The required `name` and every profile subfield (skills, capacity, industries, geographies, excludedActivities) and their constraints go unmentioned.

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 ('Save a research thesis workspace and declared capabilities') and immediately demarcates scope from the closely named sibling research_opportunity_workspace ('does not run research or establish demand'). An agent can distinguish this from get/list/update_opportunity_workspace and research_* tools 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?

The exclusion 'does not run research or establish demand' implicitly routes agents to research_opportunity_workspace for actual research, and the retry line gives operational guidance. It stops short of naming the alternative explicitly or stating prerequisites (e.g. whether a thesis must exist first), so it's clear context without 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?

Annotations only say non-read-only, non-destructive, non-idempotent, closed-world; the description adds real value by enumerating the negative side effects: it never publishes, contacts providers, forms a contract, or moves money, and it names the control requirement for the later publish step. The remaining gap is that it does not address duplicate-draft behavior or validation failures, which matters for a non-idempotent create.

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, zero filler, with the core action front-loaded and the boundary statements following. Every sentence carries 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?

Output schema existence relieves the description of explaining return values, and annotations plus the description cover the mutation safety profile. But for a 9-parameter draft-creation tool with zero schema descriptions, the absence of any field-level guidance leaves the definition materially incomplete 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 are 9 parameters with 6 required and 0% schema description coverage, so the description carries the full explanatory burden — yet it names no field at all. An agent must infer meaning from bare names like 'timing', 'budgetText', 'requiredSkills', and 'problem' and gets no hint about which fields drive matching or what content belongs in each.

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 private draft request') and immediately scopes it as private/non-published, which separates it from public-facing actions. It does not explicitly differentiate itself from creation-adjacent siblings such as create_opportunity_workspace, so it stops short of a 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?

The description implies the usage context — you draft here, an owner publishes later after website control and review of public fields — which is useful lifecycle guidance. However, it never states when to prefer this tool over siblings like create_opportunity_workspace, and gives no prerequisites for calling it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds a meaningful behavioral trait: 'does not consume a search.' This goes beyond the annotations by clarifying that the tool performs no search operation, which is important context. No contradiction with annotations.

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

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

Two concise sentences with no redundancy. The first sentence front-loads the core purpose, and the second adds a clarifying limitation. Every word earns its place, making it efficient and easy to parse.

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

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

Given zero parameters and an output schema, the description covers the essential information: what the tool returns (semantics, limits, URLs, guidance) and what it does not do (consume a search). An agent can confidently use this tool to obtain operational context for the search tools, and nothing critical is missing.

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

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

The tool has zero parameters, so the baseline is 4. The description does not need to explain parameter semantics, and the schema confirms no parameters exist. The description appropriately focuses on the tool's function rather than 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?

The description states a specific purpose: to retrieve result semantics, limits, interface URLs, and safety guidance. It explicitly distinguishes itself from search operations with 'This tool does not consume a search.' This clearly differentiates it from the sibling search tools and gives an agent a precise understanding of what it does.

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

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

The description implies usage by stating what it provides and clarifying it does not consume a search. This sets a clear boundary versus the sibling search tools, though it doesn't explicitly state 'use this when you need to understand the search tool' or provide alternative conditions. The context is clear enough for an agent to infer when to use it.

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

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

Annotations already mark the operation as read-only, idempotent, and non-destructive. The description adds valuable behavioral detail beyond that: the tool returns either job status or a paginated page, jobToken must be kept private, and cursor must be passed back unchanged. No contradiction with annotations exists.

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-load the core purpose and then give the two essential operational cautions. There is no filler or redundant restatement of the tool name.

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

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

With an output schema present, annotations providing the safety profile, and full parameter documentation, the description supplies the missing high-level semantics: status/page duality, opaque cursor chaining, and token privacy. An agent has enough information to invoke it correctly.

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

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

Schema coverage is 100%, and the schema already documents id provenance, view behavior, limit bounds, cursor opacity, and jobToken privacy. The description's 'keep jobToken private' and 'pass nextCursor back unchanged' largely echo schema text, with only the 'unchanged' nuance adding slight extra 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 states a specific verb ('Read') and resource ('job status or one cursor-paginated result page'). This clearly distinguishes it from sibling tools like start_lead_search, refine_lead_search, retry_lead_search, and cancel_lead_search, which create, modify, or cancel jobs rather than read results.

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 clearly frames the tool as a retrieval and pagination operation, and the instruction to pass nextCursor back unchanged gives concrete usage context. It does not explicitly name alternatives or exclusions, but the sibling tool set makes the retrieval-versus-creation contrast obvious.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description adds genuinely new behavioral context: an access prerequisite (verified account identity or linked API key), a consent/privacy constraint on what aggregates are visible, and an explicit caveat that rates are correlational cohort data, not causal or predictive claims. This goes well beyond what the annotations convey.

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

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

Three sentences, each carrying distinct information (what is returned, what access is required, what the numbers mean), with the core purpose front-loaded. Slightly heavy noun stacking in sentence one costs it a 5.

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

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

An output schema exists so return structure needn't be explained, and the description covers the remaining agent-relevant unknowns: auth prerequisite, data-visibility scoping, and interpretation limits. Only the missing 'when to use versus sibling tools' guidance keeps it 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. No misleading parameter language is present.

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 read operation on recorded opportunity outcomes and separates the two data sources it returns: private evidence/failure feedback and consented public aggregates. It is distinguishable from siblings like get_opportunity_workspace, though the phrasing ('evidence funnel', 'sufficiently diverse, jointly consented public outcome aggregates') is dense enough that an agent may need a second read to be sure.

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 — the description establishes this is a review/learning read but never says when to call it instead of get_opportunity_workspace or research_opportunity_workspace, nor any exclusion such as 'call after a lead search completes'. No explicit trigger or alternative is named.

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

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

The annotations already establish that this is a read-only, idempotent, non-destructive operation. The description adds useful behavioral context by stating that evidence, contradictory findings, validation milestones, and monitor configuration remain private to the 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?

The description is two concise sentences with the core purpose front-loaded. The second sentence adds privacy context without unnecessary repetition.

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

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

The tool has rich annotations, an output schema, and a fully documented single parameter. The description covers the update-preparation purpose and privacy scope, leaving little 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?

Schema description coverage is 100%, and the single id parameter is already documented as a private workspace UUID owned by the authenticated account. The description does not add parameter-specific meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb and resource: "Get the current workspace and revision." It also clarifies the read-before-update role relative to updating, though it does not explicitly name the update sibling.

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 "before updating" gives clear usage context and tells the agent when this tool is appropriate. It does not explicitly distinguish against list_opportunity_workspaces or research_opportunity_workspace, but the immediate update workflow is clear.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds the non-obvious access-control precondition (verified account, no guest/anonymous use), which is real behavioral context beyond annotations; it is quiet on result volume/pagination, though an output schema exists.

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 access prerequisite. Every clause carries information; nothing is repeated from the title or annotations.

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

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

For a zero-parameter, read-only list with full annotations and an output schema, the description covers everything needed to call it correctly: what it returns in scope terms and the auth gate. It could note that results are limited to the caller's own account set only (no shared/public entries appear in the response), but that is largely implied.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate — baseline 4 applies. The description correctly avoids inventing filtering options that the schema does not support.

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

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

Specific verb+resource ('List research workspaces') plus a clear scope constraint ('owned by your verified account'), which implicitly separates it from get_opportunity_workspace (single item) and the browse_* siblings. It does not name a sibling outright, so it stops short of full differentiation.

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 an explicit when-not: no guest access or public Atlas, plus the authentication path required (account-linked API key or signed-in identity) — valuable gating information an agent cannot infer from the empty schema. It does not route between list vs. get vs. create siblings, so it falls short of a 5.

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

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

Annotations already declare read-only, idempotent, non-destructive, and closed-world, so the bar is lower, yet the description adds real value: a hard page limit of 50 providers, disclosure that public consented outcome context is kept separate from ratings, and that missing data is treated as unknown. These are behavioral facts not present in the annotations.

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

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

Three sentences, front-loaded with the core ranking action, then pagination and data caveats. Compact and mostly waste-free, though the outcome-context sentence is a bit cryptic without more grounding.

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

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

An output schema exists, so return values needn't be explained, and annotations cover the safety profile. However, for a matching tool whose four parameters have 0% schema coverage, the description leaves industry/geography/demandId semantics unexplained, which an agent needs to call it correctly.

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

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

Schema description coverage is 0%, so the description must carry all meaning for the four parameters, yet it only loosely gestures at cursor pagination (calling it 'nextCursor' while the actual param is 'cursor'). It never explains demandId, industry, or geography, leaving the filter parameters undocumented in both schema and 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: ranks published providers by declared skill labels and market fit. This distinguishes it in spirit from browse_service_providers (browsing vs. match-ranking), but it never names a sibling to make the distinction explicit.

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

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

Provides pagination guidance ('Use nextCursor for more candidates') and a data-quality caveat, but gives no explicit when-to-use guidance versus siblings like browse_service_providers or browse_owner_demands. Usage is implied by the description rather than stated as selection criteria.

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

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

Annotations already indicate readOnly=false, destructive=false, and idempotent=false. The description adds that the original job remains unchanged, but it does not disclose persistence behavior, asynchronous job polling, rate limits, or other side effects beyond creating a new job.

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, focused sentence with no filler. It front-loads the core action and key constraint, making it easy to parse quickly.

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

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

The schema and annotations cover the parameter and safety landscape, and the description gives the essential purpose. However, it omits lifecycle context such as how to retrieve the resulting job or whether it is asynchronous, which would be useful given the job-based nature of the tool.

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

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

Schema description coverage is 100%, and each parameter has a clear one-line description. The tool description itself adds no additional meaning beyond what the input schema already provides, so the baseline score 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 ('Create'), a distinct resource ('new private search job'), and a unique action ('by changing the brief or criteria of a completed job'). The explicit non-destructive outcome ('The original job stays unchanged') further disambiguates it from similar lead-search tools.

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

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

The description implies use when refining a completed lead search and clearly frames the action, but it does not explicitly name alternatives such as start_lead_search or retry_lead_search, nor does it provide direct 'when not to use' guidance. Context is present but not fully explicit.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the synchronous, quick nature and the contrast with the durable asynchronous sibling, which is valuable context beyond the annotations. It does not contradict annotations and provides the expected call-time behavior.

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

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

Two sentences with zero waste. The primary use case is front-loaded in the first sentence, and the alternative is clearly stated in the second. It is concise, structured, and every word contributes to the agent's decision.

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

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

Given the tool's complexity (7 parameters, 1 required) and the presence of a detailed input schema and output schema, the description is sufficient. It explains the synchronous nature and the routing to the async sibling. It does not cover pagination or output details, but those are already in the schema, and the description provides the key decision guidance for an agent.

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

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

Schema coverage is 100% and all seven parameters have detailed descriptions (e.g., brief example, limit bounds, fields enum). The description does not add parameter-specific semantics but reinforces that the brief is a natural-language query. With full schema coverage, a baseline of 3 is appropriate; the description adds no extra 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 ('research') and resource ('businesses'), and immediately defines the scope: a quick synchronous search from a natural-language brief. It distinguishes itself from start_lead_search by naming the alternative, making it clear this tool is for immediate results in the current call. No ambiguity.

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

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

The description explicitly says 'Use for a quick synchronous search when the user supplies one natural-language brief and can wait for results in the current tool call' and then explicitly routes other workflows ('durable progress, retry, export, or large agent workflows') to start_lead_search instead. This gives both when-to-use and when-not-to-use guidance with a named alternative.

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?

Beyond the annotations (readOnlyHint=false, openWorldHint=true, non-idempotent), it discloses bounded scope (three businesses), a revision prerequisite implying optimistic-concurrency failure, provider rate limits, and a concurrency warning. The caveat that sampled complaints are leads, not confirmed needs or purchase proof usefully sets expectations about output quality.

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 tight sentences, front-loaded with the purpose then constraints. The quality caveat earns its place by disambiguating what the findings mean, and there is no filler or repetition.

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

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

The presence of an output schema relieves it of explaining return values, and it covers scope, concurrency, and evidence caveats. However, for a 5-parameter mutation tool with 20% schema coverage, the unaddressed target/geography/problemCategories semantics leave an agent under-informed about how to shape the scan.

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

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

Schema coverage is only 20%, so the description should compensate, but it only obliquely touches two params (revision via "current revision", target via "up to three businesses"). The meaning of target, geography, and problemCategories is left entirely to the thin schema, leaving most parameters under-explained.

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 concrete verb and scope: "run a bounded public review scan of up to three businesses and retain sourced findings in your private workspace." The resource (business reviews) and the side effect (retention in a workspace) are both explicit. It doesn't name a sibling to distinguish from, e.g., research_businesses or scan_review_pain_points, so it stops short of a 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?

Gives operational constraints ("Requires current revision", "do not launch duplicate concurrent scans", "Uses normal provider limits") but no explicit when-to-use/when-not or routing to alternatives like research_businesses or start_lead_search. Usage is implied by the description of the scan, not spelled out relative to siblings.

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

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

The description makes the mutation explicit ('Create a replacement job') and adds a side effect detail (original stays for audit). It does not mention idempotency or permissions, but the annotations already cover the read-only and destructiveness hints, and the description aligns with them.

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

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

The description is two sentences, concise and to the point, with no unnecessary details or repetition. It is well-structured and front-loads the core purpose.

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

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

The description is complete enough given the output schema exists and the parameters are well-described. It does not cover error cases or output details, but these are not required for a tool of this simplicity.

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?

Both parameters have descriptions in the schema that add meaning: 'id' is 'Failed or timed-out source job id' and 'jobToken' is 'Private token belonging to the source job'. This exceeds simple name-based inference.

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?

Description clearly states the action ('Create a replacement job') and the specific object ('replacement job'), and distinguishes it from siblings by noting the original job stays for audit. It is clear and specific.

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

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

The description explicitly states when to use it ('when a prior job failed or exceeded its execution window'), providing a clear condition. It does not explicitly name alternatives, but the condition sufficiently guides usage.

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

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

The description clearly indicates the tool returns fictional deterministic data and has no provider-side consumption, aligning with the readOnlyHint annotation. It also implies idempotency through 'deterministic' and is consistent with the destructiveHint false annotation. No behavioral contradictions are present.

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 tightly written in two sentences with no redundant wording. It front-loads the primary purpose and immediately follows with concrete usage guidance.

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

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

Given the annotations, input schema, output schema, and sibling tool context, the description covers all essential information an agent needs: purpose, behavior, parameters, and safe usage. There are no missing critical details.

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?

Both parameters are described with their meaning and role in generating deterministic test results. The schema coverage is 100%, and the description adds that values are 'echoed' into results, clarifying how the parameters affect output.

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 ('Return') and clearly identifies the resource as deterministic fictional businesses. It also distinguishes this tool from production data tools by noting it does not consume provider capacity and is intended for testing schemas, clients, and agent loops.

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

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

The description explicitly states when to use the tool: 'Use this to test schemas, clients, and agent loops.' This provides clear guidance on the intended scenario and helps differentiate it from the sibling search/research tools.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, but the description adds critical behavior beyond them: coverage is sampled (unavailable reviews never mean no problems), a five-scans-per-day rate limit, and a dependency on a configured provider for Google reviews. These are non-obvious traits that materially affect invocation.

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

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

The description is three tight sentences, front-loading the primary action and purpose. Each sentence earns its place: the core function, the sampling caveat, and the operational constraints (rate limit and provider requirement). 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?

With six parameters, zero schema descriptions, and no explanation of which parameters map to 'named business' or 'discover up to three businesses,' the description is insufficient for correct invocation. The output schema exists, so return format isn't a gap, but input semantics are entirely unaddressed. The operational constraints are helpful but don't compensate for missing parameter guidance.

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 0%, so the description must compensate by explaining parameter meanings. It does not mention any of the six parameters (target, website, business, geography, reviewUrls, googlePlaceId) or how they relate to the described behavior. An agent cannot determine what to provide.

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

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

The description clearly states a specific action (scan) and resource (a named business or discover up to three businesses) for a distinct purpose (recurring complaints). It differentiates from sibling tools by focusing on complaints and solutions, not leads or generic research.

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

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

The description implies usage for complaint analysis but doesn't explicitly contrast with alternatives like search_businesses or research_businesses. It provides caveats (coverage sampling, rate limit, provider dependency) that inform when it's applicable, but lacks explicit when-not guidance or 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?

Annotations already establish readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds useful context by characterizing the call as quick and synchronous, and there is no contradiction with the annotations.

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

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

The description is concise, front-loaded with the primary use case, and efficiently contrasts sibling tools without unnecessary detail.

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

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

The description, combined with the parameter schema and annotations, provides enough context for invoking a synchronous search and interpreting paging-related outputs. It could mention return shape more explicitly, but the output enum and parameter descriptions cover the essentials.

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 descriptions cover 100% of parameters, so the baseline applies. The tool description does not add much beyond the schema, though it does reinforce that target, geography, and qualifier are the structured search fields.

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?

Description uses the specific verb 'search' and identifies the resource 'businesses.' It clearly distinguishes from siblings by noting the structured-criteria synchronous use case versus research_businesses for plain-language briefs and start_lead_search for durable async work.

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 states when to use the tool: quick synchronous search when target, geography, and qualification fields are already structured. It also names alternatives for different scenarios, leaving little ambiguity about selection.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description adds real value by disclosing data provenance: editorial research does not imply the featured business joined, contributions and owner reports are unverified and not purchase intent. Source URLs, dates, support/contradiction fields are also disclosed. It falls short of explaining result ranking or pagination behavior.

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

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

At roughly four dense sentences it is not bloated, and each caveat is meaningful. However it front-loads corpus provenance rather than the action, so the reader must reach the end without ever learning how to scope or page the search.

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

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

An output schema exists, so return shape needn't be described. But for a zero-required, seven-parameter search tool with no schema descriptions, the description's silence on filters and pagination leaves a material gap an agent cannot fill from structured fields.

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?

All 7 parameters have 0% schema description coverage and the description explains none of them; host, query, problem, industry, geography, limit and cursor are left for the agent to guess. The only faint hint is 'across markets', which loosely gestures at geography, and 'editorial research' which does not map to any parameter.

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 enumerates what data lives in the graph (editorial research, contributed observations, website-confirmed owner demand) but supplies no operational verb or scoping statement about the search itself. An agent learns the corpus contents, not how this tool differs from browse_owner_demands or scan_review_pain_points. Purpose is inferable from the name and title only.

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

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

There is no statement of when to call this versus the many sibling read tools (browse_owner_demands, search_businesses, scan_review_pain_points). The one boundary given — 'Private workspaces are never included automatically' — is a scope exclusion, not usage guidance, and no alternatives are named.

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

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

Description discloses that it creates a job, is asynchronous and queued, and returns identifiers for subsequent operations; consistent with annotations (idempotentHint=false, readOnlyHint=false).

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 usage recommendation, then concise feature list; no 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?

Provides purpose, async nature, return identifiers, and downstream capabilities; since output schema exists, no need to detail return fields.

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 already covers all parameters with descriptions; description adds high-level workflow context but does not detail parameter usage, so baseline 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 'creates' and resource 'private queued search job', and positions it as the recommended durable asynchronous workflow, distinguishing it from synchronous siblings.

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 says 'Use for the recommended durable asynchronous workflow' and enumerates downstream capabilities (polling, paging, refinement, retry, cancellation, export), signaling when to choose this tool; however, it does not explicitly name sibling tools for contrast.

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

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

Annotations declare the safe/mutating profile, and the description adds non-obvious behavior: optimistic concurrency via revision with 409 conflict semantics, the evidence policy (public signals can't establish payment intent, milestones need attributable evidence), and explicit negative scope ('does not contact businesses or execute delivery'). It does not mention that the operation is non-idempotent, which matters for retry safety.

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 carrying a distinct point (mutation model, conflict handling, evidence policy, scope limits), with the core action front-loaded. 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 10-command dispatcher over deeply nested objects, the description covers policy and failure modes well and an output schema exists to describe returns, but it gives no per-command guidance or idempotency/retry caveat. An agent can call it, yet could easily send a wrong command shape.

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

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

Schema coverage is 33% but nested objects carry their own inline descriptions (patch, validation), and the description ties 'revision' to the conflict model. Still, it never explains which fields each command type consumes or that command.type selects the whole shape, leaving the biggest semantic question to the schema.

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

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

States a specific verb and resource: apply one validated command against an opportunity workspace at a given revision. The 10 concrete command types that define the actual capability set are only in the schema enum, not the description, so an agent can't grasp the full scope from prose 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?

Adds a clear retry rule ('409 means re-read before retrying') which is real usage guidance, but never says when to use this versus siblings like get_opportunity_workspace, create_opportunity_workspace, or research_opportunity_workspace. The reader must infer the read/write split from tool names.

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