Twelfth

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and a closed-world scope, so the safety profile is covered. The description adds genuine non-annotation context: the epistemic caveat that sparse snapshots cannot prove discontinuation. It stops short of stating the precondition that two saved offers must exist or what happens when only one is available.

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, zero filler: the operation and its output dimensions come first, usage guidance second, and the caveat/alternative last. Every clause carries distinct information and the front-loading is correct.

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, return values need no explanation, and the description covers what is compared, when to use it, its limitation, and the alternative tool. The only remaining gap is the precondition that at least two saved offer files must exist for a comparison to be possible.

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 both parameters (supplier_name, limit) are fully documented in the schema itself. The description adds no syntax, matching rules, or format detail beyond what the schema already provides, which is the baseline case for a fully-covered two-parameter tool.

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 (compare) and resource (a supplier's latest two saved offer files) and enumerates the exact comparison dimensions: restocks, depletions, cost, availability, ETA, terms changes, new and missing lines. This distinguishes it from every sibling, none of which perform offer-snapshot diffing.

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 scopes usage to 'what-changed questions about a supplier's offers', states a when-not ('never proves a discontinuation from sparse snapshots'), and names the alternative for a different intent ('for past buying decisions use recall_decisions'). All three routing signals are present.

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 openWorldHint=false, so the safety profile is covered; the description adds the meaningful scoping behavior that results come only from the current task's lines, not the whole catalogue. It doesn't describe how similarity is determined or how many results are returned, but the output schema covers the return shape.

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 scope constraint and followed by the disambiguation. 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 one-parameter, read-only lookup with rich annotations and an output schema, the description covers purpose, scope and the sibling alternative. Nothing an agent needs in order to call 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?

There is a single parameter with 100% schema description coverage, so the schema already tells the agent to pass the entity name exactly as the user wrote it. The description only implies the name resolves to a product line; it adds no format or resolution guidance 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 ('Find other lines ... in the same category as a named product') and constrains the scope to the open task. This makes it clearly distinct from search_catalogue, which the description names 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?

Gives the use case ('substitutes and alternatives among the lines in front of the buyer') and names the alternative with its condition ('to search the whole catalogue use search_catalogue with the category'). The agent can route 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?

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds behavioral context beyond that: results carry catalogue-product and open-recommendation counts, and the ranking orientation changes with order_by. It does not discuss the returned shape in detail, but the output schema covers that.

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 no filler, front-loading the resolve behavior before the usage guidance and the sibling pointer. Slightly compressed, but every clause carries actionable 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?

With annotations covering the safety profile and an output schema covering return values, the description supplies everything else an agent needs: what it resolves, how to rank, when to prefer it, and which sibling to use instead. 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?

Schema coverage is 100%, so the baseline is 3, but the description adds a real constraint the schema omits: email_domain is 'Use instead of query, not with it', clarifying mutual exclusion that the schema leaves implicit. It also frames order_by=open_recommendations in terms of ranking by pending action, reinforcing the enum semantics.

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 precise verb+resource+scope: 'Resolve a supplier name, fragment or acronym to the workspace's suppliers' and adds what comes back (product and open-recommendation counts). It names the sibling boundary ('For a supplier's products use search_catalogue'), so an agent can separate it from search_catalogue 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 explicit when-to-use rules: before filtering by supplier, or with no query and order_by=open_recommendations to rank by pending work. It also names the correct alternative for a different need (search_catalogue for a supplier's products), so selection is fully determined.

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, idempotentHint=true and openWorldHint=false, so the safety profile is covered. The description adds scope context beyond the annotations ('fields carried on the open task's lines'), which constrains what data is visible. It does not add much else (return shape is covered by the output schema), so a 4 rather than 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, zero waste, and the core usage constraint is front-loaded ahead of the sibling routing. 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?

With annotations covering the safety profile, an output schema explaining return values, and 100% schema coverage for the two optional params, the description supplies exactly the missing piece: when to use this versus the pricing siblings. Nothing an agent needs to call it 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 description coverage is 100%, so both parameters (category, entity_name) are already documented in the schema. The description adds no syntax or filtering nuance beyond what the schema states, 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 (Read) and resource (competitor-match fields) scoped to the open task's lines, and names the sibling tools (price_intel_lookup, twelfth_compare_pricing_skus) it is distinct from. An agent can pick it apart from alternatives 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?

Explicitly says when to use it ('only for a competitor question about those lines') and when to prefer alternatives ('for tracked competitor prices across the range use price_intel_lookup or twelfth_compare_pricing_skus'). Both the inclusion and the exclusion conditions are provided.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description still adds real behavioral context: it reads current recommendations only and returns no raw measures, which tells the agent what it will and will not get back. It does not, however, discuss latency, auth scoping, or how deep the provenance chain goes.

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, zero padding, with the core purpose front-loaded and the negative scope plus alternatives trailing in the order an agent needs them. 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?

An output schema exists, so return-value shape need not be explained, and the description correctly focuses on scope limits, the current-vs-past distinction, and sibling routing. For a two-parameter read tool with full schema coverage and annotations, nothing needed to call 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%, so the baseline is 3, and the description goes slightly beyond by framing both parameters as 'a named product or supplier', reinforcing that entity_type is the supplier/product discriminator and entity_name is the free-form lookup key. It does not add format or matching-caveat detail, but the schema already handles the enum semantics.

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 precise verb+resource: reading the rationale, supporting facts, rule meaning and provenance behind current recommendations for a product or supplier. It explicitly contrasts itself with get_entity_profile (raw measures) and recall_decisions (past decisions), so an agent can distinguish it from siblings 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 the exact trigger (why-this-quantity / why-this-price questions) and names two alternatives with the conditions that select them (raw measures -> get_entity_profile, past decisions -> recall_decisions). Both the when-to-use and the routing away are 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 readOnly/idempotent/closed-world, so the safety profile is covered. The description adds real value by disclosing the data domain covered (rows, commercial measures, evidence) and the key constraint that results are limited to the open task, though it says nothing about result size or entity-match fallback 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?

Front-loaded with the core action, and every clause is functional. The single long sentence packing five sibling alternatives is dense but each clause earns its place by preventing misuse.

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, return values need not be described, and the description covers purpose, prerequisites (open task) and alternatives. The remaining gap is the 'brand' vs entity_type enum mismatch, which could lead an agent to pass an unmatched type value.

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 baseline is 3. The description does not explain entity_name matching beyond the schema's 'exactly as the user wrote it', and it introduces 'brand' as a target kind while the entity_type enum only lists supplier, category and product — a small ambiguity the description leaves unresolved.

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 and resource: 'Read every measure the open task holds for one named product, brand, supplier or category'. It enumerates what is returned (product rows, commercial measures, evidence) and scopes it to the open task, which separates it from catalogue-wide 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?

Explicit routing guidance: 'Use it first when a question names something', then names three concrete alternatives with their conditions (get_sales_metrics for sales, get_inventory_position for stock, get_product_master for price/cost/lifecycle), plus get_entity_context for rationale and search_catalogue for out-of-task lookups.

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, closed-world behavior, so the safety profile is covered. The description adds real behavioral context that annotations cannot: results are per line of the open task, with no outlet-level breakdown and no aggregation, which tells the agent exactly what granularity to expect.

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

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

Three sentences, front-loaded with what is read and its scope before the exclusions and alternatives. Dense but every clause carries routing or scoping information; the alternative-routing clause is long but functional.

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 explanation is unnecessary; params are fully documented in the schema; annotations cover safety. What remains — scope, granularity, and sibling routing — is fully addressed in the description.

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 three parameters (category, entity_name, supplier_name) are already documented, including the supplier matching rule and the 'lines beyond visible' note. The description mentions neither parameter nor adds syntax or scoping hints beyond what the schema states, 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 ('Read stock on hand and cover per product') plus the exact scope ('across the lines in the open task'), then immediately bounds it with 'No outlet split and no aggregation.' An agent can distinguish it from get_entity_profile and twelfth_list_products 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?

Explicitly routes between alternatives: this tool for stock/cover across the open task's lines, get_entity_profile for one named product, twelfth_list_products for the whole range sorted by stock or cover. Both the positive condition and the two exclusions 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds meaningful content-type disclosure: it returns principles rather than workspace figures. It does not mention latency or any limits, but for a static playbook lookup 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?

Three tightly packed sentences: purpose first, usage second, a return-content caveat with sibling routing third. No filler and 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?

With an output schema present and full parameter coverage, the description does everything an agent needs: identifies the operation, says when to call it, and clarifies the kind of content returned so it isn't confused with numeric-data tools.

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

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

Schema coverage is 100% and the topic parameter already carries its own description with an example. The description reinforces the same situation-based phrasing but adds no syntax, format, or constraint 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?

Specific verb (retrieve) plus resource (category-management playbook principles) with concrete triggering examples like supply disruption, slow sales, and pricing. It explicitly distinguishes itself from get_entity_profile and twelfth_list_products by stating it returns principles rather than figures.

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?

States when to invoke ('gravity advice in the methodology after reading the data') and where to go instead for workspace figures, naming the two sibling tools. Both the use condition and the exclusion are 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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without description help. The description adds only the returned identity fields (id, source, revision) and the one-remit scope — useful, but nothing about scoring, pagination or limits beyond 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?

Two tight clauses front-load the read scope and follow with concrete use cases and the downstream call, with no redundant restatement of the title or schema.

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

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

With annotations supplying the safety profile, a full schema and an output schema covering return shape, the description need only justify existence and usage — which it does. Minor gap: it does not say whether results can be empty because bookKey was left blank or whether the window caps result size.

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%: type enum, bookKey remit key, and the YYYY-MM-DD starts/ends bounds are all documented in the schema. The description's 'one remit in a date window' and 'named season into dates' reinforce but do not extend those semantics, 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 (read) and resource (trading, promotion or custom calendar entries) plus the scope (one remit, a date window) and even the fields returned (id, source, revision). It also names the enum values, so the agent can distinguish this from catalogue, product, sales or document siblings 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 use cases — key dates, promotions, holidays, trading periods — and an explicit sequencing rule: resolve a named season into dates before calling recall_decisions. There is no explicit when-not or alternative-calendar tool, but the intended context is unambiguous.

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/closed-world, so the bar is lower, yet the description still adds real behavior: results are limited to lines in the open task, filters combine with AND, and a not-found result is not proof the product is unstocked. Only missing piece is anything about result size or visibility beyond the supplier count note.

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 payload (which fields) and scope (open task lines) in the first clause, then routing, then the caveat. Every sentence carries distinct information; nothing is repeated from the schema 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?

Output schema exists so return values need no explanation, annotations cover safety, and the description supplies the scoping constraint, filter semantics, routing alternatives and the false-negative caveat. Nothing an agent needs to invoke it 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 category, entity_name and supplier_name are already documented, including the supplier matching rule and the note about lines beyond the visible ones. The description only adds the AND-combination semantics across filters, which is the baseline 3 for full schema coverage.

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: reads price, cost, margin and lifecycle fields, scoped to 'lines in the open task'. It also explicitly names the siblings covering adjacent data (get_sales_metrics, get_inventory_position, get_entity_profile), so an agent can route 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 both when-to-use and when-not-to-use: sales goes to get_sales_metrics, stock to get_inventory_position, all measures on one product to get_entity_profile. It also adds a negative-result rule: check search_catalogue before declaring a product missing, which is exactly the kind of guidance an agent needs.

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 semantics, and the description adds genuinely new behavior: results are ordered highest first, and an unfiltered call is refused, which warns the agent away from a guaranteed error. It does not discuss result limits, pagination, or what the refusal looks like, so it stops short of full behavioral 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?

Three tight sentences: what it does, why you'd use it, then the constraint and the fallback. The critical scoping rule and the alternative are front-loaded 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?

An output schema exists, so return values needn't be explained, and the description covers purpose, ordering, refusal behavior, and the correct alternative. The only gap is not spelling out the category-versus-entity_name relationship given that both parameters are optional 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, but the description adds real semantics: ranking is scoped to exactly one named group, and despite zero required parameters an unfiltered call will be rejected, effectively mandating a category or supplier filter. Minor residual ambiguity about whether category and entity_name can be combined, and the word 'supplier' versus the schema's 'entity_name'.

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 plus scope: ranking the open task's lines within one named category or supplier by revenue or units, highest first. It is immediately distinguishable from the sibling twelfth_list_products, which it explicitly names as the different 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?

Gives an explicit use case (compare rate of sale within a group), an explicit exclusion (it refuses an unfiltered ranking), and an explicit alternative with the exact sort key to use instead (twelfth_list_products sorted by units_l4w). Nothing about tool selection is left to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds that it reflects the project 'as it stands' (a point-in-time snapshot), but does not cover permissions or pagination/activity-window limits. It also largely restates the returned field set that the output schema already defines.

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, zero filler, with the read scope front-loaded and the id-discovery hint placed last where it is needed. 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 single-parameter read tool with rich annotations and an output schema, the description supplies everything an agent needs: what it returns, when to use it, and where the required id comes from. 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?

Schema coverage is 100% and the single parameter is fully documented in the schema (uuid, sourced from THIS PROJECT or a project link). The description adds only the pointer to twelfth_list_projects for discovering an id, which is marginal value over the structured field.

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 (read) and resource (one project) and enumerates what the read exposes: workflow stage, scope, owner, open tasks, documents, artefacts and recent activity. It also names the sibling twelfth_list_projects as the way to obtain an id, so the agent can separate it from list-style 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 states the use case ('where a piece of work is up to and who holds it') and routes the agent to twelfth_list_projects when only an id is needed. The alternative and the condition that selects it are both named.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so safety behavior is covered. The description adds the important output-shape trait (one precomputed figure per product, no time series or aggregate total), which genuinely prevents misfires. It says nothing further about how the filters widen or narrow the result set, so it stops short of full behavioral disclosure.

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

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

Three sentences, zero waste. What it returns is front-loaded, the limitation follows, and the routing alternatives come last in the position an agent reads while deciding. 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?

With an output schema, full param descriptions and safety annotations, the description only needs to cover scope and routing, which it does well. The one gap is that it never says whether entity_name/category broaden or merely narrow the 'open task lines' population, leaving a small ambiguity for a contrarian-sounding filter combination.

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 both parameters carry their own descriptions, so the schema does the heavy lifting. The description adds only indirect semantic context ('lines in the open task' as the default population), and does not clarify how category or entity_name interact with that scope. 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 (read) and resources (revenue, units, margin per product) and pins the scope to 'the lines in the open task'. It also states what the tool is not (no date series, period comparison or whole-business total), which separates it from the richer entity-level 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?

Explicitly names the use case ('compare sales across those lines') and routes two alternative needs to named siblings: get_entity_profile for all measures on one product/brand/supplier, twelfth_list_products for products outside the open lines. Both condition and destination are given, nothing left to inference.

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

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

Annotations already declare safe read-only, idempotent, closed-world behavior, so the description need not repeat them. It adds a genuinely non-obvious semantic caveat: a missing field means the task does not carry the measure, not that the supplier has none. It doesn't discuss rate limits or truncation behavior beyond what the parameter schema already says.

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

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

Three sentences, front-loaded with what it returns, then the caveat, then the use-case and routing. Every clause carries information; nothing is repeated from the schema 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?

An output schema exists, so return values need no prose. Annotations cover the safety profile, all three parameters are documented at 100% coverage, and the description adds the one thing structured fields cannot: the missing-field interpretation and sibling routing. Nothing an agent needs to call this 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 baseline is 3. The description goes beyond it by tying include_stock_value to the 'inventory-capital question' framing and by clarifying that rows carry stock measures either way, which tells an agent the flag is semantic rather than purely functional.

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 (read) and resource (a named supplier's lines in the open task, or every line), then enumerates exactly what each row carries: lead time, carton quantity, on order, stock on hand, cost and margin. This is concrete enough that an agent can distinguish it from every other get_* and find_* sibling 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 the questions it answers (lead-time, pack-size, inventory-capital) and explicitly routes to alternatives: find_supplier to resolve a name, compare_supplier_offer_history for changes in offers. Both the when-to-use and the when-to-use-something-else 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 readOnly, idempotent, non-destructive, and not open-world, so the safety profile is covered. The description adds behavioral context beyond that: the per-page character cap, that page count is returned, and that the document must be shared with the workspace. It does not discuss errors or rate limits, but the additions are substantive.

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, front-loaded with the operation and its size cap, followed by usage and the sibling alternative. No filler or restatement of the tool name.

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

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

An output schema exists, so return values need no explanation, and the description still supplies the character cap, page-count behavior, id provenance, and the routing to search_docs. Nothing needed 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 page parameter already documents its 1-based default, so the schema carries the parameter burden. The description echoes the single-page/character-cap semantics and flags that documentId comes from list_documents, adding marginal but not decisive value beyond the schema.

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

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

States a specific verb (read) and resource (one page of a shared document) plus the scope cap (up to 24,000 characters) and that page count is returned. The description immediately distinguishes this from search_docs and from the generic Twelfth-help 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?

Explicitly says when to use it ('when the answer is in a shared sheet or doc'), where to obtain the required id ('from list_documents (or a project's documents in get_project)'), and names the alternative for a different need ('to find how Twelfth itself works use search_docs instead').

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's added value is in edge behavior: ids each come back matched or in not_found, overly broad identifier sets fail explicitly, and ids must be used alone rather than combined with other filters. It does not say how many rows a broad query returns by default or anything about the response envelope, 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?

Four sentences, each load-bearing: scope, trigger, bulk-resolve mode, and sibling routing. The primary purpose is front-loaded and the density never becomes noise because each clause carries a distinct operational constraint.

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-parameter search tool with full schema coverage, an output schema, and complete annotations, the description supplies exactly what the structured fields cannot: selection guidance, the ids-alone constraint, and the explicit-failure behavior. 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%, so 3 is the floor, but the description genuinely adds semantics on top: the identifiers list is capped at 100 and resolves per-item with a not_found bucket, and the failure mode for overly broad identifier sets is called out. It does not re-explain query, supplier_id, or order_by, correctly leaving those 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 (search) plus the resource and its exact scope (every product in the workspace's readable catalogue), then enumerates the filter axes: text, supplier, category, open recommendation. It names the sibling it is not (twelfth_list_products for figures, find_supplier for name resolution), so it is distinguishable 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?

Gives an explicit trigger: "Use it whenever a product, brand, barcode or supplier is named and you need to know whether and where it is stocked." It also routes to alternatives with conditions — twelfth_list_products for figures, find_supplier first when resolving an exact supplier name — and explains the bulk-resolve mode versus the broad-mode failure.

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 openWorldHint=false, so the safety profile is covered. The description adds genuine context beyond that: results include links, and an empty result signals corpus coverage rather than product capability. It stops short of describing ranking or relevance behavior, 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?

Four short sentences, each carrying distinct information: what it does, when to call it, how to interpret empty results, and which sibling to use instead. Nothing is redundant or padded.

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

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

An output schema exists, so return-value detail is not required in the description, and annotations cover the safety profile. Given that, the description delivers everything an agent needs: purpose, trigger condition, result interpretation, and sibling routing.

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 both parameters are documented in the schema, including the plain-language framing of query and the 1-10 bound on limit. The description adds no parameter-level detail beyond what the schema already supplies, 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 (search), a specific resource (Twelfth's product documentation), the scope (how a page, control or setting works) and the return shape (matching sections with links). It also names the sibling it is not, read_document, so an agent can route correctly without opening either 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 explicit when-to-use guidance ("Use it before saying Twelfth cannot do something") and an explicit alternative with its selecting condition ("For documents the workspace shared use read_document"). It even pre-empts misreading of negative results, which is unusually actionable.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), but the description adds real behavioral context: organization scope returns managed chat runtime policy and available models, but only for staff with workspace owner/admin access, and write access depends on 'Allow changes'. It stops short of describing return shape, 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?

Front-loaded with the core action, then progressively adds scope behavior, alternatives, and auth caveats; every sentence carries information. Slightly dense with parenthetical tool references, but nothing is wasted.

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

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

For a single-enum, read-only tool with an output schema, the description covers purpose, scope semantics, permission gating, and sibling alternatives. Nothing needed to select or 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 enum values are documented in the schema, so the baseline is 3. The description goes further by explaining what each scope yields and the access rule ('A workspace key can read organization only'), which adds meaning beyond the schema text.

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 stored preference values and the keys this connection may read') and immediately bounds it to user/organization/membership scope. It explicitly separates itself from nearby siblings (integrations, category remits) by naming the tools that handle those.

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 when-to-use context ('defaults such as cover targets and display choices') and routes alternative needs explicitly: twelfth_update_agent_policy for runtime settings, twelfth_list_integration_guides / twelfth_list_category_settings for their domains, and OAuth connection for personal scopes. Both the positive and negative cases 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 declare readOnly, idempotent, non-destructive, non-open-world, so the safety profile is covered. The description adds genuine behavioral context beyond that: the recommended call ordering and the semantic reason (interpreting dates/currency in workspace terms). Return-format detail is legitimately omitted because 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 tight sentences, front-loaded with the resource and its fields, followed by the usage directive and the sibling pointer. No filler, 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?

For a zero-parameter, read-only context tool with a full output schema, the definition supplies everything an agent needs: what it returns, when to call it, and which sibling to use for people. Nothing material is missing.

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

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

The tool takes zero parameters, so per the rubric baseline is 4. The enumerated fields in the description describe the response payload rather than inputs, which is useful orientation but not a parameter-semantics contribution.

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 (Get) and resource (the connected workspace) and enumerates the returned fields (name, slug, timezone, currency, country). It also explicitly carves out the sibling twelfth_list_workspace_members for the 'people' case, so an agent can distinguish it from adjacent tools 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 an explicit ordering directive ('Call it first') with the reason (dates and money read in the workspace's own terms), and names the alternative tool for a different need. Both when-to-use and the sibling routing are 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?

Annotations already declare readOnly, idempotent, non-destructive, closed-world, but the description adds value beyond them: results are narrowed to the connection's readable remits (authorization scoping), pagination shape is 50 per page with total and hasMore, and category changes require owner/admin in the app. It does not state rate limits or ordering guarantees, so it is strong rather than exhaustive.

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 what is read and how it is scoped, followed by usage and a permission caveat; every sentence carries information. It is slightly dense and the '50 per page' detail duplicates the schema's default, but nothing is wasted.

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

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

An output schema exists, so return values need not be explained, yet the description still flags total/hasMore pagination, authorization scoping, and the owner/admin boundary for mutations. For a zero-required-parameter read tool, 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 limit/offset/query are already documented in the schema; that sets the baseline at 3. The description only lightly reinforces this by explaining that query finds a single category by name or alias, adding little beyond the schema's own matching rules (label, key, aliases).

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 (Read) and resource (managed categories, aliases, remit ownership) plus the scoping constraint (this connection's readable remits). It is clearly distinguishable from siblings like twelfth_list_products and twelfth_get_preferences, and it names the downstream tool that consumes category IDs.

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 usage: map category names, find category IDs for twelfth_list_products filters, and use query to locate one category by name or alias. It also notes that changing categories is owner/admin-only, which clarifies the boundary of what this read tool can do. It stops short of stating when NOT to use it or naming a true alternative listing tool.

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

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

Annotations already declare readOnlyHint/idempotentHint/non-destructive, but the description adds value beyond them: it discloses that the tool will not initiate OAuth or mutate a connection, and it previews the return payload (connection status, provided data/chat capabilities, configuration URL). It stops short of describing pagination or field-level shape, which the output schema 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 tight sentences, front-loaded with what the tool returns, then the use case, then the negative guarantee plus alternative. Every clause earns its place with no 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 zero-parameter, read-only listing tool with an output schema present, the description covers purpose, usage, negative behavior, and routing to the sibling. An agent has everything needed to select and 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?

The tool takes no parameters, so per the rubric the baseline is 4; there is nothing for the description to clarify, and it correctly avoids inventing input semantics.

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 ('List integration guides') and immediately specifies the content of each entry: what is connected, what it provides, and the page to configure it. Explicitly names the sibling it is not (twelfth_get_preferences) for workspace defaults, so an agent can route 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 both when-to-use ('answer what is connected or how to connect something') and a hard when-not ('never starts OAuth or changes a connection'), plus the alternative for stored defaults. Nothing is left to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description still adds real value with the 100-item cap, the due-date ordering, connection-level visibility scoping, and the fields returned. The one gap is what happens beyond the 100 cap — no truncation or paging 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 sentences, zero filler, with scope and ordering front-loaded before the alternative-tool routing. Every clause carries information an 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 zero-parameter read tool with rich annotations and an output schema, the description covers scope, ordering, cap and differentiation adequately. The only missing piece is how to obtain results beyond the 100-item cap, which matters given the stated limit.

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

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

The schema has zero parameters, so there is nothing to disambiguate; baseline 4 applies. The description correctly implies no filtering arguments exist, but does not call out that filtering must be done client-side.

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 open actions') plus scope ('visible to this connection'), ordering ('soonest due first') and returned fields (assignee, remit, source). It explicitly distinguishes itself from twelfth_list_projects, so an agent can route correctly 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?

Gives an explicit use case ('what is due or overdue') and names the alternative tool for the contrasting case ('for project-level progress use twelfth_list_projects'). Both the when and the when-not 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds real behavioral context: paging semantics, that results are limited to remits the connection can read, and that unmeasured figures come back as null. This is meaningful disclosure beyond 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?

Front-loaded with the operation and the returned field set, followed by two short routing sentences. The first sentence is dense but every clause carries information; nothing is wasted.

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

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

With an output schema present and annotations covering safety, the description only needs to supply scope and routing, which it does. Adding filter dimensions or default paging behavior would complete it, but 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?

Schema description coverage is 100%, so every parameter is already documented in the schema; the description only adds a generic 'sorted or filtered' claim. Baseline 3 is appropriate since the description adds little executable detail beyond what the schema carries.

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 (page through) and resource (every product), and enumerates the returned measures (stock, velocity, cover, sales, GP%, price, supplier, category, finding count). It explicitly separates itself from search_catalogue, 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?

States the intended use case (figures across the whole range, sorted or filtered) and names the lighter alternative search_catalogue for name lookup. There is no explicit negative boundary (e.g. when to prefer get_inventory_position or get_product_ranking), but the routing advice 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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds one genuine behavioral nuance — results are scoped to what is 'visible to this connection' — but says nothing about result volume, ordering, or pagination for a list operation.

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

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

Two sentences, zero filler, with the scope and returned fields front-loaded and the routing rule in the second sentence. Every clause carries information an agent can act on.

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 restated, and the annotations cover the safety profile. With only two optional, fully documented parameters, the description supplies everything else needed: scope, purpose, and the sibling boundary.

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 the enum values and the default for 'state' and the cross-reference to twelfth_list_project_workflows for 'workflow'. The description adds no parameter semantics beyond that, 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 ('List the workspace's projects') plus the enrichment fields returned (workflow, stage, owner, open and overdue task counts). It also explicitly distinguishes itself from the single-project sibling get_project, so an agent can route without opening either 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 states the two intended uses ('find a project or see what is in flight') and names the alternative for the adjacent need ('for one project's tasks, documents and activity use get_project with its id'). This is explicit when-to-use plus an explicit alternative, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds useful content-level context about what is returned (stages, availability, per-workflow project counts) and clarifies this is per-workspace configuration data rather than live project records.

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: the first states the payload, the second routes usage. Nothing redundant, and 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 parameters needed, an output schema covering return values, and annotations covering safety/idempotency, the description supplies everything an agent needs to select and call this tool correctly.

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

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

The tool takes zero parameters, so schema coverage is complete by definition and there is nothing for the description to compensate for. Baseline 4 applies for a no-parameter tool.

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 project workflows this workspace offers') and immediately names the sibling it is distinct from ('for actual projects use twelfth_list_projects'). An agent can differentiate it from twelfth_list_projects and twelfth_get_workspace 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?

Gives an explicit use case ('explain what kinds of project exist') and an explicit exclusion with the alternative to use instead ('for actual projects use twelfth_list_projects'). Routing is unambiguous.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context beyond that: a result cap of 100 and the fields returned (email and role). It does not discuss pagination or auth requirements, but for a simple read-only list with an output schema, this is strong.

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 tightly written sentences. Purpose and result limit are front-loaded, followed immediately by routing advice. 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 parameterless read-only list with an output schema and complete safety annotations, the description supplies the missing context: the 100-person cap, the returned fields, and the correct sibling for a related question. Nothing an agent needs to select or call it correctly is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to clarify. Per the baseline for 0 params, a 4 is appropriate; the description correctly focuses on output scope instead.

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), resource (people in the connected workspace), scope (up to 100) and returned fields (email and role). It explicitly names the sibling tool (twelfth_list_open_actions) and the different question it answers, so an agent can distinguish 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?

Explicitly says when to use it (to resolve an owner or assignee by name) and when to use the alternative (twelfth_list_open_actions for what each person has open). No inference required.

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