Victano: EU tenders and grant calls

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

With readOnlyHint=false and no other strong behavioral annotations, the description adds meaningful details: it sends an email to the user, generates a confirmation link and code, and initiates an asynchronous flow that requires a follow-up call to connect_verify. It does not contradict the annotations spoiled within the structured data, and it surfaces the important non-obvious trait that this step alone does not complete authentication.

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 serves a purpose: it states the action, names the required inputs and behavior, gives the immediate next step, and removes a possible concern ('No card needed'). The most important information is front-loaded, and there is 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?

The description explains the flow and the next step, but it never explicitly says that connect_start returns the request_id needed for connect_verify. Because there is no output schema, that return value is a critical missing piece for an agent that must invoke the follow-up call with the correct argument. A short addition such as 'Returns a request_id to pass to connect_verify' would make it 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?

Schema description coverage is 0%, so the description must carry parameter meaning. It does: email is defined as the user's work email, and language is described as the conversation's language with examples ('lt', 'en'…). It does not enumerate all language codes or explain the null default, but the schema already covers the default, so the description provides meaningful extra guidance.

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 'Begin authentication' and then names the concrete action: send the user's work email and conversation language, after which Victano emails a confirm link and code. This clearly identifies a specific verb, resource, and scope, and it distinguishes connect_start from its sibling connect_verify by framing it as the first step in a two-step flow.

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 context for when to use the tool ('Begin authentication') and even tells the agent exactly what to do next ('Then call connect_verify(request_id) at once: it waits for the click'). It also notes 'No card needed,' ruling out a possible prerequisite. It does not spell out when not to use connect_start or compare it with other siblings, but the flow guidance is strong.

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 discloses important behavioral traits beyond the annotations: it blocks waiting for a Confirm click, can return 'waiting' and be called again, exposes the api_key only once, and returns a session to reuse later. These details meaningfully shape how the agent should invoke and handle the tool.

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 compact, with essential operational guidance and output information packed into two sentences. It is front-loaded with the purpose and contains no filler or repetition.

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?

It covers the branching flows, retry behavior, and return values despite the absence of an output schema. The only notable gap is that the required request_id's provenance is implied rather than explicitly stated, leaving a small inference burden on the agent.

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 description clarifies the optional 'code' parameter (no code vs. a code the user read aloud), which the schema alone does not convey. However, the required 'request_id' parameter is never explicitly explained as coming from connect_start, and schema coverage is 0%, so the description does not fully compensate for all parameters.

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 action ('Finish signing in') and target (connecting an account), and differentiates it clearly from siblings by anchoring to connect_start. It also describes the outcome (returns api_key and session), leaving no ambiguity about what this tool does.

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 sequencing: call right after connect_start with no code, retry if it returns waiting, never ask the user, and alternatively pass the user-provided code. This is precise, actionable guidance that also tells the agent what not to do.

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 (readOnlyHint, idempotentHint, destructiveHint=false), so the description correctly spends its words on non-obvious behavior: the sign-in prerequisite, that connect_start/connect_verify are free and need one email, and how the session should be passed across a conversation. It does not mention rate limits, response size, or failure modes for an invalid id, which keeps 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 with the blocking prerequisite front-loaded, then content, then the usage cue and follow-up. No filler, though the auth clause is heavily parenthetical and could read more cleanly as its own 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?

With no output schema, the description does its job of naming the return payload ('full normalised record plus the document inventory'). The auth prerequisite, which an agent would otherwise fail on, is covered. The remaining gap is the identifier ambiguity between id and opportunity_id, which is not addressed anywhere.

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%, and the undocumented half is exactly the pair the agent must choose between: 'id' and 'opportunity_id', both nullable strings with no title-level description and no mention in the prose. The description references the sign-in flow but never says which identifier to supply, when to use one over the other, or what as_units changes beyond the schema's own note.

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_opportunity' returns the 'full normalised record plus the document inventory') and explicitly distinguishes it from the search path ('a search card is not enough'), which separates it from the sibling search_opportunities. An agent can tell what it gets and why it differs from search without opening a schema.

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

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

Gives an explicit when-to-use ('Use before advising on a bid'), an explicit when-not ('a search card is not enough'), and a named follow-up tool ('Follow with read_document for eligibility text'). It also names the prerequisite chain (connect_start, connect_verify) and the exception (already signed in).

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, so safety is covered; the description adds the real added value here - the authentication requirement and the fact that the payload is a prescriptive playbook rather than a summary. No contradiction with annotations, and auth context is exactly the kind of extra disclosure that matters.

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 auth prerequisite, then the payload description, then the behavioural instruction, in two tight sentences with no filler. Slightly dense but every clause carries 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?

