Avenbridge

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

Beyond the read-only, idempotent, non-destructive annotations, it discloses the return contents (closest approved answers with source, approval date, similarity), the fallback behavior for unanswered questions (matching document passages with document/version/page), and the caveat that document passages are not approved answers. It also covers multi-business search naming and cross-language question handling.

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 most important guidance is front-loaded: call this for approved answers, even when other sources seem sufficient. The description is long but mostly earns its length given the lack of an output schema and the nuanced fallback behavior, though a few approval/unanswered points are repeated.

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 read-only lookup tool with no output schema, the description is complete: it explains what is returned, what happens when no approved answer exists, how document passages differ from approved answers, how to handle multiple businesses, and how to handle language differences.

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 covers the parameters reasonably well, and the description adds important semantics: omitting business_id and business searches every business and labels each answer with the business, and when the user's language differs from the business's material, each question should be passed again in the business's language. It does not add much detail about the optional question label beyond what the schema already provides.

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: it looks up a business's approved answers for questionnaire and other business questions. It clearly distinguishes itself from ask_business and from using document passages, so an agent can identify the 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?

It explicitly says to call this for any business question even when notes, memory, or a web page seem to answer it, because only this tool returns approved answers. It also names ask_business for submitting an unanswered question to the business and explains how business/business_id omission changes search scope.

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

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

Annotations only say it is a non-read-only, open-world, non-destructive, non-idempotent operation; the description supplies the real behavioral detail: nothing transmits on the first call, the preview+code handshake, that Avenbridge emails the contact with the user's address as reply-to and copies the user, and that answers return via status and answer_questions. The duplicate-suppression note ('same questions sent again within a day are not sent twice') adds a rate-limit-like behavior the annotations do not convey.

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

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

The flow is front-loaded (preview first, then confirm), which is the right ordering for the reader. It is slightly dense and run-on in the back half, packing email routing and answer retrieval into one long sentence, but no sentence is filler.

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

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

With no output schema, the description still explains what each call returns (a preview plus confirmation code) and how results come back later (status, then answer_questions). For a 5-parameter, open-world mutation with a two-phase handshake, that covers everything an agent needs to invoke it correctly.

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

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

Schema coverage is 80%, so the baseline is 3, but the description adds conditional logic the schema does not state: business_id (or business) is required only when the user has more than one business. It also frames 'confirm' as the code from the preview that must follow user agreement, which explains the sequencing semantics of that parameter.

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

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

States a specific verb and resource: send questions to one business's contact person, with the two-step preview/confirm mechanism named up front. It explicitly positions itself against the sibling answer_questions, so an agent can distinguish the two 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 ('questions answer_questions could not answer'), the when-not of the first call ('Nothing is sent on the first call'), and the exact condition for the second call ('only if they agree, call again with the same business and confirm set to the code'). It also states the multi-business prerequisite for business_id/business, leaving little 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 establish read-only, idempotent, non-destructive, non-open-world behavior. The description adds valuable operational context beyond annotations: only current versions are returned, versions/issue/expiry dates are included, download links expire after 15 minutes, and results are grouped by business when no business is specified.

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 core purpose, then gives filtering and default-scope behavior, then return-value details. The examples are useful and the description remains compact with no apparent waste.

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

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

There is no output schema, so the description appropriately explains the important return values: version, issue and expiry dates, and a time-limited download link. With annotations covering safety and schema covering parameters, no material information is missing for correct invocation.

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

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

Schema description coverage is 100%, so all four parameters are already well documented in the schema, including the business/business_id relationship. The description reinforces the filtering behavior and omission semantics but does not add significant parameter detail beyond what the schema provides.

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 the current versions of a business's shareable documents') and enumerates the document families covered. It is immediately distinguishable from the sibling tools, which handle business listing, invitations, requests, sharing, status, and questions.

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?

Explains filtering by part number and/or document type and explains the important default behavior when business_id or business is omitted. It does not name explicit when-not-to-use conditions, but the context is clear and there is no competing sibling tool for this resource.

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 safety (readOnly, idempotent, non-destructive, closed-world), so the remaining burden is on describing the payload, which the description does: ids, counts, and invitation context such as shipment or part number. It stops short of noting whether the list is exhaustive or permission-scoped, cost, or ordering.

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 action and scope, then the routing directive. Every clause carries information (resource definition, returned fields, sequencing guidance) with no restatement of the title or annotations.

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

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

With no parameters and full annotation coverage, the only real gap is the return shape, which the description partially covers by naming ids, counts, and invitation context. Small omissions (empty-result behavior, whether all businesses appear) keep it just under fully complete.

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

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

The tool takes zero parameters, which is the baseline-4 case; there is nothing for the description to disambiguate. The text usefully reinforces that the scope is implicit — the calling user — rather than parameterized.

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

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

"List the businesses (suppliers) that share documents and approved answers with this user" gives a specific verb plus resource and defines the exact scope (user-linked businesses), which cleanly separates it from get_documents and answer_questions. It also previews the returned fields (ids, counts, invitation context).

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?

