eu-parliament-mcp-server

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

Goes well beyond the readOnly/idempotent annotations: it discloses that missing end dates do not imply current membership, that a missing detail returns success with found=false, and how snapshot_changed invalidates pagination state. These are non-obvious semantics an agent could not infer from the schema.

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

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

Front-loads purpose and section behavior, then pagination, then failure/discovery semantics — a sensible order with no filler. Some sentences are very compressed (e.g. 'Missing detail succeeds with found false'), which slightly taxes parsing without wasting space.

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 an output schema present, return shapes need not be explained, and the description still covers the operationally risky parts: mode selection, pagination continuation and invalidation, and the found=false failure mode. An agent has everything needed to call this 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 100%, so baseline would be 3, but the description adds real meaning: the section switch between overview and memberships, and the coupling of snapshot to offset (required above 0, restart at 0 without snapshot after snapshot_changed). It does not restate limit/language syntax, which the schema already handles.

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

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

States a specific verb and resource (read MEP identity or membership history) and enumerates exactly what is covered: committee, delegation, and political-group records. It also distinguishes itself from the sibling lookup tool by pointing to euparl_search_meps for ID discovery.

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?

Clearly routes between the two modes (default overview for identity/count, memberships for the paged history) and names euparl_search_meps as the way to obtain an ID. It lacks an explicit 'when not to use this' clause, but the alternatives and conditions are stated.

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 readOnly/openWorld/idempotent; the description adds substantive behavior well beyond that: available=false vs available=true semantics for missing vs published-empty arrays, snapshot_changed handling, decision_not_found on absent decisions, and that IDs may remain unresolved. This is exactly the safety and state-contract context the annotations cannot 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?

There is almost no wasted clause, but the entire definition is one dense semicolon-chained run with no sentence or bullet structure, and it leads with the non-default sittings mode before revealing that decisions is the default. Content density is justified; readability is not.

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 13-parameter, four-mode tool this is unusually complete: input requirements per mode, paging/snapshot lifecycle, error outcomes (decision_not_found, snapshot_changed), and availability semantics are all covered, and an output schema exists so return shape need not be restated.

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 still adds meaning beyond the schema: mep_id returning independent recorded and intended positions 'without a roster lookup' and the caveat that empty positions do not prove absence from the vote, plus document_id descendant matching before paging. The resolve_names/roster_term relationship is reinforced rather than newly explained, keeping it from a 5.

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

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

The description names the resources precisely (sittings, decisions, voters) and specifies a verb per mode, and it is clearly the plenary-vote tool among siblings like euparl_get_mep and euparl_search_documents. It never explicitly states what it is not or names a sibling, and it opens with the least-common mode (sittings) in a way that can momentarily obscure that 'decisions' is the default.

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-use per mode: 'Mode decision requires decision_id', 'Mode voters requires decision_id and one position', 'sittings with mode sittings and year'. It also states hard exclusions (rejects nondefault paging and snapshot for decision mode) and the resume strategy (page.next_offset with snapshot, restart at 0 after snapshot_changed).

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 readOnly/idempotent/openWorld annotations it discloses the paging contract and snapshot coupling, that missing detail returns found false rather than erroring, that historical participation groups stay historical, and that linked files are linked rather than parsed. These are non-obvious behaviors an agent could not infer from annotations or schema alone.

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 purpose, then paging, then error/alternative handling – a logical order for a six-parameter read tool. The semicolon-chained, telegraphic phrasing (e.g. "Historical participation groups remain historical") is compact but occasionally terse enough to slow parsing.

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

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

Covers everything an agent needs: sectioning, paging invariants, missing-detail behavior, and sibling routing. Return shape need not be described because an output schema exists, and the readOnly annotations already carry the safety profile.

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 100% schema coverage the baseline is 3, but the description adds real meaning: the snapshot/offset relationship across a single selected collection and the overview-versus-section tradeoff between scalars and complete paged items. It does not explain the local-versus-returned page limits or the language fallback beyond what the schema already says.

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

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

States a specific verb and resource plus the exact sub-resources readable (title, stage, events, participants, documents), mapping directly onto the section enum. It also names the sibling it is not (euparl_list_procedures for discovery), so an agent can choose between them without opening schemas.

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 explains the default overview versus selecting a collection section, how to continue paging (page.next_offset plus the returned snapshot), and the reset rule (offset 0 without snapshot when the collection changes). It also routes to euparl_list_procedures for reference discovery and euparl_search_documents mode get for linked documents.

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, open-world behavior, so the bar is lower, and the description still adds real operational context: a 10000-result exposure cap plus 'continue with page.next_offset when present, otherwise narrow process_type'. That is a concrete pagination and narrowing strategy an agent could not infer from the annotations. It stops short of describing record shape, but the output schema covers that.

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?

