Xevol

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is known. The description adds real value beyond them by disclosing the NOT_FOUND failure mode and the access-control nuance that a private Company the caller cannot see is indistinguishable from a missing one. It stops short of noting any pagination or field-truncation behavior, but for a single-record read that gap is minor.

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 tight sentences: the first front-loads what is returned, the second states the prerequisite. Every clause carries information and nothing is repeated from the schema beyond the necessary 'given its id' framing.

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 tool with no output schema, the description covers the three things an agent needs: what comes back (field list), how to get the required input (search/list_companies), and what failure looks like (NOT_FOUND). No material gap remains.

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

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

With 100% schema description coverage the parameter's meaning is already fully documented, and the schema itself says the id comes from search or list_companies. The description restates that provenance ('given its id') without adding format, length, or validation detail, so it neither helps nor hurts beyond the baseline.

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

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

States a specific verb and resource ('Read one Company in full, given its id') and immediately enumerates the fields returned, so the agent knows exactly what this retrieves. This clearly separates it from list_companies and search, which return collections rather than one full record.

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 tells the agent to call search or list_companies first to obtain the id, naming the sibling tools to use for discovery. The only preconditions the tool has are covered, leaving no ambiguity about how to obtain the required input.

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 bar is lower; the description still adds real value by disclosing the NOT_FOUND behavior for unknown ids and for private Contacts the caller cannot see. No mention of rate limits or response envelope, but no output schema exists to lean on.

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 purpose, then prerequisite, then failure mode. Every sentence carries actionable 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?

Since there is no output schema, listing the returned fields (including facts with sources and Deals) is essential and present. The id-sourcing prerequisite and the NOT_FOUND edge case round out what an agent needs 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?

With a single required parameter at 100% schema description coverage, the schema already fully documents 'id'. The description reinforces the provenance of the value ('from search or list_contacts') but adds no format, type, or constraint details 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?

Names the exact verb and resource ('Read one Contact in full, given its id') and enumerates the payload: phone, social links, research brief, facts with sources, Company, owner, Deals. This clearly separates it from the list_contacts/search siblings, which return many records.

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

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

'Use search or list_contacts first to get the id' gives an explicit prerequisite and names the two alternatives for acquiring the identifier. It stops short of contrasting get_contact with get_company/get_deal, but the resource distinction is self-evident.

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, non-destructive, closed-world), so the bar is lower. The description adds genuine behavioral context beyond them: the NOT_FOUND response for unknown ids and the Deals-module precondition that yields PRECONDITION_FAILED. It does not mention pagination or payload size, but for a single-record read that is minor.

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 dense sentences with no wasted words: the first front-loads what is returned, the second front-loads the id-sourcing prerequisite. Error and precondition details are appended, not 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?

There is no output schema, so naming the returned fields is essential and it is done thoroughly. Combined with the id-provenance guidance and the two error/precondition cases, an agent has 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 coverage is 100% and the single parameter already documents itself as 'The Deal's id, from search or list_deals.' The description restates the provenance of the id but adds no syntax, format, or validation detail beyond what the schema provides, so baseline 3 applies.

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

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

States a specific verb and resource ('Read one Deal in full, given its id') and enumerates the returned fields (stage, amountCents, currency, close date, Company, owner, Contacts). It is clearly distinguishable from the list/search siblings, which are named as the id source rather than as alternatives for the same read.

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: 'Use search or list_deals first to get the id,' naming the alternatives and the precondition that selects them. It also states what happens on an unknown id (NOT_FOUND) and the module requirement (PRECONDITION_FAILED), so the agent knows failure modes before calling.

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 and non-destructive, so safety is covered; the description adds workspace-scoping ('you can see'), one-page-at-a-time behavior, and the return shape (rows plus total and per-filter counts). It doesn't say how to detect the last page or how counts behave with filters combined, which keeps it off 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 sentences, each earning its place: what it does, when to use it vs siblings, and what comes back. The scope statement is front-loaded.

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

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

With no output schema, the description usefully discloses the return shape — one row per Company plus total and counts per filter value. Minor gaps remain around pagination termination and whether counts reflect active filters, but nothing blocks a correct call.

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

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

