NeoDemos

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable context beyond that: it reveals the tool is a pure knowledge base without retrieval or database calls, has <10ms response, and includes a disclaimer about local variation in rules and procedures. It also details the structure of the return value, covering safety and performance traits.

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 structured into clear sections (when to use, when not, return values). Every sentence adds information, and the bullet-style listing improves readability. It is more verbose than minimal, but given the complex nature of the tool and lack of output schema, this is justified.

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?

There is no output schema, so the description fully details the return value: a markdown recommendation including target, speed, binding, legal basis, when/when-not, outcome type, college obligations, execution duty, typical processing time, and a template. It also includes disclaimers and links to alternatives, making the tool self-contained for 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?

Schema description coverage is 0%, so the description must compensate. It does not explain each parameter explicitly, but it provides examples of goals ('informatie, college ter verantwoording roepen, uitspraak/besluit, nieuw beleid') that map to 'doel', and discusses urgency and alternative instruments. However, it leaves 'onderwerp' and 'op_agenda' without clear guidance, so compensation is 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 clearly states the tool's purpose: it advises which council instrument fits the council member's goal, with a specific verb and resource. It explicitly distinguishes itself from sibling tools by stating when NOT to use it (for content questions or finding existing motions, use search tools).

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 'Gebruik deze tool wanneer' and 'Gebruik deze tool NIET wanneer' sections, including concrete scenarios and named alternative tools (zoek_raadshistorie, zoek_moties). This gives clear guidance on when to use this tool versus alternatives.

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

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

Annotations already mark readOnly/idempotent/non-destructive, and the description adds behavioral traits: deterministic, no LLM/DB, <10ms, maximum 10 comments for sanity reviews, grouping by severity, and speaking-time comparison at ~130 wpm. 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?

Though fairly long, the description is dense and well-structured: summary line, mode list, usage guidance, return format, and workflow position. Every sentence adds operational value; the 'Positie in de drafting-keten' section is especially useful.

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?

There is no output schema, so the description compensates by specifying markdown output with concrete improvement points grouped by severity, plus mode-specific outputs (e.g., rubric with 1-10 score for spreektekst). It also covers when not to use and where it fits among siblings, making the tool fully actionable.

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 burden; it thoroughly explains the `soort` modes and their different outputs, clarifies `tekst` as the handwritten/generated concept text, and `spreektijd_sec` is covered by the spreektekst-mode explanation ('duur-vs-spreektijd ... ~130 wpm'). This exceeds schema value.

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: 'Eén deterministische review-tool voor concept-teksten van een raadslid/fractiemedewerker.' It clearly distinguishes this review tool from drafting and search siblings by stating it is NOT for corpus searching (→ zoek_raadshistorie) and should be used after genereer_raadsstuk.

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?

Usage is explicit: 'Gebruik wanneer: het raadslid een concept heeft geschreven en wil weten wat scherper kan. NIET om corpus te doorzoeken → zoek_raadshistorie.' It also provides workflow position: call after genereer_raadsstuk, process findings, then save with sla_fractie_artifact_op.

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

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