Four short sentences, each load-bearing, with the core purpose front-loaded and pagination last. Slightly dense telegraphic phrasing ('Search exposes...') but 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?

For a filtered list tool with a 100%-documented schema, an output schema, and safety annotations already in place, the description covers the remaining gaps an agent needs: what is returned, how to get detail, how to resolve codes, what filters are unavailable, and how to page past the cap.

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 limit, offset, language, and process_type are already fully documented, including the 100 effective maximum. The description reinforces process_type's dependency on the reference lookup and rules out filter parameters that do not exist, but adds no syntax or format detail beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb and resource (list procedure references) and immediately scopes it: it returns references only, not titles/stages/participants. It explicitly names euparl_get_procedure as the tool that yields the richer record, so an agent can distinguish the two without opening either schema.

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

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

Gives explicit routing: use euparl_get_procedure with a returned procedure_id for detail, and euparl_list_reference topic procedure_types for valid codes. It also lists what this tool cannot do (no keyword, year, committee, or stage filter), which prevents wasted calls more effectively than a positive description alone.

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 establish read-only/idempotent/open-world behavior, and the description adds substantial context beyond that: get rejects list filters and nondefault paging, empty answers mean no answer relation was published, term omission triggers candidate verification and requires exactly one match, and canonical IDs resolve directly. These are precisely the operational quirks an agent needs.

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 main capabilities and then layers constraints without wasted words. It is dense and mostly earns its sentences, though the single-paragraph format makes some mode-specific rules harder to scan than a short bulleted split would.

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 an output schema and rich annotations, the description covers the remaining gaps: dual-mode behavior, pagination continuation, disambiguation rules, supported work_type lookup, and the absence of keyword/author search. Nothing essential for calling this 8-parameter, two-mode tool correctly 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 schema already documents every parameter in detail. The description adds some workflow nuance (human citation format, term disambiguation, page.next_offset) but does not add much parameter-level meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description names the resource (parliamentary questions), the two operations (list by year/work_type, get by question_id), and the extra payloads available in get mode (metadata, source-file links, published answers). It also explicitly rules out keyword/author/addressee search, which distinguishes it from search-oriented siblings without needing to name them.

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 mode selection rules: default list discovers questions; get requires question_id and forbids year/work_type. It routes the agent to euparl_list_reference for work_type codes and explains how to continue pagination with page.next_offset. It also covers the term-disambiguation workflow and when to supply term versus omitting it.

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

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

Annotations already cover safety (readOnly, idempotent, openWorld), and the description adds real behavioral detail on top: an effective page cap of 20 for organizations versus 100 for other topics, the repeat-with-page.next_offset paging recipe, the meaning of found=false on ordered items, and the caveat that absent end dates do not imply current status. The snapshot remark is opaque without prior context and is the one weak disclosure.

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 resource enumeration is correctly front-loaded, but the remaining sentences are compressed to the point of ambiguity — 'Choose organizations with organization_ids' reads awkwardly and the closing 'do not require snapshots' clause is cryptic. Information density is high with little padding, yet parse effort is higher than it should be.

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

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