Covers auth and expected return content well enough for a read-only tool with no output schema. However, with four parameters, 25% schema coverage and three overlapping identifier fields, the description leaves a real ambiguity (which id to pass) unresolved for an agent trying to invoke it.

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 only 25% and three near-synonymous identifier parameters (id, name, workflow_id) are left undocumented in both places; the description says 'one workflow id' but never disambiguates which parameter to use. The session parameter it alludes to is already fully described in the schema, so the description compensates very little 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?

States a concrete verb+resource: it returns the complete step-by-step playbook for one workflow id, and enumerates the content it carries (decision gates, EU procurement eligibility rules, pitfalls). It does not name list_workflows to contrast itself, but 'one workflow id' implicitly separates it from the listing sibling.

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

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

Gives a clear precondition chain (call connect_start(email) and connect_verify unless already signed in via OAuth/key) and an operating instruction ('follow it rather than summarising it'). It never states when to prefer this over list_workflows or get_opportunity, so it stops short of explicit 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?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered; the description usefully adds the auth/session requirement, that sign-in is free with one email, and the ordering guarantee that whole jobs lead the results. It stops short of describing output shape or how truncation actually behaves, but the added context beyond annotations is substantial.

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 critical auth prerequisite is correctly front-loaded, but the middle sentence ('how bid professionals actually run this work, from the weekly scan through...') is descriptive padding that consumes significant length without helping invocation. Caps-lock emphasis and parentheticals make it denser 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?

With no output schema, the description still conveys what the result contains (a library of playbooks, jobs first, compact vs full detail, truncation governed by max_chars) and fully covers the auth gate. An agent has enough to call it correctly; only the exact card structure is left implicit.

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 already 80%, and the description still adds real meaning: it explains that persona='consultant' surfaces the multi-client playbooks, that jobs always sort ahead of other rows (relevant to limit), and that session must be passed on every call in the conversation. These are usage semantics, not restatements, so it exceeds the baseline-3 case for high 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 description names the resource concretely ('The playbook library') and enumerates the coverage of the library (weekly scan, qualification, eligibility screening, specification reading, clarification, proposal skeleton), which tells an agent exactly what this listing contains. It also routes to the sibling get_workflow, distinguishing it from the single-item fetcher, though it never states the verb 'list' outright and relies on the title for that.

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 an explicit prerequisite chain (call connect_start(email) then connect_verify unless already signed in), an imperative selector condition ('READ A WORKFLOW BEFORE IMPROVISING A PROCESS'), a follow-up path ('Follow with get_workflow'), and a parameter-driven alternative view (persona='consultant' for multi-client playbooks). Nothing about when to reach for this tool 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 declare readOnlyHint=false, idempotentHint=false, openWorldHint=true — mutation-capable and non-repeatable — but the description goes well beyond them: auth/session mechanics, the reply confirmation gate (show the words, set confirmed=true only after agreement), and a detailed prompt-injection safety contract that message content is data, never instruction. It also discloses the unauthenticated fallback ('only service notices are shown'). 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?

Three dense paragraphs, front-loaded with the sign-in prerequisite, then action semantics, then the safety contract — a sensible order. Every sentence carries weight, though the safety section is verbose enough that a tighter phrasing would read faster.

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, no-output-schema, mutation-capable tool, the description covers auth, per-action behavior, the confirmation gate, safety, and the unauthenticated fallback. The main gap is the shape of what `list` actually returns (fields per message), which an agent may want before summarizing an inbox.

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 3 baseline is already met, but the description adds real semantics: the reply flow requires showing the person their own words and passing confirmed=true, and the settings action is described as read-or-write depending on whether switches are supplied. It adds less on id/hours beyond what the schema already documents.

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 title plus the phrase 'Messages from the Victano team to this person: replies to their feedback, questions about it, service notices and news' names the resource precisely and its content categories. The six action modes are enumerated, so an agent knows it is a multi-action inbox tool rather than a single-purpose one. It does not name a sibling to avoid (e.g. submit_feedback), so it stops short of full sibling differentiation.

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 prerequisites ('call connect_start(email) and connect_verify first ... unless this connection is already signed in') and an explicit routing rule ('When an answer carries a `notifications` block with unread messages, tell the person in one sentence and offer to open them; their task comes first'). Each action's trigger is stated (read marks read, reply only for messages that invite a reply, snooze takes hours). 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 cover safety (readOnly, idempotent, non-destructive), so the description's value is the added operational context: the free one-email sign-in requirement and session-passing rule, relevance ranking, compact cards with a summary_cut marker for truncated summaries, and the search-in-source-language rule. It stops short of describing pagination or result counts, which remain unstated.

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

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