Annotations already mark the tool as read-only and idempotent. The description adds meaningful behavioral context: 'Geen DB, geen netwerk' (no DB/network), missing fields are omitted cleanly ('nooit p. None'), graceful degradation when page metadata is absent, and a specified markdown return format. These details go beyond what annotations provide.

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 adds value: main function, special case for spreker+quote, missing-field behavior, metadata caveat, usage guidance, and return type. The structure front-loads the purpose and is well-organized without fluff.

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 8-parameter tool with no output schema, the description covers the main behavior, return format, and important caveats like page metadata dependency. However, the undocumented document_id and lack of a full parameter breakdown leave a minor completeness gap.

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 must compensate. It explains the spreker+quote combination and provides an example showing date, page, and paragraph, while stating that missing fields are omitted. However, not all parameters (e.g., document_id) are explained, leaving a gap for that field.

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 begins with a specific action: 'Formatteert een bronvermelding' (formats a citation) in a particular style, and distinguishes itself as 'de formatteerlaag' (the formatting layer) versus the separate corpus ontology (WS30). Sibling tools are for content generation and context, making this formatting tool's purpose clear and distinct.

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 explicitly states 'Gebruik wanneer: je een quote of bron netjes wilt vermelden met paginanummer/alinea' (use when you want to properly cite a quote or source with page/paragraph). It also notes that corpus-level precision is a separate ontology (WS30), providing a when-not. However, it does not explicitly name alternative sibling tools, only implies separation.

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 (readOnlyHint, idempotentHint, destructiveHint), the description discloses that the tool fetches structured meeting data itself, that it returns explicit validation errors for unknown IDs or missing agendas (never a plausible empty note), and that email delivery and cron are separate infrastructure. This adds significant behavioral context not present in structured fields.

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 detailed but every sentence delivers value: purpose, behavior, integration chain, validation, and return value. The structure is logical and front-loaded with the main outcome. It is longer than typical but appropriate for a complex hero-feature; the 'Positie in de keten' section is procedural and earns its place.

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 (4 parameters, integration with two other tools, no output schema), the description covers all necessary context: what it returns (markdown with legend + overview + detail blocks), how it behaves on errors, and exactly which inputs to derive from prior tools. The absence of an output schema is mitigated by the explicit return description.

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: it explains that meeting_ids come from lijst_vergaderingen, instructs to fill covered_topics and followed_committees with confirmed values or empty lists, and implies horizon via '~2 weken' and 'horizon_dagen'. However, the exact semantics of 'vandaag' (default null) and 'horizon_dagen' (default 14) are not fully specified, only implied, so a small gap remains.

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 'Stelt de fractienotitie samen', clearly stating the verb (compose) and resource (fractienotitie). It further specifies the output as an agenda-overview with color-coded bullets and per-agenda detail blocks, making it distinct from sibling tools like genereer_raadsstuk or adviseer_raadsinstrument.

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 'Gebruik wanneer: de gebruiker een fractienotitie/voorbereiding voor de komende vergaderingen wil' and provides a full integration chain: first call mijn_fractie_context, then lijst_vergaderingen, then pass meeting_ids. It also clarifies that the host only supplies meeting_ids, not markdown, which serves as a boundary for when to invoke this 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 already mark readOnly/idempotent/non-destructive; the description adds valuable beyond-annotation context: no DB/network, <10ms performance, placeholders for missing fields, graceful degradation to a base format + disclaimer when no gemeente overlay exists, and return type (markdown with RvO citation and disclaimer). This aligns with annotations and enriches them, so 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 well-structured and front-loaded: it opens with a one-sentence summary, then uses clear 'when/when-not' subheadings, followed by concise parameter explanations and a return value note. Every sentence adds necessary guidance for a 3-parameter, 7-type tool; no repetition of schema information or 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?

For a tool with no output schema and moderate complexity, the description fully covers purpose, selection criteria, parameter semantics, return value, and next-step integration into the drafting pipeline. It also clarifies edge cases (missing fields, missing overlay) and names sibling tools for disambiguation, making the description self-sufficient for selection and 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?

Schema coverage is 0%, but the description fully compensates: doc_type is explained with the seven allowed values, velden is described as optional and automatically filled with placeholders, and gemeente is clarified with its default ('rotterdam') and fallback behavior. This goes beyond the schema's bare type/required/default fields, giving an agent everything needed to construct valid inputs.

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 ('Genereert') and resource ('volledig opgemaakt, RvO-conformant concept voor één van de zeven raadsstuktypen'), clearly distinguishing this generation tool from siblings like adviseer_raadsinstrument (choosing instrument) and beoordeel_tekst (evaluation). It even names the seven doc_type values, making scope explicit.

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 'Gebruik deze tool wanneer' and 'Gebruik deze tool NIET wanneer' sections, citing exact alternative tools (adviseer_raadsinstrument, beoordeel_tekst) and conditions. It closes with a recommended next-step workflow (validate with beoordeel_tekst, then save with sla_fractie_artifact_op), making usage decisively 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?

