sweden-parliament-mcp-server

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

Annotations already declare readOnly/idempotent/openWorld, so the extra burden is modest; the description still adds real value by disclosing pagination/continuation behavior and the consolidated-vs-historical SFS caveat, which an agent could otherwise get wrong.

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?

Three sentences, front-loaded with what is returned, then the paging mechanism, then the SFS caveat. Dense but every sentence carries information; no 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?

With an output schema and full parameter documentation, the description only needs to cover the paging model and the SFS interpretation caveat, both of which it does. Revision-conflict semantics are left entirely to the schema, a minor 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?

Schema coverage is 100%, so baseline is 3, but the description adds operational meaning the schema does not: that sections can be selected and that continuation calls are the mechanism for long documents. It still leaves the offset/length and sectionLimit interplay 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?

Specific verb ('Read') plus resource ('document') and an enumeration of what is returned (status, decisions, linked records, text). It implicitly contrasts with riksdag_search_documents by dealing with a single identified document, and the SFS note flags a distinct content type, but it does not explicitly name a sibling.

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?

Explains when to select sections, when to follow continuation calls for long reports, and warns that SFS text is consolidated rather than point-in-time. Missing an explicit 'use riksdag_search_documents first to obtain a documentId' routing statement, though the schema supplies 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 read-only, idempotent, and open-world behavior, so the description's added value is the domain caveat that assignment dates preserve source precision and do not establish historical sitting status. That is genuinely useful interpretation guidance beyond the annotations, though pagination/revision behavior is left to 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?

Two short sentences with the core purpose front-loaded and the interpretive caveat second. Every sentence earns its place with no 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?

An output schema exists and the annotations plus full parameter coverage carry most of the burden, so the description only needs purpose and caveats. It supplies both, though it could note that revision supports paging continuity to be fully self-contained.

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 all four parameters, including revision and assignment paging, are already documented in structured fields. The description adds no parameter-level detail beyond the schema, which is the expected 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?

States a specific verb and resource ('Read one member register entry and assignment history') and constrains the lookup to an exact member ID, which implicitly separates it from riksdag_search_members. It does not name the sibling explicitly, so a 4 rather than a 5.

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?

'By exact member ID' implies the caller must already have an ID, and the schema notes it comes from riksdag_search_members, so usage context is present but indirect. There is no explicit when-to-use/when-not statement or named alternative in the description itself.

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 annotations already establish a safe, idempotent read, while the description adds important behavioral caveats: report party groups are complete, continuation calls must be followed, and empty vote rows do not prove acclamation. It also warns that main votes do not include every ballot round, which is material context beyond 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 dense but front-loaded, starting with the core resource and then covering mode requirements and caveats. It remains appropriately sized for a 14-parameter tool, though the mode-specific clauses are packed tightly into a single paragraph.

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 annotations, a full input schema, and an output schema present, the description supplies the remaining decision-critical context: mode requirements, ballot behavior, continuation expectations, and vote completeness limitations. Nothing essential for correct invocation appears to be 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 14 parameters in detail. The description reinforces key requirements and continuation behavior but does not add substantial parameter semantics beyond what the schema field descriptions provide.

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-resource pair: reading authoritative report decisions, party main-vote groups, or a member’s session main votes. It also clearly separates the two supported modes, so an agent can distinguish this tool from document, member, and speech search 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 gives concrete mode requirements: report mode needs report or documentId, member mode needs memberId, and individual ballots require ballots=true with an explicit point. It does not explicitly compare against sibling tools, but the mode-specific use conditions are otherwise 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 readOnlyHint/idempotentHint already declaring safety, the description adds real context: the snapshot is dated, the session catalog can lag, document subtypes are distinct from parent type codes, and nextCall must be followed to read all entries. These are staleness and completeness traits the annotations cannot express.

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?

Three sentences, front-loaded with the topic inventory, then staleness and subtype caveats. Dense but each clause carries a distinct warning; only the topic list is close to restating the enum.

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?

