ris-austria-mcp-server

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

The description goes far beyond the readOnly/idempotent annotations, specifying exact degradation behavior ('the tool degrades explicitly, never silently'), the format_unavailable notice for PDF-only/metadata-only collections, the 40,000-byte outline/truncation mechanism with window boundaries, and the fact that html/xml renditions are never sliced. It also discloses that markdown strips screen-reader expansions. No annotation 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 long but information-dense; each clause covers a distinct behavior or constraint necessary for correct use (addressing modes, format availability, outline fallback, slicing boundaries). It is front-loaded with the primary purpose, then progressively details edge cases. While verbose, the complexity of the tool justifies it, and 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?

The description covers all major usage scenarios and edge cases: how to address documents via document_number or URL, which applications carry which formats, what happens on overflow, how to retrieve specific sections, and what happens with raw renditions. Combined with the presence of an output schema, the agent has comprehensive context for 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?

The input schema already has 100% parameter coverage with rich descriptions, so the baseline is 3. The main description adds details about line-break window cuts and the relationship between document_url and companion documents, which enriches the semantics of the `sections` and `document_url` parameters. It also clarifies that application must be copied verbatim from a result, reinforcing mutual exclusivity.

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 crisp specification: 'Fetch one RIS document’s full text or its rendition URLs, with explicit binding status and the amtssigniert authentic PDF surfaced wherever it exists.' It distinguishes from sibling search/lookup tools by stating that metadata comes from the preceding search step, and describes the two addressing modes. This clearly identifies the tool's unique job.

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 instructs when to use this tool (after a ris_search_* or ris_lookup_citation result) and provides alternatives/exclusions, e.g., 'This tool returns content, not fresh metadata — the metadata rides the search/lookup step.' It also names the exact sibling source for each input ('a ris_search_drafts record’s materials[].url'), and explains that certain applications are PDF-only. This is exemplary usage guidance.

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

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

The description aligns with annotations (readOnlyHint, idempotentHint) and adds behavioral context: the tool is static, offline, makes no upstream calls, and serves as the destination for recovery hints. No contradictions 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?

The description is comprehensive but somewhat verbose, listing all 17 topics in detail. While this is informative, it could be more concise by moving the list to schema enum descriptions. Front-loads the key purpose but is longer than necessary.

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 simplicity (single parameter, output schema exists), the description sufficiently covers purpose, usage, and behavioral context. Annotations handle safety, and the output schema clarifies return values. No 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?

The parameter description for 'topic' adds meaningful usage context beyond the schema enum, tying it to error recovery hints. With 100% schema coverage, the baseline is 3, but the extra guidance merits a 4.

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: to ground opaque German codes across the RIS surface, returning static reference tables for various topics. It explicitly distinguishes itself from sibling tools by noting that recovery hints from other ris_* tools route here.

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 guidance on when to use this tool: when an error recovery hint or zero-hit notice from another ris_* tool directs the agent here. It also notes the tool is static and offline, implying it is safe and fast for quick lookups.

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 (readOnly, idempotent, openWorld), the description discloses critical behavior: it never throws for a miss, returns found:false with guidance, probes up to two courts for ambiguous case numbers, and returns ambiguous VwSlg cites as ambiguous rather than resolving arbitrarily. These details substantially exceed annotation-provided information.

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 each sentence contributes unique information—purpose, route taxonomy, examples, ambiguity handling, and alternatives. It is front-loaded with the core purpose and structured logically by routes, though a bulleted layout would improve readability without cutting 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 a tool with four routes, five parameters, and an output schema, the description is remarkably complete: it covers all citation shapes, edge cases (ambiguous VwSlg, pre-e-Recht fallback), return shape (same as search tools), and error behavior. The existing output schema covers return values, so the description's focus on selection and behavior is appropriate.

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 valuable semantics: it illustrates kind routes with concrete citation examples, clarifies that court skips detection, and explains the state hint's pre-e-Recht fallback. The description enriches the enum meanings and edge-case behavior beyond the schema's descriptions.

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 'Resolve a single Austrian legal citation to its canonical RIS document deterministically — no keyword search,' providing a specific verb and resource. It distinguishes itself from siblings by explicitly directing keyword lookups to ris_search_legislation or ris_search_case_law, making the tool's unique purpose unmistakable.

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 guidance is explicit and detailed: the description enumerates the four citation routes, explains when to force or skip detection (kind, court, state hints), and directly names alternative tools for keyword search. It also covers ambiguous VwSlg citations and the fallback for state gazettes, giving clear when/why instructions.

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?

Going beyond the readOnlyHint and idempotentHint annotations, the description discloses important behavioral traits: filters outside a collection's set are 'rejected locally,' council minutes and ministerial decrees are PDF-only with document_url as 'the only browsable surface,' and the legal status of each collection (authentic vs. decrees that do not bind citizens) is spelled out. It also reveals a current geographic limitation for court_rules. These details give an agent a realistic expectation of behavior and constraints.

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

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