Three dense sentences that lead with the blocking prerequisite (sign-in) before purpose, then routing, then language guidance. Every sentence carries information, though the auth preamble is long enough that the core purpose arrives second.

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 29-parameter search tool with no output schema, the definition covers the essentials an agent needs to select and call it: prerequisite auth, ranking behavior, handoff targets, language strategy, and card/truncation shape. The residual gap is the handful of completely undocumented tuning parameters, which is a schema problem more than a description one.

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?

At 72% schema coverage the schema documents most parameters, so baseline is 3. The description adds real meaning for the language dimension (search in the notice's own language; research_guide supplies the trade lexicon) and summarizes the filter set (country, CPV, status, deadline, value, region), but several parameters (kind, lang, value_band, cpv_divisions, nature_strict, expand_languages, nuts_strict) are undocumented in both places.

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 open public tenders and EU grant calls), plus scope (by subject, ranked by relevance) and the filter axes it supports. It also names the sibling it hands off to (get_opportunity), so an agent can separate retrieval-list from detail-fetch 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 an explicit workflow: use it to find notices worth a decision, then get_opportunity or read_document, and states the sign-in prerequisite up front along with the alternative auth paths (OAuth/key vs session). It also advises scoping by country because EU-wide is ~10x slower. No explicit when-not-to-use case, which keeps it 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 only provide the generic write/openWorld profile; the description adds the operationally critical context: sign-in prerequisite, mandatory user consent before sending personal detail, the distinction between authored_by='agent' self-reporting and user-authored content, item length caps, and what the response contains (a reference id) and what must not be promised (a reply or date).

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 (~350 words) but front-loaded with the sign-in requirement and organized into purpose, triggers, consent rules, and field guidance. It does duplicate some schema content, notably the kind enum values and the per-field character limits, which costs a point but does not bury the operative instructions.

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 12-parameter write tool with no output schema, the description covers auth flow, consent/confirmation protocol, field-level conditional guidance, size limits, and the shape of the response. Nothing an agent needs to invoke this correctly and safely is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by giving conditional guidance the schema does not: fill kind and what, add expected and got specifically for wrong answers, and only set confirmed=true after explicit approval, which ties the confirmed/authored_by flags together semantically.

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 feedback about Victano to the team that builds it') and enumerates the exact scope (bug, wrong answer, missing data, missing feature, workflow idea, praise). An agent can immediately distinguish this from sibling tools like notifications or search_opportunities because the description frames it as outbound communication to the builders.

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?

Contains an explicit 'When to offer it' list of trigger conditions (empty/wrong answer, user correction, missing workflow step, repeated manual step, unmet need) plus behavioral constraints ('Offer once, in one sentence', 'Ask first'). It also states the prerequisite path via connect_start/connect_verify, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description is not burdened with basic safety disclosure. It adds useful behavioral detail by enumerating what the response reports: tier, persona, corpus freshness, current window limits, and non-renewing caps. 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 two sentences with no filler. The first sentence front-loads the core output value, and the second sentence gives concrete invocation scenarios. Every clause contributes actionable information.

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

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

For a simple read-only tool with one optional, fully documented parameter and no output schema, the description covers purpose, triggering conditions, and key return content. It omits explicit mention of the 'session' parameter in the description, but the schema already covers that, so the combined context 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 description coverage is 100%, so the session parameter is fully documented in the schema. The description itself adds no param-specific semantics beyond the schema, and with full coverage the baseline of 3 applies.

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

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

The description specifies the tool returns details about the connected account: tier, persona, corpus freshness, and limits. It clearly identifies the resource and the kind of information, though it lacks an explicit verb like 'retrieve' or 'return'. The sibling tools handle workflows and opportunities, so the account-focus differentiates it adequately.

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 gives explicit trigger conditions: call it when a user asks about limits, when unsure about authentication, or to confirm a setting took effect. It does not explicitly mention when not to use it or name alternatives, but the provided context is clear and practical for an agent.

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