An output schema exists, so return values need not be described, and the description covers the remaining unknowns an agent needs: snapshot staleness, pagination via nextCall, subtype-vs-parent distinction, and session lag. Little is missing for a read-only reference lookup.

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 still adds meaning by glossing the enum topics — 'speech reply filters' for speech_types, 'identifier conventions' for identifiers, and 'source coverage' for coverage — clarifying intent beyond the bare enum labels.

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 ('look up') and enumerates the reference resources covered (document types, committees, parties, sessions, identifier conventions, coverage). This clearly separates it from the sibling search_/get_ tools, which retrieve documents, members, votes, or speeches, even though no sibling is named explicitly.

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 implied rather than stated: an agent gathers that this is the vocabulary tool to consult before or alongside the search tools. There is no explicit 'use this when / don't use this when' or pointer to a specific alternative, so guidance remains inferential.

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 openWorldHint, so the safety profile is covered structurally. The description adds the pagination behavior ('follow complete continuation calls') and default ordering behavior, but says nothing about result-size limits or cost of broad queries beyond what the schema already states.

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?

Two sentences, front-loaded with the verb and resource, then the filter menu and the ordering/continuation instructions, then the sibling handoff. No filler and every clause carries operational information.

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 13 optional parameters, an output schema, and full annotations, the description covers purpose, filtering, ordering, pagination, and the follow-up retrieval tool, which is sufficient for correct invocation. It does not state default behavior when no parameters are supplied or how filters combine, leaving 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?

Schema description coverage is 100%, so all 13 parameters are already documented with semantics such as revision, offset, and session behavior. The description only groups the filter families (words, type, session, committee, party, member IID, dates) at a high level without adding syntax or combination rules, matching the baseline 3 for a fully documented 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 (Search) and resource (Swedish parliamentary documents and consolidated SFS statutes) and enumerates the filter dimensions available, so an agent knows precisely what it retrieves. It also names the sibling riksdag_get_document for the status/text follow-up, cleanly separating search from retrieval.

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 routing: use this to search, then read document status and text with riksdag_get_document, and it explains the relevance-vs-date ordering choice and the continuation workflow. It stops short of explicit exclusions (e.g., when to prefer riksdag_search_speeches or riksdag_search_members for related content), so there is a small gap.

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, and open-world, so the safety profile is covered. The description adds genuinely new behavioral context: the default register scope and the timeout risk of the larger historical request, which is operationally important and not derivable from annotations 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?

Three tight sentences with no filler; the core capability comes first, then the caveat, then the sibling pointer. The phrase 'register all includes earlier source records' is slightly compressed but still readable.

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 and full parameter documentation in the schema, the description only needs to cover invocation guidance and caveats — which it does via the register/timeout warning and the get_member pointer. Nothing essential for a correct call 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 description coverage is 100%, so the schema already documents all 8 parameters including register scope and timeout behavior. The description repeats the register/timeout story rather than adding new syntax or format details, so the 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?

States a specific verb ('Find') and resource ('members and ministers') with the filterable facets (name, party, constituency, service status). It also separates itself from the sibling riksdag_get_member by assigning ID-based assignment history to that tool, so an agent can pick correctly 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?

Clearly routes ID-based lookups to riksdag_get_member and explains the register=all trade-off ('larger cold request that may time out'). It lacks an explicit statement of when NOT to search at all, but the alternative routing gives strong context.

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

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

Beyond the safety hints provided in annotations, the description specifies crucial operational behaviors: heading matching applies only to debate headings, never the body text. It also details the default hydration behavior of a single page.

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 with critical information but highly structured. Both sentences serve distinct, necessary purposes: the first establishing scope and options, and the second detailing retrieval mechanics and workflow.

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

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

Given the complexity of the 13 parameters and the dual functionality (search/get), the description provides necessary boundaries and operational context (e.g., 'heading matches debate headings only') that a standalone schema cannot convey.

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?

Although the schema is comprehensive, the description adds semantic meaning by clustering the parameters into operational stages (Search options vs. Read/Hydrate mechanics). This links the parameters functionally rather than just describing them individually.

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 identifies the resource (speeches) and the primary action (search within a required parliamentary session). It distinguishes itself by detailing optional filters (member, party, heading tokens) and implicitly separating its function from general document search tools via the context provided.

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 provides an explicit workflow, explaining the difference between 'search' mode (default, hydrating one text page) and 'get' mode (used with `speechId` to continue reading). This guides the agent on the correct sequence of tool usage.

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