With no annotations, the description carries the full transparency burden. It discloses performance (<50ms), server-side caching, per-call calculation of the `today` field, and session-invariance. It also states the return format is markdown. However, it does not mention error behavior when the database is unreachable or any access restrictions, leaving a minor gap.

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 well-structured with a main purpose, bullet-pointed usage scenarios, and a return format summary. It is front-loaded with the core purpose and performance. While it is longer than necessary, every sentence provides actionable guidance and no filler, earning a 4 rather than a 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 a context-primer tool with no parameters and no output schema, the description is remarkably complete. It details the exact sections returned, explains the `today` field, gives historical examples, mentions known limitations, and directs users to recommended tool sequences. This leaves little ambiguity about when and how to use the tool.

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 tool has zero parameters, and the schema reflects that with no properties. The baseline for 0-parameter tools is 4, and the description appropriately clarifies that it takes no inputs and instead focuses on the contextual value it provides. No additional parameter semantics are needed.

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 states it returns a structured primer containing municipalities, document types, current aldermen, coalition history, limitations, and recommended tool sequences. This goes far beyond a simple verb+resource, providing a detailed inventory of the tool's output. It clearly distinguishes itself from siblings like verzamel_context by framing itself as a session-start primer.

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 dedicated 'Gebruik deze tool wanneer' and 'Gebruik deze tool NIET wanneer' sections with concrete conditions, such as starting a new session, needing a current date, handling historical votes, and avoiding redundant calls. It also references alternative tool sequences, making the usage context 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 destructiveHint=false. The description adds significant behavioral context beyond these: it explains opt-in parameter fetching (only requested sources are fetched to keep the call fast), cache-first behavior, and network calls for some sources. Critically, it discloses refusal/abstention behavior: the cube engine 'WEIGERT illegale ops' or 'ONTHOUDT ZICH' rather than returning incorrect figures, and it provides integrity guardrails against hallucinated CBS table IDs. This is rich, non-redundant transparency.

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-structured with clear headers, bullet lists, and bolded source names. It is front-loaded with the core purpose. Some repetition exists (e.g., the warning about CBS StatLine lacking per-gemeente health data appears both in the RIVM section and guardrail #2), which adds emphasis but could be trimmed. Overall, it is appropriately sized for the tool's complexity, but not maximally concise.

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 high complexity (22 parameters, multiple data sources, no output schema), the description is remarkably complete. It covers every source with usage details, parameter constraints, data-freshness/network behavior, and even states the return format ('markdown met een sectie per gevraagde bron'). Guardrails for data integrity ensure safe usage. No critical gaps are apparent.

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 22 parameters and 0% schema description coverage, the description carries the full burden of explaining parameters. It does so in depth: each parameter group (cbs_beleidsgebied, cbs_metric, cube_query, iv3_kerncijfers_gemeenten, rivm_gezondheid, instrument_doel) receives examples, constraints, and mutual exclusions (e.g., 'precies één van beide' for cbs_compare_regions vs cbs_compare_periodes). It clarifies defaults (cbs_gemeente default GM0599), explains how to use cbs_extra_filters and cbs_top for Iv3 tables, and describes the cube_describe/cube_query workflow. This far exceeds schema-provided meaning.

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 clear, specific verb+resource statement: 'Bundelt server-side meerdere achtergrondbronnen voor een onderwerp in één antwoord' (bundles server-side multiple background sources for a topic into one answer). It enumerates distinct data sources (CBS, RIVM, IV3, raadsinstrument) and explicitly differentiates itself from sibling tools by noting that heavy corpus retrieval (zoek_raadshistorie / zoek_moties) is not bundled here. This distinguishes it from get_neodemos_context and other 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?

Provides explicit 'Gebruik wanneer' guidance and names alternatives: use this tool for societal figures and raadsinstrument advice in one call; for heavy corpus retrieval use zoek_raadshistorie/zoek_moties. It also gives strong exclusionary warnings: use iv3_kerncijfers_gemeenten instead of CBS StatLine for per-gemeente finances, and rivm_gezondheid instead of cbs_beleidsgebied for health data. This far exceeds typical when-to-use guidance.

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