switzerland-parliament-mcp-server

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

Goes well beyond the annotations by disclosing non-obvious behavior: texts are 'automatically outlined when several fields exceed the disclosure budget', textFields returns complete fields even when large, and source text/HTML 'remain unchanged'. It stops short of covering error modes or the shape of the returned paging envelope, so not a full 5.

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

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

Front-loaded with the action and identifier formats, then section selection, then caveats — a sensible priority order. It is dense with semicolon-chained clauses, which costs a little readability but nothing is redundant.

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 6-parameter tool with full schema descriptions, readOnly/idempotent annotations and an output schema, the description closes the remaining gaps: identifier provenance, section choice, paging scope, and the outlining behavior that would otherwise surprise an 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 coverage is 100%, so the schema already documents every parameter and the baseline is 3. The description still adds scoping semantics the schema leaves implicit: textFields applies only to texts, limit/offset only to relationships, and the accepted businessId forms.

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?

Opens with a specific verb+resource ('Read a Swiss parliamentary business') and immediately scopes the accepted identifiers (canonical eight-digit businessId or exact published short number). It then enumerates the section modes, which makes it unmistakable against the search/list 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?

Gives explicit when-to-use routing per section (overview for metadata/sizes, texts for original text, relationship sections for paged data) and cross-tool guidance ('Use subjects to narrow chparl_search_transcripts'). It also states the constraint that paging applies only to relationships, preventing a common misuse.

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 readOnly/idempotent/openWorld, and the description adds genuinely non-obvious semantics beyond them: missing paid status means unknown, empty interests do not establish absence of conflicts of interest, overview is unpaginated while relationship sections paginate (effective max 100 with notice), and metadata labels follow the selected language. These are exactly the interpretive caveats an agent needs to avoid misreading the response.

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

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

Purpose is front-loaded and the pagination caveat comes second, so the highest-value information leads. It is dense and semicolon-heavy, packing several sections into one sentence, but nearly every clause earns its place with a behavior an agent would otherwise get wrong.

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 a full output schema present, the description need not describe return shapes, and it instead covers the interpretive risks (paid status unknown, empty interests ambiguity, pagination scope, language of labels). Combined with complete schema annotations, nothing essential for correct invocation 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?

