vidit (demo)

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

Annotations only declare non-readOnly, non-destructive, non-idempotent, closed-world; the description adds substantial context the annotations do not: this is a demo whose output is an AI draft with no professional validation, that nothing is charged and nobody is contacted, and the exact branching logic (all fields match vs any field differs vs no entry). This is well beyond what structured fields 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?

Purpose and the demo disclaimer are front-loaded, and each sentence carries information (demo nature, fill-the-fields rule, branch outcomes, quote flow, exclusions). It is dense and reads as a run-on in places, with the no-real-data warning appearing twice across description and schema, but nothing is padding-grade.

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 11-parameter, nested-object tool with no output schema, the description carries the burden well: it describes both return shapes (draft with assumptions, sources and validity window; or sample price band and turnaround), the free/uncontacted guarantee, and the eligibility limits. Nothing an agent needs to decide whether and how to call it is missing.

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

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

Schema coverage is 91%, so the baseline is 3, but the description adds real meaning: it enumerates the intake fields that actually drive matching and states that only those fields (never the free-text question) are used. Minor flaw: it names `cross_border` and `already_filed`, which do not appear in the intake schema, so the field list is slightly imprecise.

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 (ask a Swiss tax question for a business or freelancer) and describes the two outcome paths precisely: an exact-match draft entry, or a sample indicative price band and turnaround. It also implicitly separates itself from `commit` ("Free: nothing is charged") and names `status` as the sibling that shows sample quotes.

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-not guidance ("Do not use for private matters or for countries other than Switzerland, and send no real personal data") plus a concrete instruction for how to trigger quotes ("call `ask` again with `request_quotes: true") and how to inspect them via `status`. The matching rule ("matching uses these fields only, never the question text") doubles as a usage constraint.

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?

Adds substantial context beyond the annotations: in demo mode it returns a sample ticket with nothing ordered, charged, or contacted, and in the pilot it is the only tool that commits money (the quoted fee plus a vidit operator fee) and only within the principal's budget and policy. This financial-commitment semantics is not conveyed by any annotation flag.

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 verb and object, and the three following sentences each carry distinct and non-redundant information (selection rule, demo behavior, pilot money behavior). Slightly dense but no wasted 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 7-parameter, nested-object mutation tool with no output schema, the description covers demo return behavior, money commitment, and budget/policy constraints. It omits error/retry and idempotency behavior, but the core mechanics an agent needs are present.

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 the baseline is 3, but the description adds real meaning: it clarifies that `choice`/`chosen_by` must reflect a principal decision or explicit rule and never positional picking. That goes beyond the schema's field-level definitions.

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 (commit) and resource (one of the sample quotes returned by `status`), so an agent knows it selects and commits to a quote rather than searching or asking. It names the sibling `status` as the source of the quotes, distinguishing it from `ask` and `search_library`.

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?

Says the choice must come from the principal or an explicit principal rule, and explicitly says 'never by position', which is actionable selection guidance. It implies the `status` call must precede it but does not state when not to use it versus alternatives.

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 readOnly/destructive/openWorld annotations, it discloses that the call is free, that entries are AI-drafted and unvalidated by a professional in the demo (with the pilot caveat), and critically that the entry body is withheld and only returned by `ask` when the principal's fields match. This is real behavioral context the 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 leads, which is good, but the middle is padded with marketing/provenance prose ('Free.', the full Treuhänder disclaimer) and restates the pre-ask framing at both the start and the end. The useful content could be roughly half the length without losing anything.

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 correctly carries the return contract (canonical question, assumptions, matched intake fields) and warns that the entry body is not returned here -- the single most important trap for this tool. Only the input parameters remain uncovered.

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 only 50% -- `language` and `jurisdiction` are undocumented in the schema -- and the description says nothing about any of the four input parameters (keywords matching, language, jurisdiction, category_prefix syntax). It neither compensates for the coverage gap nor adds meaning beyond the schema.

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

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

States a specific verb and resource ('Browse the demo's draft Swiss tax entries') and explicitly distinguishes itself from the sibling tool 'ask', which alone returns the entry itself. An agent can tell the two apart 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 a concrete when-to-use ('before you ask', 'to see which topics exist, or which facts decide an answer, before you collect them') and names the alternative that covers the excluded case (retrieving the entry via `ask`). 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 mark it read-only and non-destructive, and the description adds meaningful context beyond them: it is 'Free', and it explicitly warns that returned quotes are samples from 'SAMPLE Professional 1-3' in no ranked order until the pilot shows real ones. It also discloses what is returned in each state, going beyond the safety hints.

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 and cost are front-loaded, and the return-behavior detail is broken into the two relevant states. The middle sentence on choosing among quotes is long and reads as workflow policy rather than tool definition, but it is tied to how results should be interpreted.

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, single-parameter status check with no output schema, the description covers what is returned in both lifecycle states and flags that the data is sample/pilot content. An agent has enough to call it and interpret results, with only minor gaps around exact field shapes.

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

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

There is a single required parameter and schema description coverage is 100% ('A request_id or a ticket_id'), so the schema already documents the argument. The description implies the same polymorphism ('a request for quotes or a ticket') but adds no format or syntax detail beyond the schema, 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?

The opening sentence 'Check a request for quotes or a ticket' gives a concrete verb and resource, and the later references to `ask`/`request_quotes` and `commit` implicitly place it in the lifecycle alongside its siblings. The generic name 'status' does not distinguish it, but the description compensates with enough specificity to identify the tool.

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

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

It clearly states the two contexts in which it applies: after `ask` with `request_quotes` to view quotes, and after `commit` to view the ticket. No explicit 'do not use when...' exclusion is given, but the sequential routing to sibling tools is concrete.

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