wals.pro AI 4 weclapp

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, but the description adds substantial behavioral detail beyond that: the 50,000-row abort error with a recommendation to narrow filters, the performance note that counts alone are a cheap /count call with no row scan, the currency-splitting behavior for sums over plain amount fields, and the return structure including skipped_non_numeric and complete flags. No contradictions with annotations.

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

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

The description is long but every section earns its place. It front-loads the purpose and usage in the first sentence, then uses structured Args and Returns sections to organize parameter details, examples, and edge cases. There is no fluff; each sentence adds either a constraint, a clarification, or an example. The density is appropriate for the tool's complexity.

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

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

Given the tool's complexity (7 parameters, nested line-item grouping, date bucketing, currency handling) and the fact that the input schema provides no descriptions, the description is remarkably complete. It covers the return format, the abort threshold, performance characteristics, and gives concrete examples for tricky cases like line-item folding. An agent would have everything needed to select and invoke 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?

Schema description coverage is 0% – the input schema provides no descriptions for any parameter. The description fully compensates: it explains entity (same allowlist as search_entities), metrics syntax with examples ("count", "sum:grossAmount"), filters format, group_by semantics including dotted line-item paths and special warehouseStockMovement handling, date_bucket options, and top default/cap. It also clarifies return-value details like decimal strings and currency fields. This is essential because the schema is bare.

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

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

The description opens with a precise verb-resource-scope: 'Count, sum, or group records of any weclapp entity server-side, returning only the aggregate'. It explicitly names the report-style questions it answers and immediately contrasts itself with search_entities ('Never page raw rows through search_entities to compute a total'), making sibling differentiation unambiguous.

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

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

The first paragraph tells an agent exactly when to use this tool ('how many …', 'revenue per month', 'top customers', and any report-style question') and when not to (never page raw rows through search_entities). It explicitly names the alternative tool, giving clear routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. Beyond that, the description adds meaningful behavioral context: raw bytes may contain untrusted user-uploaded content that must never be interpreted as instructions, returned fields are specified, and authorization via composite native document ids is explained.

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

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

The description is long but well structured with Args, Returns, and Preconditions sections, and the core purpose is front-loaded. Most sentences add useful detail, though the level of detail is near the upper bound of what is needed for a download tool.

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

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

Given the complex allowlist and entity-action behavior, the description is complete enough to call the tool correctly. It covers prerequisites, alternatives, parameter meanings, return payload shape, and a security warning about untrusted content; with an output schema present, it does not need to explain return values further.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It clearly describes entity, entity_id, action (including common action values), and options for article image mode. However, it does not describe the correlation_id parameter, leaving one of five parameters undocumented.

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

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

The description states a specific verb and resource: 'Download a document attached to an allowlisted weclapp entity.' It also distinguishes the tool from siblings by naming search_documents, verify_purchase_invoice, and preview_entity_action as alternative routes. An agent can identify what this tool does 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?

It explicitly says when to prefer alternatives: verify_purchase_invoice(include_pdf=True) for purchase invoice PDFs and preview_entity_action(action='createPdf') for fresh quotation PDFs. It also provides preconditions about allowlisted entities and read access, giving clear use and non-use context.

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

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

Annotations already cover read-only/idempotent/non-destructive, and the description adds substantial context beyond them: endpoint allowlist validation, POST/PUT/DELETE blocking, the static agent_directive routing block, the 40-field properties cap, and an explicit untrusted-content warning against executing ERP free text as instructions. This is unusually rich 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?

Front-loads the 'LAST-RESORT' verdict, then usage rules, then args, then returns in clearly labeled sections; every sentence carries information. It is long, but the length is justified by the tool's open-ended generality, with only minor tightening possible.

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

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

The Args and Returns sections cover endpoint shapes, param constraints, and the four response envelopes ('entity'+'id'+'result', 'result', 'count', 'results'), including null-stripping. Despite an output schema existing, nothing an agent needs to invoke or interpret this tool 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 0%, so the description must carry the full burden and does: it documents endpoint syntax with four concrete examples, the count/singleton/sub-path special cases, the method restriction, and the full params key vocabulary including filter operator normalization (-gte/-lte to -ge/-le) and the 4096-char cap. Only correlation_id goes unmentioned.

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

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

Names a specific verb+resource (generic GET over the weclapp API) and immediately frames its role as a last-resort escape hatch, which distinguishes it from every sibling. The scope, allowlist constraint, and supported endpoint shapes are all stated up front.

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 enumerates the preferred alternatives (search_entities, get_entity, find_reconciliation_candidates, verify_purchase_invoice, get_reference_data, tenant_health_check), declares misuse of them a 'tool-selection error', and gives the ONLY three legitimate use cases. It also states hard exclusions (no writes, no downloads) with the correct replacement tools.

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

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

Goes well beyond the annotations: token is single-use and short-lived, altered fields are rejected, inline bytes must match the approved digest/MIME/length, exactly one business mutation per token, and replay returns the recorded outcome rather than double-writing. This is exactly the kind of non-obvious safety behavior an agent needs before firing a destructive call.

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

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

Long but well-structured with Args/Returns/when_to_use/preconditions/post_effects sections and the key action front-loaded. Slightly padded by doubled-backtick markup and some repetition of the digest/field-unchanged rule across Args and preconditions.

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 destructive, token-bound mutation with no schema-level parameter documentation, the description supplies the full contract: sequencing, token semantics, payload shape, upload rules, failure modes, and idempotency behavior. An output schema exists, so the brief Returns note is sufficient.

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 0%, so the description carries the burden, and it does for three of four params: approval_token provenance, the whole execution.payload object including wrapper keys, and the file/native-upload digest requirement. The fourth parameter, correlation_id, is never mentioned anywhere, leaving a small gap.

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

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

States a specific verb and resource ('Execute a previewed entity write or workflow action') and immediately positions itself as 'the single second step' after any preview_* tool, which cleanly separates it from the many preview_* 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 when_to_use ('after a successful preview_* call'), explicit preconditions (valid unconsumed token from the same connection, approved fields unchanged), and a named alternative workflow (run preview_* first). 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 readOnlyHint, idempotentHint and openWorldHint, yet the description still adds genuine behavioral context: the Berlin-timezone boundary semantics for date_to, the scoring thresholds (auto_apply >= 80, review_recommended >= 60), the fact that include_scores is compatibility-only and anchor mode always scores, and the warning that bank transaction descriptions are untrusted ERP text.

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 one-line purpose, then cleanly sectioned into when-to-use, args, and returns; each line is functional. It is long, but the length is driven by 16 parameters and five modes rather than padding, and only the tail-end schema pointer feels slightly expendable.

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?

Despite an output schema existing, the description usefully summarizes the returned keys per mode and explains the score payload, so an agent knows what it is getting. Combined with the mode routing and the untrusted-text caution, nothing needed to invoke this 16-parameter tool 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?

With 16 parameters at 0% schema description coverage, the description carries the load and does so well for most: side, candidate_kind, invoice_id/contract_id, date range, amount bounds, text_search, party_id, include_scores and limit all get meaning beyond their names. It falls short only on a few (correlation_id is never mentioned, and mode/open_item_id/bank_transaction_id are defined only indirectly via the mode descriptions rather than as named arguments).

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) plus two concrete resources (payment candidates, invoice-to-contract match) and names the downstream sibling preview_entity_action as the next step. An agent can distinguish this from search_entities or verify_purchase_invoice 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?