The description is a single dense paragraph that enumerates seven collections, a dozen filter types, and result characteristics. While logically ordered, it repeats information already present in the schema (e.g., parameter scope details) and could be more scannable with bullet points or a tighter summary. The length is partly justified by the tool's complexity, but it feels over-packaged for quick agent 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?

Given the high parameter count and existing schema/annotations, the description covers key contextual gaps: collection semantics, authenticity, PDF-only limitations, and where to find the detailed matrix. The presence of an output schema means return values are already documented, so the description's note about result labels and links is supplementary. It's a thorough overview, though it could have explicitly mentioned pagination or distinct use cases for each collection.

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?

Since schema description coverage is 100%, the structured schema already tells the agent which parameter applies to which collection (e.g., norm is 'veterinary and ministerial_decrees only'). The description adds a high-level conceptual grouping of filters and points to ris_list_reference for the full matrix, but it doesn't introduce new parameter-specific semantics that aren't already in the schema. It earns a baseline 3 for not adding meaningful depth 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 opens with a specific verb and resource: 'Search Austria’s sectoral official gazettes and executive documents.' It immediately clarifies the tool's unique scope by enumerating seven distinct collections behind a single `collection` enum, distinguishing it from sibling search tools. The level of detail about what each collection contains leaves no ambiguity about what the tool does.

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 rich context about when to use specific collections (e.g., ministerial_decrees 'bind the administration, not citizens') and notes limitations like court_rules being 'currently LVwG Tirol and Vorarlberg only.' However, it never explicitly states when this tool should be preferred over sibling tools like ris_search_gazette or ris_search_legislation, nor does it offer direct 'when not to use' guidance. The mention of ris_list_reference for the parameter matrix is helpful but not a true alternative-selection guideline.

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

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

Even with readOnlyHint, openWorldHint, and idempotentHint annotations, the description adds substantial behavioral context: one-court-per-call constraint, 'historical bodies are closed windows with successors', explicit warnings about filters that return 0 hits due to corpus gaps (e.g., subject_area and decision_kind for justiz), and court-specific format quirks like vwgh collection_number matching. It also notes 'calls are cheap' for cross-court research, a useful operational trait.

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 a single dense paragraph that front-loads the core action and then uses compact semicolon-separated lists to enumerate courts and filters. It delegates detailed enumerations to ris_list_reference topics rather than repeating them, so every sentence carries unique information without fluff or redundancy.

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 24 parameters, rich annotations, and an output schema present, the description covers all necessary context: court enumeration, filter categories, exclusions, and practical examples for dates and norms. It explicitly flags known data-quality issues (zero-hit filters) and cross-tool pointers, making it complete for safe and effective 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 100%, so the baseline is 3, but the description adds meaningful grouping and prioritization: it calls norm 'the highest-value filter', explains case_number 'returns that decision’s documents', and clarifies court-conditional applicability for several filters (e.g., issuing_body, court_name, state, party, commission, subject_law). It also adds caveats like 'Not available for normenliste' for sort_by and case_number, which the schema alone doesn't convey as succinctly.

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: 'Search Austrian case law (Judikatur) in ONE court or tribunal per call' and lists the exact court codes, giving clear scope. It also distinguishes itself from siblings by explicitly referencing ris_lookup_citation for known citations and ris_list_reference for court metadata, so the tool's unique function is well-defined.

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 when to use this tool versus alternatives: 'For a known Geschäftszahl or VfSlg/VwSlg cite, ris_lookup_citation resolves it directly' and points to ris_list_reference for court codes/windows. However, it does not explicitly compare against other search tools like ris_search_legislation or ris_search_announcements, so guidance is strong within the case-law family but incomplete across the full sibling set.

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, openWorldHint, and idempotentHint, but the description adds substantial behavioral context: documents are preparatory and not binding law, government_bills are only available from 2004+, ministry lookup uses the historical name at submission time, and materials can only be read via ris_get_document with a materials[].url. It also discloses the coarse nature of changed_since and points to ris_track_changes for finer control.

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 and front-loaded with the core purpose, then flows logically through stage selection, filter semantics, and output context. Every sentence earns its place: purpose, stage details, filter explanations, materials handling, and cross-references to sibling tools. Despite its length, it is well-structured and free of 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 a complex tool with 12 parameters, an output schema, and annotations, the description fully covers the essential context: what is searched, the two pipeline stages, how filters depend on stage, how to read companion documents, and which sibling tools to use for related tasks. It also clarifies the legal status of results, and since an output schema exists, describing return values is unnecessary.

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 schema coverage is 100% (baseline 3), the description enriches meaning well beyond the schema. It explains stage values with full context (Begutachtungsentwürfe vs Regierungsvorlagen), expands on ministry abbreviation handling ('expanded to RIS’s exact designation; the historical name at submission time counts'), clarifies date filter semantics ('today = what is in Begutachtung right now'), and describes the materials structure and how to access it.

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 defines the tool as searching Austria's federal lawmaking pipeline before promulgation, with an explicit verb and resource. It also distinguishes itself from sibling ris_search_gazette by calling itself the 'monitoring counterpart' and describing the two pipeline stages (review_drafts and government_bills) with German terms.

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 explicitly contrasts this tool with ris_search_gazette ('what will become law') and directs users to ris_get_document for reading materials, ris_list_reference for ministry codes, and ris_track_changes for exact recency windows. It also clarifies stage-specific filters (in_review_on vs decided_from/to) and notes that changed_since is coarse, giving clear when-to-use and when-not-to-use guidance.

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

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