Though schema coverage is 100% (baseline 3), the description adds meaning the schema does not: PersonNumber need not equal Person.ID, limiting applies only to relationship sections (omit for overview), and language governs the labels returned. These are genuine semantic additions rather than restatements.

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 verb and resource — read a Swiss Parliament member by PersonNumber — and immediately clarifies the non-obvious ID semantics (PersonNumber need not equal Person.ID). This is an unambiguous, single-purpose getter that an agent can distinguish from the sibling search/get tools by resource alone.

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 routes the agent among the four sections: overview for identity and all base affiliations without pagination, council_terms for historical terms, committees for published MemberCommittee rows, interests for declared interests. Only gap is it does not state when to prefer this over chparl_search_members (that hint lives in the schema's personNumber description, not the tool description).

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 readOnly/idempotent/openWorld, so the description earns credit for going further: it warns that an empty result does not prove no vote occurred, distinguishes member counts (delivered rows only) from groups mode (reads all published rows before totaling), notes Ständerat votes are excluded and the coverage starts in the 2003 winter session, and states unknown codes are retained. These are non-obvious data-fidelity caveats an agent could not infer.

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 core purpose and mode routing, with caveats after. The eight enumerated code meanings take up roughly a third of the text and largely restate decodable output, which is the one portion that does not clearly earn its space given an output schema exists.

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, three-mode, paged tool, the description covers mode selection, filter combinations, coverage limits, code interpretation, retention of unknown values, and pagination via nextOffset. Return-shape detail is left to the output schema, which is the right division of labor.

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 still adds value by explaining how mode interacts with filters as a workflow rather than isolated fields. It does not add syntax or format detail beyond the schema, but the mode-conditioned usage framing exceeds baseline.

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

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

Opens with a specific verb+resource ("Find Nationalrat roll calls") and immediately enumerates the three workflow modes, which no sibling offers. It references siblings only as ID sources (chparl_search_business, chparl_search_members) rather than stating an explicit this-not-that boundary, so differentiation is strong but not stated outright.

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?

Each mode is paired with its required and permitted inputs: "mode members with voteId for one paged roll call, or personNumber without voteId for member history", and "mode groups with voteId for complete decision counts". It also flags the combination constraints (voteId cannot combine with businessId/sessionId) so an agent can pick a mode without opening the schema.

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 readOnly/idempotent/openWorld, and the description adds non-obvious behavior: pagination via nextOffset must repeat the same topic, language, and dates; labels stay in the requested metadata language; unknown labels stay unknown rather than falling back. It does not discuss rate limits or return envelope shape, but the output schema covers the latter.

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 sentence, then the topic-routing clause, then operational notes; no filler. Dense but appropriate for an 11-value enum tool, though the longer trailing sentences about labels could be tightened.

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 paginated reference-dictionary tool with a full output schema and complete annotation coverage, the description supplies everything an agent needs: topic routing, the sessions-only date rule, pagination invariants, and label-language behavior. Return shape is left to the output schema, as allowed.

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 is 3; the description earns a bump by adding semantics the schema lacks — that dateFrom/dateTo are meaningful only for the sessions topic, and that offset continuation requires holding topic, language, and dates constant. It does not explain limit clamping, but the schema already does.

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?

Opens with a specific verb and resource ("List Swiss Parliament reference entries and source coverage") and then enumerates every topic value, so an agent knows exactly what class of data this returns. It does not name sibling tools, but the reference/dictionary nature is clearly distinct from the chparl_search_* and chparl_get_* 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?

Explicitly routes each topic to its use case: identifiers/coverage/languages for server explanations, statuses for the legacy/current snapshot, and the remaining topics for live dictionaries. It also states the key conditional constraint that "Date filters apply only to sessions," which prevents a common misuse.

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?

Goes well beyond the readOnly/openWorld/idempotent annotations by disclosing non-obvious behavior: newest canonical IDs come first, author searches omit the business total, committee searches page over role candidates and may return short pages without a distinct total, and metadata labels are never translated. These are exactly the quirks that would otherwise cause an agent to misread or re-page results.

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?

Five tight sentences: purpose first, then prerequisite/follow-up routing, then pagination rule, then the two search-mode caveats, then the localization caveat. No filler or repetition of schema content.

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 11-parameter, open-world search with an output schema, it covers everything an agent needs to call it correctly: code resolution, cursor discipline, result ordering, and the degraded-result cases. Return value explanation is rightly omitted since an output schema exists.

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%, including defaults, enum values, patterns and the maximum-vs-clamped limit nuance, so the schema already carries parameter meaning. The description restates the facet list and adds only marginal semantics (inclusive date bounds, published submitter label), so baseline 3 applies.

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

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

Names a specific verb (search) and resource (Swiss parliamentary business) and enumerates the exact facets that can be searched: title substring, published submitter label, type, status, session, submission dates, committee role. It also distinguishes itself from siblings by pointing to chparl_list_reference for code resolution and chparl_get_business for reading a returned businessId.

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 clear operational context: resolve codes with chparl_list_reference first, follow nextCursor only with unchanged filters, and use chparl_get_business to expand results. There is no explicit statement of when *not* to use this tool (e.g., versus chparl_search_transcripts for debate text), so it stops short of the top band.

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 readOnly, idempotent, and open-world, so the safety profile is covered. The description adds genuinely non-structured behavior: default activity filtering and the requirement to reuse the same filters when following nextOffset. It does not mention the byte-budget truncation of results, which is only visible in 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?

Four sentences, each carrying distinct information: scope, filter semantics, query semantics, cross-tool routing, and pagination. Nothing is repeated from the schema verbatim and the core purpose is front-loaded.

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

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

With nine optional parameters, full schema coverage, and an output schema, the description supplies what the structured fields cannot: filter-mode semantics, cross-tool routing, and pagination protocol. An agent can call and iterate this tool correctly from the description alone.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond it: the precise semantics of current/former/all activity filtering and the fact that query matches a substring of first, last, or official names rather than free text. Filter-to-reference-tool resolution is left to 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?

States a specific verb and resource ('Find ... Swiss Parliament affiliation records') plus the exact filterable dimensions (name, council, canton, party, parliamentary group). It also distinguishes itself from chparl_get_member by scoping this tool to search and routing detail lookups elsewhere.

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 membership modes ('current' default, 'former' selects inactive, 'all' omits the filter), how query substring matching works, and the handoff path: use personNumber with chparl_get_member for identity and terms. Pagination guidance ('Follow nextOffset with the same filters') closes the loop on repeated calls.

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 establish read-only, idempotent, open-world behavior, so the bar is lower; the description adds the return-mode behavior that annotations cannot express: metadata by default, full original passages with includeText, and full text when transcriptId is supplied. It also discloses the language caveat that metadata language never translates speaker text and that missing LanguageOfText stays unknown. It says nothing about failure modes or rate behavior, so not a 5.

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 sentences, front-loaded with purpose and the admission constraint before secondary details like the 20-subject cap and pagination. Some clauses are densely packed and slightly cryptic ('missing LanguageOfText remains unknown'), but no sentence is 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 13-parameter, zero-required tool with complex conditional constraints, the description covers admission rules, text-search preconditions, output-shape toggles, language caveats, and pagination. Return field details are rightly left to the output schema. Only error/edge behavior is unaddressed.

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 is 3; the description earns above baseline by articulating a one-of constraint the schema does not encode (required: 0) — at least one of business, subject, speaker, session, or date bound — and by pairing query with the 31-day window. It also flags the includeText default inversion for transcriptId, though much of that is duplicated in 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 first sentence names a specific verb (Find) and resource (Amtliches Bulletin passages) plus the full set of filterable dimensions, so the agent knows exactly what this returns. It is clearly distinguishable from siblings such as chparl_search_business or chparl_get_votes, which are not about retrieving passage text.

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 the minimum viable call ('Supply at least a business, subject, speaker, session, or date bound'), the extra precondition for text queries (sessionId or a closed range of at most 31 calendar days), and a concrete alternative path (select subjectId via chparl_get_business when a business has more than 20 subjects). It also closes the loop on follow-up calls ('Follow nextOffset with unchanged filters').

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