NeoDemos

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description is fully consistent with them. The description adds genuine value beyond the annotations by disclosing execution characteristics — 'Pure kennisbank: geen retrieval, geen DB-call, <10ms' — plus the exact return structure in markdown. It also clarifies that returned legal deadlines are local-RvO specific and must be verified, which is important behavioral context. This exceeds what structured annotations convey.

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

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

The description is long but well-organized into clear front-loaded sections: what it does, when to use, when not to use, and what it returns. Every major section adds value and the formatting makes it scannable. It loses a point for some redundancy — the doorlooptijd point is made in the intro, then repeated in the 'when to use' bullet about schriftelijke vragen — so not every sentence strictly earns its place, but overall this is efficient for the information load it carries.

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 and 0% parameter description coverage, the description carries a heavy burden and largely rises to it: it fully specifies the return structure (instrument, alternatives and goals, outcomes, legal basis, lead time, process, RvO template, disclaimer). The main gap is that two parameters ('urgentie' value options and 'op_agenda' semantics) are not explicitly described. But for advising a tool, the core use, outcome types, and verification warnings are all present — the only residual completeness of an agent's correct use.

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 carries the full burden for parameter meaning. It compensates well for the two core parameters: 'doel' is effectively enumerated via the goal examples (informatie, college ter verantwoording roepen, uitspraak/besluit, nieuw beleid) and 'urgentie' is given meaning through the discussion of lead times and fast vs. slow instruments. However, 'onderwerp' and 'op_agenda' receive virtually no semantic explanation, so the compensation is only partial.

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+resource pair ('Adviseert welk raadsinstrument past bij wat het raadslid wil bereiken') that defines the tool's exact purpose: matching a council member's goal to the right legal instrument. It immediately distinguishes itself from the listed siblings (text generation, context gathering) and even names alternatives for excluded cases (zoek_raadshistorie / zoek_moties). The purpose is unmistakable even 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?

The description gives an explicit 'Gebruik deze tool wanneer' list (four concrete situations) and a 'Gebruik deze tool NIET wanneer' list that names alternative tools (zoek_raadshistorie, zoek_moties) and the conditions that select them. It even includes a specific trigger — when about to advise 'stel schriftelijke vragen', check here first — which is exactly the kind of routing guidance that helps an agent pick correctly.

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?

Even though annotations already carry readOnlyHint, idempotentHint, and destructiveHint, the description adds meaningful behavioral facts: it is deterministic, does not use an LLM or database, runs in <10ms, and returns results grouped by severity. Nothing contradicts 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 longer than average, but each section earns its place: mode enumeration, recommended usage, output description, and workflow position are all useful. The bullet-list layout makes it scannable, so the length feels justified rather than 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?

This is a multi-mode tool with no output schema, so the description must carry a heavier explanatory load. It does: it explains what each mode returns, the severity grouping, the spreektekst rubric details, and the RvO format types. Given the tool's complexity, the description is remarkably complete.

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

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

With 0% schema description coverage, the description compensates well for 'soort' by listing all valid modes (vragen, notitie, spreektekst, RvO formats) and explains how the mode changes behavior. It does not literally map 'spreektijd_sec' to the spreektekst duration estimate, though the 130 wpm mention implicitly connects it. 'tekst' is obvious but not explicitly described.

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 explicitly names the tool as a deterministic review tool for concept texts of a council member/employee and enumerates the exact review modes. It also distinguishes itself from sibling tools by placing it in the drafting chain (after genereer_raadsstuk) and explicitly saying it is not a corpus search 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 states clearly when to use it (when a concept text has been written and the user wants sharpening suggestions), when not to use it (not for corpus search, pointing to zoek_raadshistorie), and even gives the workflow position: call it after genereer_raadsstuk, then save with an artifact tool. This exceeds normal usage guidance.

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 read-only/idempotent annotations, it discloses that there is no DB or network access, that missing fields are cleanly omitted (never 'p. None'), that page numbers degrade gracefully when metadata is absent, and that the result is a Markdown string. This is substantial behavioral context beyond annotations, with 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 front-loaded with the purpose and example, then uses short labeled sections for the metadata caveat, usage condition, and return value. Every sentence adds useful behavioral or scoping information; nothing is redundant with the 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?