Annotations already cover readOnly/idempotent. Description adds meaningful context: one call per era tier, date interval rejection with boundaries, result labels/PDF. No contradictions.

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 core purpose, then logically expands. Every sentence adds unique information; could be slightly more concise but remains focused and helpful.

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 all 17 parameters, edge cases (1941-44 gap, Vienna state_era), output characteristics (labels, PDF), and references external resources. Sufficient for correct 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 100%, but description adds significant value: number auto-routing, scope era interactions, state_era nuances (Wien none), precedence in filtering. Not just repetition.

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 browses Austrian gazettes, listing specific jurisdictions and data types. It distinguishes from siblings like ris_lookup_citation (single number) and ris_list_reference (reference topics).

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 says when to use ris_lookup_citation for a known number and ris_list_reference for coverage details. Provides clear context on when the tool is appropriate and when alternatives are better.

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 (readOnlyHint, openWorldHint, idempotentHint) are complemented by the description's note that 'Consolidated text is informational, not legally binding' and that the authentic version is in ris_search_gazette. It also discloses that the applied date is echoed back. 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?

The description is dense with needed information, but it is front-loaded with the core purpose and then details parameters. While every sentence earns its place, the length (over 10 sentences) could be slightly trimmed without losing clarity. Still well-structured.

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 21 parameters, full schema coverage, and an output schema (mentioned), the description covers all key aspects: version filter windows, mutual exclusivities, default dates, wildcard rules, scope combinations, and the informational nature. 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 coverage is 100%, but the description adds significant context beyond names: explains that law_id 'returns every section of that law', that language='english' requires scope='federal' and combines only with query/title, and details wildcard rules ('trailing-only *'). It clarifies mutual exclusivities and default behaviors, substantially enhancing understanding.

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 'Search Austrian consolidated law and English translations' and specifies scope options (federal, Bundesland, municipal, English translations). It distinguishes from siblings like ris_lookup_citation ('For a specific citation... resolves it deterministically') and ris_search_gazette ('authentic gazette artifact lives in ris_search_gazette'), making the tool's purpose unambiguous.

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

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

Explicit guidance on when to use this tool vs alternatives: 'For a specific citation... ris_lookup_citation resolves it deterministically' and 'For exact windows and deletions use ris_track_changes.' It also explains mutual exclusivity of version filters ('mutually exclusive') and default behaviors (in_force_as_of defaults to today).

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, openWorldHint, and idempotentHint, indicating the tool is safe, returns possibly new results each time, and can be retried. The description adds important behavioral context: it returns both changed and deleted records, describes the compact record structure (document_number, title, etc.), and mentions automatic mapping of History-feed names. No contradictions 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?

The description is a single dense paragraph covering all key points: purpose, usage guidelines, parameter details, and return structure. It is concise and front-loaded, but could benefit from slightly more structure (e.g., bullet points or breaks) for easier scanning. No extraneous sentences.

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 has 6 parameters (1 required), an output schema (not shown but summarized), and complexity (delete-aware, exact dates, multiple applications), the description is fully complete. It explains what the tool does, when to use it, what parameters mean, and what the return value looks like. An agent can confidently select and invoke this tool based on 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 description coverage is 100%, but the description adds significant meaning beyond the schema: it explains that changed_from/changed_to are exact dates (not coarse intervals), that include_deleted is the only way to observe deletions, and that application codes are mapped automatically. It also advises pagination for large windows.

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: tracking documents added/changed in one RIS application within an exact date window, and specifically calls out its role as a delta-sync and monitoring primitive. It distinguishes from search tools by mentioning exact-dated and deletion-aware capabilities, making it easy to differentiate from siblings like ris_search_legislation.

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 explicitly states when to use the tool ('the delta-sync and monitoring primitive for mirrors and watchers', 'the only surface that reports removals') and contrasts with alternatives ('Unlike the search tools’ coarse, additive-only changed_since intervals'). It also provides guidance on parameters (one application per call, page for large windows) and references ris_list_reference for application codes.

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