The 'When to use' block enumerates each operating mode (status, anchor, filter, contract-cost) with the exact parameters that select it, tells the agent to start in status mode and then pick a pair, and links to the follow-up action. Explicit routing with no inference required.

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, but the description adds substantial context beyond them: 5-minute caching per tenant credential, the fact that all writes are attributed to this user (e.g. comment.authorUserId), and a prompt-injection warning that profile strings are untrusted ERP content. This is rich 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?

Front-loads the purpose in the first clause and is well organized, but the multi-line 'Returns' block enumerates dict fields that largely duplicate the available output schema, adding length without much marginal value.

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

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

Given an output schema exists, the description does not need to re-explain returns, yet it covers what the schema cannot: auth semantics, caching, write attribution, and security caveats. Nothing an agent needs in order to call this 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 description coverage is 0% and the single optional correlation_id parameter is never mentioned in the description, so it does not compensate for the coverage gap. However, it is one low-stakes optional plumbing parameter, so the omission is minor rather than damaging.

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: returns the weclapp user identity and system (Live/Demo) behind the connection's API key. It self-describes as 'whoami', and the sibling tools (execute_api, tenant_health_check, get_entity) make clear this is a distinct diagnostic 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 says when to use it ('check it before the first write') and routes the agent to an alternative for a related need ('For this user's upstream permission strings use tenant_health_check(include_permissions=True)'). This is a clear when-to-use plus named alternative.

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

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), and the description adds substantial context beyond them: the untrusted-content warning, the payload-size tradeoff of properties, the note that open-item existence stays unverified, and the rule that view='completion' owns its projection with no property/include overrides. That last point is a genuinely useful behavioral constraint. It stops short of 5 only because the untrusted-content warning is asserted without saying how the caller should treat it.

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 purpose and usage trigger, then progressively discloses optional features. It is long, but nearly every sentence carries operative information; the density is justified by nine parameters and three view modes.

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

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

An output schema exists, so return values need not be described, and the description nonetheless covers the non-obvious return shapes (quality report contents, contact_persons, referenced_entities, translations completeness). For a complex multi-parameter read tool this is complete enough to invoke correctly.

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

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