Schema coverage is 100% with enums and defaults documented, so the schema carries the parameter burden. The description only recaps the filter dimensions (owner, industry, research state, source) and sort, adding no syntax or format detail 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?

States a specific verb and resource ('List the Companies you can see in this Workspace, one page at a time') with scope and pagination baked in. It is immediately distinguishable from search and get_company, which are named.

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: use this to filter by owner/industry/research state/source or to sort, use search for name lookup, and get_company for details. Both alternatives and their selecting conditions are stated.

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, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely new behavioral context: paged results, visibility scoping ('you can see'), and the exact return payload including totals and per-filter counts. It stops short of describing pagination termination or how accessScope interacts with results, which the schema only partly covers.

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 doing distinct work: what it lists, when to use it vs. siblings, and what comes back. The primary purpose is front-loaded in the first clause 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?

With 9 optional parameters, no output schema and safety already covered by annotations, the description fills the key gaps by describing the returned row shape and the aggregate totals. Minor gaps remain around pagination behavior (what signals the last page) and the accessScope omission semantics, though the latter is documented in the schema.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes slightly beyond it by grouping the filter dimensions (owner, Company, source) and by noting that the response includes counts per filter value, which hints at how the filters are meant to be used for faceting. It adds no syntax or edge-case detail the schema lacks, so it sits just above baseline.

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

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

States a specific verb and resource ('List the Contacts'), scopes it ('you can see in this Workspace'), and characterizes the mode ('one page at a time'). It is clearly distinguishable from get_contact and search, which are named 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?

Names the two competing siblings with the exact condition that selects each: 'use search to find one by name, and get_contact for one person's phone, background and Deals.' It also states the intended use of this tool (filter by owner, Company or source, or sort), so the routing decision is explicit rather than inferred.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description still adds real context beyond them: pagination semantics ("one page at a time"), the returned row shape with a total, and a concrete failure mode (PRECONDITION_FAILED when the Deals module is absent). It does not mention permission scoping or rate limits, so not 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: capability first, routing second, return shape and precondition last. Every clause carries information and nothing is repeated from the schema verbatim.

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 nine-parameter read-only list tool with full schema coverage and no output schema, the description supplies what the schema cannot: the paginated contract, the returned fields, and the module prerequisite error. An agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so every one of the nine parameters (q, dir, page, sort, owner, stage, status, closing, pageSize) is already documented in the schema, including the enum values and defaults. The description only restates the filter categories at a high level and adds no syntax or interaction detail (e.g. that a stage filter overrides status). 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 ("List the Deals you can see in this Workspace") plus a scope qualifier (workspace-visible, paginated). It explicitly distinguishes itself from the search sibling and from get_deal, so an agent can identify it 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?

Names concrete use cases (filter by open/closed, stage, owner, expected close date, or sort) and routes to alternatives with conditions: "use search to find one by name, and get_deal for its Contacts." Both when-to-use and when-not-to-use are covered.

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/non-destructive safety, and the description adds real value beyond them: result cap (5 per kind), the shape of each hit (kind, id, label), and the environment-dependent omission of Deals. It doesn't cover ranking/ordering of hits or behavior on ambiguous matches, so it falls 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: what it does and returns first, then routing to the get_* siblings with the returned id, then routing to list_* for filtering. Every clause earns its place, including the Deals-module caveat.

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 tool with full schema coverage and annotations, the description covers purpose, result cardinality, return fields, next-step routing, and the one environment dependency. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% and the schema already documents the 2-character minimum, so baseline is 3. The description adds semantic breadth by mapping what the single query string can match (name fragment, email, domain), which is more than the schema states.

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

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

States a specific verb (find) and the exact resource types (Contact, Company, Deal) plus the matching keys (name fragment, email, domain). It explicitly distinguishes itself from the get_* siblings (you don't have an id) and from list_* siblings (they filter/sort/page).

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 when-to-use: when you lack an id or don't know the record kind. Explicit alternatives: pass the returned id to get_contact/get_company/get_deal, and use list_* to filter, sort or page. Also gives a negative condition (Workspace lacking the Deals module).

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