"Call it first when you do not know which business the user means or need a business_id" states both the triggering condition and the precedence relative to siblings, and implicitly excludes the case where the business is already known. No inference is required to route here.

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 safety (readOnly, idempotent, non-destructive, closed-world), and the description adds the non-obvious auth behavior ('works before the user signs in') plus a summary of what the call surfaces. With no output schema, that return summary carries real weight, though it could say more about failure on a bad/expired code.

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, no filler: action and input first, then what comes back, then the pre-auth caveat. 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?

For a single-parameter read tool with full schema coverage and annotations, the description supplies everything an agent needs: input format, return shape, and the sign-in-independence trait. No output schema exists, and the return summary compensates.

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 parameter description already includes the format example, so the description's '8 letters and digits, e.g. K7Q2M8XD' largely repeats structured data. Baseline 3 applies.

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

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

States a specific verb and resource: opens an invitation a business sent the user, keyed by the invitation code. The resource is distinct enough from siblings like get_documents or status that an agent can route correctly without opening any schema.

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

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

Gives clear usage context: use the code from the user's message, and note that it works before sign-in, which is a meaningful precondition for an agent handling an unauthenticated user. It stops short of naming alternatives or when-not conditions.

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

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

The description adds substantial behavior beyond the annotations: the two-phase preview/confirm handshake, that nothing is transmitted on the first call, that Avenbridge emails the contact with the user's email as reply-to and copies the user, and that the reply surfaces via `status`. However, it states that an identical request re-sent within a day is not sent twice, while annotations declare idempotentHint=false — a mild tension an agent could trip over. With annotations already covering safety and openness, the added context is good but this friction costs a point.

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

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

Front-loaded with purpose and the call-vs-preview branch before the mechanics, and nearly every sentence carries operational weight. It is dense and on the long side, with one awkward double negative ('is not sent twice') that could be tighter, but nothing is 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 an open-world, multi-step mutation tool with no output schema, the description covers the confirmation workflow, delivery side effects, deduplication, and where the business's reply appears. An agent has everything needed to call it correctly on the first and second attempt.

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%, yet the description still adds semantics the schema lacks: `kind` must match a kind the business lists (with 'call' triggering a fundamentally different flow), `confirm` is the code from the preview and must be omitted on the first call, `details` should carry the checklist items, and `business`/`business_id` may be omitted when the user has one business.

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 concrete verb and resource ('Send a request to one business') and enumerates the request kinds, so its function is unmistakable. It cross-references list_my_businesses and status, but never distinguishes itself from the sibling ask_business, which sounds like it could serve a similar need — an agent must guess between the two.

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 branching: when the business lists 'call', use kind call and the user books on the business's page; otherwise the first call only returns a preview and a confirmation code, and a second call with confirm is required. It also tells the agent to ask for checklist items before quote/sample requests, which is a concrete when-to-use rule rather than an 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 declare non-read-only, idempotent, non-destructive, but the description adds genuinely non-obvious behavior: the generated link expires after 15 minutes, and file content cannot be transmitted through the tool itself. It does not clarify what happens to the link/upload after expiry or what object is returned, which keeps it from a 5.

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

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

Three sentences, front-loaded with the what and followed by the platform constraint and the branch logic. Slightly clunky phrasing ('Files cannot travel through this tool, so the page is the way') but no wasted sentences.

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

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

No output schema exists, and the description implies a link is produced but does not say how it is returned or what to do with it in the response. For a zero-required-parameter, low-complexity tool with fully described params, this is close to complete.

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

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

With 100% schema coverage the baseline is 3, but the description adds meaning beyond the schema by explaining the conditional effect of `case_id` (attach vs. create new request). `note`, `business`, and `business_id` are left entirely to their 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?

The description states a concrete action and resource: produce a page where the user attaches files for a business, with examples of file kinds (drawings, forms, defect photos). It is distinguishable from siblings like `request` or `ask_business`, though it never explicitly names those alternatives to reinforce the distinction.

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 clearly explains the two modes: pass `case_id` to attach files to an existing request, omit it to send files as a new request. It also states why this tool is needed at all ('Files cannot travel through this tool, so the page is the way'). It stops short of naming siblings or exclusions, so not 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 cover safety (readOnly, idempotent, non-destructive, closed world). The description adds valuable context about what is returned: open and recent requests with details such as what was asked, when, where it stands, and the business's reply. It does not specify pagination or limits, which is a minor gap.

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

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

Two sentences with little waste. The first sentence front-loads the resource and its contents; the second gives usage context. The first sentence is slightly dense but still easily parsed.

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 read-only tool with two optional parameters, no output schema, and rich annotations, the description is largely complete: it explains purpose, usage, and return content. It omits pagination or result limits, but otherwise provides what an agent needs to call it correctly.

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

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

Schema coverage is 100%, so the schema already documents both parameters thoroughly. The description implies filtering by business or all businesses, but adds no syntax or format details beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states it retrieves the user's open and recent requests (questions, quotes, samples, documents, complaints) and what they contain (what was asked, when, where it stands, business's reply). It distinguishes the resource from siblings like get_documents by indicating a broader status view, though it does not explicitly name alternatives.

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

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

It explicitly says 'Use it when the user asks whether a business has answered or what is pending,' giving a clear usage scenario. It does not state when to use other tools or when not to use this one, but the context is sufficiently clear.

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