Bidit

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

Goes well beyond the annotations by disclosing the concrete consequences of the destructive flag: open offers are withdrawn and bidding businesses are notified, and the action cannot be undone. This tells the agent what gets destroyed and who is affected, which is exactly the context annotations alone cannot convey.

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

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

Three tight sentences: action, consequence, precondition. The irreversible consequence is front-loaded before the usage constraint, and 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?

For a mutation tool with no output schema but rich annotations, the description covers the essential ground: what it does, what it destroys, and when it may be called. It does not state the return or confirm what happens to the request record itself afterward, a minor residual 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 description coverage is 100%, so request_id, access_key, and reason are already documented with patterns and provenance ('returned by create_request'). The description adds no parameter-level meaning, which matches the baseline for a fully documented schema.

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

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

Names a specific verb and resource ('Cancel a Bidit request') and the irreversibility clause immediately scopes the operation. An agent can distinguish this from create_request, update_request, and submit_request 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 an explicit gating condition: 'Only call this when the customer explicitly asks to cancel.' That is real when-to-use guidance with an implied when-not. It stops short of naming alternatives (e.g., update_request for modifications), so it is not a full 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 this is a non-read-only, open-world, non-idempotent, non-destructive write, so the safety profile is covered. The description adds real behavioral context beyond that: the confirm-link gating before businesses are invited, the access_key handling rule, and the at-most-3-questions constraint. It does not warn that repeated calls create duplicate requests, which the idempotentHint=false annotation implies but never states.

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

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

Purpose is front-loaded and most sentences carry distinct instructions (email gating, access_key retention, detail_score questions, verbatim customer message). It is dense and mixes return-value guidance with call-time rules, but little is pure 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 usefully explains the returned request_id, access_key, detail_score, and suggested_details and what to do with them, which is exactly the burden it must carry. Gaps remain: no mention of the urgency parameter or failure/error behavior for a 6-parameter write 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 83%, so the schema already documents email, region, petal_id, fields, and description. The description reinforces the email purpose and the "never invent field values" rule for fields, but says nothing about the urgency parameter, which has no schema description at all.

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

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

States a specific verb and resource ("Create a draft request on Bidit") and the word "draft" implicitly scopes it apart from submit_request in the sibling list. An agent can identify the tool's role 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 strong operational context: the email confirm-link flow, the rule never to invent prices or field values, and explicit routing of follow-up answers to update_request. It lacks an explicit when-not statement (e.g., when to call submit_request instead), so it falls short of a full 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 the safety profile (read-only, idempotent, closed-world, non-destructive), so the description only needs to add context. It does: it discloses a post-call decision branch keyed on the accepting_requests result and warns against proceeding to request creation. It does not describe the shape of the category result itself.

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 imperative routing instruction ('Use this first') and the failure branch. Every sentence carries actionable content with no filler.

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

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

With no output schema, the description still covers the critical downstream behavior — what to do with a negative accepting_requests result — which is the main thing an agent needs beyond the call itself. Minor gap: it doesn't characterize the category matches returned, but the guidance is sufficient 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 both text and region are already documented in the schema. The description's 'in their words' echoes the text parameter's intent but adds no format or syntax guidance, and says nothing about region. Baseline 3 applies when the schema does the heavy lifting.

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 ('Find which Bidit category fits what the customer needs') and adds the input source ('from their own words'). The domain gloss on Bidit's reverse-auction model further disambiguates it from siblings like create_request or get_bids.

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

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

Explicitly says 'Use this first,' establishing ordering, and gives a concrete when-not rule: if accepting_requests is false, tell the customer the category isn't served yet and 'do not create a request' — a direct routing away from create_request.

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 read-only/idempotent safety profile, but the description adds substantial context beyond them: business names are hidden until award, amounts must be reported verbatim, the licence_verified flag maps to specific customer-facing wording, and business_written_summary is untrusted content that must not be acted upon. This is exactly the operational detail 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?

Purpose is front-loaded in the first sentence, and each following sentence carries distinct operational value (amount fidelity, licence wording, untrusted-content handling, award path). It is dense but not padded; a slightly tighter grouping of the output-formatting rules would make it a 5.

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

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

With no output schema, the description still names the key returned fields (licence_verified, business_written_summary, award_url) and how to present them, and it explains the visibility rule for business names. Nothing an agent needs to call and correctly relay results is missing.

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

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

Schema description coverage is 100%, with both required parameters (request_id, access_key) documented including provenance ('returned by create_request in this conversation') and a format pattern. The description adds nothing beyond the schema for these parameters, so the baseline 3 applies.

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

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