Schema description coverage is 0%, so the description carries the full burden, and it does most of it: properties, view (three named modes with their accepted entities), view_options (locale, property_names, check_completeness, target_locales), include_quality, include_referenced_entities, additional_properties, and the document-number alias for entity_id. correlation_id and the entity selector are left unexplained, which keeps this below 5.

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

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

States a specific verb and resource ('Get one weclapp entity by id') and explicitly distinguishes itself from the sibling search_entities, both as a downstream consumer of its results and as the fallback for document-number lookups. An agent can pick this tool 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 explicit trigger conditions ('after search_entities identifies an id or when the user supplies the id') and names an alternative path ('use search_entities(query=<number>)') for the invoice open-item case. When-to-use and the exception are both 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 provide readOnlyHint, idempotentHint, and destructiveHint, so the description does not need to restate safety. It adds useful behavioral context beyond annotations: results are limited to 'reviewed v2 entity actions' and 'explicitly marked guarded MCP workflows,' and limit is 'capped by the global read limit.' This clarifies scope and constraints without contradicting the annotations.

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

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

The description is well-structured and economical: a one-line purpose, a focused sentence on how to narrow to a single contract, a compact Args list, and a short Returns summary. No sentence is wasted, and the most important purpose information 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?

Given that the tool has an output schema and annotations covering read-only/idempotent behavior, the description is largely complete: it explains filtering, return contents, and the global read limit. The main gap is the undocumented correlation_id parameter and the absence of any pointer to sibling tools for related operations, but these are minor given the output schema and the description's clarity.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It does so well for most parameters: entity is an 'exact weclapp entity name,' action is 'exact case-sensitive,' method applies 'when a path supports multiple methods,' and offset/limit semantics are stated. However, correlation_id is not described, leaving one parameter unexplained.

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

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

The description opens with a specific verb and resource: 'List reviewed v2 entity actions and explicitly marked guarded MCP workflows.' This clearly identifies the tool as a catalog/lookup operation and distinguishes it from siblings like execute_api or preview_entity_action by focusing on listing contracts rather than executing or previewing them.

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

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

The description implies when to use the tool—when you need an action contract with availability, payload fields, risk, and guarded next tool—but it does not explicitly contrast it with alternatives such as preview_entity_action, execute_api, or get_schema. The guidance is practical for filtering results but stops short of explicit when-to-use vs. when-not-to-use direction.

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 cover safety (readOnly, idempotent, non-destructive), but the description adds behavior they cannot convey: ~10-minute caching, fail-closed handling of unknown types, static enums returned without a weclapp round-trip, per-mode limit defaults (100 / 20 / 300), and the shape of the salesBundle response.

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 purpose before the Args/Returns breakdown, and nearly every sentence adds operational detail. It is long and the allowlist enumeration plus nested parentheticals make it dense, but the length is defensible for a polymorphic tool with five parameters and zero schema coverage.

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, yet the description still sketches the return shape ("results", resource_uri, per-collection keys, tenant_defaults, notes), which helps the agent plan downstream calls. Given the polymorphic reference_type and 0% schema coverage, the behavioral and routing detail is complete apart from correlation_id.

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

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

Schema description coverage is 0%, so the description carries full burden and largely delivers: reference_type gets an allowlist, examples, and per-value caveats; limit gets mode-specific defaults; entity gets a usage restriction; name gets a case-insensitive 'contains' semantic. The gap is correlation_id, which is never mentioned anywhere.

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 (fetch) and resource (reference entity collection) and explicitly scopes the two modes: single type vs. the combined salesBundle. It also distinguishes itself from siblings, telling the agent that get_acting_identity serves the identity case and get_schema('party') serves partyRating.

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 downstream purpose ("supplies the IDs to plug into quotation / party / task payloads") and gives explicit alternatives with conditions: use get_acting_identity for the acting identity, get_schema for partyRating, and follow with get_schema(entity) and preview_write_entity for payload building. 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 cover the safety profile (readOnly/idempotent/non-destructive), and the description adds substantially more: warehouse_id scopes stock figures only, limit is clamped and one page is scanned, scanTruncated means partial scope coverage, demandTruncated means incomplete history that must never be presented as a complete forecast, and ERP free text is untrusted content to be ignored as instructions.

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 summary followed by clean Args/Returns sections; the length is justified by 12 parameters and the truncation caveats. The heavy markup noise (``...``) and dense inline lists cost a point but little is truly wasted.

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

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

For a complex, 12-parameter, paginated read tool, the description covers scope, defaults, truncation semantics, actionable guidance on what to do when truncated, and the downstream write path. Presence of an output schema doesn't remove the need for the interpretive guidance it provides.

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

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

Schema description coverage is 0%, so the description carries the full burden; it documents 11 of 12 parameters, including ilike semantics for article_number_pattern, the warehouse scoping caveat, and per-article call cost for include_supplier. Only correlation_id is left unexplained and the limit clamp has no stated range.

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 opening sentence states a specific verb and resource ('return one decision-ready disposition record per article in a scope') and the body enumerates exactly what the record contains (stock, on-order, demand, reorder params, supplier, baseline quantity). An agent can distinguish this clearly from generic siblings like get_entity or search_entities.

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?

