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?

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?

Annotations cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds substantial context beyond them: sources are opt-in to keep calls fast, CBS/RIVM layers are cache-first and never vector-embedded, the CBS path is a network call, and the cube engine deterministically refuses illegal aggregations or abstains on unknown members rather than emitting wrong figures. The guardrails section further warns against hallucinating table IDs.

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?

It is long but well structured — core purpose front-loaded, then one bullet per source, then a guardrails list — which suits a 22-parameter orchestrator. It loses a point for redundancy: guardrail items 2 and 3 restate caveats already given verbatim in the CBS and Iv3 bullets.

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 highly complex, 22-parameter aggregator with no output schema, the definition supplies source-by-source routing, parameter semantics, integrity guardrails, and an explicit return description ('markdown met een sectie per gevraagde bron'). An agent has everything it needs to select sources and call 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 coverage is 0%, so the description carries the full burden, and it documents the large majority of the 22 parameters with concrete examples and semantics (cbs_beleidsgebied values, cbs_metric, cube_describe→cube_query flow, iv3_taakvelden BBV codes, cbs_gemeente default GM0599, cbs_top default 100). However, instrument_urgentie and instrument_op_agenda receive no explanation at all, and the internal shape of cube_query is only loosely sketched.

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 states a specific verb and resource — bundling multiple background sources for a topic into one answer so the agent needn't chain tools — and immediately scopes the behavior (opt-in, only requested sources). It explicitly distinguishes itself from siblings by naming zoek_raadshistorie / zoek_moties as the tools for heavy corpus retrieval that are deliberately not bundled.

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 'Gebruik wanneer' line states the triggering condition (substantiate a topic with societal figures and/or determine which raadsinstrument fits), and it names the alternative tools for the excluded use case. Each source bullet further says exactly which parameter to supply for which question type (e.g. use rivm_gezondheid, not cbs_beleidsgebied, for health data; use iv3_kerncijfers_gemeenten instead of vraag_begrotingsregel for cross-municipality comparisons).

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