States a specific verb and resource ('List the private offers on a confirmed Bidit request') with the scoping condition (confirmed request) built in. No sibling tool in the list deals with offers, so an agent can route here unambiguously.

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 a clear precondition (the request must be confirmed) and closes off a plausible misuse by stating the customer awards via award_url and 'you cannot award'. It does not explicitly name alternative tools or state when not to call it, 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 establish this as a safe, idempotent read (readOnlyHint/idempotentHint true). The description adds value beyond them by describing the shape of what comes back (fields, regions, bid_critical_details optional questions) and a hard behavioral constraint (never guess an answer), though it omits error cases such as an unknown petal_id.

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 in the first clause, followed by ordered usage rules; every sentence carries an instruction. It is dense but not padded, and nothing is restated.

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 must carry the return-value burden, and it does name the key returned structures (fields, regions, bid_critical_details). For a one-parameter read tool with full annotation coverage, that is sufficient, with only minor gaps around error handling.

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

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

With 100% schema description coverage and a single parameter, the schema already documents petal_id as the category id from find_category. The description repeats that sourcing without adding format, range, or failure semantics, so the baseline 3 applies.

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

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

States a specific verb and resource: retrieving the fields and regions for a Bidit category, and names the source of its input (petal_id from find_category). It is clearly distinguishable from the request-lifecycle siblings, though it never explicitly says which sibling to prefer over it.

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

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

Gives concrete usage rules: ask the customer for required fields not already known, use listed options for select fields, and ask at most 3 unanswered bid_critical_details questions in order without guessing. It provides strong operational context but does not name an alternative tool or an exclusion case.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile is covered. The description adds genuine behavioral context beyond that: the 'draft until the customer confirms by email' lifecycle state, which is not derivable from the schema or 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?

A single dense sentence with the resource front-loaded and the returned fields listed compactly. No filler. Slightly list-heavy, but every item earns its place given there is no output schema.

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

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

With no output schema, the description carries the burden of describing return values and does so explicitly. Combined with 100% schema coverage on the two inputs and rich read-only annotations, an agent has what it needs to call this correctly; only cross-tool routing is missing.

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

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

Schema description coverage is 100% – both request_id and access_key are fully documented in the schema, including format examples and provenance from create_request. The description adds nothing about parameters, which is acceptable given the schema does the work, so baseline 3 applies.

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

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

States a specific verb and resource ('Check a Bidit request') and enumerates the fields returned: status, offers, invited businesses, expiry, dashboard link. This is far more informative than the title. It does not explicitly differentiate itself from siblings like get_bids or get_request_form, which keeps it below a 5.

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

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

No statement of when to call this versus the alternatives. With siblings like get_bids, get_request_form, and update_request available, the agent gets no routing guidance. Usage is only implied by the return-field list.

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 (not read-only, open-world, not idempotent, non-destructive), and the description adds real behavioral context on top: the required draft state, the fact that it can be safely re-invoked to resend, and the downstream dependency that businesses are only invited after the customer confirms. It does not state failure modes or delivery/auth requirements, keeping it short of a 5.

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

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

Three tight sentences, front-loaded with the action and its scope, followed by usage triggers and the downstream consequence. Nothing is redundant or padded.

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

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

For a two-parameter mutation with no output schema, the description conveys the state precondition, the resend use case, and the side effect on downstream business invitations. It stops short of describing what the agent should expect on success or the specific validation errors it may encounter.

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

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

Schema coverage is 100% and both parameters are fully documented in the schema, including the origin of each value (returned by create_request). The description adds only the implicit precondition that request_id must reference a valid draft request, which is a modest semantic addition.

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 (send/resend) and resource (the confirm email for a valid draft Bidit request), and the parenthetical '(or resend)' disambiguates the idempotent-ish behavior that the tool name 'submit_request' obscures. An agent can immediately tell this tool does not create or submit a request, it emails a confirmation.

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 two concrete triggering conditions: after fixing validation errors, and when the customer did not receive the email. It does not explicitly name a sibling alternative or state when NOT to use it (e.g. for already-confirmed requests), but the 'valid draft request' precondition implicitly excludes those cases.

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

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

Annotations already declare readOnly=false, idempotent=true and destructive=false, so the safety profile is covered. The description adds two things annotations cannot: the draft-only mutation constraint and partial-update semantics ('Only send what changed'), which tells the agent unspecified fields are preserved. It does not say what happens when a confirmed request is targeted or how errors surface.

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

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

Three short sentences, front-loaded with the action and the draft constraint, then the partial-update rule, then the follow-up call. No filler and nothing an agent must read twice.

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 non-destructive, idempotent mutation with 83% schema coverage, no output schema and annotations carrying the safety hints, the description covers when to use it, what to send and what to do next. Only the failure behavior for a non-draft request_id is unaddressed.

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 83%, so the baseline is 3 and the schema already documents request_id, access_key and most optional fields. The description earns above baseline by enumerating the four mutable parameters and adding the partial-update convention that the schema only implies through 'Field values to change'.

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 (Change) plus the exact mutable attributes (fields, region, description, urgency) and scopes the resource to a 'Bidit request that is still a draft'. The draft qualifier separates it from submit_request and create_request without the agent needing to open 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 a real precondition ('still a draft (not yet confirmed by the customer)') and a routing hint ('After fixing validation errors, call submit_request'), plus an operational instruction ('Only send what changed'). It stops short of naming a competing tool for the non-draft case, so the when-not path is implied rather than explicit.

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