'One call for reorder proposals' plus the explicit downstream workflow (apply tenant rules from read_settings domain "sops", then feed lines to preview_write_entity) tells the agent where this fits. It gives no explicit exclusion or named alternative sibling, so it falls short of a 5.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so safety is covered. The description adds genuine context beyond that: what each returned section contains (write_contract feeds preview_write_entity, live lists filter/sort fields) and how the detail/query modes change the response. This cross-tool relational detail is real added value.

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

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

The purpose is front-loaded and most sentences carry real information, but the prose is dense and the trailing 'Args: route: one key of payload_guide routes.' line is fragmentary and awkwardly placed. It reads as terse internal documentation rather than a clean, well-structured summary.

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 explanation. The description supplies mode selection, section meanings, and the query fallback for unknown entities. Only correlation_id and any deeper payload structure are left uncovered, a minor gap for a read-only schema-inspection tool.

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

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

With 0% schema description coverage across 6 parameters, the description must carry the load, and it does for most: entity ('exact API entity'), detail (payload_guide/import_guide), query+limit (candidate listing when name unknown), and route ('one key of payload_guide routes'). Only correlation_id is left unexplained, so it nearly compensates for the coverage gap.

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

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

The opening sentence states a specific verb and resource: 'Return the writable allowlist and queryable schema for one entity.' This distinguishes it functionally from siblings like get_entity and get_reference_data. It stops short of explicitly naming an alternative tool, keeping it at 4 rather than 5.

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

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

The description clearly explains which mode applies to which situation: default for openapi/live/write_contract/entity_actions, detail='payload_guide' for the workflow cheat sheet, detail='import_guide' for CSV specs, and query= without entity for unknown names. It gives strong operational context but does not state when to reach for this tool versus a sibling like get_entity.

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, but the description adds context beyond them: preconditions ('Live status and received/shipped/invoiced guards; processed records get no token'), post_effects ('No mutation; after the user explicitly confirms, execute_approved'), token-issuing semantics, and payload key-dropping behavior (dropped_fields vs domain-action rejection). This materially informs agent behavior.

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

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

Front-loads the purpose, but the body is a dense, unformatted stream of dotted pseudo-keys (when_to_use:, preconditions:, post_effects:) and a long action matrix that partly duplicates what get_entity_action_catalog returns. Much of it earns its place as reference, but the structure is scattershot and heavier than needed for a routing decision.

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

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

Given the multi-action branching, an output schema exists so return-value detail is not required, and the description still notes 'approval + execution, or ready_for_* false with diagnostics.' It covers preconditions, post-effects and hand-off, though full payload contracts for domain actions live in a separate catalog tool.

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

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

Schema coverage is 0%, so the description must carry the load, and it documents entity, action, entity_id (including when to omit it) and payload with concrete JSON examples for several actions. It defers full payload schemas to get_entity_action_catalog and never mentions correlation_id, so it is strong but not exhaustive.

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 and effect: 'Preview a weclapp workflow ACTION on one entity; return an approval token.' The enumerated action matrix (purchaseOrder.confirm, salesOrder createShipment, etc.) makes the scope concrete. It does not explicitly name or differentiate from close siblings like preview_write_entity, preview_stock_operation, or preview_escalate_to_support, so it falls short of the top mark.

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

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

Provides explicit when-to-use ('First step of a workflow or domain action'), a clear hand-off to execute_approved, and named alternatives with selecting conditions ('createIncomingGoods is refused... book via purchaseOrder.bookIncomingGoods', 'purchaseOrder.manuallyClose requires CONFIRMED'). The routing information is actionable rather than implied.

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

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

Annotations declare readOnlyHint=true and non-destructive/idempotent, but the description adds what annotations cannot: server redaction applies, preview equals exactly what is sent, a hard rate limit (max 10/day), a 'never invent' fact policy, and a post-effect that is only a token requiring explicit user confirmation. This is unusually rich 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?

Front-loaded with the core action, then sectioned into when_to_use / Args / preconditions / post_effects. Dense but every line is operative for a 15-parameter, consent-gated tool; no filler.

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

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

For a 15-param, open-world escalation tool with an output schema present, the description supplies the missing schema docs, the consent workflow, the rate limit, and the token/execute handoff. An agent has everything needed to call it correctly and safely.

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 0%, so the description carries the full burden, and it does: max lengths (title 120, description 2000, summary 500), per-kind category enums, ISO 8601 with 'never invented', 1–10 steps_already_tried, max 10 example_records, max 5 hypotheses, host-constrained weclapp_url, and server-resolved support_target. Only correlation_id goes undocumented, which is a minor omission against otherwise exhaustive 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?