For a side-effect-free formatter with rich annotations, it covers output type, missing-field behavior, metadata dependency, and when to use it. The main gap is the undocumented `document_id` parameter, which prevents full completeness; otherwise an agent has enough information to invoke the tool correctly.

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

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

Schema description coverage is 0%, so the description carries parameter meaning. It explains how `spreker`, `quote`, `partij`, `pagina`, `alinea`, `bron`, and `datum` appear in the formatted result and how omitted fields are handled. However, `document_id` is never mentioned and date/page formats are not specified, so compensation is incomplete.

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 a precise action ('Formatteert een bronvermelding') and gives a concrete output example with page number and paragraph, plus a separate full quote-attribution template. It also scopes the tool as the formatting layer versus separate corpus-level ontology, so it is clearly distinguished from content-generation siblings.

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 has an explicit 'Gebruik wanneer' condition: use it to present a quote or source with page/paragraph. It also warns that page metadata must exist in the source and that corpus-level sentence/paragraph precision is out of scope. It does not explicitly compare against sibling tools, but the stated usage context is clear.

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 annotations (readOnly, idempotent, non-destructive), the description discloses significant behavioral details: it internally fetches structured meetings and agendas, raises explicit validation errors for unknown IDs or missing agendas, never returns a plausible empty note, and clarifies that email delivery and cron scheduling are separate infrastructure. This fully informs the agent of the tool's internal behavior and failure modes.

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 relatively long, but it is well-structured with clear sections: core function, chain position, usage condition, and return format. The key purpose is front-loaded in the first sentence. While a few phrases (like the parenthetical on Erik's hero-feature) could be trimmed, the structure earns a 4 for being organized and 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?

Given the complexity of the tool (4 parameters, nested user object, no output schema), the description is remarkably complete. It covers the return format (markdown with legend, overview, and detail blocks), error handling, the necessary preceding calls, and the exact input sources. An agent has all the information needed to invoke this tool correctly.

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

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

While the schema has no descriptions for top-level parameters (0% coverage), the description compensates by explaining the key ones: 'meeting_ids' are the selected 'vergadering_id' values from 'lijst_vergaderingen', and the 'gebruiker' object's fields 'covered_topics' and 'followed_committees' should be filled with confirmed values or empty lists, never invented. It does not explicitly explain 'vandaag' or 'horizon_dagen', but these have defaults and are self-explanatory. The description adds meaningful meaning beyond the bare 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?

The description clearly states the tool composes a faction note ('Stelt de fractienotitie samen') and details what that includes: an agenda overview for the next ~2 weeks on the user's portfolio, with status bullets and detail blocks. It is unambiguous about the resource and action, and the detailed explanation distinguishes it from the sibling tools (e.g., 'genereer_raadsstuk' is for drafting council documents, while this is for preparing a briefing).

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 states when to use: 'Gebruik wanneer: de gebruiker een fractienotitie/voorbereiding voor de komende vergaderingen wil.' It also provides a precise workflow: call 'mijn_fractie_context' first, then 'lijst_vergaderingen' with specific parameters, and pass the resulting IDs as 'meeting_ids'. This leaves no ambiguity about the calling sequence and context.

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 pure generation behavior with no DB/network access and <10ms latency, default Rotterdam overlay behavior with graceful degradation, and the placeholder substitution mechanism for missing fields. This meaningfully complements the existing readOnly/idempotent/destructive annotations and adds concrete behavioral constraints.

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 organized with clear bullet sections and remains information-dense. Every sentence adds value, though the length could be slightly trimmed without loss.

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?

Despite sparse schema and no output schema, the description covers return format (RvO-compliant structure with disclaimer), parameter semantics, exclusions, and downstream validation steps. An agent has everything needed to select and invoke the tool correctly.

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

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

With 0% schema coverage, the description fully compensates: it explains doc_type choices, optional velden semantics with placeholder behavior, and gemeente overlay defaults. Each parameter receives concrete guidance beyond raw schema property names.

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 a specific action (generate a fully formatted, RvO-compliant council document), lists the seven supported document types, and explicitly distinguishes itself from sibling tools like adviseer_raadsinstrument and beoordeel_tekst. An agent can clearly identify what this tool does and what it does not do.

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 provides explicit when-to-use conditions, including prior use of adviseer_raadsinstrument polluted advice and reuse scenarios. It also gives clear when-not-to-use guidance with named alternatives (beoordeel_tekst for content review and format validation).

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=true, idempotentHint=true, destructiveHint=false, so the safety profile is fully covered. The description adds valuable behavioral context beyond this: the tool is cheap (<50ms), server-side cached, and returns a 'structured primer' with specific content sections. It also explains the dynamic 'today' field is computed per call. This adds context beyond the annotations without contradicting them.

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 moderately long but well-structured: a concise summary of outputs and performance, followed by clear use-case bullet points and explicit non-use cases. Some redundancy exists (returns-line repeats the content summary) but the structure is clear and 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?

The description covers what the tool returns, when to use it, when not to use it, and notes the cheap/cached nature. With zero parameters and a rich output description, this is complete for an agent to select and 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?

There are zero parameters, so the schema carries no burdenable weight. The description fully describes what the tool returns, which is the only relevant semantic information for a no-parameter call. Baseline 4 for zero params is appropriate, and the description goes further by specifying the markdown structure and content areas.

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 verb ('Retourneert', 'Gebruik') and a clear resource: a structured primer containing available municipalities, document types, current Rotterdam wethouders, coalition history, limitations, and recommended tool sequences. It distinguishes itself from siblings by framing itself as a context/session initialization tool rather than a retrieval, generation, or review tool. The explicit 'Gebruik deze tool wanneer' and 'Gebruik deze tool NIET wanneer' sections make the purpose and boundaries unambiguous.

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 provides explicit when-to-use and when-not-to-use criteria, including concrete triggers like 'new session', 'need current date', 'historical vote question', and 'unsure of tool sequence'. It also states when NOT to use it (when context already known or already fetched in same session). This is exemplary usage guidance.

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?

With annotations already declaring readOnlyHint=true, the description goes far beyond by disclosing cache-first behavior, network-call timing, opt-in parameter semantics, deterministic cube-engine compilation, and explicit refusal/abstention behavior on illegal operations. It adds critical data-integrity guardrails (never cite an unverified CBS table-ID, state unavailability honestly) and anti-Simpson rollup coverage flags. No contradiction between the read-only annotations and the gathering behavior.

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 text is very long, but the complexity (22 parameters, 6 distinct data sources, no output schema) justifies the length. It is well-structured with bolded source headers, bullet lists, and prominent 'LET OP' / 'KRITIEKE GUARDRAILS' callouts that front-load the critical caveats. The core purpose is front-loaded in the first sentence; a slightly tighter pass on the RIVM/guardrail duplication would push this to 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?

For an orchestrator of this scale — 22 params, 6 sources, zero schema coverage, no output schema — the description is remarkably complete. It states the return format (markdown with a section per requested source), documents source limitations (grootteklasse vs per-gemeente), provides concrete parameter schemas for complex fields (cube_query as a dict), and covers data-integrity behavior. The only omissions are a few rarely-used parameters and the required onderwerp field, which is self-evident from context.

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?

Despite 0% schema description coverage, the description documents nearly all 22 parameters with concrete examples: cbs_beleidsgebied (with sample values 'wonen', 'inkomen'), cbs_zoekterm/cbs_tabel_id/cbs_perioden/cbs_extra_filters/cbs_top, cbs_metric with sample 'woningvoorraad_per_1000_inw', cbs_compare_regions vs cbs_compare_periodes ('precies één van beide'), cbs_rollup_region, cube_describe/cube_query, iv3_kerncijfers_gemeenten/iv3_jaar/iv3_verslagsoort/iv3_taakvelden with BBV-code mapping, rivm_gezondheid, and instrument_doel. Only minor gaps: onderwerp (required) and instrument_urgentie/instrument_op_agenda lack explicit documentation.

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 states a specific verb (bundelt) and resource (meerdere achtergrondbronnen) — it aggregates server-side context sources for a topic in one call so the agent need not chain tools. It clearly distinguishes from siblings by explicitly naming what it is NOT (zoek_raadshistorie / zoek_moties are excluded deliberately) and routing financial comparisons to iv3_kerncijfers_gemeenten over vraag_begrotingsregel.

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 'Gebruik wanneer' section with the exact trigger conditions (maatschappelijke cijfers staven and/or raadsinstrument-advies in one call), plus explicit exclusions with named alternatives for heavy corpus retrieval (zoek_raadshistorie / zoek_moties). For every source it states when to prefer it over alternatives, e.g., 'GEBRUIK DIT voor elke vraag over levensverwachting — NIET cbs_beleidsgebied'.

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