With an output schema present, return-value explanation is unnecessary, and the description closes the remaining behavioral gaps: paging, per-topic caps, the organizations special case, and the interpretation of missing data. An agent can invoke this correctly from the definition alone, bar the unexplained snapshot reference.

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; the description mainly restates what the schema already declares (organization_ids required for organizations, 20-per-page cap, page.next_offset). It does add the operational note that the same ID list must be re-supplied across pages while order and duplicates are retained, but that is largely duplicative of the structured fields.

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 ('List') and enumerates the concrete resource families covered: codes, identifier formats, historical committees/political groups, coverage limitations. That is far more informative than the title, though it never names how it differs from the sibling get_/list_ tools that return actual parliamentary entities rather than reference data.

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 a clear conditional rule — use the organizations topic together with organization_ids to resolve IDs into names and dates, and it implies other topics take no IDs. What is missing is any explicit statement of when an agent should reach for this reference tool instead of euparl_list_procedures or euparl_search_documents, so the routing guidance is contextual rather than comparative.

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 readOnly/openWorld/idempotent annotations, the description discloses important behavior: get returns links rather than extracted full text, detail preserves specific ID fields, unrelated missing-record and upstream-error outcomes remain ordinary, and document relations never imply procedure links. It also states the 10,000-result cap and page.next_offset continuation rule.

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 front-loads purpose and mode behavior, and almost every sentence carries operational information. Some clauses are compressed to the point of being cryptic, notably the detail/relations sentence, but there is little obvious 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 14-parameter, two-mode tool with rich schema coverage, an output schema, and safety annotations, the description covers the essential decision points: mode choice, family-specific filters, work_type lookup, pagination limits, detail output nature, and non-procedure relation semantics. Remaining gaps are minor and largely covered by structured 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 description coverage is 100%, so the baseline is 3. The description adds cross-parameter meaning beyond the schema: text/title/sitting_date/related_process_id are adopted-texts-only, committee supports term but not year, plenary supports year but not term, and get mode rejects source and all search filters.

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 set: searching adopted texts, committee documents, or plenary documents, and retrieving metadata/source links via get mode. It clearly separates search from get and names the document families, though it does not explicitly contrast itself with sibling tools such as euparl_search_speeches or euparl_get_procedure.

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 strong mode guidance: search discovers records, get requires document_id and rejects source plus search filters. It also states which filters apply to which families (adopted_texts/committee/plenary) and points to euparl_list_reference for work_type codes, leaving only sibling-level alternatives implicit.

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 readOnly/idempotent/openWorld annotations, the description discloses important operational behavior: snapshot-based paging, restart behavior after snapshot_changed, complete-roster name matching before paging, and empty-match success with guidance. It also clarifies that country and group are roster context, not voting-date affiliation.

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 front-loaded and purpose-first, with no wasted filler. Each clause carries operational meaning relevant to a nine-parameter search tool.

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 nine parameters, existing output schema, and safe read-only annotations, the description covers the remaining decision-relevant behavior: filtering scope, term semantics, pagination/snapshot handling, empty results, and when to use the detail sibling. Nothing essential for correct invocation appears 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 description coverage is 100%, so the schema already documents all nine parameters and the baseline is 3. The description adds useful semantic context around term omission, name-token normalization, roster-context filtering, and snapshot continuation, though it does not add meaning for every parameter beyond the 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 uses a clear verb-resource pair, 'Find MEPs', and lists the supported filters, making the tool's purpose immediately identifiable. It also distinguishes the lookup role from the detail-oriented sibling by saying to read identity and membership history with euparl_get_mep.

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 explains how term omission versus explicit term selection behaves, how name matching works, and how country/group filters should be interpreted. It also directs agents to the appropriate sibling for identity/history and gives a clear rule for pagination continuation versus restart after a snapshot change.

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 read-only, idempotent, and open-world behavior. The description adds valuable context beyond that: it discloses that get mode rejects search filters and nondefault paging, that search exposes at most 10000 results, and that pagination should continue with page.next_offset when present. These are concrete behavioral traits an agent needs.

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 core purpose and mode distinction. Every sentence carries useful information, though it is somewhat dense and could be slightly more concise. Overall structure is logical and efficient.

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 12 parameters, two modes, pagination, and the existence of an output schema, the description covers everything an agent needs: mode behavior, defaults, result limits, how to continue pagination, and where to find related data (documents, reference codes). No critical gaps remain.

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 schema already documents all 12 parameters in detail. The description mentions some parameter names (term, speech_id, text, title, person_id, activity_type, sitting_date) but adds little beyond what the schema provides. The inter-parameter constraints it mentions (e.g., get rejects search filters, sitting_date_end requires sitting_date) are also covered in the schema. Baseline 3 is appropriate.

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 (search) and resource (speech activities), scopes it to parliamentary terms 9 or 10, and distinguishes it from sibling tools by naming euparl_search_documents and euparl_list_reference. It also clarifies that text and title search return activity metadata, not transcripts, which further differentiates from document search.

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 clearly describes when to use search mode versus get mode with speech_id, and directs the agent to euparl_search_documents for source files and euparl_list_reference for activity_type codes. It also gives pagination guidance (continue with page.next_offset when present, otherwise narrow filters). No explicit exclusions are given, but the alternatives and conditions are clear.

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