The first sentence gives a precise verb+resource+output: 'Preview a customer-confirmed platform or partner ticket and issue an approval token.' It is immediately distinguishable from sibling previewers (preview_write_entity, preview_stock_operation) and from execute_approved, which it names as the follow-up step.

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 (support or feature wishes, offer proactively), explicit consent requirement ('show the full preview... get explicit consent first'), explicit preconditions, and an explicit next action (execute_approved(approval.token, execution.payload) after user confirmation). 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?

Beyond the readOnlyHint, idempotentHint, and destructiveHint annotations, the description discloses post-effects ('no ERP mutation') and the token-drift behavior ('the token binds the plan and live stock baseline — drift forces a fresh preview'). It also states the return shape ('plan + approval + execution, or diagnostics') even 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?

The description is long but justified for a complex 21-parameter operation. It is front-loaded with purpose and per-operation parameter rules, then moves through args, returns, when-to-use, preconditions, and post-effects in a scannable structure.

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?

Despite an output schema and annotations already covering safety, the description adds operational context an agent needs: preconditions, post-effects, token staleness behavior, and pointers to related tools. Nothing material for correct invocation appears 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?

With 21 parameters and 0% schema description coverage, the description compensates thoroughly by documenting per-operation required parameters, their conditional fields, and when to omit fields such as quantity for serial-tracked articles. It explains foreign parameter rejection and routes to get_schema for full payload 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?

The description states a specific verb and scope: 'Preview warehouse stock movements, transport orders and internal deliveries, issuing one approval token.' It clearly distinguishes this preview tool from the downstream execute_approved action and from adjacent preview 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?

It gives explicit when_to_use scenarios (corrections, found/lost stock, scrapping, seeding, relocations, inter-warehouse deliveries) and the routing condition: after explicit user confirmation, use execute_approved. It also names alternatives for receipts and customer shipments, so the agent can select the right tool 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/idempotentHint/destructiveHint, but the description adds real value beyond them: single-use token semantics, 'no upload' post-effect, update-access precondition, inline size cap ~1.5 MB, batch 2-10 targets at 20 MB, and status-only intent refs. The only soft spot is that a chunk of text describes the downstream execute_approved call rather than this tool's own 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?

Purpose is front-loaded and the Args/preconditions/post_effects/guarded-routes structure is scannable, but the description is heavy and contains terse fragments ('Keep approved fields unchanged; add matching bytes INSIDE payload', 'No separate base64 parameter or file') that cost clarity rather than earning their 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 14-parameter tool with zero schema coverage, the description covers the vast majority of parameters, preconditions, size limits and transport branches, and an output schema exists so return values need not be re-explained. Minor gaps remain around correlation_id and the file object.

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

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

Schema description coverage is 0% across 14 parameters, so the description must carry the load, and it does: it documents entity_id, file_name, content_sha256, content_type, bytes, entity_name/entity_type alias, description, plus transport, upload_intent_ref, target and article_image through the guarded-routes section. Only correlation_id and the NativeFileInput 'file' object remain undocumented.

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 opening sentence gives a specific verb, resource and scope: 'Preview a document attachment to a weclapp record without upload.' It implicitly routes to execute_approved for the actual upload, but never explicitly contrasts itself with the sibling download_document or search_documents, so differentiation is only partial.

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

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

It gives concrete conditions: inline mode requires explicit user confirmation before calling execute_approved, preconditions state update access and record existence, and the guarded routes section explains which transport to pick (agent_upload vs agent_upload_batch) and when entity_id is absent. It stops short of naming an alternative tool to use instead of this one.

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, idempotentHint=true, openWorldHint=true. The description adds valuable context: 'No ERP mutation,' 'Single-use approval binds target and payload,' and the limitation 'Public conversion without mail is unsupported.' It also notes that replies inherit visibility, which is beyond the schema. These details complement the annotations without contradicting them.

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

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

The description is long but well-structured with clear sections (Args, Returns, when_to_use, preconditions, post_effects). Each parameter line provides necessary detail, and the main purpose is front-loaded. While it could be trimmed slightly, the density is justified given the tool's 14 parameters and complex behavior.

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 tool with 14 parameters, 1 required, and an output schema, the description covers all aspects: parameters, return values, preconditions, post-conditions, and execution flow. It also includes specific edge cases (e.g., 'Public ticket comments can send mail,' 'Public conversion without mail is unsupported'). Nothing critical for correct invocation is missing.

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

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

Schema description coverage is 0%, so the description must carry the full meaning of parameters. It does so comprehensively: each parameter is explained with aliases (e.g., 'alias content'), constraints (1–10000 chars), defaults, and usage rules (e.g., 'Omit for updates,' 'only internal/private updates'). This is exactly the compensation needed for the sparse schema.

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

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

