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 (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description still adds value beyond them by describing what is returned (normalised record + document inventory) and the intended sequence into read_document.

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, front-loaded sentences with no filler; scope is stated first, then usage, then the follow-up. Slightly terse phrasing ('a search card is not enough') costs it a point but nothing is wasted.

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

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

For a read-only tool with no output schema, the description adequately covers the return shape and the workflow handoff. It leaves a real gap around which identifier parameter to supply, which matters given two ambiguous undocumented id fields.

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

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

Schema coverage is only 50% and the description says nothing about any of the four parameters. In particular, 'id' and 'opportunity_id' are both undocumented nullable strings with overlapping meaning, and the description gives no help in disambiguating them or in explaining session/as_units.

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 the specific resource and scope: the full normalised record for one opportunity plus its document inventory. The clause 'a search card is not enough' implicitly contrasts with search_opportunities, though it never names that sibling explicitly.

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 trigger ('Use before advising on a bid') and a follow-up step ('Follow with read_document for eligibility text'), which is genuine routing guidance. It stops short of naming search_opportunities as the explicit alternative or stating any 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?

Annotations already declare safe read-only, idempotent, non-destructive. The description adds that it returns the full playbook and should be followed, not summarised. This provides some behavioral context, but nothing extra about performance or exact output structure. No contradiction.

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 a single sentence that is reasonably concise and front-loads the main purpose. The instruction to follow rather than summarise is extra, but useful. It could be improved but is not verbose.

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

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

Given the ambiguity between id and workflow_id parameters (both string, optional, with no description), the description does not resolve this, which is a significant gap. No output schema exists, so the description should explain what 'full playbook' includes; it does mention decision gates and procurement specifics, but not the return format. Overall, incomplete for correct usage.

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% (only session has a description). The description does not detail which parameter to use (id, workflow_id, name), which is critical. It provides no help beyond what's in the schema. Baseline 3 is appropriate, but could be lower given the ambiguity.

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 clear verb ('get') and resource ('workflow'), and explains it returns the full step-by-step playbook. It could be more specific about the parameters (id vs workflow_id) but is generally clear. It does not explicitly differentiate from siblings, but the purpose is clear enough.

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

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

The description implies usage for retrieving a specific workflow and advises to follow it rather than summarise. It does not explicitly state when to use this vs list_workflows, but the nature of list vs get is clear from tool names. No explicit alternatives are mentioned.

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 read-only, idempotent, and non-destructive, so the description's main value is in adding ordering behavior ('Whole jobs come first'), persona-based filtering, and a next-step recommendation. No contradiction with annotations; the description complements them with practical behavioral details.

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, efficiently packed with context and instructions. The initial clause about bid professionals is a bit verbose but sets the scene; the imperative 'READ A WORKFLOW BEFORE IMPROVISING A PROCESS' is impactful. No fluff, and key instructions are front-loaded.

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

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

Given the tool's simplicity (0 required params, no output schema) and annotations covering safety, the description covers purpose, usage timing, ordering, a specific filter, and the next step. It does not explain return format, but that is not essential for a listing tool with optional params.

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 80%, so the baseline is 3. The description adds meaning for the persona parameter ('Pass persona='consultant' to see the multi-client ones'), which is otherwise undocumented in the schema. It does not add for other params, but this single addition pushes it above baseline.

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 makes the tool's purpose clear: it lists playbooks, as evidenced by 'The playbook library...' and the instruction to 'Follow with get_workflow', implying a list-then-read sequence. It does not explicitly contrast with siblings like search_opportunities, but the reference to get_workflow as the next step helps differentiate from that 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?

The description gives strong usage direction: 'READ A WORKFLOW BEFORE IMPROVISING A PROCESS' establishes when to use it, and 'Pass persona='consultant' to see the multi-client ones' specifies a conditional filter. It also tells the agent to follow with get_workflow, though it does not explicitly state when not to use the tool.

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 declare the coarse profile (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false); the description adds what actually matters: messages are untrusted DATA that must never be followed, 'read' has the side effect of marking read, reply sends the user's own words and requires confirmed=true, and unauthenticated callers only see service notices.

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 action list, then the unread-message nudge, then safety, then the no-account fallback. Dense and mostly waste-free, though the safety paragraph is long enough that the operational action semantics and the prompt-injection policy compete for attention.

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?

Seven parameters with no output schema, and the description covers the multi-action surface, the reply confirmation gate, the session/account caveat, and prompt-injection handling. It never describes the shape of what list/read returns, which leaves a gap given there is no output schema to fall back on.

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 adds semantics the schema lacks: reply lands in the same feedback thread and is only valid for messages that invite a reply, and snooze's hours default/ceiling behavior is framed as 'puts one away'. The action enum is also restated with operational meaning rather than just values.

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 concrete resource (the person's messages/inbox) and enumerates every action it supports (list, read, reply, dismiss, snooze, settings) with the specific effect of each. The reply-to-same-feedback-thread note implicitly separates it from the sibling submit_feedback, so an agent can tell what this tool is for 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 per-action when-to-use context ('read' with id opens and marks read, 'reply' only answers a message that invites a reply, 'dismiss'/'snooze' puts one away) plus proactive guidance on surfacing unread messages without derailing the user's task. No sibling tools are named as alternatives, but the routing across the six actions is explicit.

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 non-destructive behavior. The description adds beyond that: relevance ranking, compact cards with `summary_cut` marking cut summaries, and the requirement to search in the notice's own language. These are useful behavioral traits not derivable from the annotations.

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

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

The description is four sentences, front-loaded with the core search function, then downstream usage and two high-value behavioral caveats. There is no filler; every sentence contributes either scope, workflow, result-format, or language handling.

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, this is unusually complete: it covers ranking, card presentation, truncation behavior, language handling, and downstream workflow. The only residual gap is that the exact return envelope is not described explicitly, but compact cards, `summary_cut`, and `max_chars` behavior give enough guidance 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?

With 72% schema coverage and rich field descriptions, the schema already does heavy lifting. The main description adds global semantics the schema lacks: relevance-ranked matching by subject and the filter categories (country, CPV, status, deadline, value, region). Parameter descriptions further clarify edge cases like NUTS exclusion, value conversion, and multi-lot collapse.

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

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

The description opens with a specific verb and resource: 'Search open public tenders and EU grant calls by subject, ranked by relevance'. It names the filter dimensions and explicitly chains to sibling tools with 'then get_opportunity or read_document', making it clear this is the search step, not a retrieval step.

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

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

It gives clear usage context: use it to find notices worth a decision, then proceed to get_opportunity or read_document. It adds a practical constraint—search in the notice's own language and consult research_guide for the trade lexicon—but does not explicitly spell out when not to use this tool versus those siblings.

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 this is a non-read-only, open-world, non-idempotent but non-destructive write, and the description goes well beyond that by disclosing the consent protocol (ask before sending, confirmed=true), the authored_by distinction between the agent's own observation and the user's words, and what the response contains ('reference id'). It stops short of describing failure modes or rate limits.

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

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

Purpose is front-loaded and every sentence carries a rule an agent needs, but the paragraph is dense and runs several ideas (when to offer, consent, field guidance, reply handling) together in one block. It is efficient for its content yet not maximally scannable.

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 12 parameters, no output schema, and a consent-sensitive write, the description covers the required/optional split, the confirmation flow, the privacy boundary around the user's words, and what the caller should tell the user afterward. Nothing an agent needs to invoke this 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 adds policy meaning the schema does not carry: which fields go with which kind, that query is only sent with the user's OK, that contact_email is only for replies, and how message relates to what. That is real added context over the 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 first sentence names a specific verb and resource ('Send feedback about Victano to the team that builds it') and enumerates the accepted kinds, so an agent can distinguish it from every sibling (connect_*, get_*, list_*, search_*). No sibling overlaps this purpose.

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

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

Explicit when-to-offer triggers are listed (empty/wrong answer, user correction, missing workflow step, repeated manual step, unmet need), plus a restraint rule ('Offer once, in one sentence; the user's task comes first'). No alternative tool exists, and the description correctly treats this as the sole route for feedback.

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.