The description opens with a precise verb+resource statement: 'Preview a new comment or an existing comment's visibility change.' This distinguishes it from other preview_* tools (e.g., preview_write_entity, preview_accept_quotation) by targeting comments specifically. The purpose is unambiguous.

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

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

The 'when_to_use' section explicitly says 'Before writing' and points to get_schema for guidance. It also explains the execution flow via execute_approved. However, it does not explicitly contrast with alternative preview tools or state when not to use it (e.g., for batch operations), though the comment-specific scope makes this largely implicit.

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

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

Annotations declare readOnlyHint/idempotent/non-destructive, and the description is consistent with a preview that produces a token rather than mutating. It adds substantial hidden behavior: AB-resend risk and confirmation-email consent, drift blocking on confirmation snapshots, dropped unlisted fields, read-only derived totals, and batch size limits.

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

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

Purpose is front-loaded, but the body is a dense telegraphic wall mixing conventions, guarded routes, and argument notes, with some duplication ('get_schema(entity, detail="payload_guide")' appears twice). Mostly information-dense, yet trimming and tighter grouping would improve scannability.

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

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

Given 12 parameters, 20+ entity types, nested payloads, and guarded write routes, the description covers the dangerous paths, date/epoch conventions, and the get_schema fallback; an output schema exists so return-shape detail (approval.token + execution or tokenless diagnostics) is a bonus rather than a gap.

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

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

Schema coverage is 0%, so the description must carry parameter meaning, and it largely does: entity's allowed values and routes, payload semantics (aliases folded, version required except article), resolve_quotation_recipient_email fails-closed, duplicate_decision/duplicate_candidate_ids, sop_snapshot_hash, and reconfirm/allow_automated_confirmation_email within guarded routes. delete, entity_id, and correlation_id are only implied and never explained.

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

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

States a specific verb+resource+outcome: preview create/update/delete and return an approval token. It also names the disambiguating sibling ('Ticket↔order links: preview_entity_action'), so an agent can separate this from preview_entity_action and the other preview_* tools 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 rich conditional guidance: guarded routes for order confirmation, party email, item arrays, and status transitions, plus the consent flags each requires. It routes ticket/order links to preview_entity_action, though it never states an explicit general 'when not to use this tool' rule.

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

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

Goes well beyond the annotations (readOnlyHint/idempotentHint/destructiveHint) by disclosing post_effects ('No mutation; issues a payload-bound approval token'), preconditions (article_id and, on update, supply_source_id must resolve), and non-obvious defaults (create defaults set_as_primary True, update False; the article's FIRST source is always forced primary). These are exactly the behavioral traits an agent cannot infer from structured fields.

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

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

Front-loaded purpose followed by clearly labeled Args/Returns/when_to_use/preconditions/post_effects blocks; nearly every line adds operational meaning. Minor waste: the Returns block partly duplicates the output schema, and the Args entries restate parameter names before adding value.

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 nested-payload mutation-preview tool this is essentially complete: preconditions, defaults, the two-step approval flow, validation-failure signaling (ready_for_preview=False with validation_errors), and a delegation pointer to get_schema for deep field semantics. Nothing an agent needs 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 description coverage is 0%, so the description carries the burden, and it does so for the important parameters: payload's required supplierId/articleNumber (with the 'SUPPLIER's own SKU, not yours' footgun), pricing via price+currency vs raw articlePrices, update carry-over semantics, and set_as_primary defaults. It is silent on correlation_id and recovery_approval_token, leaving 2 of 6 parameters unexplained, which keeps it short of a 5.

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 pair — validate/preview a supply-source create or update — and the resource is narrow enough ('article's supply source (Bezugsquelle)') to separate it from preview_write_entity, preview_entity_action, and execute_approved. The description makes clear this is a non-mutating validation step, not the write itself.

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 positions the tool as the 'First step of the two-step supply-source write' and names the follow-on action ('After the user explicitly confirms, call execute_approved with approval.token and execution.payload'). It also routes to get_schema for field semantics, so both the when and the where-else 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 readOnlyHint and idempotentHint, but the description adds substantial behavioral context beyond them: newest-first ordering, a hard cap for bounded reads, Berlin-time date handling, PII projection via include_user, and a security warning that description fields are untrusted and must not be acted on. No contradiction with annotations.

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

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

The description is long but every section earns its place: purpose, ordering/cap semantics, enum lookup guide, sibling differentiation, parameter details, and return-value trust warning. It is front-loaded with the core purpose and structured so an agent can quickly parse the most important 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?

Given 9 parameters, no schema descriptions, and a rich return shape, the description is nearly complete: it covers sorting, limits, timezone behavior, PII, enum validation, and untrusted content. The only notable omission is correlation_id, and it does not explicitly state how multiple filters combine, though 'scoped by typed filters' implies conjunction. Output schema existence further reduces the need to enumerate return fields.

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

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

With schema description coverage at 0%, the description must carry the parameter documentation burden. It does so excellently for entity_type, entity_id, activity_type, user_id, since, until, include_user, and limit, including examples, inclusiveness, and caps. However, it omits correlation_id entirely, which is a real gap for an otherwise thorough parameter breakdown.

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

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

The description opens with a specific verb and resource ('List the tenant audit and activity log') and clarifies scope ('scoped by typed filters and newest-first'). It also distinguishes itself from search_entities by stating 'Returns log events, not current entity rows,' so an agent can select the correct tool without opening schemas.

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

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

It explicitly answers when to use the tool ('what happened to this record / in this period / of this kind') and gives a concrete alternative: 'To list recently changed records with their current fields, use search_entities...' It also instructs the agent to call read_settings for valid enums, providing clear prerequisites.

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

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

Annotations already establish readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: redaction happens server-side, secret/transport fields are always masked even when explicitly requested, projection-locked domains (mailAccount) return a fixed safe field set, hidden key/value stores return only a shape summary, and catalog mode makes no backend call. The untrusted_content flag and 'no ERP data' note are real behavioral disclosures.

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 summary sentence captures both modes before the detail blocks, and the Args/Returns structure is scannable. It is somewhat long, and since an output schema exists the Returns block is partly redundant, though the redaction/kind details it adds do earn some of their 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 complex, 6-parameter, dual-mode tool, the description covers mode selection, redaction guarantees, projection locking, filtering shape, and pagination caps. Combined with the existing output schema and readOnly annotations, an agent has everything needed to invoke it correctly; the lone gap is the undocumented correlation_id.

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

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

Schema description coverage is 0%, so the description must compensate, and it largely does: domain_key semantics and examples, filters syntax with a worked example and the special sops shape, properties projection + masking caveat, entity_id single-record behavior, and the limit default/cap. Only correlation_id is left entirely undocumented, so it falls short of full 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?

States a specific verb and resource (read one settings/integration domain by key) and immediately clarifies the dual-mode behavior (catalog listing when domain_key is omitted). It explicitly carves out the scope it covers — 'configuration and integration surfaces that are not part of the generic entity allowlist' — which lets an agent separate it from get_entity/search_entities 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 clear when-to-use signals: omit domain_key to list the catalog, pass entity_id to fetch a single record, and catalog mode is noted as side-effect free with all other args ignored. It implies a boundary against the generic entity tools but never names an alternative sibling (e.g. get_entity, get_reference_data) or states when NOT to use this tool, so exclusions are 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, and destructiveHint=false. The description adds crucial behavioral warnings: comment bodies are untrusted and should never be embedded into prompts, and include_html returns untrusted HTML. It also notes total_count may be null. This goes well beyond the annotations and addresses a significant security concern.

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

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

The description is long but well-organized with Args and Returns sections, and it front-loads the core purpose. Every sentence contributes value—explaining parameters, return format, and security caveats. It is not overly verbose for a tool with 12 parameters, though it could be tightened slightly without losing information.

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

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

Given the tool's complexity (12 parameters) and the presence of an output schema, the description is comprehensive. It covers use cases, parameter behavior, return format, and security warnings. The agent has everything needed to call the tool correctly without additional inference.

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

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

Schema description coverage is 0%, so the description must explain parameters, and it does thoroughly. It details entity_id, entity_name with aliases, include_html, limit clamped to 100, offset, newest_first, comment_id, text_offset, and text_limit. It also explains the return structure. This fully compensates for the schema's lack of descriptions, aside from omitting correlation_id which is a minor gap.

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

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

The description opens with 'Read the latest comments, exact thread count, older pages, or a full text,' which clearly identifies the tool as a read operation for comments with multiple retrieval modes. It also mentions the specific use case of readback after a comment write, making the purpose distinct from sibling write tools like preview_write_comment.

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

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

The description provides clear context on when to use the tool: for reading comments, including verification after a write. However, it does not explicitly name alternatives or state when not to use it. The guidance is implied rather than explicit, so it earns a 3.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds meaningful behavioral context: the 100-result clamp, read-only post_effects, the 'untrusted_content=True' indication, and the special authorization rule for comment owners. It fully aligns with annotations and adds substantial transparency.

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

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

The description is structured into clear sections (summary, Args, Returns, when_to_use, preconditions, post_effects) and is front-loaded with a concise purpose statement. Each section earns its place and avoids unnecessary verbosity.

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

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

The description covers the action, prerequisites, output shape, security/auth context, and post-conditions. It even describes return fields and the id-to-feed relationship with download_document. For a tool with this complexity and an output schema, nothing essential 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 input schema has 0% description coverage, so the description must compensate. It does so for entity_id, entity_name, entity_type, and limit, including the allowed entity list and the clamp behavior. However, the correlation_id parameter is not covered, leaving one parameter semantically undocumented.

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

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

The description opens with a specific action and scope: 'List a weclapp record's document attachments (up to a 100 limit)'. This clearly distinguishes the tool from siblings like download_document and search_entities by identifying the exact resource and verb.

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

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

The description includes an explicit 'when_to_use' section: call before download_document because a document id is only obtainable by listing attachments, and call after an upload to confirm attachment. It also states preconditions such as read access and documentable entity requirements, giving clear guidance on when the tool is appropriate.

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

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

Annotations only cover the safe-read profile (readOnly, idempotent, openWorld), and the description adds substantial non-obvious behavior: Europe/Berlin day semantics with no Z suffix, half-open date ranges, view_options exclusivity, the payload_guide/has_more contract, invoice payment-state caveats ('paid=false proves nothing'), and the untrusted-ERP-text warning. This is exactly the kind of context annotations cannot carry.

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?

Every sentence carries real information and the tool's routing constraint is front-loaded, but the body is a dense interleaved wall of facts with minimal visual structure outside the 'Args:' block. It is efficient in content but heavier than it needs to be.

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 14-parameter search tool with an output schema and rich annotations, the description covers query construction, date semantics, view selection, projection, and invoice-specific caveats, plus pointers to payload_guide and has_more handling. Nothing essential to correct invocation is missing.

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

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

Schema description coverage is 0%, so the description must compensate, and it largely does: it enumerates filter ops, explains (i)like vs %x% matching, documents date_field requirements, names per-domain view_options keys (article, ticket, task, shipment, articleSupplySource), and flags additional_properties as expensive. Minor gaps remain for page/sort/correlation_id, but the semantically significant parameters are well covered.

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 ('Search weclapp entities with text and typed filters') and immediately frames the tool against its siblings by naming aggregate_entities (for counts/sums) and get_entity (for a single id). An agent can distinguish it from the other 25 tools 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?

Explicit routing rules are given ('Counts/sums → aggregate_entities; one id → get_entity'), plus when to use date_preset vs ge/lt filters, when view_options are valid, and when NOT to combine them ('not with filters/date_preset/properties/view/page', 'never combine with view=contract_links'). Alternatives and exclusions are both 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?

Beyond the annotations, the description discloses bounded results, fail-closed behavior for unknown job types, unknown sections surfaced in sections_unavailable, permission caching (5 minutes), and the untrusted-content policy. This is substantial behavioral context that annotations alone do not provide.

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

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

The description is dense but each sentence adds value: scope, use case, drill-in guidance, permission caveat, parameter semantics, and return shape. The most important information is front-loaded in the first sentence.

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 9-parameter diagnostic tool with no required parameters, the description covers the full return contract, section behavior, job filtering, permission options, and safety handling of ERP free text. The presence of an output schema further reduces the need to detail return values, and the description still summarizes the top-level keys.

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

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

Schema description coverage is 0%, but the description compensates with meaningful explanations for sections, job_types, include_permissions, permissions_name_filter, permissions_limit, permissions_refresh, include_licenses, and include_permission_catalog. Only correlation_id is left undocumented, but its purpose is conventional.

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

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

The description names a specific verb and resource: 'Check tenant health across webhooks, jobs, invoices, and print status.' It also distinguishes itself as 'the single entry point for background-job health,' separating it from the many sibling preview/diagnostic 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?

It explicitly frames when to use the tool: 'One-call sysadmin/support diagnostic' and 'use that before a write or when debugging weclapp 403 / not permitted errors.' It also directs follow-up: 'drill in with the per-section tool named in each finding's next_action.'

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

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

Annotations already mark this as read-only and idempotent, and the description adds meaningful behavior beyond that: PDF failures collapse to pdf.available=False without raising, large PDFs return metadata only, contract matching is deterministic, and invoice text/PDF bytes are untrusted third-party content. This is rich, non-obvious behavioral context.

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

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

The description is well-structured with a one-line summary, usage guidance, Args, and Returns sections. It front-loads the core purpose and adds only valuable details about defaults, failure modes, and security. Despite its length, every sentence 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?

The description covers purpose, usage, parameter semantics, return shape, failure behavior, and security considerations. An output schema exists, but the description still explains the return contract in enough detail for an agent to invoke the tool correctly and interpret results safely.

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

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

Schema description coverage is 0%, so the description must carry the parameter documentation burden. It explains invoice_id (omit for most recent), include_pdf (default True and failure behavior), and contract_id (deterministic contract_match). However, correlation_id is not described at all, leaving one of four parameters undocumented.

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

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

The description opens with a specific verb and resource: 'Fetch one purchase invoice with key fields and (optionally) the PDF.' It clearly distinguishes this tool from the sibling find_reconciliation_candidates by stating the inspection use case before correction or payment.

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

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

The description explicitly says when to use this tool ('Inspect a single invoice... before correcting it or applying payment') and names the alternative to prefer for matching ('Prefer find_reconciliation_candidates when the goal is matching'). This gives an agent unambiguous routing guidance.

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